Luna2 REST API Fields

This page lists the fields a request body may carry for each object of the Luna2 REST API. A create or update request sends one object under its route segment and its name:

{"config": {"<object>": {"<name>": {"<field>": "<value>", ...}}}}

The name in the URL says which object is meant. A body that also carries name should carry the same name; for nodes, groups, networks, BMC setups, OS images, switches, other devices and racks a different name is refused. Where an object has a different body shape, its section says so.

How to read the tables

Column Meaning
Field The key as it is sent in the body. A reference to another object is sent by name (osimage, not the internal id).
Presence required on create, optional, request only (an instruction, not stored as such: renames, clone options), or read-only (appears in responses; a request that sends it is refused, or the value is ignored or replaced — the row says which).
Expected What the daemon accepts.
Default The value applied when the field is left out on create, or "inherited from …" where the daemon resolves the value from another object when the field is empty.
Notes Only where needed.

Rules that apply to every object

  • Names. Three rules recur in the tables below:
    • name rule: a-z A-Z 0-9, space, -, _ and .; at most 253 characters. Repeated dots are collapsed to one.
    • strict name rule: a-z 0-9, - and . (lower case, no spaces). Applies to the names of nodes, switches, other devices and profiles.
    • DNS name rule: lower-case labels of a-z, 0-9 and -, 1 to 63 characters each, not starting or ending with -. Applies to network names.
    • Under the name and strict name rules the words default and inventory are refused. The DNS name rule does not refuse them.
  • Booleans accept true/false, yes/no, y/n and 1/0, and responses return true or false. Another value is not refused: it is stored and returned as sent.
  • Base64. Scripts, disk layouts, mounts documents, options, ztpconfig and file content are sent base64-encoded. The luna CLI also sends comment, kerneloptions, grab_filesystems and grab_exclude base64-encoded; the daemon stores what it receives and accepts plain text for these as well.
  • Free text. Control characters and single and double quotes are removed from every string before it is stored. A field with its own rule is checked as sent, so a quote makes most values fail the rule; the rules of an interface's interface and vlan_parent let a quote through, and it is then removed.
  • Unknown fields. Most objects refuse a key that is not one of their fields with a 400. Static routes, DNS entries, rack devices and the interfaces entries of nodes, groups and switches ignore it. A secrets list answers success but does not store that entry, and a rack update answers success but stores none of the rack's own fields. A rack create and a BIOS configuration change refuse it with a 404, and a firmware catalogue create fails with a 500.
  • Clearing. Sending an empty string clears an optional field, where the notes do not say otherwise.
  • Ownership. Cluster, node, group, network, BMC setup, Redfish setup, BIOS configuration, firmware catalogue, OS image, profile, switch, other device, static route, rack and cloud objects also carry owners (user names, comma-separated), usergroups (usergroup names, comma-separated) and access (rwxrwxrwx with - for an absent bit, or three octal digits). Rootus and admin users may set them in a create or update body, except that a BIOS configuration change refuses them for every caller (its _clone body may carry them) and a static route ignores them. For any other caller a body that names them is refused with a 403. The _chown, _chgrp and _chmod actions change them for everyone with the right to do so.
  • Inherited values. A node or group response marks where each resolved value came from with read-only _<field>_source keys (node, group, osimage, bmcsetup, cluster, network or default), and _override is true when the object sets a value of its own.

Cluster

Body: {"config": {"cluster": {"<field>": ...}}}, without a name level.

