tritonadm cn

tritonadm cn manages compute-node registration and approvals. The family has six direct commands (list, show, approve, disable, root-password, exec) and five groups: label, reservoir, auto-approve, boot, and setup.

Execution context

Every command in this family is an HTTP call against a running tritond. The commands run on any host that has tritonadm installed and resolves both an endpoint and a credential. No command in this family runs vmadm, imgadm, or zlogin. No command in this family requires the head node global zone.

Every command in this family accepts the two global options, --endpoint <URL> and --api-key <KEY>. The tritonadm command index documents their resolution order.

The synopsis blocks below are usage forms, not terminal transcripts.

Compute node states

CnState has five wire values. tritonadm cn list --state accepts only the first three.

Wire value	Meaning	Accepted by --state
pending	Self-registered, awaiting approval. Carries an active claim code until approval or expiry.	Yes
approved	Approved and active. The bound per-CN API key is the agent's credential for the rest of /v1/agent/*.	Yes
disabled	Explicitly disabled by an operator. The record stays for audit visibility.	Yes
awaiting_setup	Discovered over the boot bus, not yet running tritonagent. No claim code, no credential.	No
setting_up	Approved for setup. The boot bus is authorized to drive zpool creation and install.	No

cn list and cn show print all five values. The --state filter accepts only the first three, because the CLI's value enum has three variants. A node in awaiting_setup or setting_up appears in the unfiltered list and in --json output.

Placement roles

CnRole has three wire values. tritonadm cn label set --role sets the value.

Wire value	Meaning
tenant	Eligible for tenant workload placement. This is the default for a new compute node.
edge	Eligible for north and south edge placement.
both	Eligible for tenant workload placement and for north and south edge placement.

tritonadm cn list

Synopsis

tritonadm cn list [--state <STATE>] [--json]

Description

Lists registered compute nodes, with an optional state filter. The command calls GET /v1/system/cns and requires the SystemRead capability. The server rejects a caller without that capability.

With --json, the command prints the full results page. Without it, the command prints a fixed-width table, or this line when no compute node matches:

(no compute nodes)

Arguments and options

Argument or option	Type	Default	Description
--state <STATE>	pending, approved, disabled	No filter	Restrict the list to one state.
--json	flag	off	Print the raw results page as JSON.

Columns

Column	Source field
SERVER_UUID	server_uuid
HOSTNAME	hostname
STATE	state
ROLE	role
ADMIN_IP	admin_ip, or - when unset
REGISTERED_AT	registered_at, as RFC 3339

tritonadm cn show

Synopsis

tritonadm cn show <SERVER_UUID> [--json]

Description

Reads one compute node. The command calls GET /v1/system/cns/{cn_id} and requires the SystemRead capability.

With --json, the command prints the whole CnView. Without it, the command prints a labeled block, then the node's sysinfo blob, indented.

Arguments and options

Argument or option	Type	Default	Description
<SERVER_UUID>	UUID, positional, required		The SmartOS server_uuid of the compute node.
--json	flag	off	Print the raw CnView as JSON.

Printed fields

Label	Notes
state	One of the five wire values.
role	One of tenant, edge, both.
hostname
admin_ip	- when unset.
registered_at	RFC 3339.
approved_at	RFC 3339, or - when unset.
last_seen	RFC 3339, or - when unset.
claim_code	Printed only while a claim code is present, followed by claim_code_expires_at.
bound_api_key_id	Printed only when a key is bound. The key plaintext is never printed.
sysinfo	The full nested blob, pretty-printed and indented two spaces.

The server removes secret boot parameters from sysinfo at the serve boundary, so root_shadow and rabbitmq never appear in it.

The --json output carries fields the plain output omits, including last_status, last_setup_error, setup_progress, and disk_layout.

tritonadm cn approve

Synopsis

tritonadm cn approve <CODE> [--json]

Description

Approves a pending compute node by its claim code. The command calls POST /v1/cn-approvals. The server applies a per-source-IP rate limit before any authorization work runs. The server mints the per-CN API key inside the same transaction that changes the state.

The claim code is six characters of Crockford base32. The alphabet is 0123456789ABCDEFGHJKMNPQRSTVWXYZ. It omits O, I, L, and U to prevent console misreads. The code is displayed as XXX-XXX and expires one hour after the server mints it. The command removes whitespace and hyphens and uppercases the input before it sends it, so abc-def, ABCDEF, and ABC-DEF are all the same code.

