Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ISNS_CONFIG(5)		      File Formats Manual		ISNS_CONFIG(5)

       isns_config - iSNS configuration	file


       All  Open-iSNS  utilities  read	their  configuration  from  a  file in
       /etc/isns.  There is a separate configuration file  for	each  applica-
       tion,  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 argu-

       Some options specify timeout values, which are given in units  of  sec-
       onds  by	 default. You can specify an explicit unit, however, such as d
       (days), h (hours), m (minutes), or s (seconds).

   Generic Options
	      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  op-
	      tion, you	can overried this. This	option is rarely needed.

	      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,  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.

	      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  sur-
	      rounded 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  lo-
	      cate 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  hav-
	      ing to configure its address statically.

       PIDFile (server):
	      This  specifies  the  name  of  the  server's PID	file, which is
	      /var/run/ by default.

   Database Related Options
       These options apply to the iSNS server only, and	control	 operation  of
       the iSNS	database.

	      This option is used to specify how the database is stored.  Set-
	      ting 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.

	      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 dis-
	      covery domain, it	will not see any other nodes.

	      By  setting DefaultDiscoveryDomain=1, you	can tell isnsd to cre-
	      ate a virtual "default discovery domain",	which holds all	 nodes
	      that  are	 not part of any administratively configured discovery

	      By default, there	is no default discovery	domain.

	      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  reg-
	      istration	within this period.

	      The  default value is 1 hour. Setting it to 0 disables expiry of
	      entities from the	database.

	      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	regis-
	      trations that specify an ESI port	with an	error code of "ESI not

	      The default value	is 3.

	      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.

	      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.

	      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.

	      This is the path name of a helper	program	that isnsdd  will  in-
	      voke  whenever it	processes a state change notification from the
	      server. The helper program will be invoked with an argument  in-
	      dicating 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).

   Security Related Options
       The iSNS	standard defines an authentication method based	on the DSA al-
       gorithm.	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:

	      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  re-
	      strictive	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

	      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).

	      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.

	      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/

	      This server-side option specifies	the  key  store	 to  use,  de-
	      scribed 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 re-
       play attacks.

	      In  order	 to  compensate	 for clock drift between two hosts ex-
	      changing 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 sys-
	      tem  time	 is  less than the number of seconds given by this op-
	      tion, the	message	is acceptable. Otherwise, it is	rejected.

	      The default value	is 5m.

	      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 ac-
	      cepted.  If the time stamp of an incoming	messages is no earlier
	      than  TimestampJitter  seconds  before  the  last	time stamp re-
	      ceived, then the message is acceptable.  Otherwise,  it  is  re-

	      The default value	is 1s.

   Key Stores and Policy
       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,  be-
       sides the SPI:

	      This is the source node name the client must use.	It defaults to
	      the SPI string.

	      This is a	bitmap detailing which functions the client is permit-
	      ted  to  invoke. The bit names correspond	to the shorthand names
	      used in RFC 4171,	such as	DevAttrReg, DevAttrQry,	etc.  The  de-
	      fault  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	regis-
	      tration by the client is not permitted to	use a different	entity
	      name. If the client sends	a registration without Entity  identi-
	      fier,  the  server will assign the entity	name given in the pol-
	      icy.  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 de-
	      fault grants read	and write access to objects  of	 type  Entity,
	      Storage  Node,  Portal and Portal	Group; and read	access to Dis-
	      covery 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  ini-
	      tiators only.

   Network Related Options
	      This  is	the  number  of	incoming connections accepted, and de-
	      faults to	1024. This usually applies to server side only,	but is
	      relevant if you create a passive TCP socket for ESI or SCN.

	      This  is a timeout value,	which specifies	the time to wait for a
	      TCP connection to	be established.	 It defaults to	60s.

	      When a connection	attempt	failed,	we wait	for a short  time  be-
	      fore we try connecting again. This is intended to	take the pres-
	      sure off overloaded servers. The default value is	10s.

	      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 <>

				  11 May 2007			ISNS_CONFIG(5)


Want to link to this manual page? Use this URL:

home | help