OviOS Storage Controller

1 Introduction

OviOS Linux v6 is a purpose-built ZFS-based storage appliance operating system. It is designed to be configured entirely through a guided shell interface — no Linux expertise is required for day-to-day administration. Every major operation has an interactive wizard that walks you through each step.

What OviOS Can Do

2 Network Configuration

2.1 Interface Setup — netsetup

netsetup configures physical interfaces (and bonds/VLANs) for systemd-networkd. Use --text for non-interactive scripted mode.

DHCP

netsetup --text --iface enp1s0 --method dhcp

Static IP

netsetup --text --iface enp1s0 --method static \
  --address 192.168.10.20 --prefix 24 \
  --gateway 192.168.10.1 \
  --dns 1.1.1.1 9.9.9.9

Fix Speed / Duplex

netsetup --text --iface enp1s0 --method dhcp --speed 1000 --duplex full

Remove Persistent Link Tuning

netsetup --text --iface enp1s0 --method dhcp --clear-link-tuning

2.2 Network Bonding — bondadm

Bonding combines multiple physical NICs into one logical interface for redundancy and/or throughput aggregation.

Create a Bond (LACP)

bondadm -n bond0 -m 4 -i enp1s0 -i enp2s0

Create a Bond (Active-Backup)

bondadm -n bond0 -m 1 -i enp1s0 -i enp2s0

Assign IP to Bond

netsetup --text --iface bond0 --method static \
  --address 192.168.10.20 --prefix 24 --gateway 192.168.10.1

List / Remove Bonds

bondadm -l           # list all bonds
bondadm -r bond0    # remove bond

2.3 VLANs — vlanadm

Creates tagged VLAN sub-interfaces on top of a physical or bonded interface. Interactive mode is recommended — you will be prompted for parent interface, VLAN name, and VLAN ID.

vlanadm                           # interactive — recommended
vlanadm --remove VLAN_NAME       # remove a VLAN

# Assign IP after creation:
netsetup --text --iface vlan10 --method static --address 10.10.10.1 --prefix 24

3 Command Reference Overview

Access the full command list at any time from the OviOS shell by typing ?. The most commonly used commands are listed below.

4 Listing Disks

Before creating pools, inspect available disks using listdsk (or its alias ld).

listdsk           # full details (default)
listdsk --free    # only disks not assigned to any pool
listdsk simple   # name and size only
listdsk by-id    # persistent /dev/disk/by-id/ paths
listdsk by-path  # persistent /dev/disk/by-path/ paths

5 Services Management

Interactive Service Manager

Run service and use the arrow keys to select a service, then choose start, stop, restart, or status.

service

Full Status Dashboard

service   # then select → status-all

SERVICE      STATUS             WORKLOAD / DETAILS
SSH          ONLINE    Listening on port 22
OVIOS-WEB    ONLINE    -
SMB          ONLINE    1 Connected Users
NFS          ONLINE    -
ISCSI        ONLINE    0 Active Sessions
SMARTD       OFFLINE   -

Recommended Services to Enable

options smartd.enable on   # enable S.M.A.R.T. monitoring
send-logs                     # collect and email diagnostic logs

6 Creating Storage Pools

What Is a Pool?

A ZFS storage pool is the top-level storage container. It is built from one or more physical disks organized into a RAID layout. All LUNs and volumes live inside pools.

RAID Layouts

Creating a Pool

pool create

The wizard prompts you for a pool name, RAID layout, and which disks to include. That is all.

# Replace sdX with each affected disk
sudo wipefs -af /dev/sdX

Pool Commands

pool list      # show all pools with health and capacity
pool status    # detailed pool status including vdev tree
pool health    # quick health summary across all pools
pool extend    # add vdevs to grow an existing pool online
pool modify    # add and remove spare, read cache (L2ARC) and log (SLOG) devices
pool delete    # destroy a pool — irreversible, all data lost

7 iSCSI Targets

What Is an iSCSI Target?

iSCSI presents block-level storage over an IP network. The target is the server side (OviOS) that exports one or more LUNs. The initiator is the client — VMware ESXi, Windows Server, Linux — that connects and sees the LUN as a locally attached disk.

Every target has a unique IQN (iSCSI Qualified Name) automatically generated by OviOS:

iqn.YYYY-MM.org.ovios:<unique-id>-<your-name>

Creating a Target

target create

Example session:

Enter a custom target name: tg-esx01
Creating Target iqn.2026-05.org.ovios:lxh5jtu1zf9u-tg-esx01 ...
Define an initiator for this target? [y/n] (Default: n): y
Enter the IQN (e.g., iqn.1991-05.com.microsoft:client1) or the IP address of the initiator: 192.168.10.50
Add another initiator? [y/n] (Default: n): n

The iSCSI service must be running (options iscsi.enable on) to create or change targets.

Target Commands

