bionic (5) isnsdd.conf.5.gz

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