Deployment Guide

Platform Quickstart & OS Deployment

Pillar’s standard Agent deployment uses a read-only container root, restricted capabilities, host telemetry mounts, and persistent credential storage. Pillar is observe-only and never writes to the host; device access remains a sensitive host permission.

Before you install

Confirm Linux and Docker support for your appliance version, administrator access, persistent configuration storage, outbound HTTPS/DNS access, and vendor approval for third-party containers. TrueNAS CORE/FreeBSD is not supported by this Linux image. Run changes in an agreed maintenance window and retain your host recovery procedure.

Pillar CLI

The signed pairing flow below is the fastest path: it downloads a small bootstrap script that fetches and verifies the Pillar CLI, then runs pillar install agent for you — you never need to build or run the CLI yourself. See the CLI reference for its full command set, including update and rollback, if you prefer to build it from source.

1.Preflight readiness inspection

Review the script before running it on your host. It reports the OS and architecture, tests VFS accessibility for /proc/diskstats and /sys/block, counts physical drives while excluding virtual devices (ZVOLs/DeviceMapper/MDRAID), and probes outbound connectivity. The shell check is a preliminary inspection; it does not establish compatibility or replace the signed image’s preflight and post-install verification.

bash

curl --fail --silent --show-error --location --proto '=https' --output pillar-preflight.sh https://pillarinteractive.com/test

After a successful download, open pillar-preflight.sh in a text editor and review it. Run the reviewed file with:

bash

sh pillar-preflight.sh

Pair a storage system

Fastest

In Settings → Agent pairing, a Facility Admin or Organization Admin can generate a one-time token and copy the installation command. Review it and run it on the intended Linux storage host with Docker available and approved administrator access. The command downloads a small HTTPS bootstrap script that verifies and installs the signed Pillar CLI, then hands off to pillar install agent, which verifies the signed release manifest and image, runs image preflight, and starts the Agent. Treat the command as a secret until its token expires or is used.

After installation, confirm the intended node appears in Storage, its heartbeat is fresh, and the expected pools and drives are visible. Set the facility timezone, operating hours, workloads, and alert routing before relying on notifications.

The Observer is installed by default (uncheck it in setup to opt out) when the release publishes a signed Observer image for this host's architecture and the host supports it; otherwise the Agent installs alone. Confirm it reports connected and has samples; Agent-only mode does not provide per-I/O percentiles. See How Pillar works.

2.Advanced platform configuration examples

Use the signed pairing flow above for installation. These templates illustrate platform differences; digest placeholders must be replaced with verified release artifacts and are not executable install commands.

Visual OS Selector

Choose Your Storage Host Environment

Read-only filesystem • No production dataset mounts in the documented configuration

•Paste into System Settings → Shell or SSH terminal as root.
•Reads /proc/diskstats and /sys/block directly; unmounted from /mnt datasets.
•To persist across reboot: add as a Post-Init script in System Settings → Advanced.

bash

docker run -d \
  --name pillar-agent \
  --restart unless-stopped \
  --read-only \
  --cap-drop=ALL \
  --cap-add=SYS_RAWIO \
  --security-opt no-new-privileges:true \
  --pids-limit 128 \
  --memory 256m \
  --device-cgroup-rule 'b *:* r' \
  --device-cgroup-rule 'c 10:249 rw' \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -v /dev:/dev:ro \
  -v /proc/diskstats:/proc/diskstats:ro \
  -v /sys/block:/sys/block:ro \
  -v /sys/class/block:/sys/class/block:ro \
  -v pillar-agent-data:/etc/pillar \
  -v pillar-run:/run/pillar \
  -e PILLAR_API_URL="https://pillarinteractive.com" \
  -e PILLAR_CLAIM_TOKEN="<YOUR_CLAIM_TOKEN>" \
  ghcr.io/pillar-interactive/pillar-agent@sha256:<verified-release-digest>

3.Platform-Specific Implementation Details

TrueNAS SCALE (Debian ZFS)

TrueNAS SCALE runs Debian GNU/Linux. While TrueNAS manages primary datasets under /mnt, the Pillar Agent strictly binds to the host kernel block virtual filesystems:

Persistent Init Script: For a supported TrueNAS version, review its persistence guidance before using System Settings → Advanced → Init/Shutdown Scripts, select Add, set Type to Command, select Post-Init, and paste the TrueNAS docker run snippet.
ZFS Pool Metrics: The agent reports every pool returned by zpool list and evaluates scrubbing/resilvering progress through zpool status, provided the zpool and zfs CLIs are reachable on the container's PATH.
TrueNAS CORE: TrueNAS CORE is based on FreeBSD and is not a supported deployment target for the Linux container image.

Tested releases, required access, Agent versus Observer on TrueNAS, and a worked scrub-overlap investigation: Pillar for TrueNAS post-production facilities.

Unraid (Parity Array & Standby Preservation)

Unraid relies on spinning down non-accessed archive drives to save power and mechanical wear. Pillar Edge Agent preserves this behavior:

Standby-aware SMART checks: Hardware health scans pass --nocheck=standby to smartctl. The Agent requests checks that avoid intentionally waking standby drives and may retain prior metadata. Verify behavior with your actual disks, controller, and other host workloads.
Flash Drive Configuration Mount: Unraid persistence depends on your Docker and filesystem configuration. The Unraid command explicitly maps /boot/config/plugins/pillar:/etc/pillar so that your paired node API key survives reboot.

45Drives Houston / Enterprise Ubuntu Heads

For 45Drives Storinators (15-bay, 30-bay, 45-bay, 60-bay top loaders) and high-density Supermicro chassis:

SCSI Enclosure Services (SES): Include -v /sys/class/enclosure:/sys/class/enclosure:ro. The agent inspects SES slot links to correlate device nodes (/dev/sdac) to physical chassis bays (Enclosure 1, Slot 24).
Systemd Supervision: Deploy via the provided pillar-agent.service unit file for native Linux process supervision and automatic crash recovery.

← How Pillar works Pillar CLI →