Helios
@mccormick/heliosv2026.08.09.1
01README
Manage an illumos/Helios host over SSH from swamp. Five model types compose to provision and inventory zones with explicit ZFS layout and isolation/security controls:
@mccormick/helios/host— connection profile + uname/release probe -@mccormick/helios/zfs— remote ZFS dataset and pool ops, including encrypted datasets anddataset_load_keyto unlock them after a reboot@mccormick/helios/dladm— datalink and exclusive-IP VNIC management -@mccormick/helios/zone— zonecfg/zoneadm with hardened defaults (ip-type=exclusive, file-mac-profile, hardened limit-priv, capped-cpu/memory) plus a fan-outinventorymethod that gathers live usage, security state, network, storage, SMF health, and recent log lines for every zone in a single SSH session.@mccormick/helios/postgres— PostgreSQL inside a zone: pkgsrc install, initdb on a delegated dataset, TLS + SCRAM configuration, and idempotent certificate rotation that reloads only on change.
Brands: the illumos-native ipkg, lipkg, and pkgsrc brands, Oracle Solaris solaris, and bhyve for hardware VMs — subject to which brand packages the target host has installed. SSH key supplied by the user's ssh-agent (e.g. the 1Password SSH agent); no key material flows through swamp. Privileged commands run via pfexec so the model can connect as a non-root user with the relevant Solaris RBAC profiles.
02Models
@mccormick/helios/hostv2026.05.14.4helios_host.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| sshUser | string | Default SSH user; recommended: a non-root user with Solaris RBAC |
| sshPort? | number | Default SSH port |
| sshKnownHosts? | string | Path to a known_hosts file. Omit to use accept-new on first connect. |
fn lookup()
Probe the Helios host for hostname, illumos build, helios release,
fn thermal()
Read-only thermal snapshot. Aggregates prtdiag -v, kstat fan/temp
fn load()
Read-only load snapshot: load average, per-core CPU, top processes,
fn faults()
Read-only fault snapshot: active faults from fmadm plus the most
fn messages(pattern: string, lines: number)
Filtered tail of /var/adm/messages and the fmd service log. The
| Argument | Type | Description |
|---|---|---|
| pattern | string | |
| lines | number |
fn health_check(messagePattern: string, messageLines: number)
Fan-out: gather thermal + load + faults + recent messages in a
| Argument | Type | Description |
|---|---|---|
| messagePattern | string | |
| messageLines | number |
Resources
host_info(infinite)— Probed identity and capacity of the Helios host
thermal(7d)— Temperature/fan sensor snapshot from prtdiag, kstat, and (when
load_snapshot(7d)— CPU/IO/memory pressure snapshot: load averages, per-core CPU, top
fault_state(7d)— Active faults from fmadm and recent ereports from fmdump. One per
kernel_messages(7d)— Filtered lines from /var/adm/messages and the fmd service log
audit(7d)— Combined host health audit: thermal + load + faults + recent
@mccormick/helios/zfsv2026.08.04.1helios_zfs.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| sshUser | string | |
| sshPort? | number | |
| sshKnownHosts? | string |
fn dataset_list()
List all filesystem and volume datasets on the host.
fn dataset_lookup(name: string)
Look up one dataset's full property set.
| Argument | Type | Description |
|---|---|---|
| name | string |
fn dataset_create(name: string, quota?: string, reservation?: string, compression: string, encryption?: string, encryptionPassphrase?: string, recordsize?: string, mountpoint?: string, canmount?: enum)
Create a ZFS filesystem with optional quota, reservation,
| Argument | Type | Description |
|---|---|---|
| name | string | |
| quota? | string | e.g. 10G; omit for unlimited |
| reservation? | string | |
| compression | string | |
| encryption? | string | e.g. aes-256-gcm. Omit to disable encryption. |
| encryptionPassphrase? | string | Passphrase for keyformat=passphrase keylocation=prompt. |
| recordsize? | string | |
| mountpoint? | string | |
| canmount? | enum |
fn dataset_load_key(name: string, passphrase: string, recursive: boolean, mount: boolean)
Load the encryption key for a dataset created with
| Argument | Type | Description |
|---|---|---|
| name | string | |
| passphrase | string | Passphrase the dataset was created with. |
| recursive | boolean | Also load the key for every descendant that inherits it. |
| mount | boolean | Mount the filesystems after unlocking. `zfs load-key` only makes |
fn dataset_destroy(name: string, recursive: boolean, force: boolean)
Destroy a dataset (recursive optional).
| Argument | Type | Description |
|---|---|---|
| name | string | |
| recursive | boolean | |
| force | boolean |
fn snapshot_create(name: string, recursive: boolean)
Create a snapshot pool/dataset@name.
| Argument | Type | Description |
|---|---|---|
| name | string | Fully-qualified e.g. rpool/zones/foo@2026-05-14 |
| recursive | boolean |
fn snapshot_destroy(name: string)
Destroy a snapshot.
| Argument | Type | Description |
|---|---|---|
| name | string |
fn delegate(dataset: string, zone: string)
Delegate a dataset into a zone: `zfs zone <dataset> <zone>`.
| Argument | Type | Description |
|---|---|---|
| dataset | string | |
| zone | string |
fn pool_status(pool: string)
Capture pool size/usage and zpool status output.
| Argument | Type | Description |
|---|---|---|
| pool | string |
fn pool_scrub(pool: string)
Start a scrub on a pool.
| Argument | Type | Description |
|---|---|---|
| pool | string |
Resources
dataset(infinite)— A ZFS filesystem or volume on the Helios host
pool(infinite)— A ZFS pool on the Helios host
snapshot(infinite)— A ZFS snapshot on the Helios host
@mccormick/helios/dladmv2026.08.04.1helios_dladm.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| sshUser | string | |
| sshPort? | number | |
| sshKnownHosts? | string |
fn link_list()
List every datalink (phys, vnic, aggr, etherstub).
fn phys_list()
List physical NICs (`dladm show-phys`).
fn etherstub_create(name: string)
Create an etherstub.
| Argument | Type | Description |
|---|---|---|
| name | string |
fn etherstub_destroy(name: string)
Destroy an etherstub.
| Argument | Type | Description |
|---|---|---|
| name | string |
fn vnic_create(name: string, over: string, macAddress?: string, vlanId?: number, allowedIps: array)
Create a VNIC over `over` (phys/etherstub/aggr) and immediately
| Argument | Type | Description |
|---|---|---|
| name | string | |
| over | string | |
| macAddress? | string | |
| vlanId? | number | |
| allowedIps | array | Host addresses to pin via the allowed-ips linkprop, e.g. |
fn vnic_destroy(name: string)
Destroy a VNIC.
| Argument | Type | Description |
|---|---|---|
| name | string |
Resources
link(infinite)— A datalink
phys(infinite)— A physical NIC
vnic(infinite)— A VNIC, with mac, vlan, link-protection, allowed-ips
etherstub(infinite)— An etherstub
@mccormick/helios/zonev2026.08.04.1helios_zone.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| sshUser | string | |
| sshPort? | number | |
| sshKnownHosts? | string |
fn list()
List every configured zone via `zoneadm list -cp`.
fn lookup(name: string)
Look up a single zone with full zonecfg.
| Argument | Type | Description |
|---|---|---|
| name | string |
fn create(name: string, brand: enum, zonepath: string, vnicLink?: string, allowedAddress?: string, defaultRouter?: string, autoboot: boolean, limitPriv: string, fileMacProfile: string, cappedCpu?: number, cappedMemoryMb?: number, rcapPhysicalMb?: number, dedicatedCpu?: string, delegatedDatasets: array, lofs: array)
Create a zone with hardened security defaults. ip-type=exclusive,
| Argument | Type | Description |
|---|---|---|
| name | string | |
| brand | enum | |
| zonepath | string | |
| vnicLink? | string | |
| allowedAddress? | string | |
| defaultRouter? | string | |
| autoboot | boolean | Start the zone when the host boots. Default false — a zone whose |
| limitPriv | string | |
| fileMacProfile | string | |
| cappedCpu? | number | |
| cappedMemoryMb? | number | Caps zone.max-swap (total virtual memory) and zone.max-locked- |
| rcapPhysicalMb? | number | Cap on resident physical memory. Enforced by rcapd, so the zone |
| dedicatedCpu? | string | |
| delegatedDatasets | array | |
| lofs | array |
fn install(name: string, extraArgs: array, timeoutSecs: number)
Install a zone. Idempotent and recoverable: an already-installed
| Argument | Type | Description |
|---|---|---|
| name | string | |
| extraArgs | array | |
| timeoutSecs | number | Deadline for `zoneadm install`. A pkgsrc- or ipkg-brand install |
fn boot(name: string, bootArgs?: string, waitForSmf: boolean, smfTimeoutSecs: number)
Boot a zone and, by default, wait until its SMF repository is
| Argument | Type | Description |
|---|---|---|
| name | string | |
| bootArgs? | string | |
| waitForSmf | boolean | Block until `svcs` responds inside the zone. `zoneadm boot` |
| smfTimeoutSecs | number |
fn halt(name: string)
Halt a zone.
| Argument | Type | Description |
|---|---|---|
| name | string |
fn uninstall(name: string)
Uninstall a zone (force).
| Argument | Type | Description |
|---|---|---|
| name | string |
fn delete(name: string)
Delete a zone configuration.
| Argument | Type | Description |
|---|---|---|
| name | string |
fn exec(name: string, command: string, timeoutSecs?: number)
Run a shell script inside the zone. The script is piped to
| Argument | Type | Description |
|---|---|---|
| name | string | |
| command | string | Shell script to run inside the zone. May be multiple lines. |
| timeoutSecs? | number |
fn inventory(includeLogs: boolean, logTailLines: number)
Single fan-out: gather identity, live usage, security config,
| Argument | Type | Description |
|---|---|---|
| includeLogs | boolean | |
| logTailLines | number |
Resources
zone(infinite)— An illumos zone (configured/installed/running) on the host
zone_inventory(7d)— Per-zone inventory snapshot: identity, security, network, storage,
inventory_summary(7d)— Host-level zone inventory rollup. One per inventory call.
exec_result(1d)— stdout/stderr/exit from a zlogin exec call
@mccormick/helios/postgresv2026.08.04.1helios_postgres.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| sshUser | string | Default SSH user on the global zone; needs pfexec plus the Zone |
| sshPort? | number | Default SSH port |
| sshKnownHosts? | string | Path to a known_hosts file. Omit to use accept-new on first connect. |
| serviceUser | string | Account the server runs as. The pkgsrc postgresql-server package |
| fmri | string | SMF service instance for the server inside the zone. |
| prefix | string | pkgsrc installation prefix inside the zone. |
fn bootstrap(pkgsrcBranch: string, bootstrapUrl?: string, serverPackage: string, clientPackage: string, dataDir: string)
Install PostgreSQL from pkgsrc inside the zone: bootstrap pkgsrc
| Argument | Type | Description |
|---|---|---|
| pkgsrcBranch | string | pkgsrc quarterly branch to bootstrap from. |
| bootstrapUrl? | string | Override the bootstrap tarball URL. Defaults to the SmartOS x86_64 |
| serverPackage | string | |
| clientPackage | string | |
| dataDir | string | PGDATA path inside the zone; should live on the delegated encrypted |
fn initdb(dataDir: string, encoding: string, locale: string, requireDataset?: string)
Initialise the cluster in `dataDir` as the service user, with data
| Argument | Type | Description |
|---|---|---|
| dataDir | string | |
| encoding | string | |
| locale | string | initdb locale. `C` avoids depending on locale data being present in |
| requireDataset? | string | ZFS dataset that must be mounted before the cluster is touched, e.g. |
fn configure(dataDir: string, requireDataset?: string, listenAddresses: string, port: number, allowedCidrs: array, sslCertFile: string, sslKeyFile: string, sslMinProtocol: string)
Write the swamp-managed TLS/listener settings and pg_hba.conf.
| Argument | Type | Description |
|---|---|---|
| dataDir | string | |
| requireDataset? | string | ZFS dataset that must be mounted before the configuration is written |
| listenAddresses | string | |
| port | number | |
| allowedCidrs | array | Networks permitted to connect, TLS + SCRAM only. |
| sslCertFile | string | |
| sslKeyFile | string | |
| sslMinProtocol | string |
fn set_role_password(role: string, password: string)
Set a role's password over the local socket. The statement is fed
| Argument | Type | Description |
|---|---|---|
| role | string | |
| password | string |
fn cert_install(certificate: string, privateKey: string, chain?: string, certPath: string, keyPath: string, reload: boolean)
Install a TLS certificate and key for the server. Compares the
| Argument | Type | Description |
|---|---|---|
| certificate | string | Leaf certificate, PEM. |
| privateKey | string | Private key for the leaf, PEM. |
| chain? | string | Intermediate chain, PEM. Appended after the leaf. |
| certPath | string | |
| keyPath | string | |
| reload | boolean | Refresh the SMF service (SIGHUP) after a change so the new |
fn service(action: enum, wait: boolean)
Drive the SMF service: enable, disable, restart, or refresh.
| Argument | Type | Description |
|---|---|---|
| action | enum | |
| wait | boolean | Block until the service settles (`svcadm -s`). |
fn status(certPath: string)
Read-only health snapshot: SMF state, server version, whether TLS
| Argument | Type | Description |
|---|---|---|
| certPath | string |
Resources
instance(infinite)— A PostgreSQL cluster running inside an illumos zone
certificate(infinite)— The TLS certificate currently installed for the server
status(infinite)— Runtime health snapshot of the server
03Previous Versions
2026.05.19.1
2026.05.14.1
04Stats
A
100 / 100
Downloads
5
Archive size
84.2 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
05Platforms
06Labels