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

Supported attributes

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

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

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-portal=....

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

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 automatically assign an entity name that is in line with its policies, 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 attributes.

target[=name]

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

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

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

List Mode

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 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 members 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 handle when referring to a discovery domain.

Discovery Domain Deregistration mode

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

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 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 following set of attributes is supported:

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 encoded 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 --keyfile=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 following command:

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

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