1ISNSADM(8)                  System Manager's Manual                 ISNSADM(8)
2
3
4

NAME

6       isnsadm - iSNS client utility
7

SYNOPSIS

9       isnsadm [options...]  --register object...
10
11       isnsadm [...]  --query attr[=value]
12
13       isnsadm [...]  --deregister attr=value
14
15       isnsadm [...]  --list type attr=value
16
17       isnsadm [...]  --dd-register attr=value
18
19       isnsadm [...]  --dd-deregister dd-id attr=value
20
21       isnsadm [...]  --enroll client-name attr=value
22
23       isnsadm [...]  --edit-policy attr=value
24
25

DESCRIPTION

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

OPTIONS

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
36       --config filename, -c filename
37              This option overrides the default configuration file.
38
39       --debug facility, -d facility
40              enables debugging. Valid facilities are
41
42           ┌────────┬─────────────────────────────────────────────────────┐
43socket  │ network send/receive                                │
44auth    │ authentication and security related information     │
45message │ iSNS protocol layer                                 │
46state   │ database state                                      │
47scn     │ SCN (state change notification) messages            │
48esi     │ ESI (entity status inquiry) messages                │
49all     │ 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
58       --server servername, -s servername
59              specifies  the server to use (if not specified in the configura‐
60              tion file).
61
62       --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
67       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
71       --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
76       --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
83       --help This will print a help message and exit.
84
85   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
91       isnsadm --register help
92
93       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
97   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
103       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
106       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
110       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
117       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
122       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
125       Isnsadm currently supports the following attributes:
126
127          ┌───────────────────┬───────────────────────────────────────────┐
128ContextAttribute              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
173       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
177       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
182       addr=<address> port=<port>[/protocol].  portal=<adress>:port[/protocol]
183
184       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
188       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
192   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
200       node-type=control+initiator
201
202   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
210       Each object is specified as a type, optionally followed by a comma-sep‐
211       arated list of attributes, such as this:
212
213       target=iqn.2005-01.org.open-iscsi.foo:disk1,alias=disk1
214
215       The following object types are currently supported:
216
217       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
223       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
227              This can be  followed  by  any  number  of  iSCSI  storage  node
228              attributes.
229
230       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
234              This object accepts the same set of attributes as initiator.
235
236       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
242              This object accepts the same set of attributes as initiator.
243
244       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
253              This can be followed by any number of portal attributes.
254
255       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
259              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
263       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
272       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
276       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
281         isnsadm --replace --key portal=10.1.1.1:860 portal=10.2.7.7:860
282
283       The --key option recognizes only a subset of the usual attributes:
284
285              ┌────────────┬─────────────────────┐
286Object typeSyntax
287              ├────────────┼─────────────────────┤
288Entity      eid=identifier      │
289Portal      portal=address:port │
290iSCSI Node  iscsi-name=name     │
291              └────────────┴─────────────────────┘
292       To get a list of supported attributes, invoke isnsadm --register help.
293
294   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
300       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
305       To obtain a list of supported attributes, invoke isnsadm --query help.
306
307   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
311       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
316       Possible type names are: entities, nodes, portals, dds, ddsets, portal-
317       groups, and policies.
318
319       Additional information is available via isnsadm --list help.
320
321   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
327       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
331   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
337       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
341   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
347       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
352   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
356       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
360       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
367       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
371       This is followed by a list of attribute/value pairs, where the  follow‐
372       ing set of attributes is supported:
373
374             ┌────────────┬─────────────────────────────────────────────┐
375AttributeDescription                     Aliases
376             ├────────────┼─────────────────────────────────────────────┤
377name        │ Policy Name                         spi     │
378key         │ Client's DSA public key                     │
379entity      │ Assigned Entity Identifier                  │
380node-type   │ Permitted node type(s)                      │
381node-name   │ Permitted node name(s)                      │
382functions   │ Bitmap of permitted functions               │
383object-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
393       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
399       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
403       For  a description of the open-isns security model and policies, please
404       refer to the isns_config(5) manual page.
405
406       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
412               openssl dsaparam 1024 -out /etc/isns/dsa.params
413
414       where 1024 is the chosen DSA key size, in bits.
415

EXAMPLES

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
421       isnsd --init
422
423       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
426       The  following  command  will  create  a policy object for a node named
427       isns.control , and grant it control privileges:
428
429       isnsadm --local --keyfile=control.key --enroll isns.control \
430                  node-type=ALL functions=ALL object-type=ALL
431
432       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
437       Next,  you need to create a storage node object for the management sta‐
438       tion:
439
440       isnsadm --local --register control
441
442       On the management station, you can then enroll additional hosts:
443
444       isnsadm --control --keyfile=somehost.key --enroll iqn.2005-01.org.open-
445       iscsi.somehost \
446                  node-type=target+initiator
447
448       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
453       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
458       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
463       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
467       To create a discovery domain, and add nodes to it, you can use
468
469       isnsadm --control --dd-register dd-name=mydomain \
470                  member-name=iqn.org.bozo.client iqn.org.bozo.jbod ...
471
472       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
476       isnsadm --control --dd-register dd-id=42 \
477                  member-name=iqn.com.foo member-name=iqn.com.bar
478
479       The DD ID can be obtained by doing a query for the DD name:
480
481       isnsadm --control --query dd-name=mydomain
482
483       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
488       isnsadm --control --register entity=client.bozo.org \
489                  initiator=iqn.org.bozo.client portal=191.168.7.1:860
490
491       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

SEE ALSO

497       RFC 4171, isnsd(8), isns_config(5).
498

AUTHORS

500       Olaf Kirch <olaf.kirch@oracle.com>
501
502
503
504                                  11 May 2007                       ISNSADM(8)
Impressum