target list           # show all targets with IDs and IQNs
target show           # detailed view including mapped LUNs and initiators
target remove         # delete a target (only when no LUNs are mapped)
target bind           # allow an initiator (IQN or IP) on a target
target unbind         # remove an initiator from a target
target chap           # add or remove incoming, outgoing and mutual CHAP accounts (6.2)
target edit [nano|vim] # edit raw target configuration

CHAP Authentication (6.2)

target chap opens a menu to require a username and password from initiators (incoming CHAP), to have the target prove itself to initiators (outgoing CHAP), or both (mutual CHAP). Passwords are entered masked and stored in /etc/tgt/chap.secrets (root only); targets.conf only names the users. CHAP accounts are included in configuration sync, backups and stateless saves.

8 LUNs — iSCSI Block Storage

What Is a LUN?

A LUN (Logical Unit Number) is a virtual block device carved from a ZFS pool and exported through an iSCSI target. From the initiator's perspective, it looks exactly like a locally attached hard disk.

Thin vs. Thick Provisioning

Creating a LUN

lun create              # fully interactive
lun create esx/lun02   # shortcut — skips pool/name prompts

You will be prompted for size (e.g. 50g, 1t) and provisioning type.

Mapping a LUN to a Target

A LUN must be mapped to an iSCSI target before initiators can use it. The recommended all-in-one approach is:

lun_setup   # guided: create LUN → map to target in one flow

LUN Commands Reference

lun list        # all LUNs with size, provisioning, mapping status
lun mappings    # all active target→LUN mappings
lun map         # map a LUN to an iSCSI target
lun umap        # unmap a LUN from a target
lun resize      # expand a LUN online (no downtime on most OS)
lun clone       # full, independent copy of a LUN (zfs send/receive)
lun info        # detailed LUN properties
lun delete      # permanently destroy a LUN — always umap first

# Example: lun mappings output
ID   TARGET IQN                                     LUN   PATH            STATUS
4    iqn.2026-05.org.ovios:...-tg-01-esx             1     /esx/lun01      IDLE
5    iqn.2026-05.org.ovios:...-vmware                1     /data/vms_lun   IDLE

Reclaiming Space: Thin LUNs, Discard and UNMAP (6.2)

Thin LUNs support SCSI UNMAP. When a client deletes data and sends discard / UNMAP commands, the freed blocks are returned to the pool, so a thin LUN only uses the space that holds live data.

Choose thin at the LUN type prompt of lun create (or lun_setup). UNMAP is enabled automatically for thin LUNs only. Thick LUNs keep their full reservation and never advertise UNMAP; the opt-out property below has no effect on them.

Every thin LUN is opted in by default. To opt one out, or back in, set the ZFS property on its volume (from the system shell, su-ovios):

sudo zfs set ovios:thin_provisioning=off <pool/lun>   # opt this thin LUN out of UNMAP
sudo zfs inherit ovios:thin_provisioning <pool/lun>   # opt it back in (default)
zfs get ovios:thin_provisioning <pool/lun>         # off = opted out, - = opted in

Older clients without UNMAP support can zero free space instead (for example sdelete -z on Windows); with ZFS compression enabled, zeroed blocks take no pool space.

9 Volumes — File-Based Sharing (NFS & SMB)

What Is a Volume?

A volume in OviOS is a ZFS dataset — a mountable filesystem exported over the network via NFS or SMB. Unlike LUNs (block devices), volumes are accessed as standard network file shares.

Creating a Volume

vol create                  # fully interactive
vol create data/myshare    # shortcut — skips pool/name prompts

You are asked for a size. It is set as both the quota and the reservation: the space is reserved in the pool immediately, so the volume can always grow to that size. If the volume already exists, OviOS exits gracefully with an error rather than overwriting data.

vol list     # all volumes with size and availability
vol resize   # change a volume's size (quota and reservation)
vol clone    # full, independent copy of a volume (zfs send/receive)
vol delete   # remove a volume and all its data

NFS Exports

NFS is the standard protocol for sharing filesystems with Linux and Unix clients.

nfs-export add data/myshare      # add export (interactive prompts for options)
nfs-export list                   # list active exports
nfs-export remove data/myshare   # remove export

Default options applied: rw,no_root_squash,no_subtree_check

SMB/CIFS Shares

SMB is the standard protocol for Windows file sharing, also supported natively by macOS and Linux.

Without Active Directory (Local Users)

# Step 1 — create a local SMB user
smb-user add username home_share_path

# Step 2 — share a volume with that user
smb-export add /data/myshare username

# Manage shares
smb-export list
smb-export remove data/myshare

With Active Directory

smb-join   # select option 1, provide domain, DC, and admin credentials

OviOS handles the Kerberos ticket and Samba configuration automatically. Once joined, use smb-export add to share a volume, then assign permissions from the Windows side using standard ACL tools (Security tab on share properties).

