Requirements & permissions
The install script asks for a root shell, so this page spells out what that root shell does and what privileges the collector is left with afterward. The short version: an unprivileged system user, no open ports, a read-only view of the OS, and disk capabilities only when physical drives exist. The script itself is plain POSIX shell, readable at get.monitorable.net/install.sh — you can read every line before running it.
What the server needs
Section titled “What the server needs”| Requirement | Detail |
|---|---|
| OS | Linux on x86_64 (amd64) or arm64. Bare metal, VMs, and LXC containers are all supported. The collector is Linux-only. |
| Init system | systemd — the collector runs as the monitorable-agent.service unit. |
| Tools | curl, used to fetch the script, binary, and configuration, and openssl, used to check the release signature. The script stops before changing anything if openssl is missing (apt-get install -y openssl / dnf install -y openssl). |
| Network | Outbound HTTPS (port 443). No inbound ports, no firewall changes. |
The collector is a single binary, about 47 MB on disk. On the small server these docs are verified against, it holds 12–16 MB of resident memory and has averaged under 0.1% of one CPU core.
Network traffic is outbound only
Section titled “Network traffic is outbound only”| Destination | When | What |
|---|---|---|
get.monitorable.net | Install, upgrade and uninstall | The install script. |
get.monitorable.io | Install and upgrade | The collector binary, base configuration, service file, and the signed checksum file. |
ingest.monitorable.net | Runtime, every 60 seconds | Metrics as gzip-compressed OTLP over HTTPS, authenticated with the server’s API key. |
The collector binds no listening ports — ss -ltnp on a monitored server
shows nothing owned by it. There is no remote-control channel: the only
connection is the one the collector opens to post metrics.
Root installs it, an unprivileged user runs it
Section titled “Root installs it, an unprivileged user runs it”Root is needed once, for setup. The install script creates:
- The
monitorablesystem user and group. The user has no login shell (/sbin/nologin) and no password; its home is/var/lib/monitorable, the collector’s only writable directory. /opt/monitorable/— the agent binary, owned by root so the collector can’t replace its own executable. There is no separate launcher./etc/monitorable/collector-config.yaml— the collector configuration, mode640, readable only by root and themonitorablegroup./etc/monitorable/agent.env— mode600, owned byroot:root. Holds the server’s API key and the ingest endpoint as environment variables; nothing but root can read it./etc/systemd/system/monitorable-agent.service— the service unit. It references the env file above (EnvironmentFile=) rather than carrying the API key itself, so the unit file — which is world-readable — never exposes the secret.
The service runs as the monitorable user, and the unit sandboxes it
further. From the installed unit file:
NoNewPrivileges=yesProtectSystem=strictProtectHome=tmpfsReadWritePaths=/var/lib/monitorablePrivateTmp=yesProtectKernelTunables=yesProtectKernelModules=yesProtectControlGroups=yesIn practice: the collector can’t gain privileges it wasn’t started with,
sees the whole OS read-only except /var/lib/monitorable, gets a private
/tmp, and can’t touch kernel tunables, kernel modules, or cgroups.
/root and users’ session directories are masked out entirely; /home is
re-exposed read-only so the disk-usage panel can measure how full it is,
with normal file permissions still applying on top.
Disk (SMART) capabilities are probed, not blanket
Section titled “Disk (SMART) capabilities are probed, not blanket”Reading SMART health data from drives needs kernel capabilities that most
of the collector never uses, so the install script checks /sys/block and
grants only what the detected hardware requires:
| Detected | Granted to the service |
|---|---|
| NVMe drive | CAP_SYS_RAWIO + CAP_SYS_ADMIN, membership of the disk group, and a udev rule (/etc/udev/rules.d/99-monitorable-nvme-smart.rules) that lets the disk group open the NVMe controller node read-only. |
| SATA/SAS drives, no NVMe | CAP_SYS_RAWIO and membership of the disk group. |
| No physical drive (typical VPS or VM) | Nothing. The unit’s capability set is empty. |
NVMe needs the broader grant because SMART reads on NVMe are admin ioctls
on Linux. The unit sets CapabilityBoundingSet to the same list as the
grant, so the table above is also the ceiling — the collector can’t acquire
anything beyond it. Re-running the install command re-probes the hardware,
which is how you extend the grant after adding a drive.
SMART data itself appears only for bare-metal servers: virtual disks don’t expose drive health, so on a VM the probe finds nothing and no capability is granted.
Docker socket access
Section titled “Docker socket access”If a docker group exists when the script runs, the monitorable user
joins it — the standard way to grant read access to the Docker socket — and
the collector reports container metrics. It probes the socket on each
collection cycle, so containers show up without any configuration.
If you install Docker after the collector, the group membership is missing. Re-run the install command, or grant it directly:
usermod -aG docker monitorablesystemctl restart monitorable-agentWhen the collector lacks a permission
Section titled “When the collector lacks a permission”Missing privileges never break monitoring — the affected feature is skipped and reported. The Permission Limitations card at the bottom of the server’s page lists each skipped check and the privilege it would need:
The example above is from a server with ZFS present: querying pool status needs root, and the collector never runs as root, so that check is skipped. If a card entry names something the install script can grant — SMART capabilities or the docker group — re-run the install command; it re-probes the server and grants what the hardware calls for.