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

NAME

       isns_config - iSNS configuration file

SYNOPSIS

       /etc/isns/isnsadm.conf
       /etc/isns/isnsd.conf
       /etc/isns/isnsdd.conf

DESCRIPTION

       All  Open-iSNS  utilities  read  their configuration from a file in /etc/isns.  There is a
       separate configuration file for each application, isnsd, isnsadm, and isnsdd.  The  syntax
       and  the  set  of supported options is identical, even though some options are specific to
       e.g. the server.  Unless indicated, options are applicable to all utilities.

       An Open-iSNS configuration file  contains  keyword-argument  pairs,  one  per  line.   All
       keywords are case insensitive.

       A  #  character introduces a comment, which extends until the end of the line. Empty lines
       are ignored.

       There are no line continuations, and you cannot use quotes around arguments.

       Some options specify timeout values, which are given in units of seconds by  default.  You
       can  specify  an  explicit  unit,  however, such as d (days), h (hours), m (minutes), or s
       (seconds).

   Generic Options
       HostName
              By default, Open-iSNS applications will retrieve the machine's hostname  using  the
              gethostname(3)  system  call,  and  use a DNS lookup to look up the canonical name.
              Using the HostName option, you can overried this. This option is rarely needed.

       SourceName
              This option is mandatory for all Open-iSNS applications.  This  should  be  a  name
              which  identifies  the  client  uniquely.   There are two readings of RFC 4171; one
              requires that this is an iSCSI qualified name such as iqn.2001-04.com.example.host,
              whereas  other  language in the RFC suggests that this is pretty much a free-format
              string that just has to be unique (using e.g. the client's fully  qualified  domain
              name).

              When  using  DSA  authentication,  Open-iSNS  currently requires the source name to
              match the key identifier (SPI) of the client's public key.

              If  left  empty,  the  source  name  is  derived  from  either  from  the   default
              initiatorname  in  /etc/iscsi/initiatorname.iscsi  or,  failing  that, the client's
              hostname using the IQNPrefix option to generate an iSCSI qualified name.

       IQNPrefix
              Specifies the iSCSI qualified name prefix; must be of  the  form  iqn.YYYY-MM  with
              YYYY being the year and MM the month.

       ServerAddress (client):
              This  options  specifies the host name or address of the iSNS server to talk to. It
              can optionally be followed by a colon, and a port number.

              Instead of a hostname, IPv4 or IPv6 addresses can  be  used.   In  order  to  avoid
              ambiguities,  literal  IPv6  addresses must be surrounded by square brackets, as in
              [2001:4e5f::1].

              When specifying a port number, you can use either the numeric  port,  or  a  string
              name  to  be  looked up in /etc/services.  When the port is omitted, it defaults to
              3205, the IANA assigned port number of iSNS.

              If the special string SLP: is used, the client will try to locate the  iSNS  server
              through SLP.

       SLPRegister (server):
              If set to 1, the iSNS daemon will register itself will the SLP service. This allows
              clients to contact the server without having to configure its address statically.

       PIDFile (server):
              This specifies the name of the server's PID file, which  is  /var/run/isnsd.pid  by
              default.

   Database Related Options
       These options apply to the iSNS server only, and control operation of the iSNS database.

       Database
              This  option  is  used  to  specify how the database is stored.  Setting this to an
              absolute path name will make isnsd keep its database in the specified directory.

              If you leave this empty, isnsd will keep its database in memory.  This is also  the
              default setting.

       DefaultDiscoveryDomain
              iSNS  scopes visibility of other nodes using so-called Discovery Domains. A storage
              node A will only "see" storage node B, if both are members of  the  same  discovery
              domain.

              So  if  a  storage node is registered which is not part of any discovery domain, it
              will not see any other nodes.

              By setting DefaultDiscoveryDomain=1,  you  can  tell  isnsd  to  create  a  virtual
              "default  discovery  domain",  which  holds  all  nodes  that  are  not part of any
              administratively configured discovery domain.

              By default, there is no default discovery domain.

       RegistrationPeriod
              The iSNS server can purge registered entities after a certain period of inactivity.
              This  is called the registration period.  Clients who register objects are supposed
              to refresh their registration within this period.

              The default value is 1 hour. Setting it to 0 disables expiry of entities  from  the
              database.

       ESIRetries
              Open-iSNS is able to monitor the reachability of storage nodes and their portals by
              using a protocol feature called ESI (Entity status inquiry).  Clients  request  ESI
              monitoring  by registering an ESI port along with each portal. The server will send
              ESI messages to these portals at regular intervals.  If the portal fails  to  reply
              several  times  in  a  row,  it  is  considered  dead, and will be removed from the
              database.

              ESIRetries specifies the maximum  number  of  attempts  the  server  will  make  at
              contacting  the  portal  before  pronouncing  it dead. If set to 0, the server will
              disable ESI and reject any registrations that specify an ESI  port  with  an  error
              code of "ESI not supported".

              The default value is 3.

       ESIMinInterval
              This timeout value specifies the minimum ESI interval.  If a client requests an ESI
              interval less than this value, it is silently rounded up.

              The default value is 60 seconds.

       ESIMaxInterval
              This timeout value specifies the maximum ESI interval.  If a client requests an ESI
              interval greater than this value, it is silently rounded down.

              The default value is 10 minutes.

              The maximum ESI interval must not exceed half the value of the registration period.

       SCNRetries
              iSNS  clients  can  register to receive State Change Notification (SCN) messages to
              learn about changes in the iSNS database.   This  value  specifies  how  often  the
              server will try to retransmit an SCN message until giving up.

              The default value is 3.

       SCNCallout
              This  is  the  path  name  of  a helper program that isnsdd will invoke whenever it
              processes a state change notification from the server. The helper program  will  be
              invoked with an argument indicating the type of event, being one of add, update, or
              remove.  This is followed by a list of attributes in name=value notation, using the
              names and conventions described in isnsadm(8).

   Security Related Options
       The   iSNS  standard  defines  an  authentication  method  based  on  the  DSA  algorithm.
       Participants in a message exchange authenticate  messages  by  adding  an  "authentication
       block" containing a time stamp, a string identifying the key used, and a digital signature
       of the message.  The same method is also used by SLP, the Service Location Protocol.

       The string contained in the authentication block is referred to  as  the  Security  Policy
       Index(SPI).   This  string can be used by the server to look up the client's public key by
       whatever mechanism; so the string could be used as the name of a  public  key  file  in  a
       directory, or to retrieve an X509 certificate from LDAP.

       From  the  perspective  of  Open-iSNS  client  applications,  there are only two keys: the
       client's own (private) key, used to sign the messages it sends  to  the  server,  and  the
       server's public key, used to verify the signatures of incoming server messages.

       The  iSNS  server  needs, in addition to its own private key, access to all public keys of
       clients that will communicate to it. The latter are kept in what is called  a  key  store.
       Key stores and their operation will be discussed in section Key Stores and Policy below.

       The following configuration options control authentication:

       Security
              This  enables  or disables DSA authentication.  When set to 1, the client will sign
              all messages, and expect all server messages to be signed.

              When enabling security in  the  server,  incoming  messages  are  checked  for  the
              presence  of  an  auth  block.  If  none is present, or if the server cannot find a
              public key corresponding to the SPI, the message is treated as originating from  an
              anonymous  source.  If the SPI is known but the signature is incorrect, the message
              is dropped silently.

              Messages from an anonymous source will be assigned a very restrictive  policy  that
              allows database queries only.

              Setting this option to 0 will turn off authentication.

              The  default  value  is  -1, which tells iSNS to use authentication if the required
              keys are installed, and use unauthenticated iSNS otherwise.

       AuthName
              This is the string that will be used as the SPI in all outgoing messages that  have
              an auth block. It defaults to the host name (please refer to option HostName).

       AuthKeyFile
              This is the path name of a file containing a PEM encoded DSA key.  This key is used
              to sign outgoing messages.  The default is /etc/isns/auth_key.

       ServerKeyFile
              This option is used by client applications only, and specifies the path name  of  a
              file  containing  a  PEM  encoded  DSA  key.   This key is used to authenticate the
              server's replies.  The default is /etc/isns/server_key.pub.

       KeyStore
              This server-side option specifies the key store  to  use,  described  in  the  next
              section.

       The  following  two  options  control how iSNS will verify the time stamp contained in the
       authentication block, which is supposed to prevent replay attacks.

       Auth.ReplayWindow
              In order to compensate for clock drift between two hosts exchanging iSNS  messages,
              Open-iSNS  will  apply a little fuzz when comparing the time stamp contained in the
              message to the local system time. If the difference between time  stamp  and  local
              system time is less than the number of seconds given by this option, the message is
              acceptable. Otherwise, it is rejected.

              The default value is 5m.

       Auth.TimestampJitter
              When verifying incoming messages, Open-iSNS checks that the time stamps sent by the
              peer  are  increasing  monotonically.  In order to compensate for the reordering of
              messages by the network (eg when using UDP as  transport),  a  certain  time  stamp
              jitter  is  accepted.  If the time stamp of an incoming messages is no earlier than
              TimestampJitter seconds before the last time stamp received, then  the  message  is
              acceptable.  Otherwise, it is rejected.

              The default value is 1s.

   Key Stores and Policy
       The current implementation supports two types of key stores.

       The simple key store uses a flat directory to store public keys, each key in a file of its
       own. The file is expected to hold the client's PEM-encoded public key, and it must use the
       client's  SPI  as  the name.  This type of key store is not really recommended, as it does
       not store any policy information.

       A simple key store can be configured by setting the KeyStore option to the  path  name  of
       the directory.

       The  recommended  approach  is to use the database as key store. This uses vendor-specific
       policy objects to tie SPI string, public key, entity name, source name and other  bits  of
       policy together, and store them in a persistent way.

       The  database key store is configured by setting the KeyStore option to the reserved value
       DB:, which is also the default.

       Currently, Open-iSNS policy objects have the following attributes, besides the SPI:

       Source:
              This is the source node name the client must use. It defaults to the SPI string.

       Functions:
              This is a bitmap detailing which functions the client is permitted to  invoke.  The
              bit  names  correspond to the shorthand names used in RFC 4171, such as DevAttrReg,
              DevAttrQry, etc. The default is to allow registration, query and deregistration, as
              well as SCNRegister.

       Entity name:
              This  is  the  entity  name  assigned  to the client. If set, a registration by the
              client is not permitted to use a different entity  name.  If  the  client  sends  a
              registration  without  Entity  identifier,  the  server will assign the entity name
              given in the policy.  The default is to not restrict the entity name.

       Object access:
              This is a bitfield describing access permissions for each object  type.   For  each
              object  type,  you can grant Read and/or Write permissions.  Read access applies to
              the Query and GetNext calls; all other operations require  write  permission.   The
              default  grants  read  and  write  access  to objects of type Entity, Storage Node,
              Portal and Portal Group; and read access to Discovery Domains.

       Node types:
              This bitfield describes which types  of  storage  nodes  a  client  is  allowed  to
              register; the valid bit names are target, initiator and control.  The default is to
              restrict nodes to register initiators only.

   Network Related Options
       Network.MaxSockets
              This is the number of incoming connections accepted, and  defaults  to  1024.  This
              usually  applies  to  server side only, but is relevant if you create a passive TCP
              socket for ESI or SCN.

       Network.ConnectTimeout
              This is a timeout value, which specifies the time to wait for a TCP  connection  to
              be established.  It defaults to 60s.

       Network.ReconnectTimeout
              When a connection attempt failed, we wait for a short time before we try connecting
              again. This is intended to take the pressure off overloaded  servers.  The  default
              value is 10s.

       Network.CallTimeout
              Total  amount  of  time  to  wait before timing out a call to the iSNS server.  The
              default value is 60s.

SEE ALSO

       RFC 4171, isnsd(8), isnsadm(8).

AUTHORS

       Olaf Kirch <olaf.kirch@oracle.com>

                                           11 May 2007                             ISNS_CONFIG(5)