smb-join          # option 3 — renew Kerberos ticket if auth stops working
ovios ad status   # check AD join status

10 Centralized Management with ovios

The ovios command is a single entry point for the most common administrative tasks and a quick health check of your entire system.

ovios smb list           # list SMB exports
ovios smb add            # add SMB export
ovios nfs list           # list NFS exports
ovios nfs add pool/data # add NFS export
ovios ad join            # join Active Directory
ovios ad status          # check AD status
ovios user add           # add local SMB user
ovios hc                 # full storage health check

Health Check

ovios hc is the single most useful command for situational awareness. Run it after any configuration change or when troubleshooting.

ovios hc

Reports in a single output: all service statuses, AD join state, SMB/NFS share consistency, all LUN mappings with sizes and provisioning, and ZFS pool health with error counters.

11 Configuration Backup & Disaster Recovery

11.1 Automatic Configuration Saves (6.2)

From OviOS 6.2, every configuration change is saved automatically to a hidden dataset on each data pool (.ovios-system), as a ZFS snapshot per change. Nothing to schedule:

sync-config persist          # save now
sync-config persist-status   # saved generations per pool

11.2 Configuration Backup Archives

In addition, you can write a backup archive (.tar.gz) to the osbackup dataset of system.backup.pool (or /tmp/osbackup if no backup pool is set):

sync-config bo             # backup-only: create an archive
sync-config list-backups   # list archives
sync-config sync           # push the configuration to replication partners

11.3 Restoring After a Crash

After reinstalling OviOS on a new or repaired system disk:

1. Import your pools. OviOS detects existing pools on connected disks and prompts you to import them on first boot. Or run manually:

options skip.import off

service zfs  start

sync-config restore

2. Restore OviOS configuration. This reads metadata from the imported pools and reconstructs all iSCSI targets, LUN mappings, pool attributes, and share/export configurations:

restore all   # apply ovios specific flags on pools, targets, LUNs, exports, ...

3. Restart services and verify.

ovios hc   # verify everything is back online

11.4 Automated Configuration Backup

Schedule backup archives so they are always current — strongly recommended in production:

edit-cron   # edit system cron table

```
5 0 * * * /usr/bin/os sync-config bo  # backup at 5 minutes past midnight every day
```

And enable the cron service with the options command.

options cron.enable on

Or use the APIs to setup your own backup script with notifications, etc

11.5 Snapshot-Based Protection

ZFS snapshots protect against accidental deletion or data corruption. They are separate from the system-level configuration backup described above.

snap   # interactive wizard: choose volume/LUN, name snapshot, schedule

Snapshots are instant and space-efficient (copy-on-write). For off-site protection, use retadm to configure ZFS replication to a secondary OviOS system.

12 Advanced Operations & Best Practices

12.1 ZIL and SLOG

The ZFS Intent Log (ZIL) protects synchronous write operations against power loss. It is enabled by default and should remain enabled unless you have UPS protection.

options zfs.zil.disable poolname  # disable ZIL — only with UPS protection
options zfs.zil.disable reset     # re-enable ZIL for all pools

12.2 ARC Cache Tuning

The ZFS Adaptive Replacement Cache (ARC) uses system RAM to cache frequently read data. Correct sizing is the single largest performance lever in ZFS.

ovios hc                    # view current ARC stats
options arc.size 70         # set ARC to 70% of RAM

12.3 Performance Best Practices

Storage Layout

• Use mirrors for VM datastores — best random IOPS and lowest latency
• Use raidz2 for backup targets and bulk storage — best capacity with good resilience
• Keep pool utilization below 80% — ZFS fragmentation increases sharply above this threshold

Network

• Dedicate a separate NIC (or bond) to storage traffic — keep it off the management network
• Enable jumbo frames (MTU 9000) on storage NICs and switches for 10–15% throughput improvement
• For Windows SMB clients on multi-NIC systems, enable SMB Multichannel (requires Windows 8 / Server 2012+):

options smb.multichannel on

Disk Maintenance

• Turn on the monthly ZFS scrub (options zfs.scrub.auto on) to detect and correct silent data corruption
• Enable smartd to receive email alerts before a disk fails
• After a disk replacement, OviOS automatically begins resilver (RAID rebuild) — monitor with pool status
• Enable AutoTRIM on SSD-backed pools:

options zfs.trim.enable poolname

Compression

ZFS LZ4 compression is CPU-cheap and often improves throughput on compressible data (VM images, logs, databases). Compression is a ZFS dataset property; pool modify does not change it. Check or set it from the system shell (su-ovios), for example sudo zfs set compression=lz4 poolname; child volumes and LUNs inherit it.

12.4 Replication

retadm manages ZFS send/receive replication to a secondary OviOS system for off-site disaster recovery. Replication sends incremental snapshots over SSH and provides near-zero RPO with a fully independent copy of your data at a secondary site.

retadm   # interactive replication task manager