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

FreeBSD Manual Pages

  
 
  

home | help
ISNSADM(8)		    System Manager's Manual		    ISNSADM(8)

NAME
       isnsadm - iSNS client utility

SYNOPSIS
       isnsadm [options...]  --register	object...

       isnsadm [...]  --query attr[=value]

       isnsadm [...]  --deregister attr=value

       isnsadm [...]  --list type attr=value

       isnsadm [...]  --dd-register attr=value

       isnsadm [...]  --dd-deregister dd-id attr=value

       isnsadm [...]  --enroll client-name attr=value

       isnsadm [...]  --edit-policy attr=value

DESCRIPTION
       Isnsadm	is a command line utility for interacting with an iSNS server.
       It operates in one of several  modes,  which  are  mutually  exclusive.
       Currently, isnsadm supports registration, query,	and deregistration.

OPTIONS
       By  default, isnsadm will take most of its settings from	the configura-
       tion file /etc/isns/isnsadm.conf, with the exception of	the  following
       options:

       --config	filename, -c filename
	      This option overrides the	default	configuration file.

       --debug facility, -d facility
	      enables debugging. Valid facilities are

	   +--------+-----------------------------------------------------+
	   |socket  | network send/receive				  |
	   |auth    | authentication and security related information	  |
	   |message | iSNS protocol layer				  |
	   |state   | database state					  |
	   |scn	    | SCN (state change	notification) messages		  |
	   |esi	    | ESI (entity status inquiry) messages		  |
	   |all	    | all of the above					  |
	   +--------+-----------------------------------------------------+
       --local
	      makes  isnsadm use a Local (aka Unix) socket when	talking	to the
	      iSNS server. This	can be used by the  administrator  to  perform
	      management  tasks, such as enrolling new clients,	editing	access
	      control and so on. Local mode is only  available	to  the	 super
	      user.

       --server	servername, -s servername
	      specifies	 the server to use (if not specified in	the configura-
	      tion file).

       --control
	      makes isnsadm assume the identity	of  a  control	node.  Control
	      nodes are	special	in that	they have more rights in accessing and
	      modifying	the database than normal storage nodes have.

       When using this option, isnsadm will use	the source name	 and  DSA  key
       specified  by the Control.SourceName and	Control.AuthKeyFile configura-
       tion options, respectively.

       --key attr=value
	      This option is recognized	in registration	mode  only,  and  lets
	      you  specify an object key. For a	more detailed explanation, re-
	      fer to section Registration mode.

       --keyfile=filename
	      When creating a policy for a new iSNS client, isnsadm is able to
	      generate a DSA key for the client. The public part of the	key is
	      stored in	a policy object	in the iSNS server's database, whereas
	      the  private portion is stored in	the file specified by the key-
	      file option.

       --help This will	print a	help message and exit.

   Built-in help
       Isnsadm has built-in help functions. When invoked with --help, it  will
       print  a	 general help message showing all supported command modes, and
       exit. Specific help on an individual command mode is available  by  in-
       voking that mode	with a single argument of help,	like this:

       isnsadm --register help

       This will print a help message describing how to	use this command mode,
       followed	by a list of attributes	this command supports and a help  text
       describing the attribute.

   Supported attributes
       Most  command  modes take a list	of attributes as arguments on the com-
       mand line. The naming and syntax	of these attributes are	the  same  for
       all commands modes, however certain modes support only a	limited	set of
       attributes.

       Attributes are usually given as name=value pairs. Where empty (or  NIL)
       attributes are supported, the attribute name by itself can be given.

       The  syntax  of	attribute  value  depends  on  the attribute type. For
       strings and numeric values, no special conventions apply, but bitfields
       have a special syntax described below.

       The attribute name is usually preceded by the object type it applies to
       (such as	entity), followed by a hyphen and the  name  itself.  However,
       where the context clearly determines a specific object type, the	prefix
       can be omitted. For  instance,  when  editing  a	 policy	 object	 using
       --edit-policy,  it is acceptable	to use node-type as shorthand for pol-
       icy-node-type.

       Likewise, in a query command, it	is not	permitted  to  mix  attributes
       from  different	object	types.	Thus,  the  first attribute of a query
       string establishes a type context, so that the  following  two  invoca-
       tions are equivalent:

       isnsadm --query pg-name=iqn.com.foo pg-addr=10.1.1.1 pg-port=860/tcp
       isnsadm --query pg-name=iqn.com.foo addr=10.1.1.1 port=860/tcp

       Isnsadm currently supports the following	attributes:

	  +-------------------+-------------------------------------------+
	  |Context	      |	Attribute	       iSNS tag	  Aliases |
	  +-------------------+-------------------------------------------+
	  |Network Entity     |	entity-id		      1	  eid	  |
	  |		      |	entity-prot		      2		  |
	  |		      |	entity-index		      7		  |
	  |iSCSI Storage Node |	iscsi-name		     32		  |
	  |		      |	iscsi-node-type		     33		  |
	  |		      |	iscsi-alias		     34		  |
	  |		      |	iscsi-idx		     36		  |
	  |		      |	iscsi-authmethod	     42		  |
	  |Portal	      |	portal-addr		     16		  |
	  |		      |	portal-port		     17		  |
	  |		      |	portal-name		     18		  |
	  |		      |	portal-esi-port		     20		  |
	  |		      |	portal-esi-interval	     21		  |
	  |		      |	portal-idx		     22		  |
	  |		      |	portal-scn-port		     23		  |
	  |Portal Group	      |	portal-group-index	     52		  |
	  |		      |	pg-name			     48		  |
	  |		      |	pg-addr			     49		  |
	  |		      |	pg-port			     50		  |
	  |		      |	pg-tag			     51	  pgt	  |
	  |		      |	pg-idx			     52		  |
	  |Discovery Domain   |	dd-id			   2065		  |
	  |		      |	dd-name			   2066		  |
	  |		      |	dd-member-iscsi-idx	   2067		  |
	  |		      |	dd-member-name		   2068		  |
	  |		      |	dd-member-fc-name	   2069		  |
	  |		      |	dd-member-portal-idx	   2070		  |
	  |		      |	dd-member-addr		   2071		  |
	  |		      |	dd-member-port		   2072		  |
	  |		      |	dd-features		   2078		  |
	  |Policy Object      |	policy-name		      -	  spi	  |
	  |		      |	policy-key		      -		  |
	  |		      |	policy-entity		      -		  |
	  |		      |	policy-node-type	      -		  |
	  |		      |	policy-object-type	      -		  |
	  |		      |	policy-functions	      -		  |
	  +-------------------+-------------------------------------------+
   Portal attributes
       Portal  information  is conveyed	by two separate	attributes in iSNS; an
       address attribute holding the IP	address, and a TCP/UDP port  attribute
       holding	the  port  number and an indication of the protocol to be used
       (TCP or UDP).

       When parsing a TCP/UDP port, Open-iSNS will expect a port  number,  op-
       tionally	 followed  by  a  slash	 and  the protocol. Port names such as
       "iscsi-target" are not supported.

       As a convenience, isnsadm supports a notation representing a portal  as
       one  pseudo-attribute.	Separating  address and	port by	a colon. Thus,
       the following two are equivalent, with the latter being	the  shorthand
       representation of the former:

       addr=_address_ port=_port_[/protocol].  portal=_adress_:port[/protocol]

       This  notation  can be used in any context where	an addr/port attribute
       pair can	appear,	and may	be prefixed by a  type	name,  as  in  pg-por-
       tal=....

       When  using literal IPv6	addresses, the address has to be surrounded by
       square brackets,	otherwise the embedded colons would create  ambiguity:
       portal=[2001:5c0:0:2::24]:860/tcp

   Bitfield attributes
       Some  iSNS attributes are words representing a bit field.  Isnsadm dis-
       plays and parses	these attributes in human-readable  form  rather  than
       using the numerical value. The names of the bit values are displayed by
       built-in	help facilities. When specifying a bitfield attribute  on  the
       command	line,  you  can	 combine  them using the plus (+) or comma (,)
       character, like this:

       node-type=control+initiator

   Registration	mode
       Registration mode is selected by	using the --register option,  followed
       by  a list of one or more objects to register with the iSNS server.  By
       default,	this will create a network entity for the client (if none  ex-
       ists),  and place the new objects inside	it.  Usually, you register all
       objects for a network entity in one operation,  rather  than  each  one
       separately.

       Each object is specified	as a type, optionally followed by a comma-sep-
       arated list of attributes, such as this:

       target=iqn.2005-01.org.open-iscsi.foo:disk1,alias=disk1

       The following object types are currently	supported:

       entity=name
	      Tells the	server to group	all objects in the  specified  Network
	      Entity  container	 object.  Normally, the	iSNS server will auto-
	      matically	assign an entity name that is in line with  its	 poli-
	      cies, and	there is no need to specify it explicitly.

       initiator[=name]
	      This  will register an iSCSI storage node	of type	initiator.  By
	      default, the name	is set to the iSNS source name.

	      This can be followed by any number of  iSCSI  storage  node  at-
	      tributes.

       target[=name]
	      This will	register an iSCSI storage node of type target.	By de-
	      fault, the name is set to	the iSNS source	name.

	      This object accepts the same set of attributes as	initiator.

       control[=name]
	      This will	register an iSCSI storage node of  type	 control.   By
	      default,	the name is set	to the iSNS source name.  Only manage-
	      ment nodes should	be registered as control nodes,	as this	 gives
	      a	node complete control over the iSNS database.

	      This object accepts the same set of attributes as	initiator.

       portal=[address:port/proto]
	      This  will  register  a portal using the given address, port and
	      protocol triple. If the triple is	omitted, isnsadm will use  the
	      client  host's  IP address. If the portal	is preceded by an ini-
	      tiator registration (on the command line), the port defaults  to
	      860/tcp;	if  it	is preceded by a target	registration, the port
	      defaults to 3260/tcp.  For multi-homed hosts, the	choice of  ad-
	      dress is implementation dependent.

	      This can be followed by any number of portal attributes.

       pg     This  will  register a portal group joining the preceding	portal
	      and node.	Portal groups can be used to  describe	the  preferred
	      portals for a given node;	please refer to	RFC 4171 for details.

	      This  can	 be followed by	any number of portal group attributes.
	      The attribute list must specify a	portal group tag (PGT) via the
	      pgt attribute.

       There  are  two	additional command line	options	of interest, which are
       used exclusively	with Registration mode.	One is	--replace.   Normally,
       registration mode will add new objects to the network entity associated
       with the	client host. If	you specify --replace on the command line, the
       server  will wipe the network entity completely,	and remove all portals
       and storage nodes it contained. Then it will create a new  network  en-
       tity,  and  place  the portals and storage nodes	provided by the	caller
       inside.

       In addition, it is possible to replace just parts of a network  entity.
       This  is	achieved by using the command line option --key	to specify the
       object that should be replaced.

       For instance, assume a network entity contains the portal 10.1.1.1:860,
       and the client's	network	address	changed	to 10.2.7.7.  Then the follow-
       ing command will	atomically update the  database,  replacing  just  the
       portal without touching the registered storage nodes:

	 isnsadm --replace --key portal=10.1.1.1:860 portal=10.2.7.7:860

       The --key option	recognizes only	a subset of the	usual attributes:

	      +------------+---------------------+
	      |Object type | Syntax		 |
	      +------------+---------------------+
	      |Entity	   | eid=identifier	 |
	      |Portal	   | portal=address:port |
	      |iSCSI Node  | iscsi-name=name	 |
	      +------------+---------------------+
       To get a	list of	supported attributes, invoke isnsadm --register	help.

   Query mode
       Query mode is selected by using the --query option. A query consists of
       a list of attr=value pairs. All attributes must belong to the same  ob-
       ject  type,  i.e. queries that mix a Network Entity attribute with e.g.
       a Portal	attribute will be rejected.

       It is also possible to specify an attribute name	 without  value	 (i.e.
       just  attr),  which  will will match any	object that has	such an	attri-
       bute, regardless	of its value. This is useful when you  want  to	 query
       for all objects of a given type.

       To obtain a list	of supported attributes, invoke	isnsadm	--query	help.

   List	Mode
       In this mode, isnsadm will display all objects of a given type, option-
       ally restricted to those	matching certain attribute values.

       The arguments to	list mode are a	type name, optionally followed by  one
       or  more	attr=value pairs. Only attributes pertaining to	the given type
       are permitted; for instance, if you specify a  type  name  of  portals,
       only portal attributes are permitted.

       Possible	type names are:	entities, nodes, portals, dds, ddsets, portal-
       groups, and policies.

       Additional information is available via isnsadm --list help.

   Deregistration mode
       In this mode, you can deregister	objects	previously  registered.	  Only
       the  node which registered an entity in the first place is permitted to
       remove it, or any of its	child objects. (Control	nodes are not bound by
       this restriction).

       In  deregistration  mode,  the  argument	 list  consists	 of  a list of
       attr=value pairs. Deregistration	supports the same set of attributes as
       query mode.

   Discovery Domain Registration
       This  mode allows one to	register a discovery domain or to add new mem-
       bers to an existing discovery domain. Again, attributes	are  specified
       as  a  list  of	attr=value pairs. Only discovery domain	attributes are
       recognized.

       Note, in	order to add members to	an existing domain, you	 must  specify
       the domain's numeric ID.	The domain's symbolic name is not a valid han-
       dle when	referring to a discovery domain.

   Discovery Domain Deregistration mode
       In this mode, you can deregister	a discoery  domain  previously	regis-
       tered.	Only the node which registered a discovery domain in the first
       place is	permitted to remove it,	or any of its members. (Control	 nodes
       are not bound by	this restriction).

       In  Discovery Domain deregistration mode, the argument list consists of
       the Discovery Domain ID,	followed by a list of attr=value  pairs.  Dis-
       covery  Domain  Deregistration  supports	 the same set of attributes as
       query mode.

   Client Enrollment
       This mode only works when the server recognizes the  client  as	having
       control node capabilities, which	is possible in two ways:

       Invoke isnsadm  --local	as super user on the host isnsd	is running on.
	      The --local options tells	it  to	communicate  with  the	server
	      through the local	control	socket.

       Invoke isnsadm  --control,  which  tells	it to assume the identity of a
	      control node.  When given	this  option,  isnsadm	will  use  the
	      source  name and DSA key specified by the	Control.SourceName and
	      Control.AuthKeyFile configuration	 options,  respectively.   The
	      server  must  be	configured to grant this identity control node
	      status.

       To enroll a client, use the --enroll option, followed by	 the  (source)
       name  of	the client to enroll.  This string will	be used	as the name of
       the security policy the client will use to identify itself.

       This is followed	by a list of attribute/value pairs, where the  follow-
       ing set of attributes is	supported:

	     +------------+---------------------------------------------+
	     |Attribute	  | Description			    Aliases	|
	     +------------+---------------------------------------------+
	     |name	  | Policy Name				spi	|
	     |key	  | Client's DSA public	key			|
	     |entity	  | Assigned Entity Identifier			|
	     |node-type	  | Permitted node type(s)			|
	     |node-name	  | Permitted node name(s)			|
	     |functions	  | Bitmap of permitted	functions		|
	     |object-type | Object access mask				|
	     +------------+---------------------------------------------+
       The key attribute is used to specify the	DSA public key that the	server
       should use to authenticate messages from	this client.  You  can	either
       provide a file name; in which case isnsadm will try to read the PEM en-
       coded public key	from that file.	 If no key attribute is	given, or when
       using  key=gen, isnsadm will generate a DSA key.	The private portion of
       the newly generated key will be stored in the file specified by	--key-
       file=filename.

       The  object-type	 attribute  is	used to	specify	which object types the
       client is permitted to access.  This  is	 a  comma  separated  list  of
       type:perm  pairs,  where	type can be any	of entity, iscsi-node, portal,
       portal-group, dd, ddset,	and policy.  The permissions can be either rw,
       or r.

       The  functions  attribute  can  be used to restrict which functions the
       client is permitted to invoke. This is a	bitfield, using	 the  standard
       function	names from RFC 4171, such as DevAttrReg, DevAttrQry, etc.

       For  a description of the open-isns security model and policies,	please
       refer to	the isns_config(5) manual page.

       Important note: In order	to generate a DSA key, you have	to have	a  set
       of  DSA	parameters installed. By default, isnsadm expects to find them
       in /etc/isns/dsa.params.	 These parameters are created by calling isnsd
       --init  once on the server machine. Alternatively, you can use the fol-
       lowing command:

	       openssl dsaparam	1024 -out /etc/isns/dsa.params

       where 1024 is the chosen	DSA key	size, in bits.

