S.M.A.R.T. Monitoring

Beszel parses S.M.A.R.T. data from smartctl and displays it on the system page if available. This usually requires increased permissions.

To make sure your system is compatible, install smartmontools on the agent machine and scan for devices:

Debian/Ubuntu

sudo apt install smartmontools

Fedora

sudo dnf install smartmontools

Arch

sudo pacman -S smartmontools

FreeBSD

pkg install smartmontools

macOS

brew install smartmontools

sudo smartctl --scan

Docker agent

Switch to the :alpine image and add the following to your docker-compose.yml. Make sure to replace the device names with your actual devices.

beszel-agent:
  image: henrygd/beszel-agent:alpine
   devices:
   - /dev/sda:/dev/sda
   - /dev/nvme0:/dev/nvme0
   cap_add:
   - SYS_RAWIO # required for S.M.A.R.T. data
   - SYS_ADMIN # required for NVMe S.M.A.R.T. data

Pass in the base controller name, not the block / partition

Note that we are using sda and nvme0 in our example, not sda1 or nvme0n1.

Binary agent

Make sure smartctl is installed by following the installation instructions.

smartctl needs elevated privileges to talk to disks:

• SATA/ATA via SG_IO requires CAP_SYS_RAWIO
• NVMe admin passthrough requires CAP_SYS_ADMIN

Recommended: systemd ambient capabilities

If you run the agent as a systemd service, add capabilities to the service instead of the process running as root.

1. Edit your service file (for example /etc/systemd/system/beszel-agent.service) and add the following under [Service]:

AmbientCapabilities=CAP_SYS_RAWIO CAP_SYS_ADMIN
CapabilityBoundingSet=CAP_SYS_RAWIO CAP_SYS_ADMIN

2. Reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart beszel-agent

If this doesn't work, try adding the beszel user to the disk group.

Alternative: file capabilities on smartctl

If you don't use systemd or prefer not to change the service, you can add the needed capabilities to the smartctl binary and restrict execution to a dedicated group. This lets the agent user run smartctl with just the required privileges.

# grant capabilities required for SATA (RAWIO) and NVMe (SYS_ADMIN)
sudo setcap cap_sys_rawio,cap_sys_admin+ep "$(command -v smartctl)"

# optionally restrict execution to a dedicated group
sudo groupadd -r smartctl 2>/dev/null || true
sudo chgrp smartctl "$(command -v smartctl)"
sudo chmod 750 "$(command -v smartctl)"

# add the beszel service user to that group
sudo usermod -aG smartctl beszel

Then restart the agent. Note: If your systemd unit sets NoNewPrivileges=yes, file capabilities added to smartctl will not be usable by the agent.

FreeBSD

Add the agent user to the operator group so it can access disk devices:

pw groupmod operator -m beszel
service beszel-agent restart

Verify permissions

Test that smartctl works without sudo for the agent user:

sudo -u beszel smartctl -H /dev/sda
sudo -u beszel smartctl -H /dev/nvme0

If these commands succeed, the agent will be able to parse S.M.A.R.T. data.

Windows

Download and install smartmontools from the official SourceForge page:

1. Go to https://sourceforge.net/projects/smartmontools/files/
2. Download the latest Windows installer (.exe file)
3. Run the installer as Administrator
4. Follow the installation wizard to complete the setup

After installation, verify that smartctl is accessible from the command line:

smartctl --version

Adding smartctl to PATH

Click to expand/collapse

If your system cannot find the smartctl executable, you will need to manually add the smartmontools installation directory to your system's PATH environment variable.

To add smartctl to your PATH:

1. Open the Edit the system environment variables dialog:

   • Press Win + R, type sysdm.cpl, press Enter and go the Advanced tab.
   • Or search for "Environment Variables" in the Start menu

2. Click Environment Variables...

3. In the System variables section, select Path and click Edit...

4. Click New and add the smartmontools installation directory:

   C:\Program Files\smartmontools\bin

   Installation path may vary

   The exact path depends on your installation location.

5. Open a new Command Prompt or PowerShell window and verify the installation:

   smartctl --version

Scan for devices

Once smartctl is working, scan for available devices:

smartctl --scan

The agent should now be able to collect S.M.A.R.T. data from your Windows system.

Troubleshooting

Commands still require sudo despite capabilities being set

If smartctl still fails even after setting capabilities (via systemd ambient capabilities or file capabilities), the issue is likely device permissions. Even with CAP_SYS_RAWIO and CAP_SYS_ADMIN, the user needs read access to the device files themselves.

Check your device permissions:

ls -l /dev/sda /dev/nvme0

You'll typically see something like:

brw-rw---- root disk /dev/sda      # block device, group readable
crw------- root root /dev/nvme0    # char device, only root can read

Add user to disk group

Most Linux distributions have a disk group that provides access to disk devices. Add the beszel user to this group:

sudo usermod -aG disk beszel
sudo systemctl restart beszel-agent

Note for NVMe devices

Some systems set NVMe character devices (/dev/nvme0) to mode 600 (owner-only), even if SATA devices work fine with the disk group. If NVMe S.M.A.R.T. still doesn't work after adding the user to the disk group, see the solution below.

Adjust NVMe device permissions

If your NVMe devices are still inaccessible after adding the user to the disk group, you can adjust the device group to disk.

# Check current permissions
ls -l /dev/nvme0

# Create a udev rule that changes NVMe devices to disk group ownership
sudo tee /etc/udev/rules.d/99-smartctl-disk-group.rules > /dev/null << 'EOF'
# Change NVMe devices to disk group ownership for S.M.A.R.T. monitoring
KERNEL=="nvme[0-9]*", GROUP="disk", MODE="0660"
EOF

# Reload udev rules
sudo udevadm control --reload-rules
sudo udevadm trigger

# Verify the new permissions (should show disk group and 660 mode)
ls -l /dev/nvme0

# Restart the agent
sudo systemctl restart beszel-agent

This changes the group ownership to disk and the mode to 0660 (group-readable).

Potential conflicts

If other software on your system has created udev rules for the same devices, there may be conflicts. You can check for existing rules with:

grep -r "KERNEL.*nvme" /etc/udev/rules.d/

To remove the udev rule:

sudo rm /etc/udev/rules.d/99-smartctl-disk-group.rules
sudo udevadm control --reload-rules
sudo udevadm trigger