Filewatcher File Search File Search
Catalog
Content Search
» » » » » » isns-utils-0.93-1.0.el6.x86_64.rpm » Content »
pkg://isns-utils-0.93-1.0.el6.x86_64.rpm:163916/usr/share/man/man8/  info  HEADER  downloads

isns-utils - The iSNS daemon and utility programs…  more info»

isnsadm.8.gz

ISNSADM(8)                                                ISNSADM(8)



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 [...]  --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 registra‐
       tion, 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 talk‐
              ing to the iSNS server. This can be used by the admin‐
              istrator  to  perform  management   tasks,   such   as
              enrolling  new  clients, editing access control and so
              on. Local mode is only available to the super user.

       --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   Con‐
       trol.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 pub‐
              lic part of the key is stored in a  policy  object  in
              the  iSNS  server's database, whereas the private por‐
              tion 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 sup‐
       ported  command modes, and exit. Specific help on an individ‐
       ual 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
       as  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:

      ┌───────────────────┬───────────────────────────────────────────┐
      │Context            │ Attribute              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 indica‐
       tion 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].          por‐
       tal=<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 sur‐
       rounded  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-read‐
       able 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 sepa‐
       rately.

       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 ini‐
              tiator.  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  tar‐
              get.   By  default, the name is set to the iSNS source
              name.

              This object accepts the same set of attributes as ini‐
              tiator.

       control[=name]
              This  will register an iSCSI storage node of type con‐
              trol.  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 ini‐
              tiator.

       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 dependant.

              This   can   be  followed  by  any  number  of  portal
              attributes.

       pg     This will register a portal group joining the  preced‐
              ing  portal  and  node.  Portal  groups can be used to
              describe the  preferred  portals  for  a  given  node;
              please refer to RFC 4711 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 net‐
       work 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   por‐
       tal=10.2.7.7:860

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

              ┌────────────┬─────────────────────┐
              │Object type │ Syntax              │
              ├────────────┼─────────────────────┤
              │Entity      │ eid=identifier      │
              │Portal      │ portal=address:port │
              │iSCSI Node  │ iscsi-name=name     │
              └────────────┴─────────────────────┘
       To  get a list of supported attributes, invoke isnsadm --reg‐
       ister 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  Net‐
       work  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  use‐
       ful 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  fol‐
       lowed  by  one or more attr=value pairs. Only attributes per‐
       taining 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 regis‐
       tered.  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 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.

   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  communi‐
              cate with the server through the local control socket.

       Invoke isnsadm  --control, which tells it to assume the iden‐
              tity 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 con‐
              figuration  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:

        ┌────────────┬─────────────────────────────────────────────┐
        │Attribute   │ Description                     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 sep‐
       arated  list  of  type:perm  pairs,  where type can be any of
       entity, iscsi-node, portal, portal-group, dd, ddset, and pol‐
       icy.  The permissions can be either rw, or r.

       The  functions  attribute can be used to restrict which func‐
       tions 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  poli‐
       cies, 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 parame‐
       ters 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,  respec‐
       tively.

       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/con‐
       trol.key  on  the  host you wish to use as an iSNS management
       station.

       Next, you need to create a storage node object for  the  man‐
       agement 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 pri‐
       vate 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  spec‐
       ify  the  numeric domain ID - using the DD name is not suffi‐
       cient, 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 regis‐
       ter a node and portal on a host named client.bozo.org:

       isnsadm --control --register entity=client.bozo.org \
                          initiator=iqn.org.bozo.client         por‐
       tal=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)
Results 1 - 1 of 1
Help - FTP Sites List - Software Dir.
Search over 15 billion files
© 1997-2017 FileWatcher.com