ISNSADM(8)ISNSADM(8)NAMEisnsadm - iSNS client utility
SYNOPSISisnsadm [options...] --register object...
isnsadm [...] --query attr[=value]
isnsadm [...] --deregister attr=value
isnsadm [...] --list type attr=value
isnsadm [...] --dd-register 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.
--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,
refer 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
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 com‐
mand line. The naming and syntax of these attributes as 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,
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-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
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-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
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 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
address is implementation dependant.
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 4711 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 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
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, 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 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 recog‐
nized.
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.
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
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 por‐
tion 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 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
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 \
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)
