Skip to content

Security

gitsync edited this page Nov 17, 2026 · 7 revisions

Settings — Security

Sudo access model

ZNAS requires sudo privileges because most ZFS, Samba, NFS, SMART, and system operations must run as root. Three configurations are supported:

Mode How it works Recommended?
Running as root Process UID is 0; no sudo needed No — high blast radius
NOPASSWD: ALL Blanket root delegation Acceptable for home/lab use
Hardened sudoers Whitelist of specific commands only Yes — for any production deployment

The Requisites → Hardening tab shows which mode is currently active. The USB Appliance runs the portal as root on a read-only OS.


Hardened sudoers configuration

Step 1 — Create a dedicated service account

sudo useradd --system --no-create-home --shell /usr/sbin/nologin zfsnas
sudo mkdir -p /opt/zfsnas
sudo chown zfsnas:zfsnas /opt/zfsnas
sudo cp zfsnas /opt/zfsnas/

Step 2 — Add the sudoers entry

Run sudo visudo -f /etc/sudoers.d/zfsnas and add the whitelist. The full whitelist is maintained in SECURITY.md in the repository.

The whitelist is divided into named aliases. Aliases for optional features are only present while the feature is installed:

Alias Commands
ZFSNAS_ZFS zpool/zfs — pool and dataset operations, snapshots, encryption keys, replication, delegation
ZFSNAS_SMB Samba service control, user provisioning, tee /etc/samba/smb.conf, smbstatus -S
ZFSNAS_NFS exportfs -ra, NFS service control, tee /etc/exports
ZFSNAS_SMART smartctl, nvme smart-log — disk health data
ZFSNAS_DISK wipefs, sgdisk, dd, partprobe, udevadm settle, blkid — disk wipe before pool creation
ZFSNAS_ISCSI targetcli, iSCSI service control
ZFSNAS_MINIO MinIO/mc binary download, system account setup, service control
ZFSNAS_UPS NUT service control, config file writes, nut-scanner, NUT uninstall
ZFSNAS_SCAN du -b -d 6 * — Folder TreeMap usage scan
ZFSNAS_FILES find, chown, chmod, mkdir -p, rmdir — all scoped to ZFS mount paths (e.g. /mnt/*)
ZFSNAS_SYSTEM timedatectl, shutdown, modprobe zfs, portal restart, ARC sysfs writes, server name (tee /etc/hostname, tee /etc/hosts, hostname -F)
ZFSNAS_APT apt-get update/install/upgrade/remove, systemd service unit setup
ZFSNAS_SECURITY tee /etc/sudoers.d/zfsnas, cat /etc/sudoers.d/zfsnas — Sudoers Hardening self-management
ZFSNAS_SYNCOID syncoid — remote VM/LXC backups (optional feature)
ZFSNAS_RSYNC rsync, external storage mount/unmount under /mnt/zfsnas-ext (optional feature)
ZFSNAS_MERGERFS mergerfs mount/unmount, control-file tuning (optional feature)
ZFSNAS_SDN nft, ifup/ifdown, ip, sysctl, conntrack, wg, suricata-update, the Firewall's own units and auto-revert — present only while the Firewall is enabled (enabling it needs full sudo)
Virtualization aliases Incus daemon and instance management (present only when virtualization is enabled)

Step 3 — Update the systemd service

[Service]
User=zfsnas
WorkingDirectory=/opt/zfsnas
ExecStart=/opt/zfsnas/zfsnas

Sudoers Hardening (in-portal management)

Once the hardened sudoers entry is in place, the portal can manage its own sudoers file from Requisites → Hardening:

  • Review — shows a diff between the installed sudoers file and what the current version of the portal requires. New commands added in a portal update are highlighted.
  • Apply — writes the updated sudoers file. You can approve or suppress individual changes.
  • Convert to sudo all — replaces the hardened entry with a simple NOPASSWD: ALL for troubleshooting.

Linux accounts

The portal creates Linux accounts for its users (for SMB, and for SSH when Allow SSH login is on). It only ever changes or deletes accounts it created itself, marked ZNAS portal user: an existing account with the same name, such as your own login, keeps its password, shell and sudo rights, and system accounts, root and the portal's service account are never touched. Admins with SSH login get sudo with their own password; no account is ever given passwordless sudo. See User Management.


USB appliance

The USB Appliance adds its own protections:

  • Read-only OS: the system image cannot be modified; everything returns to its shipped state at reboot, except the settings kept on the settings partition.
  • Locked by default: root has no password and SSH accepts no login until you set a root password or key in Settings → SSH access, or create an admin with SSH login.
  • Signed upgrades: appliance images, like portal updates, are only installed after their signature is verified against the key built into the portal.

TLS / HTTPS

  • The portal is HTTPS-only — there is no HTTP fallback or redirect
  • A self-signed certificate is generated on first run
  • To use a CA-signed certificate, go to Settings → Certificate Management to import and activate it without manual file copying

Replacing the certificate manually

cp your-cert.pem /opt/zfsnas/config/certs/server.crt
cp your-key.pem  /opt/zfsnas/config/certs/server.key
sudo systemctl restart zfsnas

Authentication

Session cookies

  • Cookies are HttpOnly (not accessible to JavaScript) and Secure (HTTPS only)
  • Sessions expire after inactivity
  • Failed login attempts are rate-limited per IP address
  • All login attempts are written to the audit log with the client IP

User roles

Role What they can do
admin Everything — create/delete pools, datasets, users, shares; use the web terminal
standard Configurable subset of admin actions controlled by 11 individual permission flags
read-only View all data; no mutations; no terminal
smb-only Samba authentication only; cannot access the portal web UI

Two-Factor Authentication (TOTP)

The portal supports time-based one-time passwords (TOTP / RFC 6238) for all accounts. The QR code is rendered locally — the TOTP secret never leaves your server.

Enable: Profile (user menu) → Two-Factor Authentication → Enable 2FA → scan the QR code with any authenticator app (Google Authenticator, Authy, Bitwarden, …) → confirm with a 6-digit code.

Login flow: after username/password, a second screen asks for the current 6-digit code (prompt expires after 5 minutes).

Disable: from your own profile, or (admin) via Settings → Users → ⋮ → Edit → Disable 2FA.


Web terminal security

The web terminal runs a shell as the zfsnas service user. With the hardened sudoers entry, any sudo command typed in the terminal is limited to the whitelist — the terminal does not grant additional privileges beyond what the service account already has.

Access to the terminal can be restricted per-user using the Terminal permission flag on standard-role users.


Security headers

Every response includes these headers:

Header Value
X-Content-Type-Options nosniff
X-Frame-Options DENY
X-XSS-Protection 1; mode=block
Referrer-Policy strict-origin-when-cross-origin
Permissions-Policy Restricts geolocation, camera, microphone

Cross-origin requests on mutating methods (POST, PUT, DELETE, PATCH) are rejected — the Origin header must match the request host.


Reporting vulnerabilities

Open a GitHub issue or contact the maintainer directly via GitHub.

Clone this wiki locally