1ISNS_CONFIG(5)                File Formats Manual               ISNS_CONFIG(5)
2
3
4

NAME

6       isns_config - iSNS configuration file
7

SYNOPSIS

9       /etc/isns/isnsadm.conf
10       /etc/isns/isnsd.conf
11       /etc/isns/isnsdd.conf
12
13

DESCRIPTION

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
21       An  Open-iSNS  configuration  file contains keyword-argument pairs, one
22       per line.  All keywords are case insensitive.
23
24       A # character introduces a comment, which extends until the end of  the
25       line. Empty lines are ignored.
26
27       There are no line continuations, and you cannot use quotes around argu‐
28       ments.
29
30       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
34   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
41       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
50              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
54              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
59       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
63       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
68              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
72              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
77              If the special string SLP: is  used,  the  client  will  try  to
78              locate the iSNS server through SLP.
79
80       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
85       PIDFile (server):
86              This  specifies  the  name  of  the  server's PID file, which is
87              /var/run/isnsd.pid by default.
88
89   Database Related Options
90       These options apply to the iSNS server only, and control  operation  of
91       the iSNS database.
92
93       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
98              If you leave this empty, isnsd will keep its database in memory.
99              This is also the default setting.
100
101       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
106              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
109              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
114              By default, there is no default discovery domain.
115
116       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
122              The  default value is 1 hour. Setting it to 0 disables expiry of
123              entities from the database.
124
125       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
134              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
140              The default value is 3.
141
142       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
147              The default value is 60 seconds.
148
149       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
154              The default value is 10 minutes.
155
156              The maximum ESI interval must not exceed half the value  of  the
157              registration period.
158
159       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
165              The default value is 3.
166
167       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
176   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
183       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
189       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
194       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
199       The following configuration options control authentication:
200
201       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
206              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
213              Messages  from  an  anonymous  source  will  be  assigned a very
214              restrictive policy that allows database queries only.
215
216              Setting this option to 0 will turn off authentication.
217
218              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
222       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
227       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
232       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
238       KeyStore
239              This   server-side  option  specifies  the  key  store  to  use,
240              described in the next section.
241
242       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
246       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
255              The default value is 5m.
256
257       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
267              The default value is 1s.
268
269   Key Stores and Policy
270       The current implementation supports two types of key stores.
271
272       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
278       A  simple key store can be configured by setting the KeyStore option to
279       the path name of the directory.
280
281       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
286       The  database key store is configured by setting the KeyStore option to
287       the reserved value DB:, which is also the default.
288
289       Currently, Open-iSNS policy  objects  have  the  following  attributes,
290       besides the SPI:
291
292       Source:
293              This is the source node name the client must use. It defaults to
294              the SPI string.
295
296       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
303       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
310       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
319       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
325   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
331       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
335       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
340       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

SEE ALSO

345       RFC 4171, isnsd(8), isnsadm(8).
346

AUTHORS

348       Olaf Kirch <olaf.kirch@oracle.com>
349
350
351
352                                  11 May 2007                   ISNS_CONFIG(5)
Impressum