tritonadm install

tritonadm install fetches one artifact from the signed release channel and installs it on the host the command runs on. It has no subcommands.

The command resolves <NAME> against the channel manifest and picks the install mechanism from where the name appears: an entry under images drives imgadm install, an entry under agents drives a global-zone tarball extraction plus, for tritonagent, an SMF import and enable.

Run it in the head node global zone. It writes under /opt/triton and /opt/custom/smf and shells out to imgadm, /usr/bin/gtar, svccfg, svcadm, and svcs, all of which require root.

Synopsis

tritonadm install <NAME> [OPTIONS]
tritonadm install --list [OPTIONS]

Arguments

Argument	Description
<NAME>	Name of the image or agent to install, as keyed in the channel manifest, for example triton-platform or tritonagent. Required unless --list is given.

Options

Option	Effect
--stamp <STAMP>	Require the channel entry for <NAME> to carry this build stamp. A mismatch aborts before anything is downloaded.
--channel <NAME>	Named channel shorthand. Expands to https://tritoncloud.nyc3.digitaloceanspaces.com/channels/<NAME>.json. With neither --channel nor --channel-url, the cluster's channel.upstream_url is used.
--channel-url <URL>	Use this manifest URL verbatim. Wins over --channel.
--revision <REV>	Install from a sealed revision's frozen snapshot instead of the moving channel pointer.
--list	Print the channel's contents with installed status and exit. No artifact is installed.

Every option is long form. tritonadm install declares no short flags and no --image-dir, --dry-run, or --yes option.

With no channel flag, the command reads the cluster's channel.upstream_url through tritond, so --endpoint and --api-key apply to that read. With --channel or --channel-url, the command talks to the channel and the local host only.

Channel resolution

The effective manifest URL is resolved in this order:

1. --channel-url <URL>, used verbatim.
2. --channel <NAME>, expanded to https://tritoncloud.nyc3.digitaloceanspaces.com/channels/<NAME>.json.
3. The cluster's channel.upstream_url setting, read through tritond. The command prints channel <NAME> (from channel.upstream_url).

There is no built-in default channel. With no channel flag and no tritond session, the command fails with no --channel given, and the cluster's channel could not be read; pass `--channel edge` (or `stable`, or `--channel-url URL`). With a session but no channel.upstream_url, it fails with a message that begins no release channel:.

--revision <REV> then rewrites the resolved URL by stripping the trailing .json and appending /<REV>.json, so .../channels/edge.json becomes .../channels/edge/<REV>.json. A base URL that does not end in .json is left unchanged. tritonadm channel revisions lists the ids --revision accepts.

The manifest and its sibling <URL>.minisig are both fetched, and the detached signature is verified against the publisher public key compiled into the binary before the manifest is parsed. tritonadm understands manifest schema version 1 and refuses a manifest that declares a higher schema.

The channel fetch trusts only the Mozilla root certificates bundled into the binary, through the host-resources client. The HTTP client has a 30 second connect timeout and no whole-request timeout, so a multi-gigabyte image download is not cut off by the clock.

Name resolution

The manifest is searched in a fixed order:

1. manifest.images (zone images).
2. manifest.agents (global-zone tarballs).

The first map that holds the name decides the mechanism. The manifest's services and tritonadm maps are not consulted, so a name that appears only there, including tritonadm itself, is reported as unknown.

Installing an image

For a name found under images:

1. The installed image uuids are read with imgadm list -H -o uuid. When the entry's uuid is already present the run records a no-op, and nothing is downloaded.
2. Otherwise a staging directory is created under /var/tmp, not /tmp, because /tmp on a SmartOS head node is swap-backed tmpfs.
3. The imgadm manifest is fetched to <NAME>.json in that directory.
4. The content blob is streamed to <NAME>.zfs.gz and hashed in flight through a 128 KiB buffer, so the image is never held in memory in full.
5. The computed SHA-256 is compared against the sha256 recorded in the signed channel manifest.
6. imgadm install -m <manifest path> -f <content path> runs.
7. The staging directory is removed when the command exits.

The image is installed on the host. No zone is created, reprovisioned, or restarted.

Installing an agent

For a name found under agents, the install is a resource group: the bundle, then, only when the name is tritonagent, its SMF service.

The bundle step:

1. The installed stamp is read from /opt/triton/<NAME>/etc/version. When it equals the channel entry's stamp the run records a no-op and nothing is downloaded. A different stamp is recorded as an update, an absent file as a create.
2. The tarball is downloaded to a temporary directory and hashed in flight, and the digest is compared against the signed manifest.
3. The archive is listed with /usr/bin/gtar -tzf and classified before anything is extracted. Any entry with an absolute path or a .. segment is refused, and so is an empty archive.
4. A self-contained bundle, whose entries all live under <NAME>/, extracts with -C /opt/triton. /opt/triton is created mode 0755 if it does not exist.
5. A legacy ./-rooted bundle, whose entries are all under ./opt/ or ./var/, extracts with -C /.
6. Either way gtar runs with --no-overwrite-dir, so the archive cannot rewrite the permissions of directories that already exist.

