diff options
Diffstat (limited to 'sys/contrib/openzfs/man')
-rw-r--r-- | sys/contrib/openzfs/man/Makefile.am | 19 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man1/zarcstat.1 (renamed from sys/contrib/openzfs/man/man1/arcstat.1) | 6 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man1/zhack.1 | 20 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man4/zfs.4 | 82 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man7/vdevprops.7 | 39 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man7/zfsprops.7 | 24 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man8/zdb.8 | 12 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man8/zed.8.in | 32 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man8/zfs-allow.8 | 5 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man8/zinject.8 | 14 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man8/zpool-attach.8 | 20 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man8/zpool-events.8 | 10 | ||||
-rw-r--r-- | sys/contrib/openzfs/man/man8/zpool-upgrade.8 | 4 |
13 files changed, 252 insertions, 35 deletions
diff --git a/sys/contrib/openzfs/man/Makefile.am b/sys/contrib/openzfs/man/Makefile.am index 6a7b2d3e46b7..7a63641c1c39 100644 --- a/sys/contrib/openzfs/man/Makefile.am +++ b/sys/contrib/openzfs/man/Makefile.am @@ -2,7 +2,7 @@ dist_noinst_man_MANS = \ %D%/man1/cstyle.1 dist_man_MANS = \ - %D%/man1/arcstat.1 \ + %D%/man1/zarcstat.1 \ %D%/man1/raidz_test.1 \ %D%/man1/test-runner.1 \ %D%/man1/zhack.1 \ @@ -124,10 +124,21 @@ dist_noinst_DATA += $(dist_noinst_man_MANS) $(dist_man_MANS) SUBSTFILES += $(nodist_man_MANS) -CHECKS += mancheck -mancheck: - $(top_srcdir)/scripts/mancheck.sh $(srcdir)/%D% +MANFILES = $(dist_noinst_man_MANS) $(dist_man_MANS) $(nodist_man_MANS) + +PHONY += mancheck + +mancheck_verbose = $(mancheck_verbose_@AM_V@) +mancheck_verbose_ = $(mancheck_verbose_@AM_DEFAULT_V@) +mancheck_verbose_0 = @echo MANCHECK $(_MTGT); +_MTGT = $(subst ^,/,$(subst mancheck-,,$@)) +mancheck-%: + $(mancheck_verbose)scripts/mancheck.sh $(_MTGT) + +mancheck: $(foreach manfile, $(MANFILES), $(addprefix mancheck-,$(subst /,^,$(manfile)))) + +CHECKS += mancheck if BUILD_LINUX # The manual pager in most Linux distros defaults to "BSD" when .Os is blank, diff --git a/sys/contrib/openzfs/man/man1/arcstat.1 b/sys/contrib/openzfs/man/man1/zarcstat.1 index 288b98d57a11..3633c5d417fe 100644 --- a/sys/contrib/openzfs/man/man1/arcstat.1 +++ b/sys/contrib/openzfs/man/man1/zarcstat.1 @@ -14,14 +14,12 @@ .\" Copyright (c) 2020 by AJ Jordan. All rights reserved. .\" .Dd September 19, 2024 -.Dt ARCSTAT 1 +.Dt ZARCSTAT 1 .Os . .Sh NAME -.Nm arcstat +.Nm zarcstat .Nd report ZFS ARC and L2ARC statistics -.Sh NOTICE -It will be renamed to zarcstat in zfs 2.4.0. Please migrate ASAP. .Sh SYNOPSIS .Nm .Op Fl havxp diff --git a/sys/contrib/openzfs/man/man1/zhack.1 b/sys/contrib/openzfs/man/man1/zhack.1 index 743bd53b731c..63658cf930e9 100644 --- a/sys/contrib/openzfs/man/man1/zhack.1 +++ b/sys/contrib/openzfs/man/man1/zhack.1 @@ -122,6 +122,24 @@ Example: .Nm zhack Cm label repair Fl cu Ar device Fix checksums and undetach a device . +.It Xo +.Nm zhack +.Cm metaslab leak +.Op Fl f +.Ar pool +.Xc +Apply a fragmentation profile generated by +.Sy zdb +to the specified +.Ar pool Ns +\&. +.Pp +The +.Fl f +flag forces the profile to apply even if the vdevs in the +.Ar pool +don't have the same number of metaslabs as the fragmentation profile. +. .El . .Sh GLOBAL OPTIONS @@ -143,6 +161,8 @@ Search for members in .Ar dir . Can be specified more than once. +.It Fl o Ar var Ns = Ns Ar value +Set the given tunable to the provided value. .El . .Sh EXAMPLES diff --git a/sys/contrib/openzfs/man/man4/zfs.4 b/sys/contrib/openzfs/man/man4/zfs.4 index e865d6a79c5a..11bcbf430210 100644 --- a/sys/contrib/openzfs/man/man4/zfs.4 +++ b/sys/contrib/openzfs/man/man4/zfs.4 @@ -4,6 +4,7 @@ .\" Copyright (c) 2019, 2021 by Delphix. All rights reserved. .\" Copyright (c) 2019 Datto Inc. .\" Copyright (c) 2023, 2024, 2025, Klara, Inc. +.\" .\" The contents of this file are subject to the terms of the Common Development .\" and Distribution License (the "License"). You may not use this file except .\" in compliance with the License. You can obtain a copy of the license at @@ -17,7 +18,7 @@ .\" own identifying information: .\" Portions Copyright [yyyy] [name of copyright owner] .\" -.Dd August 14, 2025 +.Dd September 15, 2025 .Dt ZFS 4 .Os . @@ -601,6 +602,42 @@ new format when enabling the feature. The default is to convert all log entries. . +.It Sy vdev_read_sit_out_secs Ns = Ns Sy 600 Ns s Po 10 min Pc Pq ulong +When a slow disk outlier is detected it is placed in a sit out state. +While sitting out the disk will not participate in normal reads, instead its +data will be reconstructed as needed from parity. +Scrub operations will always read from a disk, even if it's sitting out. +A number of disks in a RAID-Z or dRAID vdev may sit out at the same time, up +to the number of parity devices. +Writes will still be issued to a disk which is sitting out to maintain full +redundancy. +Defaults to 600 seconds and a value of zero disables disk sit-outs in general, +including slow disk outlier detection. +. +.It Sy vdev_raidz_outlier_check_interval_ms Ns = Ns Sy 1000 Ns ms Po 1 sec Pc Pq ulong +How often each RAID-Z and dRAID vdev will check for slow disk outliers. +Increasing this interval will reduce the sensitivity of detection (since all +I/Os since the last check are included in the statistics), but will slow the +response to a disk developing a problem. +Defaults to once per second; setting extremely small values may cause negative +performance effects. +. +.It Sy vdev_raidz_outlier_insensitivity Ns = Ns Sy 50 Pq uint +When performing slow outlier checks for RAID-Z and dRAID vdevs, this value is +used to determine how far out an outlier must be before it counts as an event +worth consdering. +This is phrased as "insensitivity" because larger values result in fewer +detections. +Smaller values will result in more aggressive sitting out of disks that may have +problems, but may significantly increase the rate of spurious sit-outs. +.Pp +To provide a more technical definition of this parameter, this is the multiple +of the inter-quartile range (IQR) that is being used in a Tukey's Fence +detection algorithm. +This is much higher than a normal Tukey's Fence k-value, because the +distribution under consideration is probably an extreme-value distribution, +rather than a more typical Gaussian distribution. +. .It Sy vdev_removal_max_span Ns = Ns Sy 32768 Ns B Po 32 KiB Pc Pq uint 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. @@ -2546,6 +2583,49 @@ the xattr so as to not accumulate duplicates. .It Sy zio_requeue_io_start_cut_in_line Ns = Ns Sy 0 Ns | Ns 1 Pq int Prioritize requeued I/O. . +.It Sy zfs_delete_inode Ns = Ns Sy 0 Ns | Ns 1 Pq int +Sets whether the kernel should free an inode structure when the last reference +is released, or cache it in memory. +Intended for testing/debugging. +.Pp +A live inode structure "pins" versious internal OpenZFS structures in memory, +which can result in large amounts of "unusable" memory on systems with lots of +infrequently-accessed files, until the kernel's memory pressure mechanism +asks OpenZFS to release them. +.Pp +The default value of +.Sy 0 +always caches inodes that appear to still exist on disk. +Setting it to +.Sy 1 +will immediately release unused inodes and their associated memory back to the +dbuf cache or the ARC for reuse, but may reduce performance if inodes are +frequently evicted and reloaded. +.Pp +This parameter is only available on Linux. +. +.It Sy zfs_delete_dentry Ns = Ns Sy 0 Ns | Ns 1 Pq int +Sets whether the kernel should free a dentry structure when it is no longer +required, or hold it in the dentry cache. +Intended for testing/debugging. +. +Since a dentry structure holds an inode reference, a cached dentry can "pin" +an inode in memory indefinitely, along with associated OpenZFS structures (See +.Sy zfs_delete_inode ) . +.Pp +The default value of +.Sy 0 +instructs the kernel to cache entries and their associated inodes when they +are no longer directly referenced. +They will be reclaimed as part of the kernel's normal cache management +processes. +Setting it to +.Sy 1 +will instruct the kernel to release directory entries and their inodes as soon +as they are no longer referenced by the filesystem. +.Pp +This parameter is only available on Linux. +. .It Sy zio_taskq_batch_pct Ns = Ns Sy 80 Ns % Pq uint Percentage of online CPUs which will run a worker thread for I/O. These workers are responsible for I/O work such as compression, encryption, diff --git a/sys/contrib/openzfs/man/man7/vdevprops.7 b/sys/contrib/openzfs/man/man7/vdevprops.7 index 61e60d950416..0fb28d7db13c 100644 --- a/sys/contrib/openzfs/man/man7/vdevprops.7 +++ b/sys/contrib/openzfs/man/man7/vdevprops.7 @@ -19,7 +19,7 @@ .\" .\" CDDL HEADER END .\" -.\" Copyright (c) 2021 Klara, Inc. +.\" Copyright (c) 2021, 2025, Klara, Inc. .\" .Dd July 23, 2024 .Dt VDEVPROPS 7 @@ -106,11 +106,17 @@ The number of children belonging to this vdev .It Sy read_errors , write_errors , checksum_errors , initialize_errors , trim_errors The number of errors of each type encountered by this vdev .It Sy slow_ios -The number of slow I/Os encountered by this vdev, -These represent I/O operations that didn't complete in +This indicates the number of slow I/O operations encountered by this vdev. +A slow I/O is defined as an operation that did not complete within the .Sy zio_slow_io_ms -milliseconds +threshold in milliseconds .Pq Sy 30000 No by default . +For +.Sy RAIDZ +and +.Sy DRAID +configurations, this value also represents the number of times the vdev was +identified as an outlier and excluded from participating in read I/O operations. .It Sy null_ops , read_ops , write_ops , free_ops , claim_ops , trim_ops The number of I/O operations of each type performed by this vdev .It Xo @@ -150,6 +156,31 @@ The amount of space to reserve for the EFI system partition .It Sy failfast If this device should propagate BIO errors back to ZFS, used to disable failfast. +.It Sy sit_out +Only valid for +.Sy RAIDZ +and +.Sy DRAID +vdevs. +True when a slow disk outlier was detected and the vdev is currently in a sit +out state. +This property can be manually set to cause vdevs to sit out. +It will also be automatically set by the +.Sy autosit +logic if that is enabled. +While sitting out, the vdev will not participate in normal reads, instead its +data will be reconstructed as needed from parity. +.It Sy autosit +Only valid for +.Sy RAIDZ +and +.Sy DRAID +vdevs. +If set, this enables the kernel-level slow disk detection logic. +This logic automatically causes any vdevs that are significant negative +performance outliers to sit out, as described in the +.Sy sit_out +property. .It Sy path The path to the device for this vdev .It Sy allocating diff --git a/sys/contrib/openzfs/man/man7/zfsprops.7 b/sys/contrib/openzfs/man/man7/zfsprops.7 index 0930771c9fce..77e994b912b6 100644 --- a/sys/contrib/openzfs/man/man7/zfsprops.7 +++ b/sys/contrib/openzfs/man/man7/zfsprops.7 @@ -39,7 +39,7 @@ .\" Copyright (c) 2019, Kjeld Schouten-Lebbing .\" Copyright (c) 2022 Hewlett Packard Enterprise Development LP. .\" -.Dd August 6, 2025 +.Dd September 13, 2025 .Dt ZFSPROPS 7 .Os . @@ -1192,18 +1192,26 @@ keylocation can be with either .Nm zfs Cm set or .Nm zfs Cm change-key . +.Pp If .Sy prompt -is selected ZFS will ask for the key at the command prompt when it is required -to access the encrypted data (see +is selected, ZFS will expect the key to be provided when it is required to +access the encrypted data (see .Nm zfs Cm load-key for details). -This setting will also allow the key to be passed in via the standard input -stream, -but users should be careful not to place keys which should be kept secret on -the command line. -If a file URI is selected, the key will be loaded from the +If stdin is a TTY, then ZFS will ask for the key to be provided. +Otherwise, stdin is expected to be the key to use and will be processed as such. +Users should be careful not to place keys which should be kept secret on the +command line, as most operating systems may expose command line arguments to +other processes. +If the +.Dq raw +.Sy keyformat +was used, then the key must be provided via stdin. +.Pp +If a file URL is selected, the key will be loaded from the specified absolute file path. +.Pp If an HTTPS or HTTP URL is selected, it will be GETted using .Xr fetch 3 , libcurl, or nothing, depending on compile-time configuration and run-time diff --git a/sys/contrib/openzfs/man/man8/zdb.8 b/sys/contrib/openzfs/man/man8/zdb.8 index e00544e4a5a4..c3290ea14769 100644 --- a/sys/contrib/openzfs/man/man8/zdb.8 +++ b/sys/contrib/openzfs/man/man8/zdb.8 @@ -69,6 +69,13 @@ .Op Fl U Ar cache .Ar poolname Op Ar vdev Oo Ar metaslab Oc Ns … .Nm +.Fl -allocated-map +.Op Fl mAFLPXY +.Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns … +.Op Fl t Ar txg +.Op Fl U Ar cache +.Ar poolname Op Ar vdev Oo Ar metaslab Oc Ns … +.Nm .Fl O .Op Fl K Ar key .Ar dataset path @@ -128,6 +135,11 @@ that zdb may interpret inconsistent pool data and behave erratically. .Sh OPTIONS Display options: .Bl -tag -width Ds +.It Fl Sy -allocated-map +Prints out a list of all the allocated regions in the pool. +Primarily intended for use with the +.Nm zhack metaslab leak +subcommand. .It Fl b , -block-stats Display statistics regarding the number, size .Pq logical, physical and allocated diff --git a/sys/contrib/openzfs/man/man8/zed.8.in b/sys/contrib/openzfs/man/man8/zed.8.in index eda377aafc1e..2d19f2d8496b 100644 --- a/sys/contrib/openzfs/man/man8/zed.8.in +++ b/sys/contrib/openzfs/man/man8/zed.8.in @@ -158,6 +158,8 @@ Multiple ZEDLETs may be invoked for a given zevent. ZEDLETs are executables invoked by the ZED in response to a given zevent. They should be written under the presumption they can be invoked concurrently, and they should use appropriate locking to access any shared resources. +The one exception to this are "synchronous zedlets", which are described later +in this page. Common variables used by ZEDLETs can be stored in the default rc file which is sourced by scripts; these variables should be prefixed with .Sy ZED_ . @@ -233,6 +235,36 @@ and .Sy ZPOOL . These variables may be overridden in the rc file. . +.Sh Synchronous ZEDLETS +ZED's normal behavior is to spawn off zedlets in parallel and ignore their +completion order. +This means that ZED can potentially +have zedlets for event ID number 2 starting before zedlets for event ID number +1 have finished. +Most of the time this is fine, and it actually helps when the system is getting +hammered with hundreds of events. +.Pp +However, there are times when you want your zedlets to be executed in sequence +with the event ID. +That is where synchronous zedlets come in. +.Pp +ZED will wait for all previously spawned zedlets to finish before running +a synchronous zedlet. +Synchronous zedlets are guaranteed to be the only +zedlet running. +No other zedlets may run in parallel with a synchronous zedlet. +Users should be careful to only use synchronous zedlets when needed, since +they decrease parallelism. +.Pp +To make a zedlet synchronous, simply add a "-sync-" immediately following the +event name in the zedlet's file name: +.Pp +.Sy EVENT_NAME-sync-ZEDLETNAME.sh +.Pp +For example, if you wanted a synchronous statechange script: +.Pp +.Sy statechange-sync-myzedlet.sh +. .Sh FILES .Bl -tag -width "-c" .It Pa @sysconfdir@/zfs/zed.d diff --git a/sys/contrib/openzfs/man/man8/zfs-allow.8 b/sys/contrib/openzfs/man/man8/zfs-allow.8 index b154aebd92aa..e3b0e1ab3e12 100644 --- a/sys/contrib/openzfs/man/man8/zfs-allow.8 +++ b/sys/contrib/openzfs/man/man8/zfs-allow.8 @@ -30,7 +30,7 @@ .\" Copyright 2018 Nexenta Systems, Inc. .\" Copyright 2019 Joyent, Inc. .\" -.Dd March 13, 2025 +.Dd September 8, 2025 .Dt ZFS-ALLOW 8 .Os . @@ -212,7 +212,8 @@ receive subcommand Must also have the \fBmount\fR and \fBcreate\fR ability, requ release subcommand Allows releasing a user hold which might destroy the snapshot rename subcommand Must also have the \fBmount\fR and \fBcreate\fR ability in the new parent rollback subcommand Must also have the \fBmount\fR ability -send subcommand +send subcommand Allows sending a replication stream of a dataset. +send:raw subcommand Only allows sending raw replication streams, preventing encrypted datasets being sent in decrypted form. share subcommand Allows sharing file systems over NFS or SMB protocols snapshot subcommand Must also have the \fBmount\fR ability diff --git a/sys/contrib/openzfs/man/man8/zinject.8 b/sys/contrib/openzfs/man/man8/zinject.8 index 1d9e43aed5ec..704f6a7accd8 100644 --- a/sys/contrib/openzfs/man/man8/zinject.8 +++ b/sys/contrib/openzfs/man/man8/zinject.8 @@ -138,6 +138,20 @@ This injector is automatically cleared after the import is finished. . .It Xo .Nm zinject +.Fl E Ar delay +.Op Fl a +.Op Fl m +.Op Fl f Ar freq +.Op Fl l Ar level +.Op Fl r Ar range +.Op Fl T Ar iotype +.Op Fl t Ar type Ns | Ns Fl b Ar bookmark +.Xc +Inject pipeline ready stage delays for the given object or bookmark. +The delay is specified in milliseconds. +. +.It Xo +.Nm zinject .Fl I .Op Fl s Ar seconds Ns | Ns Fl g Ar txgs .Ar pool diff --git a/sys/contrib/openzfs/man/man8/zpool-attach.8 b/sys/contrib/openzfs/man/man8/zpool-attach.8 index f120350a5190..04996ed4fa11 100644 --- a/sys/contrib/openzfs/man/man8/zpool-attach.8 +++ b/sys/contrib/openzfs/man/man8/zpool-attach.8 @@ -39,24 +39,24 @@ .Cm attach .Op Fl fsw .Oo Fl o Ar property Ns = Ns Ar value Oc -.Ar pool device new_device +.Ar pool vdev new_device . .Sh DESCRIPTION Attaches .Ar new_device to the existing -.Ar device . +.Ar vdev . The behavior differs depending on if the existing -.Ar device +.Ar vdev is a RAID-Z device, or a mirror/plain device. .Pp -If the existing device is a mirror or plain device +If the existing vdev is a mirror or plain device .Pq e.g. specified as Qo Li sda Qc or Qq Li mirror-7 , -the new device will be mirrored with the existing device, a resilver will be +the new device will be mirrored with the existing vdev, a resilver will be initiated, and the new device will contribute to additional redundancy once the resilver completes. If -.Ar device +.Ar vdev is not currently part of a mirrored configuration, .Ar device automatically transforms into a two-way mirror of @@ -64,7 +64,7 @@ automatically transforms into a two-way mirror of and .Ar new_device . If -.Ar device +.Ar vdev is part of a two-way mirror, attaching .Ar new_device creates a three-way mirror, and so on. @@ -72,7 +72,7 @@ In either case, .Ar new_device begins to resilver immediately and any running scrub is canceled. .Pp -If the existing device is a RAID-Z device +If the existing vdev is a RAID-Z device .Pq e.g. specified as Qq Ar raidz2-0 , the new device will become part of that RAID-Z group. A "raidz expansion" will be initiated, and once the expansion completes, @@ -112,7 +112,7 @@ the checksums of all blocks which have been copied during the expansion. Forces use of .Ar new_device , even if it appears to be in use. -Not all devices can be overridden in this manner. +Not all vdevs can be overridden in this manner. .It Fl o Ar property Ns = Ns Ar value Sets the given pool properties. See the @@ -121,7 +121,7 @@ manual page for a list of valid properties that can be set. The only property supported at the moment is .Sy ashift . .It Fl s -When attaching to a mirror or plain device, the +When attaching to a mirror or plain vdev, the .Ar new_device is reconstructed sequentially to restore redundancy as quickly as possible. Checksums are not verified during sequential reconstruction so a scrub is diff --git a/sys/contrib/openzfs/man/man8/zpool-events.8 b/sys/contrib/openzfs/man/man8/zpool-events.8 index 2d32dce2bb65..36a9864dc73b 100644 --- a/sys/contrib/openzfs/man/man8/zpool-events.8 +++ b/sys/contrib/openzfs/man/man8/zpool-events.8 @@ -190,6 +190,16 @@ Issued when a scrub is resumed on a pool. .It Sy scrub.paused Issued when a scrub is paused on a pool. .It Sy bootfs.vdev.attach +.It Sy sitout +Issued when a +.Sy RAIDZ +or +.Sy DRAID +vdev triggers the +.Sy autosit +logic. +This logic detects when a disk in such a vdev is significantly slower than its +peers, and sits them out temporarily to preserve the performance of the pool. .El . .Sh PAYLOADS diff --git a/sys/contrib/openzfs/man/man8/zpool-upgrade.8 b/sys/contrib/openzfs/man/man8/zpool-upgrade.8 index cf69060da5ce..adae47f82eb1 100644 --- a/sys/contrib/openzfs/man/man8/zpool-upgrade.8 +++ b/sys/contrib/openzfs/man/man8/zpool-upgrade.8 @@ -65,10 +65,10 @@ property). .Cm upgrade .Fl v .Xc -Displays legacy ZFS versions supported by the this version of ZFS. +Displays legacy ZFS versions supported by this version of ZFS. See .Xr zpool-features 7 -for a description of feature flags features supported by this version of ZFS. +for a description of features supported by this version of ZFS. .It Xo .Nm zpool .Cm upgrade |