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