Provided by: open-isns-utils_0.101-0.3build3_amd64 bug

NAME

       isnsadm - iSNS client utility

SYNOPSIS

       isnsadm [options...]  --register object...

       isnsadm [...]  --query attr[=value]

       isnsadm [...]  --deregister attr=value

       isnsadm [...]  --list type attr=value

       isnsadm [...]  --dd-register attr=value

       isnsadm [...]  --dd-deregister dd-id attr=value

       isnsadm [...]  --enroll client-name attr=value

       isnsadm [...]  --edit-policy attr=value

DESCRIPTION

       Isnsadm  is a command line utility for interacting with an iSNS server. It operates in one
       of several modes, which are mutually exclusive.  Currently, isnsadm supports registration,
       query, and deregistration.

OPTIONS

       By  default,  isnsadm  will  take  most  of  its  settings  from  the  configuration  file
       /etc/isns/isnsadm.conf, with the exception of the following options:

       --config filename, -c filename
              This option overrides the default configuration file.

       --debug facility, -d facility
              enables debugging. Valid facilities are

                    ┌────────┬─────────────────────────────────────────────────────┐
                    │socket  │ network send/receive                                │
                    │auth    │ authentication and security related information     │
                    │message │ iSNS protocol layer                                 │
                    │state   │ database state                                      │
                    │scn     │ SCN (state change notification) messages            │
                    │esi     │ ESI (entity status inquiry) messages                │
                    │all     │ all of the above                                    │
                    └────────┴─────────────────────────────────────────────────────┘
       --local
              makes isnsadm use a Local (aka Unix) socket when talking to the iSNS  server.  This
              can be used by the administrator to perform management tasks, such as enrolling new
              clients, editing access control and so on. Local mode  is  only  available  to  the
              super user.

       --server servername, -s servername
              specifies the server to use (if not specified in the configuration file).

       --control
              makes  isnsadm  assume the identity of a control node. Control nodes are special in
              that they have more rights in accessing and  modifying  the  database  than  normal
              storage nodes have.

       When  using  this  option,  isnsadm  will use the source name and DSA key specified by the
       Control.SourceName and Control.AuthKeyFile configuration options, respectively.

       --key attr=value
              This option is recognized in registration mode only, and lets you specify an object
              key. For a more detailed explanation, refer to section Registration mode.

       --keyfile=filename
              When creating a policy for a new iSNS client, isnsadm is able to generate a DSA key
              for the client. The public part of the key is stored in a policy object in the iSNS
              server's  database,  whereas the private portion is stored in the file specified by
              the keyfile option.

       --help This will print a help message and exit.

   Built-in help
       Isnsadm has built-in help functions. When invoked with --help, it  will  print  a  general
       help message showing all supported command modes, and exit. Specific help on an individual
       command mode is available by invoking that mode with a single argument of help, like this:

       isnsadm --register help

       This will print a help message describing how to use this command mode, followed by a list
       of attributes this command supports and a help text describing the attribute.

   Supported attributes
       Most  command modes take a list of attributes as arguments on the command line. The naming
       and syntax of these attributes are the same for all commands modes, however certain  modes
       support only a limited set of attributes.

       Attributes  are  usually  given  as  name=value pairs. Where empty (or NIL) attributes are
       supported, the attribute name by itself can be given.

       The syntax of attribute value depends on the  attribute  type.  For  strings  and  numeric
       values, no special conventions apply, but bitfields have a special syntax described below.

       The  attribute name is usually preceded by the object type it applies to (such as entity),
       followed by a hyphen and the name itself. However, where the context clearly determines  a
       specific  object  type,  the  prefix  can  be omitted. For instance, when editing a policy
       object using --edit-policy, it is acceptable to use node-type  as  shorthand  for  policy-
       node-type.

       Likewise,  in a query command, it is not permitted to mix attributes from different object
       types. Thus, the first attribute of a query string establishes a type context, so that the
       following two invocations are equivalent:

       isnsadm --query pg-name=iqn.com.foo pg-addr=10.1.1.1 pg-port=860/tcp
       isnsadm --query pg-name=iqn.com.foo addr=10.1.1.1 port=860/tcp

       Isnsadm currently supports the following attributes:

                    ┌───────────────────┬───────────────────────────────────────────┐
                    │ContextAttribute              iSNS tag   Aliases │
                    ├───────────────────┼───────────────────────────────────────────┤
                    │Network Entity     │ entity-id                     1   eid     │
                    │                   │ entity-prot                   2           │
                    │                   │ entity-index                  7           │
                    │iSCSI Storage Node │ iscsi-name                   32           │
                    │                   │ iscsi-node-type              33           │
                    │                   │ iscsi-alias                  34           │
                    │                   │ iscsi-idx                    36           │
                    │                   │ iscsi-authmethod             42           │
                    │Portal             │ portal-addr                  16           │
                    │                   │ portal-port                  17           │
                    │                   │ portal-name                  18           │
                    │                   │ portal-esi-port              20           │
                    │                   │ portal-esi-interval          21           │
                    │                   │ portal-idx                   22           │
                    │                   │ portal-scn-port              23           │
                    │Portal Group       │ portal-group-index           52           │
                    │                   │ pg-name                      48           │
                    │                   │ pg-addr                      49           │
                    │                   │ pg-port                      50           │
                    │                   │ pg-tag                       51   pgt     │
                    │                   │ pg-idx                       52           │
                    │Discovery Domain   │ dd-id                      2065           │
                    │                   │ dd-name                    2066           │
                    │                   │ dd-member-iscsi-idx        2067           │
                    │                   │ dd-member-name             2068           │
                    │                   │ dd-member-fc-name          2069           │
                    │                   │ dd-member-portal-idx       2070           │
                    │                   │ dd-member-addr             2071           │
                    │                   │ dd-member-port             2072           │
                    │                   │ dd-features                2078           │
                    │Policy Object      │ policy-name                   -   spi     │
                    │                   │ policy-key                    -           │
                    │                   │ policy-entity                 -           │
                    │                   │ policy-node-type              -           │
                    │                   │ policy-object-type            -           │
                    │                   │ policy-functions              -           │
                    └───────────────────┴───────────────────────────────────────────┘
   Portal attributes
       Portal  information  is  conveyed by two separate attributes in iSNS; an address attribute
       holding the IP address, and a TCP/UDP port  attribute  holding  the  port  number  and  an
       indication of the protocol to be used (TCP or UDP).

       When parsing a TCP/UDP port, Open-iSNS will expect a port number, optionally followed by a
       slash and the protocol. Port names such as "iscsi-target" are not supported.

       As a convenience, isnsadm supports  a  notation  representing  a  portal  as  one  pseudo-
       attribute.   Separating  address  and  port  by  a  colon.  Thus,  the  following  two are
       equivalent, with the latter being the shorthand representation of the former:

       addr=<address> port=<port>[/protocol].  portal=<adress>:port[/protocol]

       This notation can be used in any context where an addr/port attribute pair can appear, and
       may be prefixed by a type name, as in pg-portal=....

       When  using  literal  IPv6 addresses, the address has to be surrounded by square brackets,
       otherwise the embedded colons would create ambiguity: portal=[2001:5c0:0:2::24]:860/tcp

   Bitfield attributes
       Some iSNS attributes are words representing a bit  field.   Isnsadm  displays  and  parses
       these  attributes  in human-readable form rather than using the numerical value. The names
       of the bit values are displayed by built-in help facilities. When  specifying  a  bitfield
       attribute  on  the  command  line,  you  can  combine them using the plus (+) or comma (,)
       character, like this:

       node-type=control+initiator

   Registration mode
       Registration mode is selected by using the --register option, followed by a list of one or
       more  objects  to  register  with the iSNS server.  By default, this will create a network
       entity for the client (if none exists), and place the new objects inside it.  Usually, you
       register  all  objects  for  a  network  entity  in  one  operation,  rather than each one
       separately.

       Each object is specified as a type, optionally  followed  by  a  comma-separated  list  of
       attributes, such as this:

       target=iqn.2005-01.org.open-iscsi.foo:disk1,alias=disk1

       The following object types are currently supported:

       entity=name
              Tells  the  server  to  group all objects in the specified Network Entity container
              object.  Normally, the iSNS server will automatically assign an entity name that is
              in line with its policies, and there is no need to specify it explicitly.

       initiator[=name]
              This  will  register an iSCSI storage node of type initiator.  By default, the name
              is set to the iSNS source name.

              This can be followed by any number of iSCSI storage node attributes.

       target[=name]
              This will register an iSCSI storage node of type target.  By default, the  name  is
              set to the iSNS source name.

              This object accepts the same set of attributes as initiator.

       control[=name]
              This  will register an iSCSI storage node of type control.  By default, the name is
              set to the iSNS source name.  Only management nodes should be registered as control
              nodes, as this gives a node complete control over the iSNS database.

              This object accepts the same set of attributes as initiator.

       portal=[address:port/proto]
              This  will  register a portal using the given address, port and protocol triple. If
              the triple is omitted, isnsadm will use the client host's IP address. If the portal
              is  preceded  by an initiator registration (on the command line), the port defaults
              to 860/tcp; if it is preceded by  a  target  registration,  the  port  defaults  to
              3260/tcp.    For  multi-homed  hosts,  the  choice  of  address  is  implementation
              dependent.

              This can be followed by any number of portal attributes.

       pg     This will register a portal group joining the preceding  portal  and  node.  Portal
              groups can be used to describe the preferred portals for a given node; please refer
              to RFC 4171 for details.

              This can be followed by any number of portal group attributes.  The attribute  list
              must specify a portal group tag (PGT) via the pgt attribute.

       There are two additional command line options of interest, which are used exclusively with
       Registration mode. One is --replace.  Normally, registration mode will add new objects  to
       the  network  entity  associated  with  the  client  host. If you specify --replace on the
       command line, the server will wipe the network entity completely, and remove  all  portals
       and  storage  nodes  it contained. Then it will create a new network entity, and place the
       portals and storage nodes provided by the caller inside.

       In addition, it is possible to replace just parts of a network entity. This is achieved by
       using the command line option --key to specify the object that should be replaced.

       For  instance,  assume a network entity contains the portal 10.1.1.1:860, and the client's
       network address changed to 10.2.7.7.  Then the following command  will  atomically  update
       the database, replacing just the portal without touching the registered storage nodes:

         isnsadm --replace --key portal=10.1.1.1:860 portal=10.2.7.7:860

       The --key option recognizes only a subset of the usual attributes:

              ┌────────────┬─────────────────────┐
              │Object typeSyntax              │
              ├────────────┼─────────────────────┤
              │Entityeid=identifier      │
              │Portalportal=address:port │
              │iSCSI Nodeiscsi-name=name     │
              └────────────┴─────────────────────┘
       To get a list of supported attributes, invoke isnsadm --register help.

   Query mode
       Query  mode  is  selected  by  using  the  --query  option.  A query consists of a list of
       attr=value pairs. All attributes must belong to the same object type,  i.e.  queries  that
       mix a Network Entity attribute with e.g.  a Portal attribute will be rejected.

       It  is  also  possible  to specify an attribute name without value (i.e. just attr), which
       will will match any object that has such an attribute, regardless of its  value.  This  is
       useful when you want to query for all objects of a given type.

       To obtain a list of supported attributes, invoke isnsadm --query help.

   List Mode
       In  this  mode, isnsadm will display all objects of a given type, optionally restricted to
       those matching certain attribute values.

       The arguments to list mode are a type name, optionally followed by one or more  attr=value
       pairs.  Only  attributes  pertaining to the given type are permitted; for instance, if you
       specify a type name of portals, only portal attributes are permitted.

       Possible type names  are:  entities,  nodes,  portals,  dds,  ddsets,  portal-groups,  and
       policies.

       Additional information is available via isnsadm --list help.

   Deregistration mode
       In  this  mode,  you  can  deregister  objects previously registered.  Only the node which
       registered an entity in the first place is permitted to remove it, or  any  of  its  child
       objects. (Control nodes are not bound by this restriction).

       In  deregistration  mode,  the  argument  list  consists  of  a  list of attr=value pairs.
       Deregistration supports the same set of attributes as query mode.

   Discovery Domain Registration
       This mode allows one to register a discovery domain or to add new members to  an  existing
       discovery  domain.  Again,  attributes  are  specified as a list of attr=value pairs. Only
       discovery domain attributes are recognized.

       Note, in order to add members to an existing domain, you must specify the domain's numeric
       ID. The domain's symbolic name is not a valid handle when referring to a discovery domain.

   Discovery Domain Deregistration mode
       In  this  mode, you can deregister a discoery domain previously registered.  Only the node
       which registered a discovery domain in the first place is permitted to remove it,  or  any
       of its members. (Control nodes are not bound by this restriction).

       In  Discovery  Domain  deregistration  mode,  the  argument list consists of the Discovery
       Domain ID, followed by  a  list  of  attr=value  pairs.  Discovery  Domain  Deregistration
       supports the same set of attributes as query mode.

   Client Enrollment
       This  mode  only  works  when  the  server  recognizes  the  client as having control node
       capabilities, which is possible in two ways:

       Invoke isnsadm --local as super user on the host isnsd is running on. The --local  options
              tells it to communicate with the server through the local control socket.

       Invoke isnsadm  --control,  which tells it to assume the identity of a control node.  When
              given this option, isnsadm will use the source name and DSA key  specified  by  the
              Control.SourceName  and  Control.AuthKeyFile  configuration  options, respectively.
              The server must be configured to grant this identity control node status.

       To enroll a client, use the --enroll option, followed by the (source) name of  the  client
       to  enroll.   This  string will be used as the name of the security policy the client will
       use to identify itself.

       This is followed by a list of attribute/value pairs, where the following set of attributes
       is supported:

                      ┌────────────┬─────────────────────────────────────────────┐
                      │AttributeDescription                     Aliases     │
                      ├────────────┼─────────────────────────────────────────────┤
                      │name        │ Policy Name                         spi     │
                      │key         │ Client's DSA public key                     │
                      │entity      │ Assigned Entity Identifier                  │
                      │node-type   │ Permitted node type(s)                      │
                      │node-name   │ Permitted node name(s)                      │
                      │functions   │ Bitmap of permitted functions               │
                      │object-type │ Object access mask                          │
                      └────────────┴─────────────────────────────────────────────┘
       The  key  attribute  is  used  to specify the DSA public key that the server should use to
       authenticate messages from this client. You can either provide a file name; in which  case
       isnsadm  will  try to read the PEM encoded public key from that file.  If no key attribute
       is given, or when using key=gen, isnsadm will generate a DSA key. The private  portion  of
       the newly generated key will be stored in the file specified by --keyfile=filename.

       The object-type attribute is used to specify which object types the client is permitted to
       access. This is a comma separated list of type:perm  pairs,  where  type  can  be  any  of
       entity,  iscsi-node,  portal, portal-group, dd, ddset, and policy.  The permissions can be
       either rw, or r.

       The functions attribute can be used to restrict which functions the client is permitted to
       invoke.  This  is  a  bitfield,  using  the standard function names from RFC 4171, such as
       DevAttrReg, DevAttrQry, etc.

       For a description of the open-isns security  model  and  policies,  please  refer  to  the
       isns_config(5) manual page.

       Important  note:  In order to generate a DSA key, you have to have a set of DSA parameters
       installed. By default, isnsadm  expects  to  find  them  in  /etc/isns/dsa.params.   These
       parameters  are created by calling isnsd --init once on the server machine. Alternatively,
       you can use the following command:

               openssl dsaparam 1024 -out /etc/isns/dsa.params

       where 1024 is the chosen DSA key size, in bits.

