isnsadm - iSNS client utility
] --register object...
] --query attr
] --deregister attr=value
] --list type attr=value
] --dd-register attr=value
] --dd-deregister dd-id attr=value
] --enroll client-name attr=value
] --edit-policy attr=value
is a command line utility for interacting with an iSNS server. It
operates in one of several modes, which are mutually exclusive. Currently,
supports registration, query, and deregistration.
By default, isnsadm
will take most of its settings from the configuration
, with the exception of the following
- --config filename, -c
- This option overrides the default configuration file.
- --debug facility, -d
- enables debugging. Valid facilities are
||authentication and security related information
||iSNS protocol layer
||SCN (state change notification) messages
||ESI (entity status inquiry) messages
||all of the above
- 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
- specifies the server to use (if not specified in the
- 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
configuration 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, refer to
section Registration mode.
- 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 keyfile option.
- This will print a help message and exit.
has built-in help functions. When invoked with --help
will print a general help message showing all supported command modes, and
exit. Specific help on an individual command mode is available by invoking
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
Most command modes take a list of attributes as arguments on the command 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
empty (or NIL) attributes are supported, the attribute name by itself can be
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
), 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 policy-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 invocations are
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
currently supports the following attributes:
|iSCSI Storage Node
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, optionally
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:
This notation can be used in any context where an addr
attribute pair can appear, and may be prefixed by a type name, as in
When using literal IPv6 addresses, the address has to be surrounded by square
brackets, otherwise the embedded colons would create ambiguity:
Some iSNS attributes are words representing a bit field. Isnsadm
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
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 exists), 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-separated
list of attributes, such as this:
The following object types are currently supported:
- Tells the server to group all objects in the specified
Network Entity container object. Normally, the iSNS server will
automatically assign an entity name that is in line with its policies, and
there is no need to specify it explicitly.
- 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
- This will register an iSCSI storage node of type target. By
default, the name is set to the iSNS source name.
- This object accepts the same set of attributes as
- This will register an iSCSI storage node of type control.
By default, the name is set to the iSNS source name. Only management 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
- 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 initiator
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 address is implementation dependent.
- This can be followed by any number of portal
- 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
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 entity, 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
following 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
option recognizes only a subset of the usual attributes:
To get a list of supported attributes, invoke isnsadm --register help
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 object 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
), which will will match any object that has such an attribute,
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
In this mode, isnsadm
will display all objects of a given type,
optionally restricted to those matching certain attribute values.
The arguments to list mode are a type name
, optionally followed by one or
pairs. Only attributes pertaining to the
given type are permitted; for instance, if you specify a type name of
, only portal attributes are permitted.
Possible type names are: entities
, and policies
Additional information is available via isnsadm --list help
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
pairs. Deregistration supports the same set of
attributes as query mode.
This mode allows one to register a discovery domain or to add new members to an
existing discovery domain. Again, attributes are specified as a list of
pairs. Only discovery domain attributes are
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 handle when
referring to a discovery domain.
In this mode, you can deregister a discoery domain previously registered. 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
In Discovery Domain deregistration mode, the argument list consists of the
Discovery Domain ID, followed by a list of attr=value
pairs. Discovery Domain Deregistration supports the same set of attributes as
This mode only works when the server recognizes the client as having control
node capabilities, which is possible in two ways:
- 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.
- 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 following set of
attributes is supported:
||Client's DSA public key
||Assigned Entity Identifier
||Permitted node type(s)
||Permitted node name(s)
||Bitmap of permitted functions
||Object access mask
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 encoded
public key from that file. If no key
attribute is given, or when using
will generate a DSA key. The private portion of
the newly generated key will be stored in the file specified by
attribute is used to specify which object types the
client is permitted to access. This is a comma separated list of
pairs, where type
can be any of
, and policy
. The permissions can be either
, or r
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
For a description of the open-isns security model and policies, please refer to
(5) manual page.
: 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
. These parameters are created by calling isnsd
once on the server machine. Alternatively, you can use the
openssl dsaparam 1024 -out /etc/isns/dsa.params
where 1024 is the chosen DSA key size, in bits.
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
This will create the server's private and public key, and place them in
The following command will create a policy object for a node named
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 station:
isnsadm --local --register control
On the management station, you can then enroll additional hosts:
isnsadm --control --keyfile=somehost.key --enroll
Again, this will generate a DSA key pair and store the private key portion in
auth_key. Note the use of the --control
option that tells
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
. Likewise, the server's public key (which resides in
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 privilege. Future
extensions may allow iSNS clients to add themselves to one or more DDs upon
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 numeric
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 \
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 portals
manually, in case you want to fix up an inconsisteny in the database. For
instance, this will register a node and portal on a host named
isnsadm --control --register entity=client.bozo.org \
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.
RFC 4171, isnsd
Olaf Kirch <firstname.lastname@example.org>