Field Presence Expected Default Notes
name optional name rule mycluster
controller read-only; request only as an address IPv4 or IPv6 address The response carries the primary controller's details. Sent as an address, it renumbers the primary controller.
<controller hostname> read-only; request only as an address IPv4 or IPv6 address The same for the other controllers; a - in the hostname is written as _.
controller_network request only name of an existing network The network the new controller address belongs to.
ntp_server optional IPv4 addresses, comma-separated controller address IPv6 addresses are refused.
nameserver_ip optional IPv4 addresses, comma-separated controller address IPv6 addresses are refused.
forwardserver_ip optional IP addresses, comma-separated from the installer DNS forwarders.
domain_search optional domains, comma- or space-separated from the installer
technical_contacts optional text root@localhost
provision_method optional name of a provisioning plugin, such as torrent or http torrent The plugin must exist.
provision_fallback optional name of a provisioning plugin http Empty: no second method.
install_mode optional auto, sync, full, local, memboot, sanitize or legacy from the installer, else not set, which nodes read as legacy
mounts optional base64 JSON mounts document One entry at a time: /config/cluster/mounts.
debug optional boolean false Empty sets false.
security optional boolean false Empty sets false.
packing_bootpause optional boolean true Holds node boots while their OS image is being packed.
createnode_ondemand optional boolean true Empty sets true.
createnode_macashost optional boolean false Empty sets true.
nextnode_discover optional boolean false Empty sets false.
bind_legacy optional boolean from the installer, else false
dnssec_enable optional boolean Reads N/A unless bind_legacy is set.
dnssec_validation optional boolean Reads N/A when dnssec_enable is false.
user optional text Stored and returned; the daemon does not use it.

Node

Body: {"config": {"node": {"<name>": {...}}}}. The node name follows the strict name rule.

Field Presence Expected Default Notes
newnodename request only strict name rule, at most 63 characters Renames the node, or names the copy on _clone. Refused on create.
group required name of an existing group
osimage optional name of an existing OS image inherited from the group Setting it resets osimagetag.
osimagetag optional tag of that OS image: a-z A-Z 0-9, space, -, _, ., :, + inherited from the group, else default
kerneloptions optional text inherited from the OS image, else the group
ipxe_kernel optional default or alternative inherited from the group, else default
interfaces optional list of interface objects, see below the group's interfaces
switch optional name of an existing switch
switchport optional text (not checked)
cloud optional name of an existing cloud
service optional boolean false Halts the installer in service mode.
bmcsetup optional name of an existing BMC setup inherited from the group
redfishsetup optional name of an existing Redfish setup inherited from the group
biosconfig optional name of an existing BIOS configuration inherited from the group
setupbmc optional boolean inherited from the group, else false
setupredfish optional boolean inherited from the group Reads null when the node has no value of its own.
unmanaged_bmc_users optional disable, delete or empty inherited from the group, else the BMC setup
roles optional role plugin names, comma-separated (a-z 0-9 - .) inherited from the group Each plugin must exist.
scripts optional script plugin names, comma-separated (a-z 0-9 - .) inherited from the group Each plugin must exist.
profiles optional profile names, comma-separated Applied in addition to the group's profiles.
routes optional static route names, comma-separated inherited from the group, else the networks Unknown names are ignored.
prescript optional base64 script inherited from the group
partscript optional base64 script inherited from the group
postscript optional base64 script inherited from the group
install_mode optional auto, sync, full, local, memboot, sanitize or legacy inherited from the group, else the cluster, else legacy
disklayout optional base64 JSON disk layout inherited from the group Checked when it is stored.
osimage_filter optional base64 text inherited from the group
mounts optional base64 JSON mounts document inherited from the group, else the cluster One entry at a time: /config/node/{name}/mounts.
netboot optional boolean inherited from the group, else false
bootmenu optional boolean inherited from the group, else false
provision_interface optional interface name inherited from the group, else BOOTIF
provision_method optional name of a provisioning plugin inherited from the group, else the cluster, else torrent An OS image of type kickstart forces kickstart.
provision_fallback optional name of a provisioning plugin inherited from the group, else the cluster, else http
vendor optional text
assettag optional text
tpm_uuid optional text TPM identity of the node.
tpm_pubkey optional text
tpm_sha256 optional text
comment optional text
status optional text (not checked) Responses show the install state from the monitor instead. A value sent is stored but not shown.
hostname read-only The name plus the provisioning network's domain.
profiles_digest optional text (not checked) Written by the daemon: the digest of the profiles last delivered to the node. A value sent is stored.

Node interfaces

Sent as the interfaces list of a node, or through /config/node/{name}/interfaces.

