Menu="Utilities" Title="ZFS Master NG" Icon="zfs.master.png" Tag="zfs.master.png" ---

_(General Settings)_ _(Refresh Interval)_: : :zc_settings_refresh_interval_plug: > How often the Main tab reloads pools, datasets and snapshots. It pauses while the tab is in the background. > Choose **No refresh** to reload only when you click the refresh button or an action succeeds. :end _(Lazy Load)_: : :zc_settings_lazy_load_plug: > **Yes** shows datasets straight away, then fills in snapshots one pool at a time. > Use it when a pool with many snapshots makes the Main tab slow to appear. :end _(Load ZnapZend Data)_: : :zc_settings_znapzend_data_plug: > **Yes** reads the ZnapZend backup plans stored on each dataset and shows them in its details. > Leave it on **No** if you don't use ZnapZend. :end _(Size Units)_: : :zc_settings_size_units_plug: > **ZFS** shows sizes in powers of 1024 (GiB, TiB), the units zfs and zpool print. > **Unraid** shows them in powers of 1000 (GB, TB), rounded as Unraid's Main page does, so the same pool reads the same in both tables. > Either way, a pool's Size, Used and Free are the space you can use, as in Unraid's pool tables. The raw size zpool prints, which on raidz counts parity too, shows only while the pool's top dataset can't be read. :end _(Destructive Mode)_: : :zc_settings_destructive_mode_plug: > **Yes** adds Rename, Edit and Destroy to dataset menus, and Convert and Delete to folder menus. > It also lets a rollback remove newer snapshots, and a snapshot delete include child datasets. Each action still asks first. > Snapshots to keep and Keep Replicas remove old snapshots by their own rules whatever this is set to. :end _(Debug Log)_: : :zc_settings_debug_log_plug: > **Yes** also writes a debug log, `/var/log/zfs.master.debug.log`: the commands the plugin runs, how each ended and how long it took, and the name of each request to its admin page. > Turn it on to reproduce a problem, make the diagnostics zip, then turn it off again. > > - A replication and a rewrite run their copy or rewrite commands outside the debug log, and log their own lines in `/var/log/zfs.master.log` whether this is on or not. > - On a server receiving copies, a sender's requests run outside the debug log too: `/var/log/zfs.master.log` has each copy received or failed, and each request refused. > - The rsync that copies a folder into a dataset, and a diagnostics run's own commands, are in neither log. > - The arguments of rsync, and of a command that loads a key or names where one is kept, are left out. > - Each log keeps about 1 MB at most, its oldest lines going first. A diagnostics zip holds both. :end
_(Datasets)_ _(Dataset Exclusion Pattern)_: : :zc_settings_datasets_exclusion_plug: > Hides datasets whose names match this regular expression, with their child datasets, their snapshots and any matching folders. Leave it empty to hide nothing. > > - `/docker` hides every dataset with `/docker` in its name, such as `cache/system/docker`. > - It is one pattern: join several with `|`, such as `/docker|/vms`. > - Case is ignored. A `.` matches any character, so write `\.` for a dot. > - A pattern with `%` is read as a Lua pattern, the format older versions used: there a dot is `%.`, `|` is a plain character, and case counts. > > A pattern that isn't valid is ignored, and the Main tab says so. :end _(Directory Listing)_: : :zc_settings_directory_listing_plug: > One dataset name per line, such as `cache/appdata`. The Main tab then lists the folders directly inside each one, with a menu to move or rename each folder; with **Destructive Mode** on, also to convert it into a dataset or delete it. :end
_(Snapshots)_ _(Dataset Icon Alert Max Days)_: : :zc_settings_dataset_icon_color_plug: > Days since a dataset's last snapshot before its camera icon turns orange. Datasets with no snapshots stay grey. **Stale Snapshot Alerts** use the same number. :end _(Snapshots Pattern)_: : :zc_settings_snapshots_pattern_plug: > Date format for new snapshot names, written with [PHP date letters](https://www.php.net/manual/en/function.date.php): `Y` year, `m` month, `d` day, `H` hour, `i` minute, `s` second. It names snapshots taken from the Main tab, those **Replicate** takes, and each scheduled run's. > `Y-m-d-His` gives names like `tank/data@2026-11-03-181920`. With the prefix, a name may hold only letters, digits, spaces and `_ . : -`: one with any other character is refused. :end _(Snapshot Time)_: : :zc_settings_snapshots_utc_plug: > The clock used for the date in new snapshot names. UTC names sort the same on every server and across daylight-saving changes. :end _(Snapshots Prefix (Do not include the '@'))_: : :zc_settings_snapshots_prefix_plug: > Text placed before the date in new snapshot names. Leave out `@`. > With `zfs-master-`, names look like `tank/data@zfs-master-2026-11-03-181920`. :end
_(Alerts)_ _(Pool Health Alerts)_: : :zc_settings_alerts_interval_plug: > Checks the pools this often and sends an Unraid notification when a pool: > > - is not ONLINE, > - has read, write or checksum errors, or damaged files, > - or is not imported while the array is started, once 10 minutes have passed since the server booted or a check last saw the array stopped. > > It notifies again when the pool recovers. Checks start once the array has started. With **Off**, nothing checks the pools on a schedule, so none of these notifications is sent. :end _(Stale Snapshot Alerts)_: : :zc_settings_alerts_stale_plug: > With pool health alerts on, also notifies when a dataset's newest snapshot is older than **Dataset Icon Alert Max Days**. > Datasets with no snapshots, and datasets the exclusion pattern hides, are left out. :end
_(Replication)_ _(Accept Replicas Into)_: : :zc_settings_replica_accept_plug: > Lets other servers running ZFS Master NG send copies of their datasets here. To set it up: > > 1. Create the dataset the copies go into, such as `backup/replicas` (Main, **Create Dataset** on its pool), type its name here and Apply. A pool's top dataset isn't accepted. > 2. On the sending server, open ZFS Master NG's Settings and add this server under **Add A Server**. Compare the host key it reads with **This Server's Host Key** below, tick that they match, then Add. > 3. The sender then shows one line under this server's name. Copy it unchanged into this server's Users, root, **SSH authorized keys**, and Apply there. Unraid 6.9 has no such field: add the line to `/boot/config/ssh/root/authorized_keys` instead. > 4. Press Test beside this server on the sender. It makes the sender's own dataset inside this one, and shows its name. > > That line lets the sender's key only list, check and receive copies inside its own dataset here: it can't destroy, roll back or replace anything, or run anything else. Paste it unchanged: the sender's key on a line without these limits, such as the key alone, can run anything as root here. > Copies never mount or show as block devices, and run with setuid, devices and exec off. A quota on this dataset caps the space all copies use. Leave this empty to accept none. > > When both servers have zstd, as current Unraid does, copies of unencrypted datasets travel compressed with it and land just as they would without; with an earlier version of ZFS Master NG at either end they travel as they are. :end _(Keep Replicas)_: : :zc_settings_replica_keep_plug: > After each copy a server sends lands here, only the snapshots of that copy it keeps stay, up to 50 removed a time; the rest go with the next one. It reads as **Snapshots To Keep** under Schedules does: a number keeps the newest that many, and `7d`, `4w` and `12m` the newest of each of the last 7 days, 4 weeks and 12 months that have one (such as `24 7d 4w 12m`), by when the sender took each, in this server's time zone. Every snapshot of a copy counts, whichever run sent it, but one held or cloned here stays. The newest always stays: the sender's next run sends the changes since it. A copy that stops part-way loses nothing. When one can't be removed, this server's log and a notification say which and why. Empty keeps all. :end _(This Server's Host Key)_: : :zc_settings_replica_hostkey_plug: > The fingerprint of this server's SSH host key. A server adding this one reads the key over the network and shows its fingerprint: if the two differ, something else is answering at this server's address, so don't add it. :end _(Sender Keys)_: : :zc_settings_replica_keys_plug: > The lines in root's SSH authorized keys that run replica-serve.php, which receives copies here. A line limits its key to replication only when it has all three: > > - `restrict`, and none of `pty`, `port-forwarding`, `agent-forwarding`, `x11-forwarding` or `user-rc`: each gives back something `restrict` takes away. > - `from=` with the sender's exact IP addresses, commas between several: no ranges, wildcards, `!` or host names. > - `command=` with exactly `/usr/local/emhttp/plugins/zfs.master/scripts/replica-serve.php`, a space and the sender's name. > > A line shown in red lacks one of these: replace it with the line the sender shows, unchanged. :end
  :
_(Replicate To Other Servers)_ _(This Server's Key)_: : :zc_settings_send_key_plug: > This server's own SSH key for sending copies, made here once. Its private half is kept on the flash drive, unencrypted: keep the flash share and every flash backup private. To set up a server to send to, follow the steps under **Accept Replicas Into** in that server's ZFS Master NG Settings. :end _(Servers)_: : :zc_settings_send_servers_plug: > The servers this one may send copies to. Under each is the line to add to that server's SSH authorized keys (see **Accept Replicas Into** there), or what stops this server showing it. > > - Test makes this server's dataset there if it is missing, and shows its name. > - Each server's host key is kept from when it was added. If it changes, that server is refused until you remove it and add it again. > - The line's `from=` is the address this server sends from to reach that server. If this server's address changes, replace the line there with the new one. If a router between them changes the address (source NAT), that server refuses the key: set `from=` there to the exact address it sees. > > To send a copy, choose **Actions**, **Replicate** on a dataset in the Main tab, and pick the server under Server. :end _(Add A Server)_: : :zc_settings_send_add_plug: > Give the server a name for this list and the Replicate dialog, its IP address and its SSH port, then press **Read Host Key**. Compare the host key read here with **This Server's Host Key** in that server's ZFS Master NG Settings, under Replication; tick that they match, then Add. :end
_(Schedules)_ _(Snapshot Every Dataset)_: : :zc_settings_snapsched_plug: > Takes a snapshot of every dataset in every pool: every hour at a minute of its own, or at the time you set on the days you tick (all seven: every day), in this server's time zone. Save changes it, and the answer and the list below say when it runs. Off stops it; the snapshots it took stay. > > - A dataset can have a schedule of its own, or None, under **Actions**, **Schedules** in the Main tab: it and the datasets below it follow that one instead, unless they have their own. > - It leaves out read-only datasets, such as copies received here (a snapshot in one stops the next replication into it), and those mounted `legacy`, such as Docker's image layers. Make a dataset another tool receives copies into read-only too (`zfs set readonly=on`), or turn this off. > - It also leaves out datasets with Sanoid or Syncoid snapshots (named `autosnap_` or `syncoid_`): that tool takes their snapshots, and Syncoid would carry scheduled ones into its copies, where Sanoid never removes them. Once those snapshots are deleted, the dataset is taken again. With a **Snapshots Prefix** that itself starts `autosnap_` or `syncoid_`, snapshots named with it count as this plugin's own, and so do that tool's when they start the same. > - A run takes all of a pool's snapshots at one moment (one at a time if that fails), named by **Snapshots Pattern**. Nothing is taken when you save: the first run is at its time. > - **Snapshots To Keep**: after each run, only the scheduled snapshots it keeps stay on each dataset, whichever snapshot schedule took them (a run removes up to 50 from each). A number keeps the newest that many; `7d`, `4w` and `12m` keep the newest snapshot of each of the last 7 days, 4 weeks (Monday first) and 12 months that have one, in this server's time zone, so a day with none doesn't count; `h` and `y` count hours and years. Give any of them together, such as `24 7d 4w 12m`: what any one keeps stays. Snapshots made by hand or by a copy's schedule are never counted or removed, and one held or cloned stays. Empty keeps all. > - It and a copy's schedule can't start in the same minute: saving either one says so. > - The first run with a problem sends a notification. Later ones are logged in `/var/log/zfs.master.log` until a run works again, and that run's notification says so. :end _(Days)_: : _(Starts At)_: : _(Snapshots To Keep)_: :   : _(Replicate Every Dataset)_: : :zc_settings_copysched_plug: > Copies every dataset in every pool into the dataset you name under **Copy Under**, on this server, each copy named for its dataset: with `backup`, `cache/appdata` is copied to `backup/cache/appdata`. It runs every hour at a minute of its own, or at the time you set on the days you tick (all seven: every day), in this server's time zone. Save changes it, and the answer says how many datasets it copies. Off stops it; the copies and the snapshots it made stay. > > - Each run takes a new snapshot of each dataset, named by **Snapshots Pattern**, and sends the changes since the last one, as a copy's schedule does (see **Schedules** below): the first run sends each dataset in full, as does a run after a copy is gone, such as when the pool it goes into was made again. The copies are read-only and not mounted. > - It leaves out the datasets in the pool it copies into, and the ones Snapshot Every Dataset leaves out: read-only datasets, such as copies received here, those mounted `legacy`, and those with Sanoid or Syncoid snapshots. It also leaves out a dataset whose own copy schedule (**Actions**, **Replicate** in the Main tab) makes that same copy, one whose name is too long for the bookmark its copy keeps (over about 70 characters under `backup`, fewer under a longer **Copy Under**), and, when a run can't read the snapshot names, those it couldn't read: they may be left to Sanoid or Syncoid. > - A dataset's copy goes after the copy of the dataset above it. Where the dataset above one is not copied, an empty dataset, read-only and not mounted, is made in its place to hold the copies below it. If that dataset is copied later, its first copy replaces the empty one and the copies below it stay, though not while one of them is mounted, which receiving over it would unmount; an encrypted dataset sent raw can't replace it, nor can any copy replace an empty one that is encrypted, as one under an encrypted dataset is, and the run says what to do. When the copy of the dataset above one is missing because it failed, or the schedule that copies it has not made it yet, that one waits for the next run. > - **Snapshots To Keep**: for each dataset, as for a copy's schedule: only the snapshots this schedule took that it keeps stay, on the dataset and in its copy. Empty keeps all. A new **Copy Under** starts new copies there: the copies under the old one, and the snapshots taken for them, stay, as with Off. > - A dataset can have copies of its own, or None, under **Actions**, **Schedules** in the Main tab (**Replication**): it and the datasets below it follow that one instead, unless they have their own, each with its own **Copy Under**. > - Renaming a dataset in the Main tab renames its copies under each **Copy Under** a schedule uses with it, unless a dataset already has the new name there, no schedule copies it or a dataset below it there now, what is there is neither its copy nor a holder of the copies below it, or a dataset made to hold it would stop an encrypted copy due there; it says which of those stayed, and a clash its schedules meet where they went. Nothing is renamed while a copy of it or a dataset below it runs, or when the new name leaves no room for the bookmark a copy made now keeps (named by Snapshots Pattern as it is now); a bookmark made before that no longer fits stays, and the rename says so. Copies under a **Copy Under** no schedule uses now stay as they are. Destroying a dataset removes what it and the datasets below it had under **Actions**, **Schedules**, and leaves its copies. > - It and a snapshot schedule or copy's schedule of the same dataset can't start in the same minute: saving either one says so. > - A run waits for another replication of a dataset that is still sending; its waits add up to 55 minutes at most. A dataset that can't start in that time is skipped, and counts as a problem. A run that falls due while the one before still goes, as a first run can, is skipped and logged; once the one before has gone on for a day, it counts as a problem. > - Each run sends one notification at most: what it copied and its first problems. The first run with a problem sends it; later ones are logged in `/var/log/zfs.master.log` until a run works again, and that run's notification says so. The log has each dataset's replication. :end _(Copy Under)_: : _(Days)_: : _(Starts At)_: : _(Snapshots To Keep)_: :   : _(Schedules)_: : :zc_settings_schedules_plug: > Snapshot Every Dataset and Replicate Every Dataset, set above, each dataset's own snapshot schedule and copies (set under **Actions**, **Schedules** in the Main tab; Remove here sets it back to Default, unless the schedule it then follows would clash with one as saved), and the replications that run on their own. To add one of those, choose **Actions**, **Replicate** on a dataset in the Main tab and pick how often under Repeat: it runs then, and again every hour at a minute of its own, or at the time you set on the days you tick (all seven: every day), in this server's time zone. This list shows when. > > - Each run takes a new snapshot, named by **Snapshots Pattern**, and sends the changes since the last one. If the run before it stopped part-way, it carries that on first. > - **Snapshots to keep** (set in Replicate; Remove the schedule and add it again to change it): from its second run on, once a run lands, only those it keeps of the snapshots this copy's schedules took stay, as **Snapshots To Keep** above reads it (such as `24 7d 4w 12m`), up to 50 removed a run. In a copy on this server the same snapshots go first; one held or cloned, there or here, stays on both. Snapshots made by hand, by Snapshot Every Dataset or by a schedule of another copy are never counted or removed. The one just sent counts but always stays: the next run sends the changes since it. A copy on another server keeps all of them, unless that server's **Keep Replicas** keeps fewer. Empty keeps all. > - Each run holds its snapshot and the one it sends the changes since (`zfsm-resume-…`). One that stops part-way leaves them held, so nothing removes them before a run carries it on; a run to the copy that lands takes the hold off, and so does **Release** in Snapshots. When removing a snapshot fails, the run says which stays and why, and the next run tries again. > - A run that finds its copy gone doesn't send it in full again: replicate it once by hand to make a new copy. (Copies under a **Copy Under** are made again.) > - The first run with a problem sends a notification. Later ones are logged in `/var/log/zfs.master.log` until a run works again, and that run's notification says so. > - A run that falls due while another replication of its dataset is still sending waits for it, up to 55 minutes. One that can't start in that time is skipped, and counts as a problem. :end
_(Diagnostics)_ _(Unraid Diagnostics)_: : :zc_settings_diag_unraid_plug: > Put Unraid's own diagnostics zip inside the plugin's. It goes in as Unraid made it: this plugin changes nothing in it, and its system log can name datasets. > Its disk list (`system/df.txt`) can show mounted datasets by name. :end _(Diagnostics Zip)_: : :zc_settings_diag_zip_plug: > Collects what a bug report needs into one zip: the plugin's settings, install and log, the pools and datasets as it reads them, what this browser shows, and what it finds wrong. The zip is kept in `/boot/logs`, the newest three of them. > Dataset, snapshot and folder names, addresses and keys are replaced by tokens before anything is packed; pool names stay. > If this page does not load, run `/usr/local/emhttp/plugins/zfs.master/scripts/diagnostics.php` in a terminal: it prints what it finds and the zip's path. :end