The operator never sees the plaintext API key. The key reaches the agent through the agent's long-poll on /v1/agent/register/status. The operator sees only the bound key id, which correlates the approval to later audit events.

On success without --json, the command prints:

Approved CN <SERVER_UUID>; bound api key id <KEY_ID>

When no key is bound, the key id renders as (none).

The server returns 404 for an unknown, expired, or already-approved code. The three cases return one status so that the endpoint cannot be used to enumerate valid codes. The server returns 429 when the per-IP bucket is empty. The server rejects a code that is not six characters of the alphabet with 400 and this message:

claim code must be 6 chars of Crockford base32 (XXX-XXX accepted)

Arguments and options

Argument or option	Type	Default	Description
<CODE>	string, positional, required		Six-character claim code displayed on the compute node's console. XXX-XXX and XXXXXX are both accepted.
--json	flag	off	Print the resulting CnView as JSON. The wire shape is redacted and never contains the plaintext key.

tritonadm cn disable

Synopsis

tritonadm cn disable <SERVER_UUID> [--json]

Description

Changes a compute node to disabled. The command calls POST /v1/cns/{server_uuid}/disable. The server keeps the record for audit visibility. A second call against an already-disabled node is idempotent.

A fresh anonymous registration from the same server_uuid returns a disabled record to pending with a new claim code. This is the supported path back to an active node.

On success without --json, the command prints:

Disabled CN <SERVER_UUID> (state=disabled)

warning

The command help and the API description both state that disable revokes the bound API key. The handler does not do that today. The revocation branch logs TODO: revoke bound api key (slice C-3) and holds a placeholder in place of the delete. Treat the bound key as still valid after a disable. Delete the key explicitly if the credential itself is the concern.

Arguments and options

Argument or option	Type	Default	Description
<SERVER_UUID>	UUID, positional, required		The compute node to disable.
--json	flag	off	Print the resulting CnView as JSON.

tritonadm cn label set

Synopsis

tritonadm cn label set <SERVER_UUID> --role <ROLE> [--json]

Description

Sets the placement role that the placers read for this compute node. The command calls POST /v1/cns/{server_uuid}/role. label has exactly one subcommand, set.

On success without --json, the command prints:

Set CN <SERVER_UUID> role to <ROLE>

Arguments and options

Argument or option	Type	Default	Description
<SERVER_UUID>	UUID, positional, required		The compute node to label.
--role <ROLE>	tenant, edge, both, required		Placement role. See Placement roles.
--json	flag	off	Print the resulting CnView as JSON.

tritonadm cn reservoir set

Synopsis

tritonadm cn reservoir set <SERVER_UUID> [--enabled <BOOL>] [--percent <FLOAT>] [--json]

Description

Sets the per-compute-node bhyve memory reservoir override. The command calls POST /v1/cns/{server_uuid}/reservoir. The body fully replaces the override.

The reservoir floor is a fraction of physical RAM. Neither tritonadm nor tritond range-checks --percent. tritonagent clamps the effective value to 0.0 through 1.0 and to the kernel reservoir limit before it applies the value.

The response carries both the stored override and the effective values after the server applies the cluster defaults. Without --json, the command prints the override with (inherit) in place of a cleared field, then the effective pair:

CN <SERVER_UUID> reservoir override:
  enabled: (inherit)
  percent: (inherit)
  effective: enabled=true percent=0.80

warning

An omitted flag does not mean "leave unchanged". The request sends null for any flag you do not pass. A null clears that field, so the compute node inherits the cluster default. Passing only --percent also clears an existing --enabled override, and the reverse. Pass both flags on every set to keep both pinned.

Arguments and options

Argument or option	Type	Default	Description
<SERVER_UUID>	UUID, positional, required		The compute node to override.
--enabled <BOOL>	true or false	Field cleared when omitted	Enable or disable the reservoir on this compute node.
--percent <FLOAT>	float	Field cleared when omitted	Reservoir floor as a fraction of physical RAM, 0.0 through 1.0.
--json	flag	off	Print the resulting CnReservoirView as JSON.

Cluster defaults

A cleared field inherits a cluster-wide setting. tritonadm config reads and writes these settings.

Setting key	Built-in default
reservoir.enabled_default	true
reservoir.percent_default	0.80

tritonadm cn reservoir clear

Synopsis

tritonadm cn reservoir clear <SERVER_UUID> [--json]

Description