Field Presence Expected Default Notes
interface required interface name BOOTIF and BMC are the boot and BMC interfaces.
newinterfacename request only at least 3 characters: a-z A-Z 0-9 . - : Renames the interface.
network optional name of an existing network Without ipaddress, the next free address is assigned.
ipaddress optional IPv4 or IPv6 address next free address Empty clears it.
force request only boolean false Takes the address from another node's interface that holds it.
dhcp optional boolean false
macaddress optional six pairs of hex digits, separated by : or - Stored with :.
mtu optional number
vlanid optional digits or empty
vlan_parent optional interface name or empty
bond_mode optional name rule, or empty
bond_slaves optional interface names, comma-separated
options optional base64 text
ipaddress_ipv6 read-only An IPv6 address is sent in ipaddress.

Group

Body: {"config": {"group": {"<name>": {...}}}}. The group name follows the name rule.

Field Presence Expected Default Notes
newgroupname request only name rule Renames the group, or names the copy on _clone. Refused on create.
osimage optional name of an existing OS image Cannot be cleared. Setting it resets osimagetag.
osimagetag optional tag of that OS image default
bmcsetupname optional name of an existing BMC setup Cannot be cleared. On create it needs a BMC interface and sets setupbmc.
redfishsetupname optional name of an existing Redfish setup
biosconfig optional name of an existing BIOS configuration
setupbmc optional boolean false On create, true needs bmcsetupname.
setupredfish optional boolean
unmanaged_bmc_users optional disable, delete or empty inherited from the BMC setup
domain optional text
kerneloptions optional text inherited from the OS image
ipxe_kernel optional default or alternative default
interfaces optional list of interface objects, see below BOOTIF on the controller's network
roles optional role plugin names, comma-separated Each plugin must exist.
scripts optional script plugin names, comma-separated Each plugin must exist.
profiles optional profile names, comma-separated
routes optional static route names, comma-separated inherited from the networks Unknown names are ignored.
prescript optional base64 script empty
partscript optional base64 script a tmpfs root script with install_mode legacy, else empty
postscript optional base64 script an fstab line for that tmpfs root with install_mode legacy, else empty
install_mode optional auto, sync, full, local, memboot, sanitize or legacy inherited from the cluster, else legacy
disklayout optional base64 JSON disk layout Checked when it is stored.
osimage_filter optional base64 text
mounts optional base64 JSON mounts document inherited from the cluster One entry at a time: /config/group/{name}/mounts.
netboot optional boolean true
bootmenu optional boolean false
provision_interface optional interface name BOOTIF
provision_method optional name of a provisioning plugin inherited from the cluster, else torrent An OS image of type kickstart forces kickstart.
provision_fallback optional name of a provisioning plugin inherited from the cluster, else http
comment optional text

Group interfaces

Sent as the interfaces list of a group, or through /config/group/{name}/interfaces. Nodes in the group receive these interfaces.

Field Presence Expected Default Notes
interface required interface name
newinterfacename request only at least 3 characters: a-z A-Z 0-9 . - : Only through /config/group/{name}/interfaces; ignored in the group body's interfaces list.
network optional name of an existing network
dhcp optional boolean
mtu optional number
vlanid optional digits or empty
vlan_parent optional interface name or empty
bond_mode optional name rule, or empty
bond_slaves optional interface names, comma-separated
options optional base64 text

Network

Body: {"config": {"network": {"<name>": {...}}}}. The network name follows the DNS name rule. An IPv6 value is sent in the same field as an IPv4 one; the daemon stores it in the matching _ipv6 field, which is read-only.

