1ISNSADM(8) System Manager's Manual ISNSADM(8)
2
6 isnsadm - iSNS client utility
7
9 isnsadm [options...] --register object...
10 isnsadm [...] --query attr[=value]
12 isnsadm [...] --deregister attr=value
14 isnsadm [...] --list type attr=value
16 isnsadm [...] --dd-register attr=value
18 isnsadm [...] --dd-deregister dd-id attr=value
20 isnsadm [...] --enroll client-name attr=value
22 isnsadm [...] --edit-policy attr=value
24
27 Isnsadm is a command line utility for interacting with an iSNS server.
28 It operates in one of several modes, which are mutually exclusive.
29 Currently, isnsadm supports registration, query, and deregistration.
30
32 By default, isnsadm will take most of its settings from the configura‐
33 tion file /etc/isns/isnsadm.conf, with the exception of the following
34 options:
35 --config filename, -c filename
37 This option overrides the default configuration file.
38 --debug facility, -d facility
40 enables debugging. Valid facilities are
41 ┌────────┬─────────────────────────────────────────────────────┐
43 │socket │ network send/receive │
44 │auth │ authentication and security related information │
45 │message │ iSNS protocol layer │
46 │state │ database state │
47 │scn │ SCN (state change notification) messages │
48 │esi │ ESI (entity status inquiry) messages │
49 │all │ all of the above │
50 └────────┴─────────────────────────────────────────────────────┘
51 --local
52 makes isnsadm use a Local (aka Unix) socket when talking to the
53 iSNS server. This can be used by the administrator to perform
54 management tasks, such as enrolling new clients, editing access
55 control and so on. Local mode is only available to the super
56 user.
57 --server servername, -s servername
59 specifies the server to use (if not specified in the configura‐
60 tion file).
61 --control
63 makes isnsadm assume the identity of a control node. Control
64 nodes are special in that they have more rights in accessing and
65 modifying the database than normal storage nodes have.
66 When using this option, isnsadm will use the source name and DSA key
68 specified by the Control.SourceName and Control.AuthKeyFile configura‐
69 tion options, respectively.
70 --key attr=value
72 This option is recognized in registration mode only, and lets
73 you specify an object key. For a more detailed explanation,
74 refer to section Registration mode.
75 --keyfile=filename
77 When creating a policy for a new iSNS client, isnsadm is able to
78 generate a DSA key for the client. The public part of the key is
79 stored in a policy object in the iSNS server's database, whereas
80 the private portion is stored in the file specified by the key‐
81 file option.
82 --help This will print a help message and exit.
84 Built-in help
86 Isnsadm has built-in help functions. When invoked with --help, it will
87 print a general help message showing all supported command modes, and
88 exit. Specific help on an individual command mode is available by
89 invoking that mode with a single argument of help, like this:
90 isnsadm --register help
92 This will print a help message describing how to use this command mode,
94 followed by a list of attributes this command supports and a help text
95 describing the attribute.
96 Supported attributes
98 Most command modes take a list of attributes as arguments on the com‐
99 mand line. The naming and syntax of these attributes are the same for
100 all commands modes, however certain modes support only a limited set of
101 attributes.
102 Attributes are usually given as name=value pairs. Where empty (or NIL)
104 attributes are supported, the attribute name by itself can be given.
105 The syntax of attribute value depends on the attribute type. For
107 strings and numeric values, no special conventions apply, but bitfields
108 have a special syntax described below.
109 The attribute name is usually preceded by the object type it applies to
111 (such as entity), followed by a hyphen and the name itself. However,
112 where the context clearly determines a specific object type, the prefix
113 can be omitted. For instance, when editing a policy object using
114 --edit-policy, it is acceptable to use node-type as shorthand for pol‐
115 icy-node-type.
116 Likewise, in a query command, it is not permitted to mix attributes
118 from different object types. Thus, the first attribute of a query
119 string establishes a type context, so that the following two invoca‐
120 tions are equivalent:
121 isnsadm --query pg-name=iqn.com.foo pg-addr=10.1.1.1 pg-port=860/tcp
123 isnsadm --query pg-name=iqn.com.foo addr=10.1.1.1 port=860/tcp
124 Isnsadm currently supports the following attributes:
126 ┌───────────────────┬───────────────────────────────────────────┐
128 │Context │ Attribute iSNS tag Aliases │
129 ├───────────────────┼───────────────────────────────────────────┤
130 │Network Entity │ entity-id 1 eid │
131 │ │ entity-prot 2 │
132 │ │ entity-index 7 │
133 │iSCSI Storage Node │ iscsi-name 32 │
134 │ │ iscsi-node-type 33 │
135 │ │ iscsi-alias 34 │
136 │ │ iscsi-idx 36 │
137 │ │ iscsi-authmethod 42 │
138 │Portal │ portal-addr 16 │
139 │ │ portal-port 17 │
140 │ │ portal-name 18 │
141 │ │ portal-esi-port 20 │
142 │ │ portal-esi-interval 21 │
143 │ │ portal-idx 22 │
144 │ │ portal-scn-port 23 │
145 │Portal Group │ portal-group-index 52 │
146 │ │ pg-name 48 │
147 │ │ pg-addr 49 │
148 │ │ pg-port 50 │
149 │ │ pg-tag 51 pgt │
150 │ │ pg-idx 52 │
151 │Discovery Domain │ dd-id 2065 │
152 │ │ dd-name 2066 │
153 │ │ dd-member-iscsi-idx 2067 │
154 │ │ dd-member-name 2068 │
155 │ │ dd-member-fc-name 2069 │
156 │ │ dd-member-portal-idx 2070 │
157 │ │ dd-member-addr 2071 │
158 │ │ dd-member-port 2072 │
159 │ │ dd-features 2078 │
160 │Policy Object │ policy-name - spi │
161 │ │ policy-key - │
162 │ │ policy-entity - │
163 │ │ policy-node-type - │
164 │ │ policy-object-type - │
165 │ │ policy-functions - │
166 └───────────────────┴───────────────────────────────────────────┘
167 Portal attributes
168 Portal information is conveyed by two separate attributes in iSNS; an
169 address attribute holding the IP address, and a TCP/UDP port attribute
170 holding the port number and an indication of the protocol to be used
171 (TCP or UDP).
172 When parsing a TCP/UDP port, Open-iSNS will expect a port number,
174 optionally followed by a slash and the protocol. Port names such as
175 "iscsi-target" are not supported.
176 As a convenience, isnsadm supports a notation representing a portal as
178 one pseudo-attribute. Separating address and port by a colon. Thus,
179 the following two are equivalent, with the latter being the shorthand
180 representation of the former:
181 addr=<address> port=<port>[/protocol]. portal=<adress>:port[/protocol]
183 This notation can be used in any context where an addr/port attribute
185 pair can appear, and may be prefixed by a type name, as in pg-por‐
186 tal=....
187 When using literal IPv6 addresses, the address has to be surrounded by
189 square brackets, otherwise the embedded colons would create ambiguity:
190 portal=[2001:5c0:0:2::24]:860/tcp
191 Bitfield attributes
193 Some iSNS attributes are words representing a bit field. Isnsadm dis‐
194 plays and parses these attributes in human-readable form rather than
195 using the numerical value. The names of the bit values are displayed by
196 built-in help facilities. When specifying a bitfield attribute on the
197 command line, you can combine them using the plus (+) or comma (,)
198 character, like this:
199 node-type=control+initiator
201 Registration mode
203 Registration mode is selected by using the --register option, followed
204 by a list of one or more objects to register with the iSNS server. By
205 default, this will create a network entity for the client (if none
206 exists), and place the new objects inside it. Usually, you register
207 all objects for a network entity in one operation, rather than each one
208 separately.
209 Each object is specified as a type, optionally followed by a comma-sep‐
211 arated list of attributes, such as this:
212 target=iqn.2005-01.org.open-iscsi.foo:disk1,alias=disk1
214 The following object types are currently supported:
216 entity=name
218 Tells the server to group all objects in the specified Network
219 Entity container object. Normally, the iSNS server will auto‐
220 matically assign an entity name that is in line with its poli‐
221 cies, and there is no need to specify it explicitly.
222 initiator[=name]
224 This will register an iSCSI storage node of type initiator. By
225 default, the name is set to the iSNS source name.
226 This can be followed by any number of iSCSI storage node
228 attributes.
229 target[=name]
231 This will register an iSCSI storage node of type target. By
232 default, the name is set to the iSNS source name.
233 This object accepts the same set of attributes as initiator.
235 control[=name]
237 This will register an iSCSI storage node of type control. By
238 default, the name is set to the iSNS source name. Only manage‐
239 ment nodes should be registered as control nodes, as this gives
240 a node complete control over the iSNS database.
241 This object accepts the same set of attributes as initiator.
243 portal=[address:port/proto]
245 This will register a portal using the given address, port and
246 protocol triple. If the triple is omitted, isnsadm will use the
247 client host's IP address. If the portal is preceded by an ini‐
248 tiator registration (on the command line), the port defaults to
249 860/tcp; if it is preceded by a target registration, the port
250 defaults to 3260/tcp. For multi-homed hosts, the choice of
251 address is implementation dependent.
252 This can be followed by any number of portal attributes.
254 pg This will register a portal group joining the preceding portal
256 and node. Portal groups can be used to describe the preferred
257 portals for a given node; please refer to RFC 4171 for details.
258 This can be followed by any number of portal group attributes.
260 The attribute list must specify a portal group tag (PGT) via the
261 pgt attribute.
262 There are two additional command line options of interest, which are
264 used exclusively with Registration mode. One is --replace. Normally,
265 registration mode will add new objects to the network entity associated
266 with the client host. If you specify --replace on the command line, the
267 server will wipe the network entity completely, and remove all portals
268 and storage nodes it contained. Then it will create a new network
269 entity, and place the portals and storage nodes provided by the caller
270 inside.
271 In addition, it is possible to replace just parts of a network entity.
273 This is achieved by using the command line option --key to specify the
274 object that should be replaced.
275 For instance, assume a network entity contains the portal 10.1.1.1:860,
277 and the client's network address changed to 10.2.7.7. Then the follow‐
278 ing command will atomically update the database, replacing just the
279 portal without touching the registered storage nodes:
280 isnsadm --replace --key portal=10.1.1.1:860 portal=10.2.7.7:860
282 The --key option recognizes only a subset of the usual attributes:
284 ┌────────────┬─────────────────────┐
286 │Object type │ Syntax │
287 ├────────────┼─────────────────────┤
288 │Entity │ eid=identifier │
289 │Portal │ portal=address:port │
290 │iSCSI Node │ iscsi-name=name │
291 └────────────┴─────────────────────┘
292 To get a list of supported attributes, invoke isnsadm --register help.
293 Query mode
295 Query mode is selected by using the --query option. A query consists of
296 a list of attr=value pairs. All attributes must belong to the same
297 object type, i.e. queries that mix a Network Entity attribute with e.g.
298 a Portal attribute will be rejected.
299 It is also possible to specify an attribute name without value (i.e.
301 just attr), which will will match any object that has such an
302 attribute, regardless of its value. This is useful when you want to
303 query for all objects of a given type.
304 To obtain a list of supported attributes, invoke isnsadm --query help.
306 List Mode
308 In this mode, isnsadm will display all objects of a given type, option‐
309 ally restricted to those matching certain attribute values.
310 The arguments to list mode are a type name, optionally followed by one
312 or more attr=value pairs. Only attributes pertaining to the given type
313 are permitted; for instance, if you specify a type name of portals,
314 only portal attributes are permitted.
315 Possible type names are: entities, nodes, portals, dds, ddsets, portal-
317 groups, and policies.
318 Additional information is available via isnsadm --list help.
320 Deregistration mode
322 In this mode, you can deregister objects previously registered. Only
323 the node which registered an entity in the first place is permitted to
324 remove it, or any of its child objects. (Control nodes are not bound by
325 this restriction).
326 In deregistration mode, the argument list consists of a list of
328 attr=value pairs. Deregistration supports the same set of attributes as
329 query mode.
330 Discovery Domain Registration
332 This mode allows one to register a discovery domain or to add new mem‐
333 bers to an existing discovery domain. Again, attributes are specified
334 as a list of attr=value pairs. Only discovery domain attributes are
335 recognized.
336 Note, in order to add members to an existing domain, you must specify
338 the domain's numeric ID. The domain's symbolic name is not a valid han‐
339 dle when referring to a discovery domain.
340 Discovery Domain Deregistration mode
342 In this mode, you can deregister a discoery domain previously regis‐
343 tered. Only the node which registered a discovery domain in the first
344 place is permitted to remove it, or any of its members. (Control nodes
345 are not bound by this restriction).
346 In Discovery Domain deregistration mode, the argument list consists of
348 the Discovery Domain ID, followed by a list of attr=value pairs. Dis‐
349 covery Domain Deregistration supports the same set of attributes as
350 query mode.
351 Client Enrollment
353 This mode only works when the server recognizes the client as having
354 control node capabilities, which is possible in two ways:
355 Invoke isnsadm --local as super user on the host isnsd is running on.
357 The --local options tells it to communicate with the server
358 through the local control socket.
359 Invoke isnsadm --control, which tells it to assume the identity of a
361 control node. When given this option, isnsadm will use the
362 source name and DSA key specified by the Control.SourceName and
363 Control.AuthKeyFile configuration options, respectively. The
364 server must be configured to grant this identity control node
365 status.
366 To enroll a client, use the --enroll option, followed by the (source)
368 name of the client to enroll. This string will be used as the name of
369 the security policy the client will use to identify itself.
370 This is followed by a list of attribute/value pairs, where the follow‐
372 ing set of attributes is supported:
373 ┌────────────┬─────────────────────────────────────────────┐
375 │Attribute │ Description Aliases │
376 ├────────────┼─────────────────────────────────────────────┤
377 │name │ Policy Name spi │
378 │key │ Client's DSA public key │
379 │entity │ Assigned Entity Identifier │
380 │node-type │ Permitted node type(s) │
381 │node-name │ Permitted node name(s) │
382 │functions │ Bitmap of permitted functions │
383 │object-type │ Object access mask │
384 └────────────┴─────────────────────────────────────────────┘
385 The key attribute is used to specify the DSA public key that the server
386 should use to authenticate messages from this client. You can either
387 provide a file name; in which case isnsadm will try to read the PEM
388 encoded public key from that file. If no key attribute is given, or
389 when using key=gen, isnsadm will generate a DSA key. The private por‐
390 tion of the newly generated key will be stored in the file specified by
391 --keyfile=filename.
392 The object-type attribute is used to specify which object types the
394 client is permitted to access. This is a comma separated list of
395 type:perm pairs, where type can be any of entity, iscsi-node, portal,
396 portal-group, dd, ddset, and policy. The permissions can be either rw,
397 or r.
398 The functions attribute can be used to restrict which functions the
400 client is permitted to invoke. This is a bitfield, using the standard
401 function names from RFC 4171, such as DevAttrReg, DevAttrQry, etc.
402 For a description of the open-isns security model and policies, please
404 refer to the isns_config(5) manual page.
405 Important note: In order to generate a DSA key, you have to have a set
407 of DSA parameters installed. By default, isnsadm expects to find them
408 in /etc/isns/dsa.params. These parameters are created by calling isnsd
409 --init once on the server machine. Alternatively, you can use the fol‐
410 lowing command:
411 openssl dsaparam 1024 -out /etc/isns/dsa.params
413 where 1024 is the chosen DSA key size, in bits.
415
417 If you want to use Open-iSNS in authenticated mode, you first need to
418 initialize the server's DSA key and DSA parameters. This can be done
419 conveniently by using
420 isnsd --init
422 This will create the server's private and public key, and place them in
424 /etc/isns/auth_key and auth_key.pub, respectively.
425 The following command will create a policy object for a node named
427 isns.control , and grant it control privileges:
428 isnsadm --local --keyfile=control.key --enroll isns.control \
430 node-type=ALL functions=ALL object-type=ALL
431 In the process of entrolling the client, this will generate a DSA key
433 pair, and place the private key portion in the file control.key. This
434 file must be installed as /etc/isns/control.key on the host you wish to
435 use as an iSNS management station.
436 Next, you need to create a storage node object for the management sta‐
438 tion:
439 isnsadm --local --register control
441 On the management station, you can then enroll additional hosts:
443 isnsadm --control --keyfile=somehost.key --enroll iqn.2005-01.org.open-
445 iscsi.somehost \
446 node-type=target+initiator
447 Again, this will generate a DSA key pair and store the private key por‐
449 tion in auth_key. Note the use of the --control option that tells
450 isnsadm to use the identity of the control node instead of the default
451 key and source name.
452 You then need to copy somehost.key to the client host and install it as
454 /etc/isns/auth_key. Likewise, the server's public key (which resides
455 in /etc/isns/auth_key.pub on the server) needs to be copied to the
456 client machine, and placed in /etc/isns/server_key.pub.
457 By default, when a client registers a storage node (be it initiator or
459 target) with iSNS, the client will not be able to see any other storage
460 nodes. In order for targets to be visible to a given initiator, you
461 need to create so-called Discovery Domains (or DDs for short).
462 Currently, domain membership operations require administrator privi‐
464 lege. Future extensions may allow iSNS clients to add themselves to one
465 or more DDs upon registration.
466 To create a discovery domain, and add nodes to it, you can use
468 isnsadm --control --dd-register dd-name=mydomain \
470 member-name=iqn.org.bozo.client iqn.org.bozo.jbod ...
471 In order to add members to an existing DD, you have to specify the
473 numeric domain ID - using the DD name is not sufficient, unfortunately
474 (this is a requirement of the RFC, not an implementation issue):
475 isnsadm --control --dd-register dd-id=42 \
477 member-name=iqn.com.foo member-name=iqn.com.bar
478 The DD ID can be obtained by doing a query for the DD name:
480 isnsadm --control --query dd-name=mydomain
482 In management mode, you can also register and deregister nodes and por‐
484 tals manually, in case you want to fix up an inconsisteny in the data‐
485 base. For instance, this will register a node and portal on a host
486 named client.bozo.org:
487 isnsadm --control --register entity=client.bozo.org \
489 initiator=iqn.org.bozo.client portal=191.168.7.1:860
490 Note that this registration explicitly specifies the network entity in
492 which to place the new objects. If you omit this, the new objects will
493 be placed in an entity named CONTROL, which is decidedly not what you
494 want.
495
497 RFC 4171, isnsd(8), isns_config(5).
498
500 Olaf Kirch <olaf.kirch@oracle.com>
501 11 May 2007 ISNSADM(8)