ISNSADM(8)

okay bestie, buckle up 💖 this is the manual page for isnsadm(8) — from the System Manager's Manual, section 8, admin territory, main character energy only. it's long so we're doing it in parts. part 1 starts now 🎀

---

✨ 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 talking to an iSNS server. it operates in one of several modes, and those modes are mutually exclusive — like, pick one, bestie, you can't be in your villain era and your soft girl era at the exact same time 💅

Currently, isnsadm supports registration, query, and deregistration. that's the whole roster for now 👑

---

✨ OPTIONS ✨

okay so by default, isnsadm will take most of its settings from the configuration file /etc/isns/isnsadm.conf — with the exception of the following options, which are the ones that do their own thing 🙈

• --config filename, -c filename — this option overrides the default configuration file. you're basically telling it "not that one, this one" 🎀
• --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 one's for the administrator doing management tasks — enrolling new clients, editing access control, that whole vibe 🫶

Local mode is only available to the super user. no superuser, no entry, sorry bestie 💀

• --server servername, -s servername — specifies the server to use (if it's not specified in the configuration file). so like, if the config file didn't say, you say 🌸
• --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. it's giving main character, and honestly it is the main character 👑

when you use this option, isnsadm will use the source name and DSA key specified by the Control.SourceName and Control.AuthKeyFile configuration options, respectively.

• --key attr=value — this option is recognized in registration mode only, and it lets you specify an object key. for a more detailed explanation, go read the Registration mode section below 👇
• --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 keyfile option. keep that file safe, fr fr 🫣
• --help — this will print a help message and exit. classic. iconic. does exactly what it says 🎀

---

🌟 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. bye bestie 👋

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. so much lore, all for you 💖

---

🌟 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 command modes, however certain modes support only a limited set of attributes. know your limits, slay 💅

attributes are usually given as name=value pairs. where empty (or NIL) attributes are supported, the attribute name by itself can be given — no =, no value, just vibes 🌸

the syntax of an 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's acceptable to use node-type as shorthand for policy-node-type. shorthand is self-care 🎀

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:

• Network Entity
  • entity-id — iSNS tag 1 — alias eid
  • entity-prot — iSNS tag 2
  • entity-index — iSNS tag 7
• iSCSI Storage Node
  • iscsi-name — iSNS tag 32
  • iscsi-node-type — iSNS tag 33
  • iscsi-alias — iSNS tag 34
  • iscsi-idx — iSNS tag 36
  • iscsi-authmethod — iSNS tag 42
• Portal
  • portal-addr — iSNS tag 16
  • portal-port — iSNS tag 17
  • portal-name — iSNS tag 18
  • portal-esi-port — iSNS tag 20
  • portal-esi-interval — iSNS tag 21
  • portal-idx — iSNS tag 22
  • portal-scn-port — iSNS tag 23
• Portal Group
  • portal-group-index — iSNS tag 52
  • pg-name — iSNS tag 48
  • pg-addr — iSNS tag 49
  • pg-port — iSNS tag 50
  • pg-tag — iSNS tag 51 — alias pgt
  • pg-idx — iSNS tag 52
• Discovery Domain
  • dd-id — iSNS tag 2065
  • dd-name — iSNS tag 2066
  • dd-member-iscsi-idx — iSNS tag 2067
  • dd-member-name — iSNS tag 2068
  • dd-member-fc-name — iSNS tag 2069
  • dd-member-portal-idx — iSNS tag 2070
  • dd-member-addr — iSNS tag 2071
  • dd-member-port — iSNS tag 2072
  • dd-features — iSNS tag 2078
• Policy Object
  • policy-name — iSNS tag - — alias spi
  • policy-key — iSNS tag -
  • policy-entity — iSNS tag -
  • policy-node-type — iSNS tag -
  • policy-object-type — iSNS tag -
  • policy-functions — iSNS tag -

---

🌟 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). it's a duo, and honestly? they ate 🔥

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 — sorry bestie, no nicknames here 🙈

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 — and ambiguity is not the vibe:

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 — bulk it, don't dribble it 💅

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 the objects in the Network Entity container you named. Ngl, you usually don't need this: the iSNS server will just auto-assign an entity name that matches its own policies. ✨ let the server cook ✨
• initiator[=name] — registers an iSCSI storage node of type initiator. If you don't hand it a name, it defaults to the iSNS source name. 🫶

