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