Repository navigation
Security

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.
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/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) |
[Service]
User=zfsnas
WorkingDirectory=/opt/zfsnas
ExecStart=/opt/zfsnas/zfsnasOnce 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: ALLfor troubleshooting.
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.
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:
roothas 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.
- 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
cp your-cert.pem /opt/zfsnas/config/certs/server.crt
cp your-key.pem /opt/zfsnas/config/certs/server.key
sudo systemctl restart zfsnas- Cookies are
HttpOnly(not accessible to JavaScript) andSecure(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
| 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 |
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.
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.
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.
Open a GitHub issue or contact the maintainer directly via GitHub.
Getting Started
Storage
- Dashboard & Monitoring
- Physical Disks
- ZFS Pools
- Datasets & ZVols
- MergerFS
- Snapshots & Protection
- File Sharing — SMB
- File Sharing — NFS
- iSCSI
- S3 Object Storage
- Capacity Trends
- Encryption
- UPS Management
Virtualization
Networking
Administration
Reference