Field Presence Expected Default Notes
newnetname request only DNS name rule Renames the network.
network required IPv4 or IPv6 network in CIDR notation Stored as network and subnet, or their _ipv6 fields.
subnet optional prefix length (not checked) Set from network; sent without network, it is stored as sent.
gateway optional IP address inside the network Empty clears it.
gateway_metric optional integer 101 with a gateway, 100 in an external zone
nameserver_ip optional IP addresses, comma-separated IPv4 and IPv6 addresses are stored apart.
ntp_server optional IP address or host name
dhcp optional boolean true needs a DHCP range.
dhcp_range_begin optional IP address inside the network
dhcp_range_end optional IP address inside the network
dhcp_nodes_in_pool optional boolean false true enables dhcp.
dhcp_nodes_only optional boolean false true clears the DHCP ranges.
dhcp_relay optional IP addresses, comma-separated Only on a shared network. Empty also clears dhcp_link_subnet.
dhcp_link_subnet optional IPv4 or IPv6 networks in CIDR notation, comma-separated Needs dhcp_relay; not the network's own subnet.
shared optional name of the network this one is shared with Not checked to exist.
zone optional internal or external internal
type optional ethernet or infiniband
non_authoritative optional boolean
routes optional static route names, comma-separated Unknown names are ignored.
clear request only ipv4 or ipv6 Removes one address family; the other must be configured.
controller, <controller hostname> request only IP address New controller address when network changes.
comment optional text
network_ipv6, subnet_ipv6, gateway_ipv6, dhcp_range_begin_ipv6, dhcp_range_end_ipv6, nameserver_ip_ipv6 read-only Set through the fields above.

DNS

Additional host records of a network. Body: {"config": {"dns": {"<network>": [{"host": ..., "ipaddress": ...}, ...]}}}.

Field Presence Expected Default Notes
host required strict name rule, at most 63 characters A host may carry several addresses.
ipaddress required IPv4 or IPv6 address
replace request only boolean false Replaces the host's addresses with this one.

BMC setup

Body: {"config": {"bmcsetup": {"<name>": {...}}}}. The name follows the name rule.

Field Presence Expected Default Notes
newbmcname request only name rule Renames the setup, or names the copy on _clone.
userid optional integer 2
username optional text luna
password optional text a generated password
netchannel optional integer 2
mgmtchannel optional integer 2
cipher optional integer
unmanaged_bmc_users optional disable, delete or empty What happens to BMC users Luna does not manage.
comment optional text

Redfish setup

Body: {"config": {"redfishsetup": {"<name>": {...}}}}. The name follows the name rule.

Field Presence Expected Default Notes
newredfishsetupname request only name rule Renames the setup, or names the copy on _clone.
scheme optional https or http https
port optional 1 to 65535
verify optional boolean false Whether the BMC certificate is checked.
accounts optional list of account objects, see below Accounts left out are kept.
comment optional text

Redfish accounts

Field Presence Expected Default Notes
name required name rule Identifies the account within the setup.
username required on create text
password required on create text
role optional a-z A-Z 0-9 - _ .
comment optional text

BIOS configuration

Body: {"config": {"biosconfig": {"<name>": {...}}}}. A BIOS configuration is created by grabbing it from a node (POST /config/node/{name}/_biosgrab); a POST to a name that does not exist is refused.

Field Presence Expected Default Notes
newbiosname request only name rule Renames the configuration, or names the copy on _clone.
set request only object of attribute names and values Changes single attributes; each must be one the board publishes.
grab_exclude optional base64 text, comma-separated patterns
comment optional text
manufacturer, model, biosversion read-only From the grab.
grabbedfrom read-only The node it was grabbed from.
settings read-only Number of attributes.
attributes, labels read-only Only when one configuration is requested.
updated read-only

Firmware catalogue

Body: {"config": {"firmwarecatalog": {"<name>": {...}}}}. The name follows the name rule.

Field Presence Expected Default Notes
newfirmwarename request only name rule Renames the entry.
manufacturer required text
model required text
component required text
version required text
imagefile optional a bare file name Not checked to be staged; the response says where to stage it. A name the file server serves only with a token is refused.
updated optional text Not set by the daemon.
comment optional text

OS image

Body: {"config": {"osimage": {"<name>": {...}}}}. The name follows the name rule.