Clears the per-compute-node reservoir override so that the node inherits the cluster defaults. This is reservoir set with both fields absent. The command sends the same POST /v1/cns/{server_uuid}/reservoir with reservoir_enabled and reservoir_percent both null, and prints the same block.

Arguments and options

Argument or option	Type	Default	Description
<SERVER_UUID>	UUID, positional, required		The compute node whose override is cleared.
--json	flag	off	Print the resulting CnReservoirView as JSON.

tritonadm cn auto-approve status

Synopsis

tritonadm cn auto-approve status [--json]

Description

Reads the current auto-approve window. The command calls GET /v1/cn-auto-approve. The command sends this GET directly rather than through the generated client, so a null body parses as "no window" instead of a deserialization failure.

When no window is open the command prints:

No window open.

When a window is open the command prints Auto-approve window: followed by four fields: opened_at, expires_at, remaining_count, and opened_by. remaining_count renders as (unlimited) when the window is time-bound only. opened_by is the authenticated principal captured when the window was opened.

With --json, the command prints null or the window object.

Arguments and options

Argument or option	Type	Default	Description
--json	flag	off	Print the window, or null, as JSON.

tritonadm cn auto-approve open

Synopsis

tritonadm cn auto-approve open --duration-secs <SECS> [--count <N>] [--json]

Description

Opens or replaces the auto-approve window. The command calls POST /v1/cn-auto-approve. While the window is open, the server promotes new self-registrations to approved without operator action, so no claim code is exchanged.

Wall time bounds the window. A count budget is optional and also bounds it. The server clamps duration_secs to 24 hours, so a mistyped 86400000 becomes a 24-hour window rather than a multi-year one. The audit record captures both the requested and the effective duration.

On success without --json, the command prints Auto-approve window opened: followed by the same four fields that status prints.

Arguments and options

Argument or option	Type	Default	Description
--duration-secs <SECS>	integer, required		How long to keep the window open. The server clamps the value to 86400.
--count <N>	integer	Unlimited	Maximum number of registrations to auto-approve before the window closes early. Omit for a time-bound window.
--json	flag	off	Print the resulting window as JSON.

tritonadm cn auto-approve close

Synopsis

tritonadm cn auto-approve close

Description

Closes the auto-approve window early. The command calls DELETE /v1/cn-auto-approve. The call is idempotent. A call with no window open does nothing and still reports success.

The command prints:

Auto-approve window closed.

Arguments and options

close takes no arguments and no command-specific options. The command still accepts the two global options.

tritonadm cn root-password

Synopsis

tritonadm cn root-password <CN> [--hash <HASH> | --clear | --password-stdin]

Description

Sets or clears a compute node's global-zone root password. The command prompts for the password unless --hash, --clear, or --password-stdin is given. The server stores only the sha512-crypt hash. The hash applies at the node's next netboot, where the booter emits it as the root_shadow boot parameter.

Arguments and options

Argument or option	Type	Default	Description
<CN>	hostname, UUID, or UUID prefix, positional, required		The compute node.
--hash <HASH>	string	prompt	Store this pre-computed sha512-crypt hash ($6$salt$hash) verbatim.
--clear	flag	off	Clear the stored password. The next netboot sets none.
--password-stdin	flag	off	Read the plaintext password from stdin instead of prompting.

tritonadm cn exec

Synopsis

tritonadm cn exec [OPTIONS] <COMMAND>

Description

Runs a command on compute-node global zones over SSH, in parallel. The command reaches each target as root at its recorded admin IP. Distribute your key first with the cn.root_authorized_keys setting. With --script, the command copies the local file to the compute node and runs it there.

tritonadm cn boot

Synopsis

tritonadm cn boot list
tritonadm cn boot show <MAC>
tritonadm cn boot assign <MAC> --pi <PI_STAMP>
tritonadm cn boot declared
tritonadm cn boot converge
tritonadm cn boot policy show
tritonadm cn boot policy set [--enrollment-pi <PI_STAMP>] [--auto-enroll <BOOL>] [--enrollment-kernel-arg <ARG>]...

Description

Netboot boot records, one per admin-network MAC, and the site-wide boot policy.

