system2mqtt/SYSTEMD_SETUP.md

systemd Service Installation

Quick setup to run system2mqtt as a systemd service on Linux.

Installation Steps

1. Create dedicated user:

   sudo useradd -r -s /usr/sbin/nologin -d /opt/system2mqtt system2mqtt
   

2. Install system to /opt/system2mqtt:

   sudo mkdir -p /opt/system2mqtt
   sudo cp -r system2mqtt.py collectors config.yaml.example run.sh /opt/system2mqtt/
   sudo cp requirements.txt /opt/system2mqtt/
   sudo chmod +x /opt/system2mqtt/run.sh
   sudo chown -R system2mqtt:system2mqtt /opt/system2mqtt
   

3. Configure:

   # Copy and edit config (in user's home directory)
   sudo -u system2mqtt mkdir -p ~system2mqtt/.config/system2mqtt
   sudo -u system2mqtt cp /opt/system2mqtt/config.yaml.example ~system2mqtt/.config/system2mqtt/config.yaml
   sudo nano ~system2mqtt/.config/system2mqtt/config.yaml
   
   # OR use environment variables in .env
   sudo nano /opt/system2mqtt/.env
   sudo chown system2mqtt:system2mqtt /opt/system2mqtt/.env
   

4. Install systemd service:

   sudo cp system2mqtt.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable system2mqtt
   sudo systemctl start system2mqtt
   

5. Check status:

   sudo systemctl status system2mqtt
   sudo journalctl -u system2mqtt -f
   

Service Management

• Start: sudo systemctl start system2mqtt
• Stop: sudo systemctl stop system2mqtt
• Restart: sudo systemctl restart system2mqtt
• Logs: sudo journalctl -u system2mqtt -f
• Enable on boot: sudo systemctl enable system2mqtt
• Disable on boot: sudo systemctl disable system2mqtt

Notes

• Service runs as unprivileged system2mqtt user
• User is member of adm and systemd-journal groups for system metrics access
• ZFS (read-only): On many systems, read-only queries like zpool status and zpool list work without special privileges. If they fail on your host, consider one of these options:
  • Add the user to a zfs group if present (Debian/Ubuntu with zfsutils-linux often provide it):

    sudo usermod -aG zfs system2mqtt
    sudo systemctl restart system2mqtt
    

  • Allow read-only ZFS commands via sudoers without a password:

    echo "system2mqtt ALL=(ALL) NOPASSWD: /usr/sbin/zpool, /usr/sbin/zfs" | sudo tee /etc/sudoers.d/system2mqtt
    sudo visudo -c
    

  • Use ZFS delegation (if supported in your setup) to grant specific permissions:

    sudo zfs allow system2mqtt snapshot,send,receive YOUR_POOL
    

• run.sh automatically creates venv, installs/updates dependencies on each start
• Auto-restarts on failure (RestartSec=10)
• Reads environment from /opt/system2mqtt/.env if present
• Logs to systemd journal (view with journalctl)