You can follow this with as many iSCSI storage node attributes as your heart desires.

• target[=name] — registers an iSCSI storage node of type target. Default name? Same deal — the iSNS source name.

This object takes the exact same set of attributes as initiator. twins fr.

• control[=name] — registers an iSCSI storage node of type control, and again the default name is the iSNS source name.

🚨 Bestie, listen. Only management nodes should be registered as control nodes, because being a control node gives a node complete control over the iSNS database. That is main character energy you do NOT hand out casually. 💀

Same attributes as initiator again.

• portal=[address:port/proto] — registers a portal using that address/port/protocol triple. If you omit the triple entirely, isnsadm uses the client host's IP address. And the defaults are context-dependent, so pay attention 👀: if the portal is preceded by an initiator registration on the command line, the port defaults to 860/tcp; if it's preceded by a target registration, the port defaults to 3260/tcp. For multi-homed hosts, which address gets picked is implementation dependent.

Can be followed by any number of portal attributes.

• pg — registers a portal group that joins the preceding portal and node. Portal groups are how you describe the preferred portals for a given node; go read RFC 4171 for the deets. 📚

Can be followed by any number of portal group attributes. The attribute list must specify a portal group tag (PGT) via the pgt attribute. no pgt, no pg, that's the rule.

---

Okay so there are two extra command line options that matter here, and they are used exclusively with Registration mode. One is --replace. Normally registration mode just adds new objects to the network entity tied to the client host. But if you pass --replace on the command line, the server will wipe the network entity completely — all the portals and storage nodes it contained, gone, poof — and then build a brand new network entity and drop the portals and storage nodes you provided inside it. 🔥

You can also replace just parts of a network entity instead of the whole thing. That's what --key is for: you use it to name the object that should be replaced.

For instance — picture a network entity holding the portal 10.1.1.1:860, and the client's network address has now changed to 10.2.7.7. Then this command atomically updates the database, swapping out just that portal and leaving the registered storage nodes completely untouched:

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:

• Entity — eid=identifier
• Portal — portal=address:port
• iSCSI Node — iscsi-name=name

Want the full list of supported attributes? Just run isnsadm --register help. 💅

🌸 Query mode 🌸

Query mode is what you get when you use the --query option. A query is a list of attr=value pairs, and all attributes must belong to the same object type — so a query that mixes a Network Entity attribute with, say, a Portal attribute will get rejected. sorry babe, no mixing. 🙈

You can also give an attribute name with no value at all (just attr), which matches any object that has that attribute, whatever its value happens to be. Super useful when you just want every object of a given type.

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

🦋 List Mode 🦋

In this mode, isnsadm shows you all objects of a given type, optionally narrowed down to the ones matching certain attribute values.

The arguments to list mode are a type name, optionally followed by one or more attr=value pairs. Only attributes that belong to the type you named are allowed — so if you say the type is portals, only portal attributes are permitted. 🎀

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

More info lives at isnsadm --list help.

💜 Deregistration mode 💜

Here's where you deregister objects you previously registered. Important: only the node that registered an entity in the first place is allowed to remove it, or remove any of its child objects. (Control nodes are not bound by this restriction — they're above the law, apparently. 👑)

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

🌈 Discovery Domain Registration 🌈

This mode lets you register a discovery domain, or add new members to one that already exists. Same vibe as before: attributes are given as a list of attr=value pairs, and only discovery domain attributes are recognized.

⚠️ Note this well: 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 you're referring to a discovery domain. no cap.

✨ Discovery Domain Deregistration mode ✨

In this mode you can deregister a discovery domain you registered earlier. And again, only the node that registered a discovery domain in the first place may remove it, or remove any of its members. (Control nodes? Still not bound by this restriction. 🙃)

In Discovery Domain deregistration mode, the argument list is 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 can happen in two ways:

1. Invoke isnsadm --local as super user on the host that isnsd is running on. The --local option tells it to talk to the server through the local control socket.
2. Invoke isnsadm --control, which tells it to assume the identity of a control node. When you give it this option, isnsadm uses 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 you want to enroll. That string becomes the name of the security policy the client will use to identify itself. 🪪

That's followed by a list of attribute/value pairs, and this is the set of attributes supported:

• name — Policy Name (alias: 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 how you specify the DSA public key the server should use to authenticate messages from this client. You can give it a file name — in which case isnsadm will try to read the PEM encoded public key out of that file. But if you give no key attribute at all, or if you use key=gen, isnsadm will generate a DSA key for you. The private part of that freshly generated key gets stored in the file specified by --keyfile=filename. 🔐

The object-type attribute says which object types the client is allowed to access. It's 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 restricts which functions the client is permitted to invoke. It's a bitfield using the standard function names from RFC 4171, like DevAttrReg, DevAttrQry, etc.

For a full description of the open-isns security model and policies, go read 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. Those parameters are created by calling isnsd --init once on the server machine. Alternatively, you can use this command: openssl dsaparam 1024 -out /etc/isns/dsa.params where 1024 is the chosen DSA key size, in bits.

💖 EXAMPLES 💖

ok so like, real talk, this is the part where it all comes together and you get to see how the pieces fit, bestie. buckle up. 🎀

If you wanna run Open-iSNS in authenticated mode, you gotta initialize the server's DSA key and DSA parameters first. no skipping, it's giving prerequisites. luckily there's a cute lil shortcut:

isnsd --init

This creates the server's private and public key, and drops them into /etc/isns/auth_key and auth_key.pub, respectively. two files, one command, we love to see it. ✨

Next up, this command makes a policy object for a node called isns.control, and grants it control privileges:

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

While it's enrolling the client, this generates a DSA key pair and puts the private key portion into the file control.key. 🗝️ That file must be installed as /etc/isns/control.key on whatever host you want to use as an iSNS management station. like, non-negotiable, it goes there.

Then you need to create a storage node object for the management station:

isnsadm --local --register control

Once you're on the management station, you can enroll even more hosts:

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

Again, this generates a DSA key pair and stores the private key portion in auth_key. 👀 Notice the --control option? That's what tells isnsadm to use the identity of the control node instead of the default key and source name. iykyk.

Then you gotta copy somehost.key over to the client host and install it as /etc/isns/auth_key. same energy for the server's public key (which lives in /etc/isns/auth_key.pub on the server) — copy it to the client machine and place it in /etc/isns/server_key.pub. 🫶

Okay so here's a thing people get confused about: by default, when a client registers a storage node (initiator or target, doesn't matter) with iSNS, that client can't see any other storage nodes. literally none. so for targets to be visible to a given initiator, you need to create what are called Discovery Domains — or DDs for short. 💅

ngl, currently domain membership operations require administrator privilege. Future extensions may allow iSNS clients to add themselves to one or more DDs upon registration — but that's a someday thing, not a today thing.

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

And to add members to an existing DD, you have to specify the numeric domain ID — using the DD name is just not sufficient, unfortunately. 😭 (this is a requirement of the RFC, not an implementation issue, so don't come for the devs, they're innocent):

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

Wanna know what the DD ID actually is? just query for the DD name, bestie:

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

---

🌸 management mode things 🌸

In management mode you can also register and deregister nodes and portals manually, in case you wanna fix up an inconsistency in the database. like a lil cleanup arc. 🧹 for instance, this registers 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

⚠️ IMPORTANT ⚠️ notice how this registration explicitly specifies the network entity the new objects go into. if you omit that, the new objects land in an entity named CONTROL, which is decidedly not what you want. do not let this happen to you. 🙈

---

🔥 SEE ALSO 🔥

• RFC 4171
• isnsd(8)
• isns_config(5)

---

👑 AUTHORS 👑

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

---

and that's the whole page, bestie!! this edition is from 11 May 2007, filed under ISNSADM(8). go forth and enroll things responsibly 💜✨🎀