1ISNS_CONFIG(8) System Manager's Manual ISNS_CONFIG(8)
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 the client's
55 hostname.
56 ServerAddress (client):
58 This options specifies the host name or address of the iSNS
59 server to talk to. It can optionally be followed by a colon, and
60 a port number.
61 Instead of a hostname, IPv4 or IPv6 addresses can be used. In
63 order to avoid ambiguities, literal IPv6 addresses must be sur‐
64 rounded by square brackets, as in [2001:4e5f::1].
65 When specifying a port number, you can use either the numeric
67 port, or a string name to be looked up in /etc/services. When
68 the port is omitted, it defaults to 3205, the IANA assigned port
69 number of iSNS.
70 If the special string SLP: is used, the client will try to
72 locate the iSNS server through SLP.
73 SLPRegister (server):
75 If set to 1, the iSNS daemon will register itself will the SLP
76 service. This allows clients to contact the server without hav‐
77 ing to configure its address statically.
78 PIDFile (server):
80 This specifies the name of the server's PID file, which is
81 /var/run/isnsd.pid by default.
82 Database Related Options
84 These options apply to the iSNS server only, and control operation of
85 the iSNS database.
86 Database
88 This option is used to specify how the database is stored. Set‐
89 ting this to an absolute path name will make isnsd keep its
90 database in the specified directory.
91 If you leave this empty, isnsd will keep its database in memory.
93 This is also the default setting.
94 DefaultDiscoveryDomain
96 iSNS scopes visibility of other nodes using so-called Discovery
97 Domains. A storage node A will only "see" storage node B, if
98 both are members of the same discovery domain.
99 So if a storage node is registered which is not part of any dis‐
101 covery domain, it will not see any other nodes.
102 By setting DefaultDiscoveryDomain=1, you can tell isnsd to cre‐
104 ate a virtual "default discovery domain", which holds all nodes
105 that are not part of any administratively configured discovery
106 domain.
107 By default, there is no default discovery domain.
109 RegistrationPeriod
111 The iSNS server can purge registered entities after a certain
112 period of inactivity. This is called the registration period.
113 Clients who register objects are supposed to refresh their reg‐
114 istration within this period.
115 The default value is 1 hour. Setting it to 0 disables expiry of
117 entities from the database.
118 ESIRetries
120 Open-iSNS is able to monitor the reachability of storage nodes
121 and their portals by using a protocol feature called ESI (Entity
122 status inquiry). Clients request ESI monitoring by registering
123 an ESI port along with each portal. The server will send ESI
124 messages to these portals at regular intervals. If the portal
125 fails to reply several times in a row, it is considered dead,
126 and will be removed from the database.
127 ESIRetries specifies the maximum number of attempts the server
129 will make at contacting the portal before pronouncing it dead.
130 If set to 0, the server will disable ESI and reject any regis‐
131 trations that specify an ESI port with an error code of "ESI not
132 supported".
133 The default value is 3.
135 ESIMinInterval
137 This timeout value specifies the minimum ESI interval. If a
138 client requests an ESI interval less than this value, it is
139 silently rounded up.
140 The default value is 60 seconds.
142 ESIMaxInterval
144 This timeout value specifies the maximum ESI interval. If a
145 client requests an ESI interval greater than this value, it is
146 silently rounded down.
147 The default value is 10 minutes.
149 The maximum ESI interval must not exceed half the value of the
151 registration period.
152 SCNRetries
154 iSNS clients can register to receive State Change Notification
155 (SCN) messages to learn about changes in the iSNS database.
156 This value specifies how often the server will try to retransmit
157 an SCN message until giving up.
158 The default value is 3.
160 SCNCallout
162 This is the path name of a helper program that isnsdd will
163 invoke whenever it processes a state change notification from
164 the server. The helper program will be invoked with an argument
165 indicating the type of event, being one of add, update, or
166 remove. This is followed by a list of attributes in name=value
167 notation, using the names and conventions described in
168 isnsadm(8).
169 Security Related Options
171 The iSNS standard defines an authentication method based on the DSA
172 algorithm. Participants in a message exchange authenticate messages by
173 adding an "authentication block" containing a time stamp, a string
174 identifying the key used, and a digital signature of the message. The
175 same method is also used by SLP, the Service Location Protocol.
176 The string contained in the authentication block is referred to as the
178 Security Policy Index(SPI). This string can be used by the server to
179 look up the client's public key by whatever mechanism; so the string
180 could be used as the name of a public key file in a directory, or to
181 retrieve an X509 certificate from LDAP.
182 From the perspective of Open-iSNS client applications, there are only
184 two keys: the client's own (private) key, used to sign the messages it
185 sends to the server, and the server's public key, used to verify the
186 signatures of incoming server messages.
187 The iSNS server needs, in addition to its own private key, access to
189 all public keys of clients that will communicate to it. The latter are
190 kept in what is called a key store. Key stores and their operation will
191 be discussed in section Key Stores and Policy below.
192 The following configuration options control authentication:
194 Security
196 This enables or disables DSA authentication. When set to 1, the
197 client will sign all messages, and expect all server messages to
198 be signed.
199 When enabling security in the server, incoming messages are
201 checked for the presence of an auth block. If none is present,
202 or if the server cannot find a public key corresponding to the
203 SPI, the message is treated as originating from an anonymous
204 source. If the SPI is known but the signature is incorrect, the
205 message is dropped silently.
206 Messages from an anonymous source will be assigned a very
208 restrictive policy that allows database queries only.
209 Setting this option to 0 will turn off authentication.
211 The default value is -1, which tells iSNS to use authentication
213 if the required keys are installed, and use unauthenticated iSNS
214 otherwise.
215 AuthName
217 This is the string that will be used as the SPI in all outgoing
218 messages that have an auth block. It defaults to the host name
219 (please refer to option HostName).
220 AuthKeyFile
222 This is the path name of a file containing a PEM encoded DSA
223 key. This key is used to sign outgoing messages. The default
224 is /etc/isns/auth_key.
225 ServerKeyFile
227 This option is used by client applications only, and specifies
228 the path name of a file containing a PEM encoded DSA key. This
229 key is used to authenticate the server's replies. The default
230 is /etc/isns/server_key.pub.
231 KeyStore
233 This server-side option specifies the key store to use,
234 described in the next section.
235 The following two options control how iSNS will verify the time stamp
237 contained in the authentication block, which is supposed to prevent
238 replay attacks.
239 Auth.ReplayWindow
241 In order to compensate for clock drift between two hosts
242 exchanging iSNS messages, Open-iSNS will apply a little fuzz
243 when comparing the time stamp contained in the message to the
244 local system time. If the difference between time stamp and
245 local system time is less than the number of seconds given by
246 this option, the message is acceptable. Otherwise, it is
247 rejected.
248 The default value is 5m.
250 Auth.TimestampJitter
252 When verifying incoming messages, Open-iSNS checks that the time
253 stamps sent by the peer are increasing monotonically. In order
254 to compensate for the reordering of messages by the network (eg
255 when using UDP as transport), a certain time stamp jitter is
256 accepted. If the time stamp of an incoming messages is no ear‐
257 lier than TimestampJitter seconds before the last time stamp
258 received, then the message is acceptable. Otherwise, it is
259 rejected.
260 The default value is 1s.
262 Key Stores and Policy
264 The current implementation supports two types of key stores.
265 The simple key store uses a flat directory to store public keys, each
267 key in a file of its own. The file is expected to hold the client's
268 PEM-encoded public key, and it must use the client's SPI as the name.
269 This type of key store is not really recommended, as it does not store
270 any policy information.
271 A simple key store can be configured by setting the KeyStore option to
273 the path name of the directory.
274 The recommended approach is to use the database as key store. This uses
276 vendor-specific policy objects to tie SPI string, public key, entity
277 name, source name and other bits of policy together, and store them in
278 a persistent way.
279 The database key store is configured by setting the KeyStore option to
281 the reserved value DB:, which is also the default.
282 Currently, Open-iSNS policy objects have the following attributes,
284 besides the SPI:
285 Source:
287 This is the source node name the client must use. It defaults to
288 the SPI string.
289 Functions:
291 This is a bitmap detailing which functions the client is permit‐
292 ted to invoke. The bit names correspond to the shorthand names
293 used in RFC 4711, such as DevAttrReg, DevAttrQry, etc. The
294 default is to allow registration, query and deregistration, as
295 well as SCNRegister.
296 Entity name:
298 This is the entity name assigned to the client. If set, a regis‐
299 tration by the client is not permitted to use a different entity
300 name. If the client sends a registration without Entity identi‐
301 fier, the server will assign the entity name given in the pol‐
302 icy. The default is to not restrict the entity name.
303 Object access:
305 This is a bitfield describing access permissions for each object
306 type. For each object type, you can grant Read and/or Write
307 permissions. Read access applies to the Query and GetNext
308 calls; all other operations require write permission. The
309 default grants read and write access to objects of type Entity,
310 Storage Node, Portal and Portal Group; and read access to Dis‐
311 covery Domains.
312 Node types:
314 This bitfield describes which types of storage nodes a client is
315 allowed to register; the valid bit names are target, initiator
316 and control. The default is to restrict nodes to register ini‐
317 tiators only.
318 Network Related Options
320 Network.MaxSockets
321 This is the number of incoming connections accepted, and
322 defaults to 1024. This usually applies to server side only, but
323 is relevant if you create a passive TCP socket for ESI or SCN.
324 Network.ConnectTimeout
326 This is a timeout value, which specifies the time to wait for a
327 TCP connection to be established. It defaults to 60s.
328 Network.ReconnectTimeout
330 When a connection attempt failed, we wait for a short time
331 before we try connecting again. This is intended to take the
332 pressure off overloaded servers. The default value is 10s.
333 Network.CallTimeout
335 Total amount of time to wait before timing out a call to the
336 iSNS server. The default value is 60s.
337
339 RFC 4171, isnsd(8), isnsadm(8).
340
342 Olaf Kirch <olaf.kirch@oracle.com>
343 11 May 2007 ISNS_CONFIG(8)