Field Presence Expected Default Notes
newosimage request only name rule, at most 127 characters Renames the image, or names the copy on _clone.
path optional directory Where the image tree lives.
kernelversion optional text Through /config/osimage/{name}/kernel the version is checked against the image.
kernelfile optional file name Written when the image is packed.
initrdfile optional file name Written when the image is packed.
imagefile optional file name Written when the image is packed.
kernelmodules optional module names, comma-separated ipmi_devintf, ipmi_si, ipmi_msghandler
kerneloptions optional text
grab_filesystems optional paths, comma-separated /, /boot, /var
grab_exclude optional patterns, comma-separated a list of system paths
distribution optional text, such as redhat or ubuntu
osrelease optional text
tag optional tag name: a-z A-Z 0-9, space, -, _, ., :, + default A new name creates the tag from the current files; empty clears it.
bare, nocopy request only boolean false Options of _clone and kernel.
assigned_tags read-only
comment optional text

OS image tag

Read-only. Tags are made with the tag field of an OS image and removed with /config/osimage/{name}/osimagetag/{tag}/_delete. A response carries name, osimage, kernelfile, initrdfile, imagefile, path, and the nodes and groups that use the tag.

Profile

Body: {"config": {"profiles": {"<name>": {...}}}} — the segment is profiles. The name follows the strict name rule. A profile needs a service or at least one file.

Field Presence Expected Default Notes
newprofilename request only strict name rule Renames the profile, or names the copy on _clone.
scope optional static or dynamic static
service optional service name
action optional restart, stop, reload, start or none none What is done to service.
enabled optional boolean true
files optional list of file objects, see below Files left out are kept.

Profile files

Field Presence Expected Default Notes
name required strict name rule Identifies the file within the profile.
content required on create base64 (not checked)
path required on create path on the node
owner optional user or user:group, as names or numbers root:root
mode optional 3 or 4 octal digits 644

Secrets

Secrets are sent as a list of entries:

  • node: {"config": {"secrets": {"node": {"<node>": [ ... ]}}}}
  • group: {"config": {"secrets": {"group": {"<group>": [ ... ]}}}}
  • cluster: {"config": {"secrets": {"cluster": [ ... ]}}}
Field Presence Expected Default Notes
name required name rule
newsecretname request only name rule Names the copy on _clone.
content required base64 In a list sent to a node, group or cluster every entry needs it, also an existing one; a secret changed through its own URL (.../{secret}) needs it only when new. Encrypted at rest when secret encryption is enabled.
path optional path on the node
owner optional user or user:group, as names or numbers root:root
mode optional 3 or 4 octal digits 600
resolved_owner read-only owner as numeric ids where they can be resolved.

Switch

Body: {"config": {"switch": {"<name>": {...}}}}. The name follows the strict name rule.

Field Presence Expected Default Notes
newswitchname request only strict name rule Renames the switch, or names the copy on _clone.
network optional name of an existing network For the management interface.
ipaddress optional IP address For the management interface.
macaddress optional six pairs of hex digits, separated by : or - For the management interface.
nonetwork request only boolean false Stores ipaddress without checking it against a network.
vendor optional text
ostype optional text: nvos, cumulus or generic
oid optional SNMP OID .1.3.6.1.2.1.17.7.1.2.2.1.2
read optional SNMP community public
rw optional SNMP community trusted
uplinkports optional ports, comma-separated Left out of switch port detection.
netboot optional boolean
tftp_enable optional boolean
default_url optional text
bootfile optional text
ztpconfig optional base64 text
ztpformat optional text (not checked): commands or yaml yaml serves ztpconfig as YAML; anything else, or no ztpconfig, serves commands.
url_protocol optional text (not checked): secure or plain plain points the switch at the controller's web server; anything else at the API.
url_server optional text
comment optional text

Switch interfaces

Sent through /config/switch/{name}/interfaces as an interfaces list.

Field Presence Expected Default Notes
interface required interface name
newinterfacename request only at least 3 characters: a-z A-Z 0-9 . - :
macaddress optional six pairs of hex digits, separated by : or -
network optional name of an existing network Used only with ipaddress; ignored without it.
ipaddress optional IP address Empty clears it.
mgmt optional boolean One management interface per switch; it cannot be unset, only moved.

Other device