EXAMPLES
       If you want to use Open-iSNS in authenticated mode, you first  need  to
       initialize  the	server's  DSA key and DSA parameters. This can be done
       conveniently by using

       isnsd --init

       This will create	the server's private and public	key, and place them in
       /etc/isns/auth_key and auth_key.pub, respectively.

       The  following  command	will  create  a	policy object for a node named
       isns.control , and grant	it control privileges:

       isnsadm --local --keyfile=control.key --enroll isns.control \
		  node-type=ALL	functions=ALL object-type=ALL

       In the process of entrolling the	client,	this will generate a  DSA  key
       pair,  and place	the private key	portion	in the file control.key.  This
       file must be installed as /etc/isns/control.key on the host you wish to
       use as an iSNS management station.

       Next,  you need to create a storage node	object for the management sta-
       tion:

       isnsadm --local --register control

       On the management station, you can then enroll additional hosts:

       isnsadm --control --keyfile=somehost.key	--enroll iqn.2005-01.org.open-
       iscsi.somehost \
		  node-type=target+initiator

       Again, this will	generate a DSA key pair	and store the private key por-
       tion in auth_key. Note the use  of  the	--control  option  that	 tells
       isnsadm	to use the identity of the control node	instead	of the default
       key and source name.

       You then	need to	copy somehost.key to the client	host and install it as
       /etc/isns/auth_key.   Likewise,	the server's public key	(which resides
       in /etc/isns/auth_key.pub on the	server)	needs  to  be  copied  to  the
       client machine, and placed in /etc/isns/server_key.pub.

       By  default, when a client registers a storage node (be it initiator or
       target) with iSNS, the client will not be able to see any other storage
       nodes.  In  order  for  targets to be visible to	a given	initiator, you
       need to create so-called	Discovery Domains (or DDs for short).

       Currently, domain membership operations	require	 administrator	privi-
       lege. Future extensions may allow iSNS clients to add themselves	to one
       or more DDs upon	registration.

       To create a discovery domain, and add nodes to it, you can use

       isnsadm --control --dd-register dd-name=mydomain	\
		  member-name=iqn.org.bozo.client iqn.org.bozo.jbod ...

       In order	to add members to an existing DD, you have to specify the  nu-
       meric  domain  ID  - using the DD name is not sufficient, unfortunately
       (this is	a requirement of the RFC, not an implementation	issue):

       isnsadm --control --dd-register dd-id=42	\
		  member-name=iqn.com.foo member-name=iqn.com.bar

       The DD ID can be	obtained by doing a query for the DD name:

       isnsadm --control --query dd-name=mydomain

       In management mode, you can also	register and deregister	nodes and por-
       tals  manually, in case you want	to fix up an inconsisteny in the data-
       base. For instance, this	will register a	node  and  portal  on  a  host
       named client.bozo.org:

       isnsadm --control --register entity=client.bozo.org \
		  initiator=iqn.org.bozo.client	portal=191.168.7.1:860

       Note  that this registration explicitly specifies the network entity in
       which to	place the new objects. If you omit this, the new objects  will
       be  placed  in an entity	named CONTROL, which is	decidedly not what you
       want.

SEE ALSO
       RFC 4171, isnsd(8), isns_config(5).

AUTHORS
       Olaf Kirch <olaf.kirch@oracle.com>

				  11 May 2007			    ISNSADM(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=isnsadm&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help