bionic (8) isnsadm.8.gz

Provided by: open-isns-utils_0.97-2build1_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)