|
|
| |
ISNS_CONFIG(5) |
FreeBSD File Formats Manual |
ISNS_CONFIG(5) |
isns_config - iSNS configuration file
/etc/isns/isnsadm.conf
/etc/isns/isnsd.conf
/etc/isns/isnsdd.conf
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).
- 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.
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).
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.
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.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.
RFC 4171, isnsd(8), isnsadm(8).
Olaf Kirch <olaf.kirch@oracle.com>
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |