1ISNS_CONFIG(5) File Formats Manual ISNS_CONFIG(5)
2
6 isns_config - iSNS configuration file
7
9 /etc/isns/isnsadm.conf
10 /etc/isns/isnsd.conf
11 /etc/isns/isnsdd.conf
12
15 All Open-iSNS utilities read their configuration from a file in
16 /etc/isns. There is a separate configuration file for each applica‐
17 tion, isnsd, isnsadm, and isnsdd. The syntax and the set of supported
18 options is identical, even though some options are specific to e.g. the
19 server. Unless indicated, options are applicable to all utilities.
20 An Open-iSNS configuration file contains keyword-argument pairs, one
22 per line. All keywords are case insensitive.
23 A # character introduces a comment, which extends until the end of the
25 line. Empty lines are ignored.
26 There are no line continuations, and you cannot use quotes around argu‐
28 ments.
29 Some options specify timeout values, which are given in units of sec‐
31 onds by default. You can specify an explicit unit, however, such as d
32 (days), h (hours), m (minutes), or s (seconds).
33 Generic Options
35 HostName
36 By default, Open-iSNS applications will retrieve the machine's
37 hostname using the gethostname(3) system call, and use a DNS
38 lookup to look up the canonical name. Using the HostName
39 option, you can overried this. This option is rarely needed.
40 SourceName
42 This option is mandatory for all Open-iSNS applications. This
43 should be a name which identifies the client uniquely. There
44 are two readings of RFC 4171; one requires that this is an iSCSI
45 qualified name such as iqn.2001-04.com.example.host, whereas
46 other language in the RFC suggests that this is pretty much a
47 free-format string that just has to be unique (using e.g. the
48 client's fully qualified domain name).
49 When using DSA authentication, Open-iSNS currently requires the
51 source name to match the key identifier (SPI) of the client's
52 public key.
53 If left empty, the source name is derived from either from the
55 default initiatorname in /etc/iscsi/initiatorname.iscsi or,
56 failing that, the client's hostname using the IQNPrefix option
57 to generate an iSCSI qualified name.
58 IQNPrefix
60 Specifies the iSCSI qualified name prefix; must be of the form
61 iqn.YYYY-MM with YYYY being the year and MM the month.
62 ServerAddress (client):
64 This options specifies the host name or address of the iSNS
65 server to talk to. It can optionally be followed by a colon, and
66 a port number.
67 Instead of a hostname, IPv4 or IPv6 addresses can be used. In
69 order to avoid ambiguities, literal IPv6 addresses must be sur‐
70 rounded by square brackets, as in [2001:4e5f::1].
71 When specifying a port number, you can use either the numeric
73 port, or a string name to be looked up in /etc/services. When
74 the port is omitted, it defaults to 3205, the IANA assigned port
75 number of iSNS.
76 If the special string SLP: is used, the client will try to
78 locate the iSNS server through SLP.
79 SLPRegister (server):
81 If set to 1, the iSNS daemon will register itself will the SLP
82 service. This allows clients to contact the server without hav‐
83 ing to configure its address statically.
84 PIDFile (server):
86 This specifies the name of the server's PID file, which is
87 /var/run/isnsd.pid by default.
88 Database Related Options
90 These options apply to the iSNS server only, and control operation of
91 the iSNS database.
92 Database
94 This option is used to specify how the database is stored. Set‐
95 ting this to an absolute path name will make isnsd keep its
96 database in the specified directory.
97 If you leave this empty, isnsd will keep its database in memory.
99 This is also the default setting.
100 DefaultDiscoveryDomain
102 iSNS scopes visibility of other nodes using so-called Discovery
103 Domains. A storage node A will only "see" storage node B, if
104 both are members of the same discovery domain.
105 So if a storage node is registered which is not part of any dis‐
107 covery domain, it will not see any other nodes.
108 By setting DefaultDiscoveryDomain=1, you can tell isnsd to cre‐
110 ate a virtual "default discovery domain", which holds all nodes
111 that are not part of any administratively configured discovery
112 domain.
113 By default, there is no default discovery domain.
115 RegistrationPeriod
117 The iSNS server can purge registered entities after a certain
118 period of inactivity. This is called the registration period.
119 Clients who register objects are supposed to refresh their reg‐
120 istration within this period.
121 The default value is 1 hour. Setting it to 0 disables expiry of
123 entities from the database.
124 ESIRetries
126 Open-iSNS is able to monitor the reachability of storage nodes
127 and their portals by using a protocol feature called ESI (Entity
128 status inquiry). Clients request ESI monitoring by registering
129 an ESI port along with each portal. The server will send ESI
130 messages to these portals at regular intervals. If the portal
131 fails to reply several times in a row, it is considered dead,
132 and will be removed from the database.
133 ESIRetries specifies the maximum number of attempts the server
135 will make at contacting the portal before pronouncing it dead.
136 If set to 0, the server will disable ESI and reject any regis‐
137 trations that specify an ESI port with an error code of "ESI not
138 supported".
139 The default value is 3.
141 ESIMinInterval
143 This timeout value specifies the minimum ESI interval. If a
144 client requests an ESI interval less than this value, it is
145 silently rounded up.
146 The default value is 60 seconds.
148 ESIMaxInterval
150 This timeout value specifies the maximum ESI interval. If a
151 client requests an ESI interval greater than this value, it is
152 silently rounded down.
153 The default value is 10 minutes.
155 The maximum ESI interval must not exceed half the value of the
157 registration period.
158 SCNRetries
160 iSNS clients can register to receive State Change Notification
161 (SCN) messages to learn about changes in the iSNS database.
162 This value specifies how often the server will try to retransmit
163 an SCN message until giving up.
164 The default value is 3.
166 SCNCallout
168 This is the path name of a helper program that isnsdd will
169 invoke whenever it processes a state change notification from
170 the server. The helper program will be invoked with an argument
171 indicating the type of event, being one of add, update, or
172 remove. This is followed by a list of attributes in name=value
173 notation, using the names and conventions described in
174 isnsadm(8).
175 Security Related Options
177 The iSNS standard defines an authentication method based on the DSA
178 algorithm. Participants in a message exchange authenticate messages by
179 adding an "authentication block" containing a time stamp, a string
180 identifying the key used, and a digital signature of the message. The
181 same method is also used by SLP, the Service Location Protocol.
182 The string contained in the authentication block is referred to as the
184 Security Policy Index(SPI). This string can be used by the server to
185 look up the client's public key by whatever mechanism; so the string
186 could be used as the name of a public key file in a directory, or to
187 retrieve an X509 certificate from LDAP.
188 From the perspective of Open-iSNS client applications, there are only
190 two keys: the client's own (private) key, used to sign the messages it
191 sends to the server, and the server's public key, used to verify the
192 signatures of incoming server messages.
193 The iSNS server needs, in addition to its own private key, access to
195 all public keys of clients that will communicate to it. The latter are
196 kept in what is called a key store. Key stores and their operation will
197 be discussed in section Key Stores and Policy below.
198 The following configuration options control authentication:
200 Security
202 This enables or disables DSA authentication. When set to 1, the
203 client will sign all messages, and expect all server messages to
204 be signed.
205 When enabling security in the server, incoming messages are
207 checked for the presence of an auth block. If none is present,
208 or if the server cannot find a public key corresponding to the
209 SPI, the message is treated as originating from an anonymous
210 source. If the SPI is known but the signature is incorrect, the
211 message is dropped silently.
212 Messages from an anonymous source will be assigned a very
214 restrictive policy that allows database queries only.
215 Setting this option to 0 will turn off authentication.
217 The default value is -1, which tells iSNS to use authentication
219 if the required keys are installed, and use unauthenticated iSNS
220 otherwise.
221 AuthName
223 This is the string that will be used as the SPI in all outgoing
224 messages that have an auth block. It defaults to the host name
225 (please refer to option HostName).
226 AuthKeyFile
228 This is the path name of a file containing a PEM encoded DSA
229 key. This key is used to sign outgoing messages. The default
230 is /etc/isns/auth_key.
231 ServerKeyFile
233 This option is used by client applications only, and specifies
234 the path name of a file containing a PEM encoded DSA key. This
235 key is used to authenticate the server's replies. The default
236 is /etc/isns/server_key.pub.
237 KeyStore
239 This server-side option specifies the key store to use,
240 described in the next section.
241 The following two options control how iSNS will verify the time stamp
243 contained in the authentication block, which is supposed to prevent
244 replay attacks.
245 Auth.ReplayWindow
247 In order to compensate for clock drift between two hosts
248 exchanging iSNS messages, Open-iSNS will apply a little fuzz
249 when comparing the time stamp contained in the message to the
250 local system time. If the difference between time stamp and
251 local system time is less than the number of seconds given by
252 this option, the message is acceptable. Otherwise, it is
253 rejected.
254 The default value is 5m.
256 Auth.TimestampJitter
258 When verifying incoming messages, Open-iSNS checks that the time
259 stamps sent by the peer are increasing monotonically. In order
260 to compensate for the reordering of messages by the network (eg
261 when using UDP as transport), a certain time stamp jitter is
262 accepted. If the time stamp of an incoming messages is no ear‐
263 lier than TimestampJitter seconds before the last time stamp
264 received, then the message is acceptable. Otherwise, it is
265 rejected.
266 The default value is 1s.
268 Key Stores and Policy
270 The current implementation supports two types of key stores.
271 The simple key store uses a flat directory to store public keys, each
273 key in a file of its own. The file is expected to hold the client's
274 PEM-encoded public key, and it must use the client's SPI as the name.
275 This type of key store is not really recommended, as it does not store
276 any policy information.
277 A simple key store can be configured by setting the KeyStore option to
279 the path name of the directory.
280 The recommended approach is to use the database as key store. This uses
282 vendor-specific policy objects to tie SPI string, public key, entity
283 name, source name and other bits of policy together, and store them in
284 a persistent way.
285 The database key store is configured by setting the KeyStore option to
287 the reserved value DB:, which is also the default.
288 Currently, Open-iSNS policy objects have the following attributes,
290 besides the SPI:
291 Source:
293 This is the source node name the client must use. It defaults to
294 the SPI string.
295 Functions:
297 This is a bitmap detailing which functions the client is permit‐
298 ted to invoke. The bit names correspond to the shorthand names
299 used in RFC 4171, such as DevAttrReg, DevAttrQry, etc. The
300 default is to allow registration, query and deregistration, as
301 well as SCNRegister.
302 Entity name:
304 This is the entity name assigned to the client. If set, a regis‐
305 tration by the client is not permitted to use a different entity
306 name. If the client sends a registration without Entity identi‐
307 fier, the server will assign the entity name given in the pol‐
308 icy. The default is to not restrict the entity name.
309 Object access:
311 This is a bitfield describing access permissions for each object
312 type. For each object type, you can grant Read and/or Write
313 permissions. Read access applies to the Query and GetNext
314 calls; all other operations require write permission. The
315 default grants read and write access to objects of type Entity,
316 Storage Node, Portal and Portal Group; and read access to Dis‐
317 covery Domains.
318 Node types:
320 This bitfield describes which types of storage nodes a client is
321 allowed to register; the valid bit names are target, initiator
322 and control. The default is to restrict nodes to register ini‐
323 tiators only.
324 Network Related Options
326 Network.MaxSockets
327 This is the number of incoming connections accepted, and
328 defaults to 1024. This usually applies to server side only, but
329 is relevant if you create a passive TCP socket for ESI or SCN.
330 Network.ConnectTimeout
332 This is a timeout value, which specifies the time to wait for a
333 TCP connection to be established. It defaults to 60s.
334 Network.ReconnectTimeout
336 When a connection attempt failed, we wait for a short time
337 before we try connecting again. This is intended to take the
338 pressure off overloaded servers. The default value is 10s.
339 Network.CallTimeout
341 Total amount of time to wait before timing out a call to the
342 iSNS server. The default value is 60s.
343
345 RFC 4171, isnsd(8), isnsadm(8).
346
348 Olaf Kirch <olaf.kirch@oracle.com>
349 11 May 2007 ISNS_CONFIG(5)