Manual installation
Every other way to install the master and the agents. Covers the release package on each server, downloading the installer first, wget, self-signed certificates, SSH, cloud-init and Ansible, and a complete installation by hand without install.sh.
The quickest way to add a server is the one-line command from the panel: see Install the agents. This page covers every other way to install the master and the agents.
| Method | When to use it |
|---|---|
| Agent from the release package | The program should come from the package, not from the master |
| Download the installer first | You want to read the script before you run it, or answer its questions yourself |
| With wget instead of curl | The server has no curl |
| A master with a self-signed certificate | The panel uses HTTPS with a certificate the servers don't trust |
| Many servers from a script or a tool | SSH, cloud-init, Ansible |
| The master by hand | You can't or don't want to run install.sh |
| An agent by hand | The same, on the agents |
What you need for an agent
Every method needs the master's address and the server's token or the enrollment key. To approve AI repairs, it also needs the fingerprints of the master's signing key and of your passkeys. Copy the install command from the panel and take the values from it:
| Value | Where to find it |
|---|---|
Master URL (--master) | The address you open the panel with: Settings → General → Panel public URL |
Token (--token) | After Servers → ＋ Add server, or later in Servers → ⋯ → Install command. On the master, sudo 3rmonitor server add --name NAME also prints one. |
Enrollment key (--enroll) | Servers → Enroll many servers with one command |
MASTER_FP, PASSKEY_FP (--master-key, --approvers) | In those same commands, or in Settings → Passkeys → Fingerprints to compare. --approvers lists every trusted passkey, separated by commas; leave it out if you have no passkey yet. |
The CPU architecture
The installer finds the right program by itself. For the installation by hand, you need to know which file to use:
uname -m | Program |
|---|---|
x86_64 | 3rmonitor-linux-amd64 |
aarch64 | 3rmonitor-linux-arm64 |
armv7l | 3rmonitor-linux-arm |
i686, i386 | 3rmonitor-linux-386 |
This sets ARCH for the commands below:
case "$(uname -m)" in x86_64) ARCH=amd64 ;; aarch64) ARCH=arm64 ;; armv7l) ARCH=arm ;; i?86) ARCH=386 ;; esac; echo "$ARCH"Agents with the installer
Agent from the release package
Copy the release package to the server and extract it, as for the master. Then, in its directory:
sudo bash install.sh agent --master 'https://monitor.example.com' --token 'TOKEN' --master-key MASTER_FP --approvers PASSKEY_FPWith the enrollment key instead of a token, the server registers itself:
sudo bash install.sh agent --master 'https://monitor.example.com' --enroll 'ENROLLMENT_KEY' --master-key MASTER_FP --approvers PASSKEY_FP --name web-2 --group ProductionThe installer checks the program's checksum and installs it from the package instead of downloading it. Everything else is the same as with the panel's command. The server must still reach the master, for the test report and to report afterwards, and it updates itself from the master as usual.
With the release package, give --master and --token (or --enroll) on the command line. If you choose 1) Agent in the menu instead, the installer doesn't ask for them and stops with "Failed to write the agent configuration". The program is already copied by then: run the command above to finish.
Download the installer first
To read the installer before you run it, download it from the master. The link needs the token or the enrollment key (?t=):
curl -fsSL -o install.sh 'https://monitor.example.com/dl/install.sh?t=TOKEN'
less install.sh
sudo bash install.sh agent --master 'https://monitor.example.com' --token 'TOKEN' --master-key MASTER_FP --approvers PASSKEY_FPOr run sudo bash install.sh without options and choose 1) Agent. The installer then asks for the Master URL, the Server token (press Enter to use an enrollment key instead) and the Enrollment key. Asked this way, it doesn't trust any key: run sudo 3rmonitor approvers trust afterwards if you want approved AI repairs on this server.
In both cases, the program is downloaded from the master and its checksum is checked.
With wget instead of curl
wget -qO- 'https://monitor.example.com/dl/install.sh?t=TOKEN' | sudo bash -s -- agent --master 'https://monitor.example.com' --token 'TOKEN' --master-key MASTER_FP --approvers PASSKEY_FPThe installer itself also uses wget when curl isn't installed.
A master with a self-signed certificate
Both the download and the agent must skip the certificate check. Add -k to curl (--no-check-certificate to wget) and --insecure to the installer:
curl -fsSLk 'https://monitor.example.com/dl/install.sh?t=TOKEN' | sudo bash -s -- agent --master 'https://monitor.example.com' --token 'TOKEN' --insecure --master-key MASTER_FP --approvers PASSKEY_FP--insecure writes insecure = true in agent.conf, so the agent keeps skipping the check when it reports.
Many servers from a script or a tool
Use the enrollment command: it's the same for every server, and each one registers itself. Add -y, so the installer asks nothing. The name defaults to the server's host name.
for h in web-1 web-2 db-1; do
ssh root@$h "curl -fsSL 'https://monitor.example.com/dl/install.sh?t=ENROLLMENT_KEY' | bash -s -- agent --master 'https://monitor.example.com' --enroll 'ENROLLMENT_KEY' --master-key MASTER_FP --approvers PASSKEY_FP --name $h --group Production -y"
done- Keep the enrollment key in your tool's secrets (for example Ansible Vault): anyone who has it can add servers to your panel.
- The fingerprints must match the passkeys trusted right now. After you add or revoke a passkey, copy the command again. If they don't match, the agent is still installed, but the installer warns "Keys not pinned" and the server trusts no key: run
sudo 3rmonitor approvers truston it.
Everything by hand, without install.sh
These steps do what install.sh does, and create the same files and services. So later upgrades, the agents' automatic updates and install.sh uninstall work as usual. Replace the values in capitals with your own.
AlmaLinux, Rocky, RHEL and CentOS
On these systems sudo doesn't search /usr/local/bin. That is why the steps also link the 3rmonitor command in /usr/bin, as install.sh does. Without that link, sudo 3rmonitor … answers "command not found".
The master by hand
Extract the release package and check it.
tar xzf 3rmonitor-1.1.1.tar.gz && cd 3rmonitor-1.1.1
sha256sum -c --ignore-missing SHA256SUMSEvery program must show OK. Set ARCH for this server (see The CPU architecture), for example ARCH=amd64.
Create the user and the directories. The master runs as the unprivileged user 3rmonitor.
sudo useradd --system --home-dir /var/lib/3rmonitor --no-create-home --shell /usr/sbin/nologin 3rmonitor
sudo install -d -m 750 -o 3rmonitor -g 3rmonitor /var/lib/3rmonitor /var/lib/3rmonitor/update
sudo install -d /etc/3rmonitor /opt/3rmonitor/distInstall the program and the agent packages. Agents download the program from /opt/3rmonitor/dist when they are installed and when they update. They only update to programs listed in 3R Soft's signature, SHA256SUMS.sig, so copy it too. Keep install.sh in /opt/3rmonitor for upgrades and uninstalling.
sudo install -m 755 3rmonitor-linux-$ARCH /opt/3rmonitor/3rmonitor
sudo ln -sf /opt/3rmonitor/3rmonitor /usr/local/bin/3rmonitor
sudo ln -sf /opt/3rmonitor/3rmonitor /usr/bin/3rmonitor
sudo install -m 755 install.sh /opt/3rmonitor/install.sh
sudo cp 3rmonitor-linux-* SHA256SUMS SHA256SUMS.sig install.sh /opt/3rmonitor/dist/
sudo chmod -R a+rX /opt/3rmonitor/dist
if [ -f geoip-country.mmdb ]; then sudo install -m 640 -o 3rmonitor -g 3rmonitor geoip-country.mmdb /var/lib/3rmonitor/; fiWrite the configuration. Every key is explained in Configuration files.
sudo tee /etc/3rmonitor/master.conf >/dev/null <<'EOF'
listen = 0.0.0.0:8899
data_dir = /var/lib/3rmonitor
dist_dir = /opt/3rmonitor/dist
public_url = http://203.0.113.10:8899/
EOF
sudo chgrp 3rmonitor /etc/3rmonitor/master.conf
sudo chmod 640 /etc/3rmonitor/master.confCreate the database and the administrator. The password needs at least 8 characters.
sudo 3rmonitor init --public-url http://203.0.113.10:8899/ --admin admin --password 'STRONG_PASSWORD'It creates the database and the master's signing key in /var/lib/3rmonitor, as the user 3rmonitor. The panel's system language is taken from the terminal; to choose it, write for example sudo MONITOR_LANG=es 3rmonitor init … (en, es or zh).
Create the services: the master, its sandbox settings, and the root service that installs the updates you start from the panel.
sudo tee /etc/systemd/system/3rmonitor-master.service >/dev/null <<'EOF'
[Unit]
Description=3R Monitor master (web panel, checks, alerts)
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0
[Service]
Type=notify
NotifyAccess=main
User=3rmonitor
Group=3rmonitor
ExecStart=/opt/3rmonitor/3rmonitor master -c /etc/3rmonitor/master.conf
Restart=always
RestartSec=3
WatchdogSec=60
TimeoutStartSec=60
LimitNOFILE=65536
AmbientCapabilities=CAP_NET_RAW CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_RAW CAP_NET_BIND_SERVICE
NoNewPrivileges=true
ProtectSystem=full
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/lib/3rmonitor
[Install]
WantedBy=multi-user.target
EOF
sudo mkdir -p /etc/systemd/system/3rmonitor-master.service.d
sudo tee /etc/systemd/system/3rmonitor-master.service.d/hardening.conf >/dev/null <<'EOF'
[Service]
ProtectSystem=strict
ReadWritePaths=/var/lib/3rmonitor
PrivateDevices=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectKernelLogs=true
ProtectControlGroups=true
ProtectClock=true
ProtectHostname=true
RestrictNamespaces=true
RestrictRealtime=true
RestrictSUIDSGID=true
LockPersonality=true
MemoryDenyWriteExecute=true
SystemCallArchitectures=native
SystemCallFilter=@system-service
SystemCallErrorNumber=EPERM
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
UMask=0027
EOF
sudo tee /etc/systemd/system/3rmonitor-update.path >/dev/null <<'EOF'
[Unit]
Description=3R Monitor one-click update trigger (watches for a request from the panel)
[Path]
PathExists=/var/lib/3rmonitor/update/request
Unit=3rmonitor-update.service
[Install]
WantedBy=multi-user.target
EOF
sudo tee /etc/systemd/system/3rmonitor-update.service >/dev/null <<'EOF'
[Unit]
Description=3R Monitor one-click update (verifies the signed package, then runs install.sh upgrade)
[Service]
Type=oneshot
ExecStart=/opt/3rmonitor/3rmonitor apply-update -c /etc/3rmonitor/master.conf
TimeoutStartSec=20min
EOFStart it and check it.
sudo systemctl daemon-reload
sudo systemctl enable --now 3rmonitor-master 3rmonitor-update.path
sleep 5
curl -fsS http://127.0.0.1:8899/healthz # {"status":"ok"}
3rmonitor statushardening.conf keeps the master from writing anywhere but its data directory. A few systems, for example some LXC containers, don't support every setting in it, and the master then doesn't start (journalctl -u 3rmonitor-master shows why). Remove it there, as install.sh does:
sudo rm -r /etc/systemd/system/3rmonitor-master.service.d
sudo systemctl daemon-reload && sudo systemctl restart 3rmonitor-masterOpen the port if the server has a firewall:
sudo ufw allow 8899/tcp # ufw (Ubuntu, Debian)
sudo firewall-cmd --permanent --add-port=8899/tcp && sudo firewall-cmd --reload # firewalld (AlmaLinux, Rocky, RHEL)Then sign in with the admin account.
Also monitor the master (master + agent)
On the master, register the master itself and run its agent. It reports to the master over 127.0.0.1:
TOKEN=$(sudo 3rmonitor server add --name "$(hostname)" --group 'Master server' --reuse -q)
sudo 3rmonitor bind --master http://127.0.0.1:8899 --token "$TOKEN"
sudo chmod 600 /etc/3rmonitor/agent.conf
sudo 3rmonitor agent --test
sudo 3rmonitor agent secure
sudo 3rmonitor approvers trust --yes-q prints only the token, and --reuse reuses it if a server with that name already exists. approvers trust --yes trusts the keys without asking, because the master is on this same server. The next section explains each step.
A domain with HTTPS
What --domain and --https do, by hand: a reverse proxy in Nginx or Apache, then a Let's Encrypt certificate with certbot.
sudo tee /etc/nginx/conf.d/3rmonitor.conf >/dev/null <<'EOF'
server {
listen 80;
server_name monitor.example.com;
client_max_body_size 8m;
location / {
proxy_pass http://127.0.0.1:8899;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Connection "";
proxy_buffering off;
proxy_read_timeout 1h;
}
}
EOF
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d monitor.example.com --no-redirectInstall certbot and its Nginx or Apache plugin first if needed (python3-certbot-nginx or python3-certbot-apache; on AlmaLinux, Rocky and RHEL they come from EPEL). Then set Settings → General → Panel public URL to https://monitor.example.com/.
--no-redirectis deliberate: agents that report to thehttp://address keep working, and the master itself sends browsers tohttps://. See What happens with http:// addresses.- The default
trust_proxy = autoalready takes the visitor's real IP from a proxy on the same server. - To serve the panel only through the proxy, use
listen = 127.0.0.1:8899inmaster.conf, but only if no agent on another server reports tohttp://IP:8899.
An agent by hand
First register the server in the panel (＋ Add server), or with sudo 3rmonitor server add on the master. Then take the master URL, the token and the fingerprints from its install command.
Download the program from the master and check it. Set ARCH first (see The CPU architecture).
MASTER='https://monitor.example.com'
TOKEN='TOKEN'
mkdir -p /tmp/3rmonitor && cd /tmp/3rmonitor
curl -fsSL -o 3rmonitor-linux-$ARCH "$MASTER/dl/3rmonitor-linux-$ARCH?t=$TOKEN"
curl -fsSL -o SHA256SUMS "$MASTER/dl/SHA256SUMS?t=$TOKEN"
curl -fsSL -o install.sh "$MASTER/dl/install.sh?t=$TOKEN"
sha256sum -c --ignore-missing SHA256SUMSIt must show 3rmonitor-linux-…: OK. With wget, use wget -qO FILE URL instead of curl -fsSL -o FILE URL. You can also take the same three files from the release package.
Install it.
sudo install -D -m 755 3rmonitor-linux-$ARCH /opt/3rmonitor/3rmonitor
sudo install -m 755 install.sh /opt/3rmonitor/install.sh
sudo ln -sf /opt/3rmonitor/3rmonitor /usr/local/bin/3rmonitor
sudo ln -sf /opt/3rmonitor/3rmonitor /usr/bin/3rmonitorConnect it to the master. This writes /etc/3rmonitor/agent.conf:
sudo 3rmonitor bind --master "$MASTER" --token "$TOKEN"
sudo chmod 600 /etc/3rmonitor/agent.confWith the enrollment key, use --enroll 'ENROLLMENT_KEY' --name web-2 --group Production instead of --token. For a self-signed certificate, add --insecure.
Report once.
sudo 3rmonitor agent --testIt shows "Report succeeded: the master registered this machine as #N…". With an enrollment key, this is when the server registers itself and stores its token.
Create the services.
sudo 3rmonitor agent secureIt creates the user 3rmonitor-agent (in the adm and systemd-journal groups, to read logs) and makes agent.conf root:3rmonitor-agent 0640. Where setfacl is installed, it gives that user read access to the access logs. It then creates and starts the root helper 3rmonitor-helper, and the 3rmonitor-agent service running as that user. It shows "The agent now runs as the unprivileged user 3rmonitor-agent…".
Trust the keys, for approved AI repairs:
sudo 3rmonitor approvers trust --master-key MASTER_FP --approvers PASSKEY_FPWithout the fingerprints, it shows them and asks: compare them with Settings → Passkeys → Fingerprints to compare and type yes.
Check it.
3rmonitor status
systemctl status 3rmonitor-agent 3rmonitor-helperAfter a few seconds the server appears in the panel's Servers list.
It shows why, for example when useradd is missing or the helper doesn't start (journalctl -u 3rmonitor-helper). Fix the cause and run it again. Until then the agent isn't running. If it can't be fixed, run the agent as root, as install.sh does in that case. It monitors the server, but the AI runs nothing on it:
sudo tee /etc/systemd/system/3rmonitor-agent.service >/dev/null <<'EOF'
[Unit]
Description=3R Monitor agent (reports this server to the master)
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0
[Service]
Type=notify
NotifyAccess=main
ExecStart=/opt/3rmonitor/3rmonitor agent -c /etc/3rmonitor/agent.conf
Restart=always
RestartSec=5
WatchdogSec=120
TimeoutStartSec=60
Nice=5
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now 3rmonitor-agentWhat is created
| Master | Agent | |
|---|---|---|
| Program | /opt/3rmonitor/3rmonitor, the 3rmonitor command in /usr/local/bin and /usr/bin | The same |
| Installer, for upgrades and uninstalling | /opt/3rmonitor/install.sh | The same |
| Agent packages | /opt/3rmonitor/dist, with SHA256SUMS and its signature SHA256SUMS.sig | — |
| Configuration | /etc/3rmonitor/master.conf (root:3rmonitor, 0640) | /etc/3rmonitor/agent.conf (root:3rmonitor-agent, 0640) |
| Data | /var/lib/3rmonitor: database and signing key, owned by 3rmonitor | /var/lib/3rmonitor-helper: the trusted keys, root only |
| User | 3rmonitor | 3rmonitor-agent |
| Services | 3rmonitor-master (with 3rmonitor-master.service.d/hardening.conf), 3rmonitor-update.path and 3rmonitor-update.service | 3rmonitor-agent, 3rmonitor-helper |
Upgrades and uninstalling
The same as after an installation with install.sh. Upgrade the master from the panel, or with sudo bash install.sh upgrade in a new package; agents update themselves. To remove it, run sudo bash /opt/3rmonitor/install.sh uninstall, with --purge to delete the configuration and data too. See Upgrade and uninstall.