path: root/utils/open-isns/doc/isns_config.5

.TH ISNS_CONFIG 8 "11 May 2007"
.SH NAME
isns_config - iSNS configuration file
.SH SYNOPSIS
.B /etc/isns/isnsadm.conf
.br
.B /etc/isns/isnsd.conf
.br
.B /etc/isns/isnsdd.conf

.SH DESCRIPTION
All Open-iSNS utilities read their configuration
from a file in
.BR /etc/isns .
There is a separate configuration file for each application,
.BR 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.
.PP
An Open-iSNS configuration file contains keyword-argument pairs,
one per line.  All keywords are case insensitive.
.PP
A 
.B #
character introduces a comment, which extends until the
end of the line. Empty lines are ignored.
.PP
There are no line continuations, and you cannot use quotes
around arguments.
.PP
Some options specify timeout values, which are given in
units of seconds by default. You can specify an explicit
unit, however, such as
.BR d " (days),
.BR h " (hours),
.BR m " (minutes), or
.BR s " (seconds).
.\" ------------------------------------------------------------------
.SS Generic Options
.TP
.BR HostName
By default, Open-iSNS applications will retrieve the machine's
hostname using the
.BR gethostname (3)
system call, and use a DNS lookup to look up the canonical name.
Using the
.BR HostName
option, you can overried this. This option is rarely needed.
.TP
.BR 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
.BR 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).
.IP
When using DSA authentication, Open-iSNS currently requires the source
name to match the key identifier (SPI) of the client's public
key.
.IP
If left empty, the source name is derived from the client's hostname.
.TP
.BR 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.
.IP
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
.BR [2001:4e5f::1] .
.IP
When specifying a port number, you can use either the
numeric port, or a string name to be looked up in
.BR /etc/services .
When the port is omitted, it defaults to 3205, the IANA
assigned port number of iSNS.
.IP
If the special string
.B SLP:
is used, the client will try to locate the iSNS server
through SLP.
.TP
.BR 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.
.TP
.BR PIDFile " (server):
This specifies the name of the server's PID file, which is
.B /var/run/isnsd.pid
by default.
.\" ------------------------------------------------------------------
.SS Database Related Options
These options apply to the iSNS server only, and control operation
of the iSNS database.
.TP
.BR Database
This option is used to specify how the database is stored.
Setting this to an absolute path name will make
.B isnsd
keep its database in the specified directory.
.IP
If you leave this empty,
.B isnsd
will keep its database in memory.
This is also the default setting.
.TP
.BR 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.
.IP
So if a storage node is registered which is not part of
any discovery domain, it will not see any other nodes.
.IP
By setting
.BR 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.
.IP
By default, there is no default discovery domain.
.TP
.BR 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.
.IP
The default value is 1 hour. Setting it to 0 disables expiry
of entities from the database.
.TP
.BR 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.
.IP
.B 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".
.IP
The default value is 3.
.TP
.BR 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.
.IP
The default value is 60 seconds.
.TP
.BR 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.
.IP
The default value is 10 minutes.
.IP
The maximum ESI interval must not exceed half the value
of the registration period.
.TP
.B 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.
.IP
The default value is 3.
.TP
.B SCNCallout
This is the path name of a helper program that
.B 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
.BR add ", " update ", or " remove .
This is followed by a list of attributes in 
.IB name = value
notation, using the names and conventions described in
.BR isnsadm (8).
.\" ------------------------------------------------------------------
.SS 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.
.PP
The string contained in the authentication block is referred to
as the
.IR "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.
.PP
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.
.PP
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
.B Key Stores and Policy
below.
.PP
The following configuration options control authentication:
.TP
.BR 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.
.IP
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.
.IP
Messages from an anonymous source will be assigned a very restrictive
policy that allows database queries only.
.IP
Setting this option to 0 will turn off authentication.
.IP
The default value is -1, which tells iSNS to use authentication
if the required keys are installed, and use unauthenticated iSNS
otherwise.
.TP
.BR 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
.BR HostName ).
.TP
.BR 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
.BR /etc/isns/auth_key .
.TP
.BR 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
.BR /etc/isns/server_key.pub .
.TP
.BR KeyStore
This server-side option specifies the key store to use,
described in the next section.
.PP
The following two options control how iSNS will verify the
time stamp contained in the authentication block, which
is supposed to prevent replay attacks.
.TP
.B 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.
.IP
The default value is
.BR 5m .
.TP
.B 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
.B TimestampJitter
seconds before the last time stamp received, then the message is acceptable.
Otherwise, it is rejected.
.IP
The default value is
.BR 1s .
.\" ------------------------------------------------------------------
.SS Key Stores and Policy
The current implementation supports two types of key stores.
.PP
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.
.PP
A simple key store can be configured by setting the
.B KeyStore
option to the path name of the directory.
.PP
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.
.PP
The database key store is configured by setting the
.B KeyStore
option to the reserved value
.BR DB: ,
which is also the default.
.PP
Currently, Open-iSNS policy objects have the following attributes,
besides the SPI:
.TP
Source:
This is the source node name the client must use. It defaults to
the SPI string.
.TP
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 4711, such as
.BR DevAttrReg ,
.BR DevAttrQry ,
etc. The default is to allow registration, query and deregistration,
as well as SCNRegister.
.TP
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.
.TP
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.
.TP
Node types:
This bitfield describes which types of storage nodes a client is
allowed to register; the valid bit names are
.BR target ", " initiator " and " control .
The default is to restrict nodes to register initiators only.
.\" ------------------------------------------------------------------
.SS Network Related Options
.TP
.BR 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.
.TP
.BR Network.ConnectTimeout
This is a timeout value, which specifies the time to wait for a TCP
connection to be established.  It defaults to
.BR 60s .
.TP
.BR 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
.BR 10s .
.TP
.BR Network.CallTimeout
Total amount of time to wait before timing out a call to the iSNS server.
The default value is
.BR 60s .
.\" ------------------------------------------------------------------
.SH SEE ALSO
RFC 4171,
.BR isnsd (8),
.BR isnsadm (8).
.SH AUTHORS
Olaf Kirch <olaf.kirch@oracle.com>