OviOS Storage Controller

Administrator Guide — Complete operational reference

OviOS Linux v6 System Administrators ZFS · iSCSI · NFS · SMB

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

iSCSIPresent block storage to VMware ESXi, Windows, Linux

NFSShare filesystems with Linux and Unix clients

SMB/CIFSShare filesystems with Windows and macOS clients

S3Host an S3-compatible object storage endpoint

ZFS PoolsRAID, snapshots, replication, scrub, and compression

ovios-webWeb monitoring interface and PDF health reports

Active DirectoryJoin a domain for integrated Windows authentication

ReplicationReplicate LUNs and volumes to a secondary site

💡

Key design principle: Just run the command and follow the prompts. You rarely need to memorize syntax — OviOS guides you step-by-step through every operation.

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

⚡

For maximum iSCSI or NFS throughput, set MTU 9000 (jumbo frames) on storage-dedicated interfaces. Ensure your switch supports jumbo frames end-to-end.

2.2 Network Bonding — `bondadm`

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

Mode	Name	Use Case
0	balance-rr	Round-robin load balancing (requires switch config)
1	active-backup	Failover only — simplest and most compatible
4	802.3ad (LACP)	Active load balancing + failover; requires switch LACP support
6	balance-alb	Adaptive load balancing; no switch config needed

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

ℹ️

bondadm writes a fallback 99-*.network file. Always run netsetup afterward to create a properly numbered profile (e.g. 20-bond0.network) that takes precedence.

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.

Command	Purpose
`pool`	Create and manage ZFS storage pools
`lun`	Create, map, resize, and delete iSCSI LUNs
`lun_setup`	Interactive wizard: create LUN → map to target in one flow
`target`	Create and manage iSCSI targets
`vol`	Create ZFS datasets for NFS/SMB sharing
`smb-export`	Add/remove SMB shares
`nfs-export`	Add/remove NFS exports
`smb-user`	Manage local SMB users
`smb-join`	Join an Active Directory domain
`service`	Start/stop/restart/status all OviOS services
`options`	View and set system-wide options (ARC size, TRIM, ZIL, etc.)
`snap`	Create and manage ZFS snapshots
`retadm`	Configure volume/LUN replication tasks
`listdsk` / `ld`	List physical disks
`ovios`	Unified health check and service manager
`sync-config`	Back up configuration manually
`restore`	Restore pool attributes and LUN mappings after a crash
`send-logs`	Collect and email diagnostic logs
`sensors`	View hardware temperatures, fan speeds, voltages
`htop`	Interactive process monitor

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

💡

Always use by-id paths when creating pools on systems with many disks. This ensures ZFS can find the correct device after a reboot even if kernel device names (sda, sdb…) shift.

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

Service	Why
`ovios-web`	Web dashboard and PDF health report generation
`smartd`	Continuous disk health monitoring with email alerts
`ntp`	Time synchronization — required for Active Directory and log accuracy
`s3`	Object storage endpoint (if needed)
`auditd`	Security event logging

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

stripe

No Redundancy

1+ drives. Maximum space, zero fault tolerance. Development use only.

mirror (RAID-10)

Recommended for VMs

2+ drives (pairs). 1 disk failure per pair. Best random IOPS and lowest latency.

raidz1

1 Disk Tolerance

3+ drives. Good balance of space and protection for general workloads.

raidz2

Recommended for Bulk

4+ drives. Tolerates 2 simultaneous disk failures. Ideal for large drives (8TB+).

raidz3

3 Disk Tolerance

5+ drives. Highest fault tolerance. Best for archival and compliance workloads.

Creating a Pool

pool create

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

⚠️

If pool creation is interrupted and mirror vdevs were partially initialized, you need to wipe affected disks before retrying. Enter the system shell via su-ovios, then run:

# 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 cache and spare 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>

ℹ️

Targets with no LUNs mapped to them will not appear in the OviOS web interface. Always map at least one LUN to a target for it to be visible.

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]: y
Enter IP or IQN of the initiator: 192.168.10.50
Add another initiator? [y/n]: n

⚠️

If you skip the initiator restriction step, all initiators on the network can connect. Always restrict access in production environments.

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
target edit [nano|vim] # edit raw target configuration

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

Type	Description	Use Case
Thin	Space allocated only as data is written. LUN appears larger than actual consumed space.	Most VM deployments; efficient pool utilization
Thick	All space pre-allocated immediately at creation.	Latency-sensitive workloads; guaranteed reservation

💡

Use thick provisioning for most workloads to avoid performance issues as pools fill up. Keep pools below 80% to maintain ZFS performance.

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

ℹ️

The target must already exist before running lun_setup. If you need to map an existing LUN separately, use lun map.

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       # create a space-efficient snapshot-based clone
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 (Unmap / TRIM)

Windows clients: Run sdelete -z on the volume inside Windows before unmapping — this returns thin-provisioned space to the pool.

Linux clients: Use fstrim or the discard mount option to signal the target to reclaim unused blocks.

options zfs.trim.enable poolname   # enable automatic TRIM on a pool

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

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   # expand a volume quota
vol clone    # snapshot-based clone
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

Option	Meaning
`rw`	Read-write access
`ro`	Read-only access
`no_root_squash`	Root on the client has root-equivalent access on the share
`root_squash`	Root on the client is mapped to anonymous user (more secure)
`no_subtree_check`	Disables subtree checking — improves reliability for most setups
`sync`	Writes acknowledged only after committed to disk (safer)
`async`	Writes acknowledged before committing to disk (faster, less safe)

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