Command	Description
boot list	List boot records.
boot show <MAC>	Show one boot record by admin-network MAC.
boot assign <MAC> --pi <PI_STAMP>	Set the platform image a compute node boots next. Takes effect on the next netboot. The stamp must be staged on the booter (tritonadm pi list).
boot declared	The answers-declared node roster joined with live state: which declared machines have netbooted, enrolled, or not appeared yet. The join is by MAC. A declared aggregate's first member is the node's boot MAC.
boot converge	Write declared networking (hostname, bond, nic tags) again onto boot records that enrolled before the declaration changed. Each record applies the change at its next netboot.
boot policy show	Show the site-wide boot policy.
boot policy set	Update enrollment_pi, auto_enroll, or the enrollment kernel arguments. Unspecified fields are preserved. The allowlist and admin network are editable only through the API.

Options on boot policy set

Option	Type	Description
--enrollment-pi <PI_STAMP>	string	Platform-image stamp served to enrolling nodes.
--auto-enroll <BOOL>	true or false	Enable or disable auto-enroll of discovered nodes.
--enrollment-kernel-arg <ARG>	string, repeatable	Replace the enrollment kernel arguments. Omit to leave unchanged.

tritonadm cn setup

Synopsis

tritonadm cn setup plan <CN>
tritonadm cn setup approve <CN> --layout <LAYOUT> [--width <N>] [--spares <N>] [--exclude <DISK>]... [--no-cache] [--compress <VALUE>] [--hostname <HOSTNAME>]

Description

The ur-enrollment setup lifecycle. A netbooted node has no claim code. The boot-policy allowlist already admitted it, and setup approval is the remaining operator gate.

setup plan shows the announced disk inventory and the proposed pool layout. The proposal is advisory. approve confirms an explicit choice.

setup approve confirms the pool layout and starts the cn-setup saga. It is destructive on the compute node: the installer wipes the disks in the confirmed layout.

Options on setup approve

Option	Type	Default	Description
<CN>	hostname, UUID, or UUID prefix, positional, required		The compute node in awaiting_setup.
--layout <LAYOUT>	single, mirror, raidz1, raidz2, raidz3, required		Confirmed pool layout keyword.
--width <N>	integer	disklayout picks	Fixed stripe width.
--spares <N>	integer	auto	Fixed spare count. 0 means exactly zero spares.
--exclude <DISK>	disk name, repeatable	none	Disk to keep out of the pool.
--no-cache	flag	off	Disable the L2ARC cache assignment.
--compress <VALUE>	lz4, zstd, off	pool default	zpool compression property.
--hostname <HOSTNAME>	RFC 1123 label	announce-time hostname	Nodename persisted to the node's node.config.

Endpoints and authorization

Command	Method and path	Authorization
cn list	GET /v1/system/cns	Capability SystemRead
cn show	GET /v1/system/cns/{cn_id}	Capability SystemRead
cn approve	POST /v1/cn-approvals	Action CnApprove, plus a per-source-IP rate limit checked first
cn disable	POST /v1/cns/{server_uuid}/disable	Action CnDisable
cn label set	POST /v1/cns/{server_uuid}/role	Action CnSetRole
cn reservoir set	POST /v1/cns/{server_uuid}/reservoir	Action CnSetReservoir
cn reservoir clear	POST /v1/cns/{server_uuid}/reservoir	Action CnSetReservoir
cn auto-approve status	GET /v1/cn-auto-approve	Action AutoApproveGet
cn auto-approve open	POST /v1/cn-auto-approve	Action AutoApproveSet
cn auto-approve close	DELETE /v1/cn-auto-approve	Action AutoApproveClear

cn approve, cn disable, cn label set, and both reservoir commands write an audit record on success.

Operations this command family does not cover

tritonadm cn has no subcommand for the following operations. Each exists only as a tritond HTTP endpoint and, where noted, in the operator console.

Operation	Endpoint
Factory-reset a node back to awaiting_setup	POST /v1/cns/{server_uuid}/factory-reset
Remove a node from the control plane	DELETE /v1/cns/{server_uuid}
Read or replace placement traits	GET and POST /v1/cns/{server_uuid}/traits
Dry-run a drain plan	POST /v1/cns/{server_uuid}/drain/preview
Authorize, rescue, or decommission one boot record	POST /v2/cn-boot/{mac}/authorize, .../rescue, .../rescue/clear
Replace the boot policy allowlist or admin network	PUT /v2/cn-boot-policy

There is also no tritonadm command for instance console, VNC, or serial access at any level of the CLI.

See also

• Enroll a compute node
• Reset or remove a compute node
• Compute node lifecycle
• tritonadm command index
• tritonadm setup
• tritonadm install