The SMF step runs for tritonagent only:

1. /opt/triton/tritonagent/smf/tritonagent.xml is read and checked for a <service name='site/tritonagent'> declaration. A manifest that does not declare it is rejected before import.
2. A copy is written to /opt/custom/smf/tritonagent-tritonagent.xml mode 0644. That directory is persistent and is re-scanned by the platform at boot, which is what makes the service survive a reboot: the global zone runs from a ramdisk and the SMF repository itself does not.
3. svccfg import runs, and svcs is queried to confirm site/tritonagent is registered.
4. When the service is not already online, svcadm clear runs, then svcadm enable -s site/tritonagent.
5. When the service was already online and the bundle changed in this run, svcadm restart site/tritonagent runs.

proteusadm is a CLI-only bundle with no SMF manifest, so installing it registers, enables, and restarts nothing.

warning

An agent install applies without a confirmation prompt, including the case where it replaces an existing bundle and restarts site/tritonagent on a running head node.

Stamp pinning

--stamp is a guard, not a selector. The channel entry's stamp is compared against the requested one and the run aborts on a mismatch. It never downloads a stamp the channel does not currently advertise, so it cannot be used to reach back to a superseded build. Use --revision for that.

Listing the channel

--list fetches and verifies the manifest, prints it, and exits. It is evaluated before <NAME>, so a name passed alongside --list is ignored.

The listing has four parts:

Section	Contents
Header	The channel name and the manifest's updated_at timestamp.
=== images ===	Each image name, its stamp, its uuid, and [installed] when that uuid is in imgadm list -H -o uuid.
=== agents ===	Each agent name, its stamp, and either [installed, current] when /opt/triton/<NAME>/etc/version matches the channel stamp or [installed <STAMP>] when it differs.
=== tritonadm ===	Each target triple in the manifest's tritonadm map and its stamp. No installed status is shown.

Entries in the manifest's services map are not listed.

The installed-status probe for images is best effort: when imgadm list fails, images are reported as not installed rather than erroring, so --list still works off a head node.

Plan output and prompting

Both paths run through the same resource engine as tritonadm setup apply. The planned changes are printed first, followed by a summary line of the form plan: N to create, N to change, N to destroy. Change lines are colored when stdout is a terminal and NO_COLOR is unset.

tritonadm install always applies with confirmation suppressed. It does not prompt, and it has no dry-run option.

Progress is logged to stderr. With no RUST_LOG set the filter is warn,host_resources=info, which is what surfaces the install milestones.

Errors

Condition	Message
Neither <NAME> nor --list	usage: tritonadm install <name> | tritonadm install --list
Name in neither map	no image or agent named `<NAME>` in channel <URL>. try `tritonadm install --list` to see what is available.
--stamp mismatch	channel currently points at stamp `<CHANNEL_STAMP>` but --stamp asked for `<REQUESTED>`. Either drop --stamp (to take whatever the channel points at now) or republish/promote the desired stamp into the channel first.
Signature check failed	channel signature did NOT verify against the publisher pubkey
No channel flag and no session	no --channel given, and the cluster's channel could not be read; pass `--channel edge` (or `stable`, or `--channel-url URL`)
Image digest mismatch	downloaded image content sha256 does NOT match channel manifest
Agent digest mismatch	downloaded agent tarball sha256 does NOT match channel manifest
Bundle entry with an absolute path	agent bundle entry has an absolute path: <ENTRY>
Bundle entry with a .. segment	agent bundle entry escapes its tree with `..`: <ENTRY>
Bundle matching neither layout	agent bundle <NAME> has an unrecognized layout: entries are neither all under `<NAME>/` (self-contained) nor all `./`-rooted (legacy)
Empty bundle	agent bundle tarball has no entries
SMF manifest names the wrong service	manifest <PATH> does not declare <service name='site/<NAME>'>

Limits

• The command installs exactly one artifact per invocation. There is no --all.
• There is no --image-dir. Installing from a local build directory is available on tritonadm setup apply and tritonadm update, not here.
• The pi_min field on a channel entry is not read by this command. Nothing in the install path compares it against the running platform image.
• Installing an image does not update a zone. tritonadm update is what reprovisions a running zone onto a new image.

See also

• tritonadm command index
• tritonadm setup
• tritonadm self-update
• Updates and release channels
• Install the tritonadm CLI
• Genesis on the founder