EXAMPLES

       If you want to use Open-iSNS in authenticated mode,  you  first  need  to  initialize  the
       server's DSA key and DSA parameters. This can be done conveniently by using

       isnsd --init

       This will create the server's private and public key, and place them in /etc/isns/auth_key
       and auth_key.pub, respectively.

       The following command will create a policy object for a  node  named  isns.control  ,  and
       grant it control privileges:

       isnsadm --local --keyfile=control.key --enroll isns.control \
                  node-type=ALL functions=ALL object-type=ALL

       In  the process of entrolling the client, this will generate a DSA key pair, and place the
       private  key  portion  in  the  file  control.key.   This  file  must  be   installed   as
       /etc/isns/control.key on the host you wish to use as an iSNS management station.

       Next, you need to create a storage node object for the management station:

       isnsadm --local --register control

       On the management station, you can then enroll additional hosts:

       isnsadm --control --keyfile=somehost.key --enroll iqn.2005-01.org.open-iscsi.somehost \
                  node-type=target+initiator

       Again,  this  will  generate a DSA key pair and store the private key portion in auth_key.
       Note the use of the --control option that tells isnsadm to use the identity of the control
       node instead of the default key and source name.

       You   then   need   to   copy   somehost.key   to  the  client  host  and  install  it  as
       /etc/isns/auth_key.    Likewise,   the   server's   public   key   (which    resides    in
       /etc/isns/auth_key.pub on the server) needs to be copied to the client machine, and placed
       in /etc/isns/server_key.pub.

       By default, when a client registers a storage node (be it initiator or target) with  iSNS,
       the  client  will  not  be able to see any other storage nodes. In order for targets to be
       visible to a given initiator, you need to create so-called Discovery Domains (or  DDs  for
       short).

       Currently, domain membership operations require administrator privilege. Future extensions
       may allow iSNS clients to add themselves to one or more DDs upon registration.

       To create a discovery domain, and add nodes to it, you can use

       isnsadm --control --dd-register dd-name=mydomain \
                  member-name=iqn.org.bozo.client iqn.org.bozo.jbod ...

       In order to add members to an existing DD, you have to specify the  numeric  domain  ID  -
       using  the DD name is not sufficient, unfortunately (this is a requirement of the RFC, not
       an implementation issue):

       isnsadm --control --dd-register dd-id=42 \
                  member-name=iqn.com.foo member-name=iqn.com.bar

       The DD ID can be obtained by doing a query for the DD name:

       isnsadm --control --query dd-name=mydomain

       In management mode, you can also register and deregister nodes and  portals  manually,  in
       case  you want to fix up an inconsisteny in the database. For instance, this will register
       a node and portal on a host named client.bozo.org:

       isnsadm --control --register entity=client.bozo.org \
                  initiator=iqn.org.bozo.client portal=191.168.7.1:860

       Note that this registration explicitly specifies the network entity in which to place  the
       new  objects. If you omit this, the new objects will be placed in an entity named CONTROL,
       which is decidedly not what you want.

SEE ALSO

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

AUTHORS

       Olaf Kirch <olaf.kirch@oracle.com>

                                           11 May 2007                                 ISNSADM(8)