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