🛡️ How OviOS Protects Your Data

OviOS stores your data on ZFS pools — completely separate from the OS system disk. This means:

A system disk failure does not affect your storage data
You can reinstall OviOS or start in RAM and restore all settings from a backup in seconds and fully recover by running a single command
iSCSI targets, LUN mappings, share definitions, and pool attributes are all restored automatically

Full recovery from OS disk failure = reinstall OviOS (or boot into RAM) + restore config from a backup + run restore. That's it.

11.1 Manual Configuration Sync

Back up the current configuration at any time. This stores OviOS metadata alongside your pool data so it survives with the pools.

sync-config

💡

Run sync-config after creating or modifying pools, targets, LUNs, or shares, changing system options, or joining/leaving Active Directory.

11.2 Restoring After a Crash

After reinstalling OviOS on a new or repaired system disk:

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

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, ...

Restart services and verify.

ovios hc   # verify everything is back online

11.3 Automated Configuration Backup

Schedule system backups so your metadata is 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.4 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.

        
          ℹ️
          Snapshots protect against accidental changes. Your RAID layout protects against disk failure. Both are
            needed — they serve different purposes.



      
      
        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
        
          💡
          For high-throughput workloads with many small synchronous writes (databases, VMware), adding a dedicated
            NVMe or Optane SLOG device to the pool dramatically improves write performance while maintaining full data
            integrity.
        

        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

        
          
            
              
                Scenario
                Recommended ARC %
              
            
            
              
                Dedicated NAS/SAN appliance
                60–80% of RAM
              
              
                System also runs other services
                40–60%
              
              
                Minimum safe value
                25% — never go below this
              
            
          
        

        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
        
          Schedule a monthly ZFS scrub via edit-cron 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). Enable per-pool via pool modify.

        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
      

      
      
        
          ⚡ Quick Reference Card
          
            
              
                
                  Task
                  Command
                
              
              
                
                  Check all services & health
                  ovios hc
                
                
                  List pools
                  pool list
                
                
                  List all disks
                  listdsk
                
                
                  List free disks only
                  listdsk --free
                
                
                  Create pool
                  pool create
                
                
                  Create LUN
                  lun create
                
                
                  Create LUN + map to target
                  lun_setup
                
                
                  View LUN mappings
                  lun mappings
                
                
                  Create iSCSI target
                  target create
                
                
                  Create volume
                  vol create
                
                
                  Add NFS share
                  nfs-export add pool/volname
                
                
                  Add SMB share
                  smb-export add /pool/volname user
                
                
                  Backup config
                  sync-config
                
                
                  Restore config after crash
                  restore
                
                
                  Create snapshot
                  snap
                
                
                  View service status
                  service → status-all
                
                
                  View all commands
                  ?
                
              
            
          
        
      

      
        OviOS Linux v6 — Storage made simple.

Scenario	Recommended ARC %
Dedicated NAS/SAN appliance	60–80% of RAM
System also runs other services	40–60%
Minimum safe value	25% — never go below this

Task	Command
Check all services & health	`ovios hc`
List pools	`pool list`
List all disks	`listdsk`
List free disks only	`listdsk --free`
Create pool	`pool create`
Create LUN	`lun create`
Create LUN + map to target	`lun_setup`
View LUN mappings	`lun mappings`
Create iSCSI target	`target create`
Create volume	`vol create`
Add NFS share	`nfs-export add pool/volname`
Add SMB share	`smb-export add /pool/volname user`
Backup config	`sync-config`
Restore config after crash	`restore`
Create snapshot	`snap`
View service status	`service → status-all`
View all commands	`?`

OviOS Storage Controller

1 Introduction

What OviOS Can Do

2 Network Configuration

2.1 Interface Setup — netsetup

DHCP

Static IP

Fix Speed / Duplex

Remove Persistent Link Tuning

2.2 Network Bonding — bondadm

Create a Bond (LACP)

Create a Bond (Active-Backup)

Assign IP to Bond

List / Remove Bonds

2.3 VLANs — vlanadm

3 Command Reference Overview

4 Listing Disks

5 Services Management

Interactive Service Manager

Full Status Dashboard

Recommended Services to Enable

6 Creating Storage Pools

What Is a Pool?

RAID Layouts

stripe

mirror (RAID-10)

raidz1

raidz2

raidz3

Creating a Pool

Pool Commands

7 iSCSI Targets

What Is an iSCSI Target?

Creating a Target

Target Commands

8 LUNs — iSCSI Block Storage

What Is a LUN?

Thin vs. Thick Provisioning

Creating a LUN

Mapping a LUN to a Target

LUN Commands Reference

Reclaiming Space (Unmap / TRIM)

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

What Is a Volume?

Creating a Volume

NFS Exports

SMB/CIFS Shares

Without Active Directory (Local Users)

With Active Directory

10 Centralized Management with ovios

Health Check

11 Configuration Backup & Disaster Recovery

🛡️ How OviOS Protects Your Data

11.1 Manual Configuration Sync

11.2 Restoring After a Crash

11.3 Automated Configuration Backup

11.4 Snapshot-Based Protection

12 Advanced Operations & Best Practices

12.1 ZIL and SLOG

12.2 ARC Cache Tuning

12.3 Performance Best Practices

Storage Layout

Network

Disk Maintenance

Compression

12.4 Replication

⚡ Quick Reference Card

2.1 Interface Setup — `netsetup`

2.2 Network Bonding — `bondadm`

2.3 VLANs — `vlanadm`

10 Centralized Management with `ovios`