Body: {"config": {"otherdev": {"<name>": {...}}}} — the segment is otherdev. The name follows the strict name rule.

Field Presence Expected Default Notes
newotherdevname request only strict name rule Renames the device, or names the copy on _clone.
network optional name of an existing network
ipaddress optional IP address
nonetwork request only boolean false Stores ipaddress without checking it against a network.
macaddress optional six pairs of hex digits, separated by : or -
vendor optional text
comment optional text

Static route

Body: {"config": {"route": {"<name>": {...}}}}. The name follows the name rule. Routes are coupled to a node, group or network with their routes field or the _couple action.

Field Presence Expected Default Notes
newname request only name rule Renames the route; couplings are kept.
destination required network or host in CIDR notation
gateway optional IP address of the same family as destination A route needs gateway or device.
device optional interface name
metric optional integer
comment optional text

Rack

Body: {"config": {"rack": {"<name>": {...}}}}. The name follows the name rule.

Field Presence Expected Default Notes
newrackname request only name rule Renames the rack.
room optional text
site optional text
order optional text ascending
size optional integer 42
devices optional list of device objects, see below

Rack devices

Field Presence Expected Default Notes
name required name of an existing device
type required on create node, switch, otherdevices or controller
position optional integer
height optional integer 1
orientation optional text front

Cloud

Body: {"config": {"cloud": {"<name>": {...}}}}. The name follows the name rule.

Field Presence Expected Default Notes
newcloudname request only name rule Renames the cloud.
type optional text
comment optional text

User

Body: {"config": {"user": {"<username>": {...}}}}. The name follows the name rule.

Field Presence Expected Default Notes
newusername request only name rule Renames the user.
password request only text Stored as a digest and never returned. Empty removes it.
source optional text (not checked), such as local, pam or ldap local Any text is stored; only a change after create is refused.
external_id optional text
enabled optional boolean true
admin optional boolean false
delegate optional boolean false
password_set read-only Whether a password is stored.
createdby read-only Set to the caller; a value sent is replaced.
created, lastlogin read-only
usergroups read-only Memberships and roles.

Usergroup

Body: {"config": {"usergroup": {"<name>": {...}}}}. The name follows the name rule.

Field Presence Expected Default Notes
newusergroupname request only name rule Renames the usergroup.
hardware optional boolean false Members with the admin or manager role may change hardware.
comment optional text
members read-only Changed through /config/usergroup/{name}/members.

Usergroup members

Body of /config/usergroup/{name}/members and .../members/_remove: {"config": {"usergroup": {"<name>": {...}}}}.

Field Presence Expected Default Notes
username required name of an existing user
role required admin, manager, operator or reader Not needed to remove.
source optional text local

Usergroup map

Maps a group of an external directory to a usergroup. Body of /config/usergroupmap and /config/usergroupmap/_remove: {"config": {"usergroupmap": {...}}}.

Field Presence Expected Default Notes
source required text, such as ldap
external_group required text without quotes
usergroup required name of an existing usergroup Not needed to remove.
role required admin, manager, operator or reader Not needed to remove.

Monitor

Node status, as the installer reports it. Body of POST /monitor/node/{name}: {"monitor": {"status": {"<node>": {...}}}}.

Field Presence Expected Default Notes
state required text, such as installer.started The progress of the node.
status optional text A message that goes with the state.

Journal

Internal: used between controllers to replicate changes. Body of POST /journal: {"journal": [ ... ]}.

Field Presence Expected Default Notes
function required text The call to replay.
object required text The object it applies to.
param optional text
payload optional text The request body of the call.
masteronly optional boolean
remoteonly optional boolean
misc optional text
sendfor, sendto, sendby optional controller host names
tries optional integer
created optional time

Internal tables

These tables are written by the daemon and have no request body of their own: controller, ha, queue, status, tracker, hash, reference, ownercache, ping, ipaddress, reservedipaddress, routemap, firmwarerequest, and nodeinventory with its disk, GPU, NIC and firmware tables. Interfaces, Redfish accounts, profile files, secrets, rack devices and usergroup members and maps are covered under their objects above.