diff options
Diffstat (limited to 'sys/contrib/openzfs/man')
| -rw-r--r-- | sys/contrib/openzfs/man/Makefile.am | 204 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man1/cstyle.1 | 28 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man1/test-runner.1 | 296 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man1/ztest.1 | 12 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man4/zfs.4 | 198 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man7/dracut.zfs.7 | 278 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man7/zfsprops.7 | 25 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man7/zpool-features.7 | 27 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man7/zpoolconcepts.7 | 6 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zed.8.in | 2 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zfs-allow.8 | 24 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zfs-bookmark.8 | 6 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zfs-program.8 | 11 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zfs-send.8 | 41 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zfs-set.8 | 5 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zfs.8 | 52 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zpool-import.8 | 3 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zpool-list.8 | 2 | ||||
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zpool.8 | 2 |
19 files changed, 927 insertions, 295 deletions
diff --git a/sys/contrib/openzfs/man/Makefile.am b/sys/contrib/openzfs/man/Makefile.am index 8ab1b757242c..362ee9b7e149 100644 --- a/sys/contrib/openzfs/man/Makefile.am +++ b/sys/contrib/openzfs/man/Makefile.am @@ -1,117 +1,123 @@ -include $(top_srcdir)/config/Substfiles.am - EXTRA_DIST += \ - man1/cstyle.1 + %D%/man1/cstyle.1 dist_man_MANS = \ - man1/zhack.1 \ - man1/ztest.1 \ - man1/raidz_test.1 \ - man1/zvol_wait.1 \ - man1/arcstat.1 \ + %D%/man1/arcstat.1 \ + %D%/man1/raidz_test.1 \ + %D%/man1/test-runner.1 \ + %D%/man1/zhack.1 \ + %D%/man1/ztest.1 \ + %D%/man1/zvol_wait.1 \ \ - man5/vdev_id.conf.5 \ + %D%/man5/vdev_id.conf.5 \ \ - man4/spl.4 \ - man4/zfs.4 \ + %D%/man4/spl.4 \ + %D%/man4/zfs.4 \ \ - man7/zpool-features.7 \ - man7/zfsconcepts.7 \ - man7/zfsprops.7 \ - man7/zpoolconcepts.7 \ - man7/zpoolprops.7 \ + %D%/man7/dracut.zfs.7 \ + %D%/man7/zfsconcepts.7 \ + %D%/man7/zfsprops.7 \ + %D%/man7/zpool-features.7 \ + %D%/man7/zpoolconcepts.7 \ + %D%/man7/zpoolprops.7 \ \ - man8/fsck.zfs.8 \ - man8/mount.zfs.8 \ - man8/vdev_id.8 \ - man8/zdb.8 \ - man8/zfs.8 \ - man8/zfs-allow.8 \ - man8/zfs-bookmark.8 \ - man8/zfs-change-key.8 \ - man8/zfs-clone.8 \ - man8/zfs-create.8 \ - man8/zfs-destroy.8 \ - man8/zfs-diff.8 \ - man8/zfs-get.8 \ - man8/zfs-groupspace.8 \ - man8/zfs-hold.8 \ - man8/zfs-inherit.8 \ - man8/zfs-jail.8 \ - man8/zfs-list.8 \ - man8/zfs-load-key.8 \ - man8/zfs-mount.8 \ - man8/zfs-program.8 \ - man8/zfs-project.8 \ - man8/zfs-projectspace.8 \ - man8/zfs-promote.8 \ - man8/zfs-receive.8 \ - man8/zfs-recv.8 \ - man8/zfs-redact.8 \ - man8/zfs-release.8 \ - man8/zfs-rename.8 \ - man8/zfs-rollback.8 \ - man8/zfs-send.8 \ - man8/zfs-set.8 \ - man8/zfs-share.8 \ - man8/zfs-snapshot.8 \ - man8/zfs-unallow.8 \ - man8/zfs-unjail.8 \ - man8/zfs-unload-key.8 \ - man8/zfs-unmount.8 \ - man8/zfs-upgrade.8 \ - man8/zfs-userspace.8 \ - man8/zfs-wait.8 \ - man8/zfs_ids_to_path.8 \ - man8/zgenhostid.8 \ - man8/zinject.8 \ - man8/zpool.8 \ - man8/zpool-add.8 \ - man8/zpool-attach.8 \ - man8/zpool-checkpoint.8 \ - man8/zpool-clear.8 \ - man8/zpool-create.8 \ - man8/zpool-destroy.8 \ - man8/zpool-detach.8 \ - man8/zpool-events.8 \ - man8/zpool-export.8 \ - man8/zpool-get.8 \ - man8/zpool-history.8 \ - man8/zpool-import.8 \ - man8/zpool-initialize.8 \ - man8/zpool-iostat.8 \ - man8/zpool-labelclear.8 \ - man8/zpool-list.8 \ - man8/zpool-offline.8 \ - man8/zpool-online.8 \ - man8/zpool-reguid.8 \ - man8/zpool-remove.8 \ - man8/zpool-reopen.8 \ - man8/zpool-replace.8 \ - man8/zpool-resilver.8 \ - man8/zpool-scrub.8 \ - man8/zpool-set.8 \ - man8/zpool-split.8 \ - man8/zpool-status.8 \ - man8/zpool-sync.8 \ - man8/zpool-trim.8 \ - man8/zpool-upgrade.8 \ - man8/zpool-wait.8 \ - man8/zstream.8 \ - man8/zstreamdump.8 \ - man8/zpool_influxdb.8 + %D%/man8/fsck.zfs.8 \ + %D%/man8/mount.zfs.8 \ + %D%/man8/vdev_id.8 \ + %D%/man8/zdb.8 \ + %D%/man8/zfs.8 \ + %D%/man8/zfs-allow.8 \ + %D%/man8/zfs-bookmark.8 \ + %D%/man8/zfs-change-key.8 \ + %D%/man8/zfs-clone.8 \ + %D%/man8/zfs-create.8 \ + %D%/man8/zfs-destroy.8 \ + %D%/man8/zfs-diff.8 \ + %D%/man8/zfs-get.8 \ + %D%/man8/zfs-groupspace.8 \ + %D%/man8/zfs-hold.8 \ + %D%/man8/zfs-inherit.8 \ + %D%/man8/zfs-jail.8 \ + %D%/man8/zfs-list.8 \ + %D%/man8/zfs-load-key.8 \ + %D%/man8/zfs-mount.8 \ + %D%/man8/zfs-program.8 \ + %D%/man8/zfs-project.8 \ + %D%/man8/zfs-projectspace.8 \ + %D%/man8/zfs-promote.8 \ + %D%/man8/zfs-receive.8 \ + %D%/man8/zfs-recv.8 \ + %D%/man8/zfs-redact.8 \ + %D%/man8/zfs-release.8 \ + %D%/man8/zfs-rename.8 \ + %D%/man8/zfs-rollback.8 \ + %D%/man8/zfs-send.8 \ + %D%/man8/zfs-set.8 \ + %D%/man8/zfs-share.8 \ + %D%/man8/zfs-snapshot.8 \ + %D%/man8/zfs-unallow.8 \ + %D%/man8/zfs-unjail.8 \ + %D%/man8/zfs-unload-key.8 \ + %D%/man8/zfs-unmount.8 \ + %D%/man8/zfs-upgrade.8 \ + %D%/man8/zfs-userspace.8 \ + %D%/man8/zfs-wait.8 \ + %D%/man8/zfs_ids_to_path.8 \ + %D%/man8/zgenhostid.8 \ + %D%/man8/zinject.8 \ + %D%/man8/zpool.8 \ + %D%/man8/zpool-add.8 \ + %D%/man8/zpool-attach.8 \ + %D%/man8/zpool-checkpoint.8 \ + %D%/man8/zpool-clear.8 \ + %D%/man8/zpool-create.8 \ + %D%/man8/zpool-destroy.8 \ + %D%/man8/zpool-detach.8 \ + %D%/man8/zpool-events.8 \ + %D%/man8/zpool-export.8 \ + %D%/man8/zpool-get.8 \ + %D%/man8/zpool-history.8 \ + %D%/man8/zpool-import.8 \ + %D%/man8/zpool-initialize.8 \ + %D%/man8/zpool-iostat.8 \ + %D%/man8/zpool-labelclear.8 \ + %D%/man8/zpool-list.8 \ + %D%/man8/zpool-offline.8 \ + %D%/man8/zpool-online.8 \ + %D%/man8/zpool-reguid.8 \ + %D%/man8/zpool-remove.8 \ + %D%/man8/zpool-reopen.8 \ + %D%/man8/zpool-replace.8 \ + %D%/man8/zpool-resilver.8 \ + %D%/man8/zpool-scrub.8 \ + %D%/man8/zpool-set.8 \ + %D%/man8/zpool-split.8 \ + %D%/man8/zpool-status.8 \ + %D%/man8/zpool-sync.8 \ + %D%/man8/zpool-trim.8 \ + %D%/man8/zpool-upgrade.8 \ + %D%/man8/zpool-wait.8 \ + %D%/man8/zstream.8 \ + %D%/man8/zstreamdump.8 \ + %D%/man8/zpool_influxdb.8 nodist_man_MANS = \ - man8/zed.8 \ - man8/zfs-mount-generator.8 + %D%/man8/zed.8 \ + %D%/man8/zfs-mount-generator.8 SUBSTFILES += $(nodist_man_MANS) +CHECKS += mancheck +mancheck: + $(top_srcdir)/scripts/mancheck.sh $(srcdir)/%D% + + if BUILD_LINUX # The manual pager in most Linux distros defaults to "BSD" when .Os is blank, # but leaving it blank makes things a lot easier on # FreeBSD when OpenZFS is vendored in the base system. -install-data-hook: - cd $(DESTDIR)$(mandir) && $(SED) ${ac_inplace} -e 's/^\.Os$$/.Os OpenZFS/' $(dist_man_MANS) $(nodist_man_MANS) +INSTALL_DATA_HOOKS += man-install-data-hook +man-install-data-hook: + cd $(DESTDIR)$(mandir) && $(SED) $(ac_inplace) 's/^\.Os$$/.Os OpenZFS/' $(subst %D%/,,$(dist_man_MANS) $(nodist_man_MANS)) endif diff --git a/sys/contrib/openzfs/man/man1/cstyle.1 b/sys/contrib/openzfs/man/man1/cstyle.1 index f5f9ec78f827..e8f30f1f5950 100644 --- a/sys/contrib/openzfs/man/man1/cstyle.1 +++ b/sys/contrib/openzfs/man/man1/cstyle.1 @@ -30,7 +30,6 @@ .Sh SYNOPSIS .Nm .Op Fl chpvCP -.Op Fl o Ar construct Ns Op , Ns Ar construct Ns … .Oo Ar file Oc Ns … .Sh DESCRIPTION .Nm @@ -45,7 +44,6 @@ does not mean that you've followed Sun's C style. .Em Caveat emptor . . .Sh OPTIONS -The following options are supported: .Bl -tag -width "-c" .It Fl c Check continuation line indentation inside of functions. @@ -59,9 +57,6 @@ continuation line problems within functions only. The checks have some limitations; see .Sy CONTINUATION CHECKING , below. -.It Fl h -Performs heuristic checks that are sometimes wrong. -Not generally used. .It Fl p Performs some of the more picky checks. Includes ANSI @@ -74,10 +69,6 @@ Used as part of the putback checks. Verbose output; includes the text of the line of error, and, for .Fl c , the first statement in the current continuation block. -.It Fl C -Ignore errors in header comments (i.e. block comments starting in the -first column). -Not generally used. .It Fl P Check for use of non-POSIX types. Historically, types like @@ -91,16 +82,17 @@ types etc. This detects any use of the deprecated types. Used as part of the putback checks. -.It Fl o Ar construct Ns Op , Ns Ar construct Ns … -Available constructs include: -.Bl -tag -compact -width "doxygen" -.It Sy doxygen -Allow doxygen-style block comments -.Pq Sy /** No and Sy /*!\& . -.It Sy splint -Allow splint-style lint comments -.Pq Sy /*@ Ns ... Ns Sy @*/ . +.It Fl g +Also print GitHub-Actions-style +.Li ::error +output. .El +. +.Sh ENVIRONMENT +.Bl -tag -compact -width ".Ev CI" +.It Ev CI +If set and nonempty, equivalent to +.Fl g . .El . .Sh CONTINUATION CHECKING diff --git a/sys/contrib/openzfs/man/man1/test-runner.1 b/sys/contrib/openzfs/man/man1/test-runner.1 new file mode 100644 index 000000000000..b823aaa3e1a0 --- /dev/null +++ b/sys/contrib/openzfs/man/man1/test-runner.1 @@ -0,0 +1,296 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" Copyright (c) 2012 by Delphix. All rights reserved. +.\" +.Dd May 26, 2021 +.Dt RUN 1 +.Os +. +.Sh NAME +.Nm run +.Nd find, execute, and log the results of tests +.Sh SYNOPSIS +.Nm +.Op Fl dgq +.Op Fl o Ar outputdir +.Op Fl pP Ar script +.Op Fl t seconds +.Op Fl uxX Ar username +.Ar pathname Ns No … +.Pp +.Nm +.Fl w Ar runfile +.Op Fl gq +.Op Fl o Ar outputdir +.Op Fl pP Ar script +.Op Fl t seconds +.Op Fl uxX Ar username +.Ar pathname Ns No … +.Pp +.Nm +.Fl c Ar runfile +.Op Fl dq +.Pp +.Nm +.Op Fl h +. +.Sh DESCRIPTION +.Nm +command has three basic modes of operation. +With neither +.Fl c +nor +.Fl w , +.Nm +processes the arguments provided on +the command line, adding them to the list for this run. +If a specified +.Ar pathname +is an executable file, it is added as a test. +If a specified +.Ar pathname +is a directory, the behavior depends upon the presence of +.Fl g . +If +.Fl g +is specified, the directory is treated as a test group. +See the section on +.Sy Test Groups +below. +Without +.Fl g , +.Nm +simply descends into the directory looking for executable files. +The tests are then executed, and the results are logged. +.Pp +With +.Fl w , +.Nm +finds tests in the manner described above. +Rather than executing the tests and logging the results, the test configuration +is stored in a +.Ar runfile , +which can be used in future invocations, or edited +to modify which tests are executed and which options are applied. +Options included on the command line with +.Fl w +become defaults in the +.Ar runfile . +.Pp +With +.Fl c , +.Nm +parses a +.Ar runfile , +which can specify a series of tests and test groups to be executed. +The tests are then executed, and the results are logged. +. +.Ss Test Groups +A test group is comprised of a set of executable files, all of which exist in +one directory. +The options specified on the command line or in a +.Ar runfile +apply to individual tests in the group. +The exception is options pertaining to pre and post scripts, which act on all tests as a group. +Rather than running before and after each test, +these scripts are run only once each at the start and end of the test group. +.Ss Test Execution +The specified tests run serially, and are typically assigned results according +to exit values. +Tests that exit zero and non-zero are marked +.Sy PASS +and +.Sy FAIL , +respectively. +When a pre script fails for a test group, only the post script is executed, +and the remaining tests are marked +.Sy SKIPPED . +Any test that exceeds +its +.Ar timeout +is terminated, and marked +.Sy KILLED . +.Pp +By default, tests are executed with the credentials of the +.Nm +script. +Executing tests with other credentials is done via +.Xr sudo 1m , +which must +be configured to allow execution without prompting for a password. +Environment variables from the calling shell are available to individual tests. +During test execution, the working directory is changed to +.Ar outputdir . +. +.Ss Output Logging +By default, +.Nm +will print one line on standard output at the conclusion +of each test indicating the test name, result and elapsed time. +Additionally, for each invocation of +.Nm , +a directory is created using the ISO 8601 date format. +Within this directory is a file named +.Sy log +containing all the +test output with timestamps, and a directory for each test. +Within the test directories, there is one file each for standard output, +standard error and merged output. +The default location for the +.Ar outputdir +is +.Pa /var/tmp/test_results . +.Ss "Runfiles" +The +.Ar runfile +is an INI-style configuration file that describes a test run. +The file has one section named +.Sy DEFAULT , +which contains configuration option +names and their values in +.Sy name No = Ar value +format. +The values in this section apply to all the subsequent sections, +unless they are also specified there, in which case the default is overridden. +The remaining section names are the absolute pathnames of files and directories, +describing tests and test groups respectively. +The legal option names are: +.Bl -tag -width "tests = ['filename', …]" +.It Sy outputdir No = Ar pathname +The name of the directory that holds test logs. +.It Sy pre No = Ar script +Run +.Ar script +prior to the test or test group. +.It Sy pre_user No = Ar username +Execute the pre script as +.Ar username . +.It Sy post No = Ar script +Run +.Ar script +after the test or test group. +.It Sy post_user No = Ar username +Execute the post script as +.Ar username . +.It Sy quiet No = Sy True Ns | Ns Sy False +If +.Sy True , +only the results summary is printed to standard out. +.It Sy tests No = [ Ns Ar 'filename' , No … ] +Specify a list of +.Ar filenames +for this test group. +Only the basename of the absolute path is required. +This option is only valid for test groups, and each +.Ar filename +must be single quoted. +.It Sy timeout No = Ar n +A timeout value of +.Ar n +seconds. +.It Sy user No = Ar username +Execute the test or test group as +.Ar username . +.El +. +.Sh OPTIONS +.Bl -tag -width "-o outputdir" +.It Fl c Ar runfile +Specify a +.Ar runfile +to be consumed by the run command. +.It Fl d +Dry run mode. +Execute no tests, but print a description of each test that would have been run. +.It Fl m +Enable kmemleak reporting (Linux only) +.It Fl g +Create test groups from any directories found while searching for tests. +.It Fl o Ar outputdir +Specify the directory in which to write test results. +.It Fl p Ar script +Run +.Ar script +prior to any test or test group. +.It Fl P Ar script +Run +.Ar script +after any test or test group. +.It Fl q +Print only the results summary to the standard output. +.It Fl s Ar script +Run +.Ar script +as a failsafe after any test is killed. +.It Fl S Ar username +Execute the failsafe script as +.Ar username . +.It Fl t Ar n +Specify a timeout value of +.Ar n +seconds per test. +.It Fl u Ar username +Execute tests or test groups as +.Ar username . +.It Fl w Ar runfile +Specify the name of the +.Ar runfile +to create. +.It Fl x Ar username +Execute the pre script as +.Ar username . +.It Fl X Ar username +Execute the post script as +.Ar username . +.El +. +.Sh EXAMPLES +.Bl -tag -width "-h" +.It Sy Example 1 : No Running ad-hoc tests. +This example demonstrates the simplest invocation of +.Nm . +.Bd -literal +.No % Nm run Ar my-tests +Test: /home/jkennedy/my-tests/test-01 [00:02] [PASS] +Test: /home/jkennedy/my-tests/test-02 [00:04] [PASS] +Test: /home/jkennedy/my-tests/test-03 [00:01] [PASS] + +Results Summary +PASS 3 + +Running Time: 00:00:07 +Percent passed: 100.0% +Log directory: /var/tmp/test_results/20120923T180654 +.Ed +.It Sy Example 2 : No Creating a Ar runfile No for future use. +This example demonstrates creating a +.Ar runfile +with non-default options. +.Bd -literal +.No % Nm run Fl p Ar setup Fl x Ar root Fl g Fl w Ar new-tests.run Ar new-tests +.No % Nm cat Pa new-tests.run +[DEFAULT] +pre = setup +post_user = +quiet = False +user = +timeout = 60 +post = +pre_user = root +outputdir = /var/tmp/test_results + +[/home/jkennedy/new-tests] +tests = ['test-01', 'test-02', 'test-03'] +.Ed +.El +. +.Sh SEE ALSO +.Xr sudo 1m diff --git a/sys/contrib/openzfs/man/man1/ztest.1 b/sys/contrib/openzfs/man/man1/ztest.1 index fd1374a2f106..9e44eb4579f9 100644 --- a/sys/contrib/openzfs/man/man1/ztest.1 +++ b/sys/contrib/openzfs/man/man1/ztest.1 @@ -157,7 +157,17 @@ Time per pass. Max loops in .Fn spa_freeze . .It Fl B , -alt-ztest Ns = -Alternate ztest path. +Path to alternate ("older") +.Nm ztest +to drive, which will be used to initialise the pool, and, a stochastic half the time, to run the tests. +The parallel +.Pa lib +directory is prepended to +.Ev LD_LIBRARY_PATH ; +i.e. given +.Fl B Pa ./chroots/lenny/usr/bin/ Ns Nm , +.Pa ./chroots/lenny/usr/lib +will be loaded. .It Fl C , -vdev-class-state Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy random No (default: Sy random ) The vdev allocation class state. .It Fl o , -option Ns = Ns Ar variable Ns = Ns Ar value diff --git a/sys/contrib/openzfs/man/man4/zfs.4 b/sys/contrib/openzfs/man/man4/zfs.4 index 01e9c5de445d..5ef517c46faa 100644 --- a/sys/contrib/openzfs/man/man4/zfs.4 +++ b/sys/contrib/openzfs/man/man4/zfs.4 @@ -70,7 +70,7 @@ to a log2 fraction of the target ARC size. dnode slots allocated in a single operation as a power of 2. The default value minimizes lock contention for the bulk operation performed. . -.It Sy dmu_prefetch_max Ns = Ns Sy 134217728 Ns B Po 128MB Pc Pq int +.It Sy dmu_prefetch_max Ns = Ns Sy 134217728 Ns B Po 128 MiB Pc Pq int Limit the amount we can prefetch with one call to this amount in bytes. This helps to limit the amount of memory that can be used by prefetching. . @@ -164,7 +164,7 @@ If set to .Sy 100 we TRIM twice the space required to accommodate upcoming writes. A minimum of -.Sy 64MB +.Sy 64 MiB will be trimmed. It also enables TRIM of the whole L2ARC device upon creation or addition to an existing pool or if the header of the device is @@ -194,12 +194,12 @@ to enable caching/reading prefetches to/from L2ARC. .It Sy l2arc_norw Ns = Ns Sy 0 Ns | Ns 1 Pq int No reads during writes. . -.It Sy l2arc_write_boost Ns = Ns Sy 8388608 Ns B Po 8MB Pc Pq ulong +.It Sy l2arc_write_boost Ns = Ns Sy 8388608 Ns B Po 8 MiB Pc Pq ulong Cold L2ARC devices will have .Sy l2arc_write_max increased by this amount while they remain cold. . -.It Sy l2arc_write_max Ns = Ns Sy 8388608 Ns B Po 8MB Pc Pq ulong +.It Sy l2arc_write_max Ns = Ns Sy 8388608 Ns B Po 8 MiB Pc Pq ulong Max write bytes per interval. . .It Sy l2arc_rebuild_enabled Ns = Ns Sy 1 Ns | Ns 0 Pq int @@ -209,35 +209,35 @@ or attaching an L2ARC device (e.g. the L2ARC device is slow in reading stored log metadata, or the metadata has become somehow fragmented/unusable). . -.It Sy l2arc_rebuild_blocks_min_l2size Ns = Ns Sy 1073741824 Ns B Po 1GB Pc Pq ulong +.It Sy l2arc_rebuild_blocks_min_l2size Ns = Ns Sy 1073741824 Ns B Po 1 GiB Pc Pq ulong Mininum size of an L2ARC device required in order to write log blocks in it. The log blocks are used upon importing the pool to rebuild the persistent L2ARC. .Pp -For L2ARC devices less than 1GB, the amount of data +For L2ARC devices less than 1 GiB, the amount of data .Fn l2arc_evict evicts is significant compared to the amount of restored L2ARC data. In this case, do not write log blocks in L2ARC in order not to waste space. . -.It Sy metaslab_aliquot Ns = Ns Sy 524288 Ns B Po 512kB Pc Pq ulong +.It Sy metaslab_aliquot Ns = Ns Sy 1048576 Ns B Po 1 MiB Pc Pq ulong Metaslab granularity, in bytes. This is roughly similar to what would be referred to as the "stripe size" in traditional RAID arrays. -In normal operation, ZFS will try to write this amount of data -to a top-level vdev before moving on to the next one. +In normal operation, ZFS will try to write this amount of data to each disk +before moving on to the next top-level vdev. . .It Sy metaslab_bias_enabled Ns = Ns Sy 1 Ns | Ns 0 Pq int Enable metaslab group biasing based on their vdevs' over- or under-utilization relative to the pool. . -.It Sy metaslab_force_ganging Ns = Ns Sy 16777217 Ns B Ns B Po 16MB + 1B Pc Pq ulong +.It Sy metaslab_force_ganging Ns = Ns Sy 16777217 Ns B Po 16 MiB + 1 B Pc Pq ulong Make some blocks above a certain size be gang blocks. This option is used by the test suite to facilitate testing. . -.It Sy zfs_history_output_max Ns = Ns Sy 1048576 Ns B Ns B Po 1MB Pc Pq int +.It Sy zfs_history_output_max Ns = Ns Sy 1048576 Ns B Po 1 MiB Pc Pq int When attempting to log an output nvlist of an ioctl in the on-disk history, the output will not be stored if it is larger than this size (in bytes). This must be less than -.Sy DMU_MAX_ACCESS Pq 64MB . +.Sy DMU_MAX_ACCESS Pq 64 MiB . This applies primarily to .Fn zfs_ioc_channel_program Pq cf. Xr zfs-program 8 . . @@ -261,7 +261,7 @@ Prevent metaslabs from being unloaded. .It Sy metaslab_fragmentation_factor_enabled Ns = Ns Sy 1 Ns | Ns 0 Pq int Enable use of the fragmentation metric in computing metaslab weights. . -.It Sy metaslab_df_max_search Ns = Ns Sy 16777216 Ns B Po 16MB Pc Pq int +.It Sy metaslab_df_max_search Ns = Ns Sy 16777216 Ns B Po 16 MiB Pc Pq int Maximum distance to search forward from the last offset. Without this limit, fragmented pools can see .Em >100`000 @@ -270,7 +270,7 @@ iterations and becomes the performance limiting factor on high-performance storage. .Pp With the default setting of -.Sy 16MB , +.Sy 16 MiB , we typically see less than .Em 500 iterations, even with very fragmented @@ -279,7 +279,7 @@ pools. The maximum number of iterations possible is .Sy metaslab_df_max_search / 2^(ashift+1) . With the default setting of -.Sy 16MB +.Sy 16 MiB this is .Em 16*1024 Pq with Sy ashift Ns = Ns Sy 9 or @@ -293,7 +293,7 @@ this tunable controls which segment is used. If set, we will use the largest free segment. If unset, we will use a segment of at least the requested size. . -.It Sy zfs_metaslab_max_size_cache_sec Ns = Ns Sy 3600 Ns s Po 1h Pc Pq ulong +.It Sy zfs_metaslab_max_size_cache_sec Ns = Ns Sy 3600 Ns s Po 1 hour Pc Pq ulong When we unload a metaslab, we cache the size of the largest free chunk. We use that cached size to determine whether or not to load a metaslab for a given allocation. @@ -344,7 +344,7 @@ and the allocation can't actually be satisfied .It Sy zfs_vdev_default_ms_count Ns = Ns Sy 200 Pq int When a vdev is added, target this number of metaslabs per top-level vdev. . -.It Sy zfs_vdev_default_ms_shift Ns = Ns Sy 29 Po 512MB Pc Pq int +.It Sy zfs_vdev_default_ms_shift Ns = Ns Sy 29 Po 512 MiB Pc Pq int Default limit for metaslab size. . .It Sy zfs_vdev_max_auto_ashift Ns = Ns Sy ASHIFT_MAX Po 16 Pc Pq ulong @@ -380,7 +380,7 @@ Note that both this many TXGs and .Sy metaslab_unload_delay_ms milliseconds must pass before unloading will occur. . -.It Sy metaslab_unload_delay_ms Ns = Ns Sy 600000 Ns ms Po 10min Pc Pq int +.It Sy metaslab_unload_delay_ms Ns = Ns Sy 600000 Ns ms Po 10 min Pc Pq int After a metaslab is used, we keep it loaded for this many milliseconds, to attempt to reduce unnecessary reloading. Note, that both this many milliseconds and @@ -454,7 +454,14 @@ If we have less than this amount of free space, most ZPL operations (e.g. write, create) will return .Sy ENOSPC . . -.It Sy vdev_removal_max_span Ns = Ns Sy 32768 Ns B Po 32kB Pc Pq int +.It Sy spa_upgrade_errlog_limit Ns = Ns Sy 0 Pq uint +Limits the number of on-disk error log entries that will be converted to the +new format when enabling the +.Sy head_errlog +feature. +The default is to convert all log entries. +. +.It Sy vdev_removal_max_span Ns = Ns Sy 32768 Ns B Po 32 KiB Pc Pq int During top-level vdev removal, chunks of data are copied from the vdev which may include free space in order to trade bandwidth for IOPS. This parameter determines the maximum span of free space, in bytes, @@ -465,10 +472,10 @@ The default value here was chosen to align with which is a similar concept when doing regular reads (but there's no reason it has to be the same). . -.It Sy vdev_file_logical_ashift Ns = Ns Sy 9 Po 512B Pc Pq ulong +.It Sy vdev_file_logical_ashift Ns = Ns Sy 9 Po 512 B Pc Pq ulong Logical ashift for file-based devices. . -.It Sy vdev_file_physical_ashift Ns = Ns Sy 9 Po 512B Pc Pq ulong +.It Sy vdev_file_physical_ashift Ns = Ns Sy 9 Po 512 B Pc Pq ulong Physical ashift for file-based devices. . .It Sy zap_iterate_prefetch Ns = Ns Sy 1 Ns | Ns 0 Pq int @@ -477,13 +484,13 @@ prefetch the entire object (all leaf blocks). However, this is limited by .Sy dmu_prefetch_max . . -.It Sy zfetch_array_rd_sz Ns = Ns Sy 1048576 Ns B Po 1MB Pc Pq ulong +.It Sy zfetch_array_rd_sz Ns = Ns Sy 1048576 Ns B Po 1 MiB Pc Pq ulong If prefetching is enabled, disable prefetching for reads larger than this size. . -.It Sy zfetch_max_distance Ns = Ns Sy 8388608 Ns B Po 8MB Pc Pq uint +.It Sy zfetch_max_distance Ns = Ns Sy 8388608 Ns B Po 8 MiB Pc Pq uint Max bytes to prefetch per stream. . -.It Sy zfetch_max_idistance Ns = Ns Sy 67108864 Ns B Po 64MB Pc Pq uint +.It Sy zfetch_max_idistance Ns = Ns Sy 67108864 Ns B Po 64 MiB Pc Pq uint Max bytes to prefetch indirects for per stream. . .It Sy zfetch_max_streams Ns = Ns Sy 8 Pq uint @@ -506,7 +513,7 @@ The value of .Sy MAX_ORDER depends on kernel configuration. . -.It Sy zfs_abd_scatter_min_size Ns = Ns Sy 1536 Ns B Po 1.5kB Pc Pq uint +.It Sy zfs_abd_scatter_min_size Ns = Ns Sy 1536 Ns B Po 1.5 KiB Pc Pq uint This is the minimum allocation size that will use scatter (page-based) ABDs. Smaller allocations will use linear ABDs. . @@ -538,10 +545,10 @@ Percentage of ARC dnodes to try to scan in response to demand for non-metadata when the number of bytes consumed by dnodes exceeds .Sy zfs_arc_dnode_limit . . -.It Sy zfs_arc_average_blocksize Ns = Ns Sy 8192 Ns B Po 8kB Pc Pq int +.It Sy zfs_arc_average_blocksize Ns = Ns Sy 8192 Ns B Po 8 KiB Pc Pq int The ARC's buffer hash table is sized based on the assumption of an average block size of this value. -This works out to roughly 1MB of hash table per 1GB of physical memory +This works out to roughly 1 MiB of hash table per 1 GiB of physical memory with 8-byte pointers. For configurations with a known larger average block size, this value can be increased to reduce the memory footprint. @@ -552,9 +559,9 @@ When .Fn arc_get_data_impl waits for this percent of the requested amount of data to be evicted. For example, by default, for every -.Em 2kB +.Em 2 KiB that's evicted, -.Em 1kB +.Em 1 KiB of it may be "reused" by a new allocation. Since this is above .Sy 100 Ns % , @@ -595,12 +602,12 @@ Under Linux, half of system memory will be used as the limit. Under .Fx , the larger of -.Sy all_system_memory No \- Sy 1GB +.Sy all_system_memory No \- Sy 1 GiB and .Sy 5/8 No \(mu Sy all_system_memory will be used as the limit. This value must be at least -.Sy 67108864 Ns B Pq 64MB . +.Sy 67108864 Ns B Pq 64 MiB . .Pp This value can be changed dynamically, with some caveats. It cannot be set back to @@ -668,7 +675,7 @@ to evict the required number of metadata buffers. Min size of ARC in bytes. .No If set to Sy 0 , arc_c_min will default to consuming the larger of -.Sy 32MB +.Sy 32 MiB and .Sy all_system_memory No / Sy 32 . . @@ -709,7 +716,7 @@ If equivalent to a quarter of the user-wired memory limit under .Fx and to -.Sy 134217728 Ns B Pq 128MB +.Sy 134217728 Ns B Pq 128 MiB under Linux. . .It Sy zfs_multilist_num_sublists Ns = Ns Sy 0 Pq int @@ -787,10 +794,10 @@ Note that in practice, the kernel's shrinker can ask us to evict up to about four times this for one allocation attempt. .Pp The default limit of -.Sy 10000 Pq in practice, Em 160MB No per allocation attempt with 4kB pages +.Sy 10000 Pq in practice, Em 160 MiB No per allocation attempt with 4 KiB pages limits the amount of time spent attempting to reclaim ARC memory to -less than 100ms per allocation attempt, -even with a small average compressed block size of ~8kB. +less than 100 ms per allocation attempt, +even with a small average compressed block size of ~8 KiB. .Pp The parameter can be set to 0 (zero) to disable the limit, and only applies on Linux. @@ -798,7 +805,7 @@ and only applies on Linux. .It Sy zfs_arc_sys_free Ns = Ns Sy 0 Ns B Pq ulong The target number of bytes the ARC should leave as free memory on the system. If zero, equivalent to the bigger of -.Sy 512kB No and Sy all_system_memory/64 . +.Sy 512 KiB No and Sy all_system_memory/64 . . .It Sy zfs_autoimport_disable Ns = Ns Sy 1 Ns | Ns 0 Pq int Disable pool import at module load by ignoring the cache file @@ -839,12 +846,12 @@ bytes of memory and if the obsolete space map object uses more than bytes on-disk. The condensing process is an attempt to save memory by removing obsolete mappings. . -.It Sy zfs_condense_max_obsolete_bytes Ns = Ns Sy 1073741824 Ns B Po 1GB Pc Pq ulong +.It Sy zfs_condense_max_obsolete_bytes Ns = Ns Sy 1073741824 Ns B Po 1 GiB Pc Pq ulong Only attempt to condense indirect vdev mappings if the on-disk size of the obsolete space map object is greater than this number of bytes .Pq see Sy zfs_condense_indirect_vdevs_enable . . -.It Sy zfs_condense_min_mapping_bytes Ns = Ns Sy 131072 Ns B Po 128kB Pc Pq ulong +.It Sy zfs_condense_min_mapping_bytes Ns = Ns Sy 131072 Ns B Po 128 KiB Pc Pq ulong Minimum size vdev mapping to attempt to condense .Pq see Sy zfs_condense_indirect_vdevs_enable . . @@ -860,7 +867,7 @@ to the file clears the log. This setting does not influence debug prints due to .Sy zfs_flags . . -.It Sy zfs_dbgmsg_maxsize Ns = Ns Sy 4194304 Ns B Po 4MB Pc Pq int +.It Sy zfs_dbgmsg_maxsize Ns = Ns Sy 4194304 Ns B Po 4 MiB Pc Pq int Maximum size of the internal ZFS debug log. . .It Sy zfs_dbuf_state_index Ns = Ns Sy 0 Pq int @@ -900,21 +907,21 @@ This can be used to facilitate automatic fail-over to a properly configured fail-over partner. .El . -.It Sy zfs_deadman_checktime_ms Ns = Ns Sy 60000 Ns ms Po 1min Pc Pq int +.It Sy zfs_deadman_checktime_ms Ns = Ns Sy 60000 Ns ms Po 1 min Pc Pq int Check time in milliseconds. This defines the frequency at which we check for hung I/O requests and potentially invoke the .Sy zfs_deadman_failmode behavior. . -.It Sy zfs_deadman_synctime_ms Ns = Ns Sy 600000 Ns ms Po 10min Pc Pq ulong +.It Sy zfs_deadman_synctime_ms Ns = Ns Sy 600000 Ns ms Po 10 min Pc Pq ulong Interval in milliseconds after which the deadman is triggered and also the interval after which a pool sync operation is considered to be "hung". Once this limit is exceeded the deadman will be invoked every .Sy zfs_deadman_checktime_ms milliseconds until the pool sync completes. . -.It Sy zfs_deadman_ziotime_ms Ns = Ns Sy 300000 Ns ms Po 5min Pc Pq ulong +.It Sy zfs_deadman_ziotime_ms Ns = Ns Sy 300000 Ns ms Po 5 min Pc Pq ulong Interval in milliseconds after which the deadman is triggered and an individual I/O operation is considered to be "hung". As long as the operation remains "hung", @@ -967,7 +974,7 @@ same object. Rate limit delay and deadman zevents (which report slow I/O operations) to this many per second. . -.It Sy zfs_unflushed_max_mem_amt Ns = Ns Sy 1073741824 Ns B Po 1GB Pc Pq ulong +.It Sy zfs_unflushed_max_mem_amt Ns = Ns Sy 1073741824 Ns B Po 1 GiB Pc Pq ulong Upper-bound limit for unflushed metadata changes to be held by the log spacemap in memory, in bytes. . @@ -975,16 +982,16 @@ log spacemap in memory, in bytes. Part of overall system memory that ZFS allows to be used for unflushed metadata changes by the log spacemap, in millionths. . -.It Sy zfs_unflushed_log_block_max Ns = Ns Sy 262144 Po 256k Pc Pq ulong +.It Sy zfs_unflushed_log_block_max Ns = Ns Sy 131072 Po 128k Pc Pq ulong Describes the maximum number of log spacemap blocks allowed for each pool. The default value means that the space in all the log spacemaps can add up to no more than -.Sy 262144 +.Sy 131072 blocks (which means -.Em 32GB +.Em 16 GiB of logical space before compression and ditto blocks, assuming that blocksize is -.Em 128kB ) . +.Em 128 KiB ) . .Pp This tunable is important because it involves a trade-off between import time after an unclean export and the frequency of flushing metaslabs. @@ -1011,7 +1018,12 @@ Thus we always allow at least this many log blocks. .It Sy zfs_unflushed_log_block_pct Ns = Ns Sy 400 Ns % Pq ulong Tunable used to determine the number of blocks that can be used for the spacemap log, expressed as a percentage of the total number of -metaslabs in the pool. +unflushed metaslabs in the pool. +. +.It Sy zfs_unflushed_log_txg_max Ns = Ns Sy 1000 Pq ulong +Tunable limiting maximum time in TXGs any metaslab may remain unflushed. +It effectively limits maximum number of unflushed per-TXG spacemap logs +that need to be read after unclean pool export. . .It Sy zfs_unlink_suspend_progress Ns = Ns Sy 0 Ns | Ns 1 Pq uint When enabled, files will not be asynchronously removed from the list of pending @@ -1383,7 +1395,7 @@ Similar to .Sy zfs_free_min_time_ms , but for cleanup of old indirection records for removed vdevs. . -.It Sy zfs_immediate_write_sz Ns = Ns Sy 32768 Ns B Po 32kB Pc Pq long +.It Sy zfs_immediate_write_sz Ns = Ns Sy 32768 Ns B Po 32 KiB Pc Pq long Largest data block to write to the ZIL. Larger blocks will be treated as if the dataset being written to had the .Sy logbias Ns = Ns Sy throughput @@ -1393,7 +1405,7 @@ property set. Pattern written to vdev free space by .Xr zpool-initialize 8 . . -.It Sy zfs_initialize_chunk_size Ns = Ns Sy 1048576 Ns B Po 1MB Pc Pq ulong +.It Sy zfs_initialize_chunk_size Ns = Ns Sy 1048576 Ns B Po 1 MiB Pc Pq ulong Size of writes used by .Xr zpool-initialize 8 . This option is used by the test suite. @@ -1441,7 +1453,7 @@ This option is used by the test suite to trigger race conditions. The maximum execution time limit that can be set for a ZFS channel program, specified as a number of Lua instructions. . -.It Sy zfs_lua_max_memlimit Ns = Ns Sy 104857600 Po 100MB Pc Pq ulong +.It Sy zfs_lua_max_memlimit Ns = Ns Sy 104857600 Po 100 MiB Pc Pq ulong The maximum memory limit that can be set for a ZFS channel program, specified in bytes. . @@ -1457,15 +1469,15 @@ feature uses to estimate incoming log blocks. .It Sy zfs_max_logsm_summary_length Ns = Ns Sy 10 Pq ulong Maximum number of rows allowed in the summary of the spacemap log. . -.It Sy zfs_max_recordsize Ns = Ns Sy 1048576 Po 1MB Pc Pq int +.It Sy zfs_max_recordsize Ns = Ns Sy 16777216 Po 16 MiB Pc Pq int We currently support block sizes from -.Em 512B No to Em 16MB . +.Em 512 Po 512 B Pc No to Em 16777216 Po 16 MiB Pc . The benefits of larger blocks, and thus larger I/O, need to be weighed against the cost of COWing a giant block to modify one byte. Additionally, very large blocks can have an impact on I/O latency, and also potentially on the memory allocator. -Therefore, we do not allow the recordsize to be set larger than this tunable. -Larger blocks can be created by changing it, +Therefore, we formerly forbade creating blocks larger than 1M. +Larger blocks could be created by changing it, and pools with larger blocks can always be imported and used, regardless of this setting. . @@ -1523,7 +1535,7 @@ into the special allocation class. Historical statistics for this many latest multihost updates will be available in .Pa /proc/spl/kstat/zfs/ Ns Ao Ar pool Ac Ns Pa /multihost . . -.It Sy zfs_multihost_interval Ns = Ns Sy 1000 Ns ms Po 1s Pc Pq ulong +.It Sy zfs_multihost_interval Ns = Ns Sy 1000 Ns ms Po 1 s Pc Pq ulong Used to control the frequency of multihost writes which are performed when the .Sy multihost pool property is on. @@ -1556,7 +1568,7 @@ delay found in the best uberblock indicates actual multihost updates happened at longer intervals than .Sy zfs_multihost_interval . A minimum of -.Em 100ms +.Em 100 ms is enforced. .Pp .Sy 0 No is equivalent to Sy 1 . @@ -1605,7 +1617,7 @@ When enabled forces ZFS to sync data when flags are used allowing holes in a file to be accurately reported. When disabled holes will not be reported in recently dirtied files. . -.It Sy zfs_pd_bytes_max Ns = Ns Sy 52428800 Ns B Po 50MB Pc Pq int +.It Sy zfs_pd_bytes_max Ns = Ns Sy 52428800 Ns B Po 50 MiB Pc Pq int The number of bytes which should be prefetched during a pool traversal, like .Nm zfs Cm send or other data crawling operations. @@ -1644,7 +1656,7 @@ Disable QAT hardware acceleration for AES-GCM encryption. May be unset after the ZFS modules have been loaded to initialize the QAT hardware as long as support is compiled in and the QAT driver is present. . -.It Sy zfs_vnops_read_chunk_size Ns = Ns Sy 1048576 Ns B Po 1MB Pc Pq long +.It Sy zfs_vnops_read_chunk_size Ns = Ns Sy 1048576 Ns B Po 1 MiB Pc Pq long Bytes to read per chunk. . .It Sy zfs_read_history Ns = Ns Sy 0 Pq int @@ -1654,7 +1666,7 @@ Historical statistics for this many latest reads will be available in .It Sy zfs_read_history_hits Ns = Ns Sy 0 Ns | Ns 1 Pq int Include cache hits in read history . -.It Sy zfs_rebuild_max_segment Ns = Ns Sy 1048576 Ns B Po 1MB Pc Pq ulong +.It Sy zfs_rebuild_max_segment Ns = Ns Sy 1048576 Ns B Po 1 MiB Pc Pq ulong Maximum read segment size to issue when sequentially resilvering a top-level vdev. . @@ -1664,7 +1676,7 @@ completes in order to verify the checksums of all blocks which have been resilvered. This is enabled by default and strongly recommended. . -.It Sy zfs_rebuild_vdev_limit Ns = Ns Sy 33554432 Ns B Po 32MB Pc Pq ulong +.It Sy zfs_rebuild_vdev_limit Ns = Ns Sy 33554432 Ns B Po 32 MiB Pc Pq ulong Maximum amount of I/O that can be concurrently issued for a sequential resilver per leaf device, given in bytes. . @@ -1696,7 +1708,7 @@ pool cannot be returned to a healthy state prior to removing the device. This is used by the test suite so that it can ensure that certain actions happen while in the middle of a removal. . -.It Sy zfs_remove_max_segment Ns = Ns Sy 16777216 Ns B Po 16MB Pc Pq int +.It Sy zfs_remove_max_segment Ns = Ns Sy 16777216 Ns B Po 16 MiB Pc Pq int The largest contiguous segment that we will attempt to allocate when removing a device. If there is a performance problem with attempting to allocate large blocks, @@ -1709,7 +1721,7 @@ Ignore the feature, causing an operation that would start a resilver to immediately restart the one in progress. . -.It Sy zfs_resilver_min_time_ms Ns = Ns Sy 3000 Ns ms Po 3s Pc Pq int +.It Sy zfs_resilver_min_time_ms Ns = Ns Sy 3000 Ns ms Po 3 s Pc Pq int Resilvers are processed by the sync thread. While resilvering, it will spend at least this much time working on a resilver between TXG flushes. @@ -1720,12 +1732,12 @@ even if there were unrepairable errors. Intended to be used during pool repair or recovery to stop resilvering when the pool is next imported. . -.It Sy zfs_scrub_min_time_ms Ns = Ns Sy 1000 Ns ms Po 1s Pc Pq int +.It Sy zfs_scrub_min_time_ms Ns = Ns Sy 1000 Ns ms Po 1 s Pc Pq int Scrubs are processed by the sync thread. While scrubbing, it will spend at least this much time working on a scrub between TXG flushes. . -.It Sy zfs_scan_checkpoint_intval Ns = Ns Sy 7200 Ns s Po 2h Pc Pq int +.It Sy zfs_scan_checkpoint_intval Ns = Ns Sy 7200 Ns s Po 2 hour Pc Pq int To preserve progress across reboots, the sequential scan algorithm periodically needs to stop metadata scanning and issue all the verification I/O to disk. The frequency of this flushing is determined by this tunable. @@ -1762,7 +1774,7 @@ Otherwise indicates that the legacy algorithm will be used, where I/O is initiated as soon as it is discovered. Unsetting will not affect scrubs or resilvers that are already in progress. . -.It Sy zfs_scan_max_ext_gap Ns = Ns Sy 2097152 Ns B Po 2MB Pc Pq int +.It Sy zfs_scan_max_ext_gap Ns = Ns Sy 2097152 Ns B Po 2 MiB Pc Pq int Sets the largest gap in bytes between scrub/resilver I/O operations that will still be considered sequential for sorting purposes. Changing this value will not @@ -1791,7 +1803,7 @@ When disabled, the memory limit may be exceeded by fast disks. Freezes a scrub/resilver in progress without actually pausing it. Intended for testing/debugging. . -.It Sy zfs_scan_vdev_limit Ns = Ns Sy 4194304 Ns B Po 4MB Pc Pq int +.It Sy zfs_scan_vdev_limit Ns = Ns Sy 4194304 Ns B Po 4 MiB Pc Pq int Maximum amount of data that can be concurrently issued at once for scrubs and resilvers per leaf device, given in bytes. . @@ -1811,7 +1823,7 @@ The fill fraction of the internal queues. The fill fraction controls the timing with which internal threads are woken up. . -.It Sy zfs_send_no_prefetch_queue_length Ns = Ns Sy 1048576 Ns B Po 1MB Pc Pq int +.It Sy zfs_send_no_prefetch_queue_length Ns = Ns Sy 1048576 Ns B Po 1 MiB Pc Pq int The maximum number of bytes allowed in .Nm zfs Cm send Ns 's internal queues. @@ -1822,7 +1834,7 @@ The fill fraction of the prefetch queue. The fill fraction controls the timing with which internal threads are woken up. . -.It Sy zfs_send_queue_length Ns = Ns Sy 16777216 Ns B Po 16MB Pc Pq int +.It Sy zfs_send_queue_length Ns = Ns Sy 16777216 Ns B Po 16 MiB Pc Pq int The maximum number of bytes allowed that will be prefetched by .Nm zfs Cm send . This value must be at least twice the maximum block size in use. @@ -1833,20 +1845,20 @@ The fill fraction of the queue. The fill fraction controls the timing with which internal threads are woken up. . -.It Sy zfs_recv_queue_length Ns = Ns Sy 16777216 Ns B Po 16MB Pc Pq int +.It Sy zfs_recv_queue_length Ns = Ns Sy 16777216 Ns B Po 16 MiB Pc Pq int The maximum number of bytes allowed in the .Nm zfs Cm receive queue. This value must be at least twice the maximum block size in use. . -.It Sy zfs_recv_write_batch_size Ns = Ns Sy 1048576 Ns B Po 1MB Pc Pq int +.It Sy zfs_recv_write_batch_size Ns = Ns Sy 1048576 Ns B Po 1 MiB Pc Pq int The maximum amount of data, in bytes, that .Nm zfs Cm receive will write in one DMU transaction. This is the uncompressed size, even when receiving a compressed send stream. This setting will not reduce the write size below a single block. Capped at a maximum of -.Sy 32MB . +.Sy 32 MiB . . .It Sy zfs_override_estimate_recordsize Ns = Ns Sy 0 Ns | Ns 1 Pq ulong Setting this variable overrides the default logic for estimating block @@ -1861,7 +1873,7 @@ and you require accurate zfs send size estimates. Flushing of data to disk is done in passes. Defer frees starting in this pass. . -.It Sy zfs_spa_discard_memory_limit Ns = Ns Sy 16777216 Ns B Po 16MB Pc Pq int +.It Sy zfs_spa_discard_memory_limit Ns = Ns Sy 16777216 Ns B Po 16 MiB Pc Pq int Maximum memory used for prefetching a checkpoint's space map on each vdev while discarding the checkpoint. . @@ -1883,11 +1895,11 @@ the average number of sync passes; because when we turn compression off, many blocks' size will change, and thus we have to re-allocate (not overwrite) them. It also increases the number of -.Em 128kB +.Em 128 KiB allocations (e.g. for indirect blocks and spacemaps) because these will not be compressed. The -.Em 128kB +.Em 128 KiB allocations are especially detrimental to performance on highly fragmented systems, which may have very few free segments of this size, and may need to load new metaslabs to satisfy these allocations. @@ -1902,11 +1914,11 @@ The default value of .Sy 75% will create a maximum of one thread per CPU. . -.It Sy zfs_trim_extent_bytes_max Ns = Ns Sy 134217728 Ns B Po 128MB Pc Pq uint +.It Sy zfs_trim_extent_bytes_max Ns = Ns Sy 134217728 Ns B Po 128 MiB Pc Pq uint Maximum size of TRIM command. Larger ranges will be split into chunks no larger than this value before issuing. . -.It Sy zfs_trim_extent_bytes_min Ns = Ns Sy 32768 Ns B Po 32kB Pc Pq uint +.It Sy zfs_trim_extent_bytes_min Ns = Ns Sy 32768 Ns B Po 32 KiB Pc Pq uint Minimum size of TRIM commands. TRIM ranges smaller than this will be skipped, unless they're part of a larger range which was chunked. @@ -1954,20 +1966,20 @@ This is normally not helpful because the extents to be trimmed will have been already been aggregated by the metaslab. This option is provided for debugging and performance analysis. . -.It Sy zfs_vdev_aggregation_limit Ns = Ns Sy 1048576 Ns B Po 1MB Pc Pq int +.It Sy zfs_vdev_aggregation_limit Ns = Ns Sy 1048576 Ns B Po 1 MiB Pc Pq int Max vdev I/O aggregation size. . -.It Sy zfs_vdev_aggregation_limit_non_rotating Ns = Ns Sy 131072 Ns B Po 128kB Pc Pq int +.It Sy zfs_vdev_aggregation_limit_non_rotating Ns = Ns Sy 131072 Ns B Po 128 KiB Pc Pq int Max vdev I/O aggregation size for non-rotating media. . -.It Sy zfs_vdev_cache_bshift Ns = Ns Sy 16 Po 64kB Pc Pq int +.It Sy zfs_vdev_cache_bshift Ns = Ns Sy 16 Po 64 KiB Pc Pq int Shift size to inflate reads to. . -.It Sy zfs_vdev_cache_max Ns = Ns Sy 16384 Ns B Po 16kB Pc Pq int +.It Sy zfs_vdev_cache_max Ns = Ns Sy 16384 Ns B Po 16 KiB Pc Pq int Inflate reads smaller than this value to meet the .Sy zfs_vdev_cache_bshift size -.Pq default Sy 64kB . +.Pq default Sy 64 KiB . . .It Sy zfs_vdev_cache_size Ns = Ns Sy 0 Pq int Total size of the per-disk cache in bytes. @@ -1989,7 +2001,7 @@ lacks locality as defined by Operations within this that are not immediately following the previous operation are incremented by half. . -.It Sy zfs_vdev_mirror_rotating_seek_offset Ns = Ns Sy 1048576 Ns B Po 1MB Pc Pq int +.It Sy zfs_vdev_mirror_rotating_seek_offset Ns = Ns Sy 1048576 Ns B Po 1 MiB Pc Pq int The maximum distance for the last queued I/O operation in which the balancing algorithm considers an operation to have locality. .No See Sx ZFS I/O SCHEDULER . @@ -2007,11 +2019,11 @@ locality as defined by the Operations within this that are not immediately following the previous operation are incremented by half. . -.It Sy zfs_vdev_read_gap_limit Ns = Ns Sy 32768 Ns B Po 32kB Pc Pq int +.It Sy zfs_vdev_read_gap_limit Ns = Ns Sy 32768 Ns B Po 32 KiB Pc Pq int Aggregate read I/O operations if the on-disk gap between them is within this threshold. . -.It Sy zfs_vdev_write_gap_limit Ns = Ns Sy 4096 Ns B Po 4kB Pc Pq int +.It Sy zfs_vdev_write_gap_limit Ns = Ns Sy 4096 Ns B Po 4 KiB Pc Pq int Aggregate write I/O operations if the on-disk gap between them is within this threshold. . @@ -2059,7 +2071,7 @@ Setting this to .Sy 0 disables duplicate detection. . -.It Sy zfs_zevent_retain_expire_secs Ns = Ns Sy 900 Ns s Po 15min Pc Pq int +.It Sy zfs_zevent_retain_expire_secs Ns = Ns Sy 900 Ns s Po 15 min Pc Pq int Lifespan for a recent ereport that was retained for duplicate checking. . .It Sy zfs_zil_clean_taskq_maxalloc Ns = Ns Sy 1048576 Pq int @@ -2078,10 +2090,10 @@ The default value of .Sy 100% will create a maximum of one thread per cpu. . -.It Sy zil_maxblocksize Ns = Ns Sy 131072 Ns B Po 128kB Pc Pq int +.It Sy zil_maxblocksize Ns = Ns Sy 131072 Ns B Po 128 KiB Pc Pq int This sets the maximum block size used by the ZIL. On very fragmented pools, lowering this -.Pq typically to Sy 36kB +.Pq typically to Sy 36 KiB can improve performance. . .It Sy zil_nocacheflush Ns = Ns Sy 0 Ns | Ns 1 Pq int @@ -2094,7 +2106,7 @@ if a volatile out-of-order write cache is enabled. Disable intent logging replay. Can be disabled for recovery from corrupted ZIL. . -.It Sy zil_slog_bulk Ns = Ns Sy 786432 Ns B Po 768kB Pc Pq ulong +.It Sy zil_slog_bulk Ns = Ns Sy 786432 Ns B Po 768 KiB Pc Pq ulong Limit SLOG write size per commit executed with synchronous priority. Any writes above that will be executed with lower (asynchronous) priority to limit potential SLOG device abuse by single active ZIL writer. @@ -2126,7 +2138,7 @@ diagnostic information for hang conditions which don't involve a mutex or other locking primitive: typically conditions in which a thread in the zio pipeline is looping indefinitely. . -.It Sy zio_slow_io_ms Ns = Ns Sy 30000 Ns ms Po 30s Pc Pq int +.It Sy zio_slow_io_ms Ns = Ns Sy 30000 Ns ms Po 30 s Pc Pq int When an I/O operation takes more than this much time to complete, it's marked as slow. Each slow operation causes a delay zevent. @@ -2202,7 +2214,7 @@ many blocks, where block size is determined by the .Sy volblocksize property of a zvol. . -.It Sy zvol_prefetch_bytes Ns = Ns Sy 131072 Ns B Po 128kB Pc Pq uint +.It Sy zvol_prefetch_bytes Ns = Ns Sy 131072 Ns B Po 128 KiB Pc Pq uint When adding a zvol to the system, prefetch this many bytes from the start and end of the volume. Prefetching these regions of the volume is desirable, @@ -2394,7 +2406,7 @@ delay Note, that since the delay is added to the outstanding time remaining on the most recent transaction it's effectively the inverse of IOPS. Here, the midpoint of -.Em 500us +.Em 500 us translates to .Em 2000 IOPS . The shape of the curve diff --git a/sys/contrib/openzfs/man/man7/dracut.zfs.7 b/sys/contrib/openzfs/man/man7/dracut.zfs.7 new file mode 100644 index 000000000000..0f446fe2fe3f --- /dev/null +++ b/sys/contrib/openzfs/man/man7/dracut.zfs.7 @@ -0,0 +1,278 @@ +.\" SPDX-License-Identifier: 0BSD +.\" +.Dd April 4, 2022 +.Dt DRACUT.ZFS 7 +.Os +. +.Sh NAME +.Nm dracut.zfs +.Nd overview of ZFS dracut hooks +. +.Sh SYNOPSIS +.Bd -literal -compact + parse-zfs.sh \(-> dracut-cmdline.service + | \(da + | … + | \(da + \e\(em\(em\(em\(em\(em\(em\(em\(em\(-> dracut-initqueue.service + | zfs-import-opts.sh + zfs-load-module.service \(da | | + | | sysinit.target \(da | + \(da | | zfs-import-scan.service \(da +zfs-import-scan.service \(da \(da | zfs-import-cache.service + | zfs-import-cache.service basic.target | | + \e__________________| | \(da \(da + \(da | zfs-load-key.sh + zfs-env-bootfs.service | | + \(da \(da \(da + zfs-import.target \(-> dracut-pre-mount.service + | \(ua | + | dracut-zfs-generator | + | ____________________/| + |/ \(da + | sysroot.mount \(<-\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em dracut-zfs-generator + | | \(da | + | \(da sysroot-{usr,etc,lib,&c.}.mount | + | initrd-root-fs.target \(<-\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em or \(da + | | zfs-nonroot-necessities.service + | \(da | + \(da dracut-mount.service | + zfs-snapshot-bootfs.service | | + | \(da | + \(da … | + zfs-rollback-bootfs.service | | + | \(da | + | sysroot-usr.mount \(<-\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em/ + | | + | \(da + | initrd-fs.target + \e______________________ | + \e| + \(da + export-zfs.sh initrd.target + | | + \(da \(da + dracut-shutdown.service … + | + \(da + zfs-needshutdown.sh \(-> initrd-cleanup.service +.Ed +.Pp +Compare +.Xr dracut.bootup 7 +for the full flowchart. +. +.Sh DESCRIPTION +Under dracut, booting with +.No ZFS-on- Ns Pa / +is facilitated by a number of hooks in the +.Nm 90zfs +module. +.Pp +Booting into a ZFS dataset requires +.Sy mountpoint Ns = Ns Pa / +to be set on the dataset containing the root filesystem (henceforth "the boot dataset") and at the very least either the +.Sy bootfs +property to be set to that dataset, or the +.Sy root= +kernel cmdline (or dracut drop-in) argument to specify it. +.Pp +All children of the boot dataset with +.Sy canmount Ns = Ns Sy on +with +.Sy mountpoint Ns s +matching +.Pa /etc , /bin , /lib , /lib?? , /libx32 , No and Pa /usr +globs are deemed essential and will be mounted as well. +.Pp +.Xr zfs-mount-generator 8 +is recommended for proper functioning of the system afterward (correct mount properties, remounting, &c.). +. +.Sh CMDLINE +.Ss Standard +.Bl -tag -compact -width ".Sy root=zfs:AUTO , root=zfs: , root=zfs , Op Sy root=" +.It Sy root=zfs:\& Ns Ar dataset , Sy root=ZFS= Ns Ar dataset +Use +.Ar dataset +as the boot dataset. +All pluses +.Pq Sq + +are replaced with spaces +.Pq Sq \ . +. +.It Sy root=zfs:AUTO , root=zfs:\& , root=zfs , Op Sy root= +After import, search for the first pool with the +.Sy bootfs +property set, use its value as-if specified as the +.Ar dataset +above. +. +.It Sy rootfstype=zfs root= Ns Ar dataset +Equivalent to +.Sy root=zfs:\& Ns Ar dataset . +. +.It Sy rootfstype=zfs Op Sy root= +Equivalent to +.Sy root=zfs:AUTO . +. +.It Sy rootflags= Ns Ar flags +Mount the boot dataset with +.Fl o Ar flags ; +cf.\& +.Sx Temporary Mount Point Properties +in +.Xr zfsprops 7 . +These properties will not last, since all filesystems will be re-mounted from the real root. +. +.It Sy debug +If specified, +.Nm dracut-zfs-generator +logs to the journal. +.El +.Pp +Be careful about setting neither +.Sy rootfstype=zfs +nor +.Sy root=zfs:\& Ns Ar dataset +\(em other automatic boot selection methods, like +.Nm systemd-gpt-auto-generator +and +.Nm systemd-fstab-generator +might take precedent. +. +.Ss ZFS-specific +.Bl -tag -compact -width ".Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name" +.It Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name +Execute +.Nm zfs Cm snapshot Ar boot-dataset Ns Sy @ Ns Ar snapshot-name +before pivoting to the real root. +.Ar snapshot-name +defaults to the current kernel release. +. +.It Sy bootfs.rollback Ns Op Sy = Ns Ar snapshot-name +Execute +.Nm zfs Cm snapshot Fl Rf Ar boot-dataset Ns Sy @ Ns Ar snapshot-name +before pivoting to the real root. +.Ar snapshot-name +defaults to the current kernel release. +. +.It Sy spl_hostid= Ns Ar host-id +Use +.Xr zgenhostid 8 +to set the host ID to +.Ar host-id ; +otherwise, +.Pa /etc/hostid +inherited from the real root is used. +. +.It Sy zfs_force , zfs.force , zfsforce +Appends +.Fl f +to all +.Nm zpool Cm import +invocations; primarily useful in conjunction with +.Sy spl_hostid= , +or if no host ID was inherited. +.El +. +.Sh FILES +.Bl -tag -width 0 +.It Pa parse-zfs.sh Pq Sy cmdline +Processes +.Sy spl_hostid= . +If +.Sy root= +matches a known pattern, above, provides +.Pa /dev/root +and delays the initqueue until +.Xr zfs 4 +is loaded, +. +.It Pa zfs-import-opts.sh Pq Nm systemd No environment generator +Turns +.Sy zfs_force , zfs.force , No or Sy zfsforce +into +.Ev ZPOOL_IMPORT_OPTS Ns = Ns Fl f +for +.Pa zfs-import-scan.service +or +.Pa zfs-import-cache.service . +. +.It Pa zfs-load-key.sh Pq Sy pre-mount +Loads encryption keys for the boot dataset and its essential descendants. +.Bl -tag -compact -offset 4n -width ".Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL" +.It Sy keylocation Ns = Ns Sy prompt +Is prompted for via +.Nm systemd-ask-password +thrice. +. +.It Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL +.Pa network-online.target +is started before loading. +. +.It Sy keylocation Ns = Ns Sy file:// Ns Ar path +If +.Ar path +doesn't exist, +.Nm udevadm No is Cm settle Ns d . +If it still doesn't, it's waited for for up to +.Sy 10 Ns s . +.El +. +.It Pa zfs-env-bootfs.service Pq Nm systemd No service +After pool import, sets +.Ev BOOTFS Ns = +in the systemd environment to the first non-null +.Sy bootfs +value in iteration order. +. +.It Pa dracut-zfs-generator Pq Nm systemd No generator +Generates +.Pa sysroot.mount Pq using Sy rootflags= , No if any . +If an explicit boot dataset was specified, also generates essential mountpoints +.Pq Pa sysroot-etc.mount , sysroot-bin.mount , No &c.\& , +otherwise generates +.Pa zfs-nonroot-necessities.service +which mounts them explicitly after +.Pa /sysroot +using +.Ev BOOTFS Ns = . +. +.It Pa zfs-snapshot-bootfs.service , zfs-rollback-bootfs.service Pq Nm systemd No services +Consume +.Sy bootfs.snapshot +and +.Sy bootfs.rollback +as described in +.Sx CMDLINE . +Use +.Ev BOOTFS Ns = +if no explicit boot dataset was specified. +. +.It Pa zfs-needshutdown.sh Pq Sy cleanup +If any pools were imported, signals that shutdown hooks are required. +. +.It Pa export-zfs.sh Pq Sy shutdown +Forcibly exports all pools. +. +.It Pa /etc/hostid , /etc/zfs/zpool.cache , /etc/zfs/vdev_id.conf Pq regular files +Included verbatim, hostonly. +. +.It Pa mount-zfs.sh Pq Sy mount +Does nothing on +.Nm systemd +systems +.Pq if Pa dracut-zfs-generator No succeeded . +Otherwise, loads encryption key for the boot dataset from the console or via plymouth. +It may not work at all! +.El +. +.Sh SEE ALSO +.Xr dracut.bootup 7 , +.Xr zfsprops 7 , +.Xr zpoolprops 7 , +.Xr dracut-shutdown.service 8 , +.Xr systemd-fstab-generator 8 , +.Xr systemd-gpt-auto-generator 8 , +.Xr zfs-mount-generator 8 , +.Xr zgenhostid 8 diff --git a/sys/contrib/openzfs/man/man7/zfsprops.7 b/sys/contrib/openzfs/man/man7/zfsprops.7 index 0976e80d7309..2694938aa206 100644 --- a/sys/contrib/openzfs/man/man7/zfsprops.7 +++ b/sys/contrib/openzfs/man/man7/zfsprops.7 @@ -388,7 +388,7 @@ privilege with can access everyone's usage. .Pp The -.Sy userused Ns @ Ns Ar ... +.Sy userused Ns @ Ns Ar … properties are not displayed by .Nm zfs Cm get Sy all . The user's name must be appended after the @@ -872,14 +872,17 @@ This is done using .Sy zstd-fast- Ns Ar N , where .Ar N -is an integer in [1-9,10,20,30,...,100,500,1000] which maps to a negative +is an integer in +.Bq Sy 1 Ns - Ns Sy 10 , 20 , 30 , No … , Sy 100 , 500 , 1000 +which maps to a negative .Sy zstd level. -The lower the level the faster the compression - -.Ar 1000 No provides the fastest compression and lowest compression ratio. +The lower the level the faster the compression \(em +.Sy 1000 +provides the fastest compression and lowest compression ratio. .Sy zstd-fast is equivalent to -.Sy zstd-fast-1 . +.Sy zstd-fast- Ns Ar 1 . .Pp The .Sy zle @@ -901,7 +904,7 @@ after compression, otherwise the compression will not be considered worthwhile and the block saved uncompressed. Note that when the logical block is less than 8 times the disk sector size this effectively reduces the necessary compression -ratio; for example, 8kB blocks on disks with 4kB disk sectors must compress to 1/2 +ratio; for example, 8 KiB blocks on disks with 4 KiB disk sectors must compress to 1/2 or less of their original size. .It Xo .Sy context Ns = Ns Sy none Ns | Ns @@ -1196,7 +1199,7 @@ blocks into the special allocation class. Blocks smaller than or equal to this value will be assigned to the special allocation class while greater blocks will be assigned to the regular class. -Valid values are zero or a power of two from 512B up to 1M. +Valid values are zero or a power of two from 512 up to 1048576 (1 MiB). The default size is 0 which means no small file blocks will be allocated in the special class. .Pp @@ -1315,7 +1318,7 @@ can get and set everyone's quota. This property is not available on volumes, on file systems before version 4, or on pools before version 15. The -.Sy userquota@ Ns Ar ... +.Sy userquota@ Ns Ar … properties are not displayed by .Nm zfs Cm get Sy all . The user's name must be appended after the @@ -1423,13 +1426,13 @@ Use of this property for general purpose file systems is strongly discouraged, and may adversely affect performance. .Pp The size specified must be a power of two greater than or equal to -.Ar 512B +.Ar 512 B and less than or equal to -.Ar 128kB . +.Ar 128 KiB . If the .Sy large_blocks feature is enabled on the pool, the size may be up to -.Ar 1MB . +.Ar 1 MiB . See .Xr zpool-features 7 for details on ZFS feature flags. diff --git a/sys/contrib/openzfs/man/man7/zpool-features.7 b/sys/contrib/openzfs/man/man7/zpool-features.7 index 9a202ca8a596..b92109c4ac98 100644 --- a/sys/contrib/openzfs/man/man7/zpool-features.7 +++ b/sys/contrib/openzfs/man/man7/zpool-features.7 @@ -157,7 +157,7 @@ separated by whitespace and/or commas. Only features present in all files are enabled. .Pp Simple sanity checks are applied to the files: -they must be between 1B and 16kB in size, and must end with a newline character. +they must be between 1 B and 16 KiB in size, and must end with a newline character. .Pp The requested features are applied when a pool is created using .Nm zpool Cm create Fl o Sy compatibility Ns = Ns Ar … @@ -446,7 +446,7 @@ or smaller can take advantage of this feature. When this feature is enabled, the contents of highly-compressible blocks are stored in the block "pointer" itself (a misnomer in this case, as it contains the compressed data, rather than a pointer to its location on disk). -Thus the space of the block (one sector, typically 512B or 4kB) is saved, +Thus the space of the block (one sector, typically 512 B or 4 KiB) is saved, and no additional I/O is needed to read and write the data block. . \*[instant-never] @@ -507,6 +507,17 @@ once either of the limit properties has been set on a dataset and will never return to being .Sy enabled . . +.feature com.delphix head_errlog no +This feature enables the upgraded version of errlog, which required an on-disk +error log format change. +Now the error log of each head dataset is stored separately in the zap object +and keyed by the head id. +With this feature enabled, every dataset affected by an error block is listed +in the output of +.Nm zpool Cm status . +.Pp +\*[instant-never] +. .feature com.delphix hole_birth no enabled_txg This feature has/had bugs, the result of which is that, if you do a .Nm zfs Cm send Fl i @@ -554,29 +565,29 @@ already exist on the receiving side. \*[instant-never] . .feature org.open-zfs large_blocks no extensible_dataset -This feature allows the record size on a dataset to be set larger than 128kB. +This feature allows the record size on a dataset to be set larger than 128 KiB. .Pp This feature becomes .Sy active -once a dataset contains a file with a block size larger than 128kB, +once a dataset contains a file with a block size larger than 128 KiB, and will return to being .Sy enabled -once all filesystems that have ever had their recordsize larger than 128kB +once all filesystems that have ever had their recordsize larger than 128 KiB are destroyed. . .feature org.zfsonlinux large_dnode no extensible_dataset -This feature allows the size of dnodes in a dataset to be set larger than 512B. +This feature allows the size of dnodes in a dataset to be set larger than 512 B. . This feature becomes .Sy active -once a dataset contains an object with a dnode larger than 512B, +once a dataset contains an object with a dnode larger than 512 B, which occurs as a result of setting the .Sy dnodesize dataset property to a value other than .Sy legacy . The feature will return to being .Sy enabled -once all filesystems that have ever contained a dnode larger than 512B +once all filesystems that have ever contained a dnode larger than 512 B are destroyed. Large dnodes allow more data to be stored in the bonus buffer, thus potentially improving performance by avoiding the use of spill blocks. diff --git a/sys/contrib/openzfs/man/man7/zpoolconcepts.7 b/sys/contrib/openzfs/man/man7/zpoolconcepts.7 index 582aeae50e29..ea2b783f32a7 100644 --- a/sys/contrib/openzfs/man/man7/zpoolconcepts.7 +++ b/sys/contrib/openzfs/man/man7/zpoolconcepts.7 @@ -107,7 +107,7 @@ Unlike raidz, dRAID uses a fixed stripe width (padding as necessary with zeros) to allow fully sequential resilvering. This fixed stripe width significantly effects both usable capacity and IOPS. For example, with the default -.Em D=8 No and Em 4kB No disk sectors the minimum allocation size is Em 32kB . +.Em D=8 No and Em 4 KiB No disk sectors the minimum allocation size is Em 32 KiB . If using compression, this relatively large allocation size can reduce the effective compression ratio. When using ZFS volumes and dRAID, the default of the @@ -422,13 +422,13 @@ asynchronously when importing the pool in L2ARC (persistent L2ARC). This can be disabled by setting .Sy l2arc_rebuild_enabled Ns = Ns Sy 0 . For cache devices smaller than -.Em 1GB , +.Em 1 GiB , we do not write the metadata structures required for rebuilding the L2ARC in order not to waste space. This can be changed with .Sy l2arc_rebuild_blocks_min_l2size . The cache device header -.Pq Em 512B +.Pq Em 512 B is updated even if no metadata structures are written. Setting .Sy l2arc_headroom Ns = Ns Sy 0 diff --git a/sys/contrib/openzfs/man/man8/zed.8.in b/sys/contrib/openzfs/man/man8/zed.8.in index d3297605206e..6c51f10695cc 100644 --- a/sys/contrib/openzfs/man/man8/zed.8.in +++ b/sys/contrib/openzfs/man/man8/zed.8.in @@ -75,7 +75,7 @@ Custom .Ev $PATH for zedlets to use. Normally zedlets run in a locked-down environment, with hardcoded paths to the ZFS commands -.Pq Ev $ZFS , $ZPOOL , $ZED , ... , +.Pq Ev $ZFS , $ZPOOL , $ZED , … , and a hard-coded .Ev $PATH . This is done for security reasons. diff --git a/sys/contrib/openzfs/man/man8/zfs-allow.8 b/sys/contrib/openzfs/man/man8/zfs-allow.8 index f949a0a5eee5..52b7c43f44ba 100644 --- a/sys/contrib/openzfs/man/man8/zfs-allow.8 +++ b/sys/contrib/openzfs/man/man8/zfs-allow.8 @@ -215,19 +215,19 @@ send subcommand share subcommand Allows sharing file systems over NFS or SMB protocols snapshot subcommand Must also have the \fBmount\fR ability -groupquota other Allows accessing any \fBgroupquota@\fI...\fR property -groupobjquota other Allows accessing any \fBgroupobjquota@\fI...\fR property -groupused other Allows reading any \fBgroupused@\fI...\fR property -groupobjused other Allows reading any \fBgroupobjused@\fI...\fR property +groupquota other Allows accessing any \fBgroupquota@\fI…\fR property +groupobjquota other Allows accessing any \fBgroupobjquota@\fI…\fR property +groupused other Allows reading any \fBgroupused@\fI…\fR property +groupobjused other Allows reading any \fBgroupobjused@\fI…\fR property userprop other Allows changing any user property -userquota other Allows accessing any \fBuserquota@\fI...\fR property -userobjquota other Allows accessing any \fBuserobjquota@\fI...\fR property -userused other Allows reading any \fBuserused@\fI...\fR property -userobjused other Allows reading any \fBuserobjused@\fI...\fR property -projectobjquota other Allows accessing any \fBprojectobjquota@\fI...\fR property -projectquota other Allows accessing any \fBprojectquota@\fI...\fR property -projectobjused other Allows reading any \fBprojectobjused@\fI...\fR property -projectused other Allows reading any \fBprojectused@\fI...\fR property +userquota other Allows accessing any \fBuserquota@\fI…\fR property +userobjquota other Allows accessing any \fBuserobjquota@\fI…\fR property +userused other Allows reading any \fBuserused@\fI…\fR property +userobjused other Allows reading any \fBuserobjused@\fI…\fR property +projectobjquota other Allows accessing any \fBprojectobjquota@\fI…\fR property +projectquota other Allows accessing any \fBprojectquota@\fI…\fR property +projectobjused other Allows reading any \fBprojectobjused@\fI…\fR property +projectused other Allows reading any \fBprojectused@\fI…\fR property aclinherit property aclmode property diff --git a/sys/contrib/openzfs/man/man8/zfs-bookmark.8 b/sys/contrib/openzfs/man/man8/zfs-bookmark.8 index 88153b2ccfb5..8b268b714385 100644 --- a/sys/contrib/openzfs/man/man8/zfs-bookmark.8 +++ b/sys/contrib/openzfs/man/man8/zfs-bookmark.8 @@ -30,7 +30,7 @@ .\" Copyright 2019 Joyent, Inc. .\" Copyright (c) 2019, 2020 by Christian Schwarz. All Rights Reserved. .\" -.Dd March 16, 2022 +.Dd May 12, 2022 .Dt ZFS-BOOKMARK 8 .Os . @@ -65,8 +65,8 @@ feature. .\" These are, respectively, examples 23 from zfs.8 .\" Make sure to update them bidirectionally .Ss Example 1 : No Creating a bookmark -The following example create a bookmark to a snapshot. -This bookmark can then be used instead of snapshot in send streams. +The following example creates a bookmark to a snapshot. +This bookmark can then be used instead of a snapshot in send streams. .Dl # Nm zfs Cm bookmark Ar rpool Ns @ Ns Ar snapshot rpool Ns # Ns Ar bookmark . .Sh SEE ALSO diff --git a/sys/contrib/openzfs/man/man8/zfs-program.8 b/sys/contrib/openzfs/man/man8/zfs-program.8 index 4a9718cdcfcb..06415b2190eb 100644 --- a/sys/contrib/openzfs/man/man8/zfs-program.8 +++ b/sys/contrib/openzfs/man/man8/zfs-program.8 @@ -73,7 +73,7 @@ The default limit is 10 million instructions, and it can be set to a maximum of Memory limit, in bytes. If a channel program attempts to allocate more memory than the given limit, it will be stopped and an error returned. -The default memory limit is 10 MB, and can be set to a maximum of 100 MB. +The default memory limit is 10 MiB, and can be set to a maximum of 100 MiB. .El .Pp All remaining argument strings will be passed directly to the Lua script as @@ -96,16 +96,17 @@ argv = args["argv"] -- argv == {1="arg1", 2="arg2", ...} .Ed .Pp -If invoked from the libZFS interface, an arbitrary argument list can be +If invoked from the libzfs interface, an arbitrary argument list can be passed to the channel program, which is accessible via the same -"..." syntax in Lua: +.Qq Li ... +syntax in Lua: .Bd -literal -compact -offset indent args = ... -- args == {"foo"="bar", "baz"={...}, ...} .Ed .Pp Note that because Lua arrays are 1-indexed, arrays passed to Lua from the -libZFS interface will have their indices incremented by 1. +libzfs interface will have their indices incremented by 1. That is, the element in .Va arr[0] @@ -166,7 +167,7 @@ See the section below for function-specific details on error return codes. . .Ss Lua to C Value Conversion -When invoking a channel program via the libZFS interface, it is necessary to +When invoking a channel program via the libzfs interface, it is necessary to translate arguments and return values from Lua values to their C equivalents, and vice-versa. .Pp diff --git a/sys/contrib/openzfs/man/man8/zfs-send.8 b/sys/contrib/openzfs/man/man8/zfs-send.8 index 67e94ca85bc7..137deb94e20d 100644 --- a/sys/contrib/openzfs/man/man8/zfs-send.8 +++ b/sys/contrib/openzfs/man/man8/zfs-send.8 @@ -39,8 +39,8 @@ .Sh SYNOPSIS .Nm zfs .Cm send -.Op Fl DLPRbcehnpsvw -.Op Fl X Ar dataset Ns Oo , Ns Ar dataset Oc Ns ... +.Op Fl DLPbcehnpsvw +.Op Fl R Op Fl X Ar dataset Ns Oo , Ns Ar dataset Oc Ns … .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot .Ar snapshot .Nm zfs @@ -73,8 +73,8 @@ .It Xo .Nm zfs .Cm send -.Op Fl DLPRbcehnpvw -.Op Fl X Ar dataset Ns Oo , Ns Ar dataset Oc Ns ... +.Op Fl DLPbcehnpsvw +.Op Fl R Op Fl X Ar dataset Ns Oo , Ns Ar dataset Oc Ns … .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot .Ar snapshot .Xc @@ -102,12 +102,12 @@ The incremental source may be specified as with the .Fl i option. .It Fl L , -large-block -Generate a stream which may contain blocks larger than 128KB. +Generate a stream which may contain blocks larger than 128 KiB. This flag has no effect if the .Sy large_blocks pool feature is disabled, or if the .Sy recordsize -property of this filesystem has never been set above 128KB. +property of this filesystem has never been set above 128 KiB. The receiving system must have the .Sy large_blocks pool feature enabled as well. @@ -142,23 +142,16 @@ If the flag is used to send encrypted datasets, then .Fl w must also be specified. -.It Fl X , -exclude Ar dataset Ns Oo , Ns Ar dataset Oc Ns ... -When the -.Fl R -flag is given, -.Fl X -can be used to specify a list of datasets to be excluded from the -data stream. -The +.It Fl X , -exclude Ar dataset Ns Oo , Ns Ar dataset Oc Ns … +With +.Fl R , .Fl X -option can be used multiple times, or the list of datasets can be -specified as a comma-separated list, or both. -.Ar dataset -must not be the pool's root dataset, and all descendant datasets of -.Ar dataset -will be excluded from the send stream. -Requires -.Fl R . +specifies a set of datasets (and, hence, their descendants), +to be excluded from the send stream. +The root dataset may not be excluded. +.Fl X Ar a Fl X Ar b +is equivalent to +.Fl X Ar a , Ns Ar b . .It Fl e , -embed Generate a more compact stream by using .Sy WRITE_EMBEDDED @@ -324,12 +317,12 @@ Deduplicated send is no longer supported. This flag is accepted for backwards compatibility, but a regular, non-deduplicated stream will be generated. .It Fl L , -large-block -Generate a stream which may contain blocks larger than 128KB. +Generate a stream which may contain blocks larger than 128 KiB. This flag has no effect if the .Sy large_blocks pool feature is disabled, or if the .Sy recordsize -property of this filesystem has never been set above 128KB. +property of this filesystem has never been set above 128 KiB. The receiving system must have the .Sy large_blocks pool feature enabled as well. diff --git a/sys/contrib/openzfs/man/man8/zfs-set.8 b/sys/contrib/openzfs/man/man8/zfs-set.8 index 6092e49dfbcf..9d0c437df217 100644 --- a/sys/contrib/openzfs/man/man8/zfs-set.8 +++ b/sys/contrib/openzfs/man/man8/zfs-set.8 @@ -170,8 +170,9 @@ inherited. .It Fl r Recursively inherit the given property for all children. .It Fl S -Revert the property to the received value if one exists; otherwise operate as -if the +Revert the property to the received value, if one exists; +otherwise, for non-inheritable properties, to the default; +otherwise, operate as if the .Fl S option was not specified. .El diff --git a/sys/contrib/openzfs/man/man8/zfs.8 b/sys/contrib/openzfs/man/man8/zfs.8 index dd901e1e6e81..cac4327e0721 100644 --- a/sys/contrib/openzfs/man/man8/zfs.8 +++ b/sys/contrib/openzfs/man/man8/zfs.8 @@ -36,7 +36,7 @@ .\" Copyright 2018 Nexenta Systems, Inc. .\" Copyright 2019 Joyent, Inc. .\" -.Dd March 16, 2022 +.Dd May 12, 2022 .Dt ZFS 8 .Os . @@ -57,13 +57,32 @@ The .Nm command configures ZFS datasets within a ZFS storage pool, as described in .Xr zpool 8 . -A dataset is identified by a unique path within the ZFS namespace. -For example: -.Dl pool/{filesystem,volume,snapshot} +A dataset is identified by a unique path within the ZFS namespace: .Pp -where the maximum length of a dataset name is -.Sy MAXNAMELEN Pq 256B -and the maximum amount of nesting allowed in a path is 50 levels deep. +.D1 Ar pool Ns Oo Sy / Ns Ar component Oc Ns Sy / Ns Ar component +.Pp +for example: +.Pp +.Dl rpool/var/log +.Pp +The maximum length of a dataset name is +.Sy ZFS_MAX_DATASET_NAME_LEN No - 1 +ASCII characters (currently 255) satisfying +.Sy [A-Za-z_.:/ -] . +Additionally snapshots are allowed to contain a single +.Sy @ +character, while bookmarks are allowed to contain a single +.Sy # +character. +.Sy / +is used as separator between components. +The maximum amount of nesting allowed in a path is +.Sy zfs_max_dataset_nesting +levels deep. +ZFS tunables +.Pq Sy zfs_* +are explained in +.Xr zfs 4 . .Pp A dataset can be one of the following: .Bl -tag -offset Ds -width "file system" @@ -226,7 +245,7 @@ option reverted to the received value if one exists. Displays space consumed by, and quotas on, each user, group, or project in the specified filesystem or snapshot. .It Xr zfs-project 8 -List, set, or clear project ID and/or inherit flag on the file(s) or directories. +List, set, or clear project ID and/or inherit flag on the files or directories. .El . .Ss Mountpoints @@ -263,7 +282,8 @@ Add or change an encryption key on the specified dataset. .It Xr zfs-load-key 8 Load the key for the specified encrypted dataset, enabling access. .It Xr zfs-unload-key 8 -Unload a key for the specified dataset, removing the ability to access the dataset. +Unload a key for the specified dataset, +removing the ability to access the dataset. .El . .Ss Channel Programs @@ -586,7 +606,7 @@ mount point permission is set to 755 by default, user will be unable to mount file systems under .Ar tank/cindys . Add an ACE similar to the following syntax to provide mount point access: -.Dl # Cm chmod No A+user: Ns Ar cindys Ns :add_subdirectory:allow Ar /tank/cindys +.Dl # Cm chmod No A+user : Ns Ar cindys Ns :add_subdirectory:allow Ar /tank/cindys . .Ss Example 18 : No Delegating Create Time Permissions on a ZFS Dataset The following example shows how to grant anyone in the group @@ -683,8 +703,8 @@ M F /tank/test/modified .Ed . .Ss Example 23 : No Creating a bookmark -The following example create a bookmark to a snapshot. -This bookmark can then be used instead of snapshot in send streams. +The following example creates a bookmark to a snapshot. +This bookmark can then be used instead of a snapshot in send streams. .Dl # Nm zfs Cm bookmark Ar rpool Ns @ Ns Ar snapshot rpool Ns # Ns Ar bookmark . .Ss Example 24 : No Setting Sy sharesmb No Property Options on a ZFS File System @@ -725,6 +745,14 @@ to use to mount ZFS datasets. This option is provided for backwards compatibility with older ZFS versions. .El +.Bl -tag -width "ZFS_SET_PIPE_MAX" +.It Sy ZFS_SET_PIPE_MAX +Tells +.Nm zfs +to set the maximum pipe size for sends/recieves. +Disabled by default on Linux +due to an unfixed deadlock in Linux's pipe size handling code. +.El . .Sh INTERFACE STABILITY .Sy Committed . diff --git a/sys/contrib/openzfs/man/man8/zpool-import.8 b/sys/contrib/openzfs/man/man8/zpool-import.8 index 20ce41e6459b..b23d7dabdb55 100644 --- a/sys/contrib/openzfs/man/man8/zpool-import.8 +++ b/sys/contrib/openzfs/man/man8/zpool-import.8 @@ -71,7 +71,8 @@ .Xc Lists pools available to import. If the -.Fl d or +.Fl d +or .Fl c options are not specified, this command searches for devices using libblkid on Linux and geom on diff --git a/sys/contrib/openzfs/man/man8/zpool-list.8 b/sys/contrib/openzfs/man/man8/zpool-list.8 index ce8e34b61dec..88183b4dce1a 100644 --- a/sys/contrib/openzfs/man/man8/zpool-list.8 +++ b/sys/contrib/openzfs/man/man8/zpool-list.8 @@ -128,7 +128,7 @@ zion - - - - - - - FAULTED - The following command displays the detailed information for the pool .Ar data . This pool is comprised of a single raidz vdev where one of its devices -increased its capacity by 10GB. +increased its capacity by 10 GiB. In this example, the pool will not be able to utilize this extra capacity until all the devices under the raidz vdev have been expanded. .Bd -literal -compact -offset Ds diff --git a/sys/contrib/openzfs/man/man8/zpool.8 b/sys/contrib/openzfs/man/man8/zpool.8 index e99eaf536f2f..34c816bf0342 100644 --- a/sys/contrib/openzfs/man/man8/zpool.8 +++ b/sys/contrib/openzfs/man/man8/zpool.8 @@ -395,7 +395,7 @@ The command to remove the mirrored data The following command displays the detailed information for the pool .Ar data . This pool is comprised of a single raidz vdev where one of its devices -increased its capacity by 10GB. +increased its capacity by 10 GiB. In this example, the pool will not be able to utilize this extra capacity until all the devices under the raidz vdev have been expanded. .Bd -literal -compact -offset Ds |