From a2550c9df9a9b1346f61fb1652c1c716fc492d44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=BD=D0=B0=D0=B1?= Date: Wed, 16 Mar 2022 17:46:32 +0100 Subject: [PATCH] man: Examples: use subsections instead of lists MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reviewed-by: Brian Behlendorf Signed-off-by: Ahelenia Ziemiańska Closes #13228 --- man/man8/zdb.8 | 29 ++++++----------------- man/man8/zfs.8 | 53 ++++++++++++++++++++---------------------- man/man8/zpool-scrub.8 | 14 ++++------- man/man8/zpool.8 | 46 ++++++++++++++++++------------------ 4 files changed, 58 insertions(+), 84 deletions(-) diff --git a/man/man8/zdb.8 b/man/man8/zdb.8 index 902f818cc4..31ee601538 100644 --- a/man/man8/zdb.8 +++ b/man/man8/zdb.8 @@ -464,12 +464,7 @@ If no options are specified, all information about the named pool will be displayed at default verbosity. . .Sh EXAMPLES -.Bl -tag -width Ds -.It Xo -.Sy Example 1 : -Display the configuration of imported pool -.Ar rpool -.Xc +.Ss Example 1 : No Display the configuration of imported pool Ar rpool .Bd -literal .No # Nm zdb Fl C Ar rpool MOS Configuration: @@ -477,22 +472,16 @@ MOS Configuration: name: 'rpool' … .Ed -.It Xo -.Sy Example 2 : -Display basic dataset information about -.Ar rpool -.Xc +. +.Ss Example 2 : No Display basic dataset information about Ar rpool .Bd -literal .No # Nm zdb Fl d Ar rpool Dataset mos [META], ID 0, cr_txg 4, 26.9M, 1051 objects Dataset rpool/swap [ZVOL], ID 59, cr_txg 356, 486M, 2 objects … .Ed -.It Xo -.Sy Example 3 : -Display basic information about object 0 in -.Ar rpool/export/home -.Xc +. +.Ss Example 3 : No Display basic information about object 0 in Ar rpool/export/home .Bd -literal .No # Nm zdb Fl d Ar rpool/export/home 0 Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects @@ -500,11 +489,8 @@ Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects Object lvl iblk dblk dsize lsize %full type 0 7 16K 16K 15.0K 16K 25.00 DMU dnode .Ed -.It Xo -.Sy Example 4 : -Display the predicted effect of enabling deduplication on -.Ar rpool -.Xc +. +.Ss Example 4 : No Display the predicted effect of enabling deduplication on Ar rpool .Bd -literal .No # Nm zdb Fl S Ar rpool Simulated DDT histogram: @@ -518,7 +504,6 @@ refcnt blocks LSIZE PSIZE DSIZE blocks LSIZE PSIZE DSIZE … dedup = 1.11, compress = 1.80, copies = 1.00, dedup * compress / copies = 2.00 .Ed -.El . .Sh SEE ALSO .Xr zfs 8 , diff --git a/man/man8/zfs.8 b/man/man8/zfs.8 index 48453ef46c..eb762fb404 100644 --- a/man/man8/zfs.8 +++ b/man/man8/zfs.8 @@ -36,7 +36,7 @@ .\" Copyright 2018 Nexenta Systems, Inc. .\" Copyright 2019 Joyent, Inc. .\" -.Dd June 30, 2019 +.Dd March 16, 2022 .Dt ZFS 8 .Os . @@ -299,9 +299,7 @@ if an error occurs, and if invalid command line options were specified. . .Sh EXAMPLES -.Bl -tag -width "" -. -.It Sy Example 1 : No Creating a ZFS File System Hierarchy +.Ss Example 1 : No Creating a ZFS File System Hierarchy The following commands create a file system named .Ar pool/home and a file system named @@ -314,7 +312,7 @@ file system. .Dl # Nm zfs Cm set Sy mountpoint Ns = Ns Ar /export/home pool/home .Dl # Nm zfs Cm create Ar pool/home/bob . -.It Sy Example 2 : No Creating a ZFS Snapshot +.Ss Example 2 : No Creating a ZFS Snapshot The following command creates a snapshot named .Ar yesterday . This snapshot is mounted on demand in the @@ -324,7 +322,7 @@ directory at the root of the file system. .Dl # Nm zfs Cm snapshot Ar pool/home/bob Ns @ Ns Ar yesterday . -.It Sy Example 3 : No Creating and Destroying Multiple Snapshots +.Ss Example 3 : No Creating and Destroying Multiple Snapshots The following command creates snapshots named .Ar yesterday No of Ar pool/home and all of its descendent file systems. @@ -335,7 +333,7 @@ The second command destroys the newly created snapshots. .Dl # Nm zfs Cm snapshot Fl r Ar pool/home Ns @ Ns Ar yesterday .Dl # Nm zfs Cm destroy Fl r Ar pool/home Ns @ Ns Ar yesterday . -.It Sy Example 4 : No Disabling and Enabling File System Compression +.Ss Example 4 : No Disabling and Enabling File System Compression The following command disables the .Sy compression property for all file systems under @@ -347,7 +345,7 @@ for .Dl # Nm zfs Cm set Sy compression Ns = Ns Sy off Ar pool/home .Dl # Nm zfs Cm set Sy compression Ns = Ns Sy on Ar pool/home/anne . -.It Sy Example 5 : No Listing ZFS Datasets +.Ss Example 5 : No Listing ZFS Datasets The following command lists all active file systems and volumes in the system. Snapshots are displayed if .Sy listsnaps Ns = Ns Sy on . @@ -365,12 +363,12 @@ pool/home/anne 18K 457G 18K /export/home/anne pool/home/bob 276K 457G 276K /export/home/bob .Ed . -.It Sy Example 6 : No Setting a Quota on a ZFS File System +.Ss Example 6 : No Setting a Quota on a ZFS File System The following command sets a quota of 50 Gbytes for .Ar pool/home/bob : .Dl # Nm zfs Cm set Sy quota Ns = Ns Ar 50G pool/home/bob . -.It Sy Example 7 : No Listing ZFS Properties +.Ss Example 7 : No Listing ZFS Properties The following command lists all properties for .Ar pool/home/bob : .Bd -literal -compact -offset Ds @@ -435,7 +433,7 @@ pool/home/bob quota 20G pool/home/bob compression on .Ed . -.It Sy Example 8 : No Rolling Back a ZFS File System +.Ss Example 8 : No Rolling Back a ZFS File System The following command reverts the contents of .Ar pool/home/anne to the snapshot named @@ -443,13 +441,13 @@ to the snapshot named deleting all intermediate snapshots: .Dl # Nm zfs Cm rollback Fl r Ar pool/home/anne Ns @ Ns Ar yesterday . -.It Sy Example 9 : No Creating a ZFS Clone +.Ss Example 9 : No Creating a ZFS Clone The following command creates a writable file system whose initial contents are the same as .Ar pool/home/bob@yesterday . .Dl # Nm zfs Cm clone Ar pool/home/bob@yesterday pool/clone . -.It Sy Example 10 : No Promoting a ZFS Clone +.Ss Example 10 : No Promoting a ZFS Clone The following commands illustrate how to test out changes to a file system, and then replace the original file system with the changed one, using clones, clone promotion, and renaming: @@ -466,7 +464,7 @@ promotion, and renaming: .No # Nm zfs Cm destroy Ar pool/project/legacy .Ed . -.It Sy Example 11 : No Inheriting ZFS Properties +.Ss Example 11 : No Inheriting ZFS Properties The following command causes .Ar pool/home/bob No and Ar pool/home/anne to inherit the @@ -474,7 +472,7 @@ to inherit the property from their parent. .Dl # Nm zfs Cm inherit Sy checksum Ar pool/home/bob pool/home/anne . -.It Sy Example 12 : No Remotely Replicating ZFS Data +.Ss Example 12 : No Remotely Replicating ZFS Data The following commands send a full stream and then an incremental stream to a remote machine, restoring them into .Em poolB/received/fs@a @@ -493,7 +491,7 @@ and must not initially contain .No " " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs .Ed . -.It Sy Example 13 : No Using the Nm zfs Cm receive Fl d No Option +.Ss Example 13 : No Using the Nm zfs Cm receive Fl d No Option The following command sends a full stream of .Ar poolA/fsA/fsB@snap to a remote machine, receiving it into @@ -513,13 +511,13 @@ does not exist, it is created as an empty file system. .No " " Nm ssh Ar host Nm zfs Cm receive Fl d Ar poolB/received .Ed . -.It Sy Example 14 : No Setting User Properties +.Ss Example 14 : No Setting User Properties The following example sets the user-defined .Ar com.example : Ns Ar department property for a dataset: .Dl # Nm zfs Cm set Ar com.example : Ns Ar department Ns = Ns Ar 12345 tank/accounting . -.It Sy Example 15 : No Performing a Rolling Snapshot +.Ss Example 15 : No Performing a Rolling Snapshot The following example shows how to maintain a history of snapshots with a consistent naming scheme. To keep a week's worth of snapshots, the user destroys the oldest snapshot, @@ -536,7 +534,7 @@ renames the remaining snapshots, and then creates a new snapshot, as follows: .No # Nm zfs Cm snapshot Fl r Ar pool/users Ns @ Ns Ar today .Ed . -.It Sy Example 16 : No Setting sharenfs Property Options on a ZFS File System +.Ss Example 16 : No Setting sharenfs Property Options on a ZFS File System The following commands show how to set .Sy sharenfs property options to enable read-write @@ -550,7 +548,7 @@ file system: If you are using DNS for host name resolution, specify the fully-qualified hostname. . -.It Sy Example 17 : No Delegating ZFS Administration Permissions on a ZFS Dataset +.Ss Example 17 : No Delegating ZFS Administration Permissions on a ZFS Dataset The following example shows how to set permissions so that user .Ar cindys can create, destroy, mount, and take snapshots on @@ -575,7 +573,7 @@ will be unable to mount file systems under 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 . -.It Sy Example 18 : No Delegating Create Time Permissions on a ZFS Dataset +.Ss Example 18 : No Delegating Create Time Permissions on a ZFS Dataset The following example shows how to grant anyone in the group .Ar staff to create file systems in @@ -596,7 +594,7 @@ Local+Descendent permissions: group staff create,mount .Ed . -.It Sy Example 19 : No Defining and Granting a Permission Set on a ZFS Dataset +.Ss Example 19 : No Defining and Granting a Permission Set on a ZFS Dataset The following example shows how to define and grant a permission set on the .Ar tank/users file system. @@ -614,7 +612,7 @@ Local+Descendent permissions: group staff @pset .Ed . -.It Sy Example 20 : No Delegating Property Permissions on a ZFS Dataset +.Ss Example 20 : No Delegating Property Permissions on a ZFS Dataset The following example shows to grant the ability to set quotas and reservations on the .Ar users/home @@ -634,7 +632,7 @@ NAME PROPERTY VALUE SOURCE users/home/marks quota 10G local .Ed . -.It Sy Example 21 : No Removing ZFS Delegated Permissions on a ZFS Dataset +.Ss Example 21 : No Removing ZFS Delegated Permissions on a ZFS Dataset The following example shows how to remove the snapshot permission from the .Ar staff group on the @@ -653,7 +651,7 @@ Local+Descendent permissions: group staff @pset .Ed . -.It Sy Example 22 : No Showing the differences between a snapshot and a ZFS Dataset +.Ss Example 22 : No Showing the differences between a snapshot and a ZFS Dataset The following example shows how to see what has changed between a prior snapshot of a ZFS dataset and its current state. The @@ -669,12 +667,12 @@ R F /tank/test/oldname -> /tank/test/newname M F /tank/test/modified .Ed . -.It Sy Example 23 : No Creating a bookmark +.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. .Dl # Nm zfs Cm bookmark Ar rpool Ns @ Ns Ar snapshot rpool Ns # Ns Ar bookmark . -.It Sy Example 24 : No Setting Sy sharesmb No Property Options on a ZFS File System +.Ss Example 24 : No Setting Sy sharesmb No Property Options on a ZFS File System The following example show how to share SMB filesystem through ZFS. Note that a user and their password must be given. .Dl # Nm smbmount Ar //127.0.0.1/share_tmp /mnt/tmp Fl o No user=workgroup/turbo,password=obrut,uid=1000 @@ -701,7 +699,6 @@ in case you need to modify any options of the share afterwards. Do note that any changes done with the .Xr net 8 command will be undone if the share is ever unshared (like via a reboot). -.El . .Sh ENVIRONMENT VARIABLES .Bl -tag -width "ZFS_MOUNT_HELPER" diff --git a/man/man8/zpool-scrub.8 b/man/man8/zpool-scrub.8 index 69ae825b61..1c13d9b9b2 100644 --- a/man/man8/zpool-scrub.8 +++ b/man/man8/zpool-scrub.8 @@ -97,10 +97,8 @@ again. Wait until scrub has completed before returning. .El .Sh EXAMPLES -.Bl -tag -width "Exam" -.It Sy Example 1 : Status of pool with ongoing scrub: -Output: -.Bd -literal -compact -offset Ds +.Ss Example 1 : No Status of pool with ongoing scrub: +.Bd -literal -compact .No # Nm zpool Cm status ... scan: scrub in progress since Sun Jul 25 16:07:49 2021 @@ -108,14 +106,10 @@ Output: 0B repaired, 16.91% done, 00:00:04 to go ... .Ed -Where: -.Bl -dash -offset indent -.It -Metadata which references 403M of file data has been +.Pp +Where metadata which references 403M of file data has been scanned at 100M/s, and 68.4M of that file data has been scrubbed sequentially at 10.0M/s. -.El -.El .Sh PERIODIC SCRUB On machines using systemd, scrub timers can be enabled on per-pool basis. .Nm weekly diff --git a/man/man8/zpool.8 b/man/man8/zpool.8 index 8e7abb1161..a8e8b23b7d 100644 --- a/man/man8/zpool.8 +++ b/man/man8/zpool.8 @@ -230,35 +230,34 @@ Invalid command line options were specified. .El . .Sh EXAMPLES -.Bl -tag -width "Exam" -.It Sy Example 1 : No Creating a RAID-Z Storage Pool +.Ss Example 1 : No Creating a RAID-Z Storage Pool The following command creates a pool with a single raidz root vdev that consists of six disks: .Dl # Nm zpool Cm create Ar tank Sy raidz Pa sda sdb sdc sdd sde sdf . -.It Sy Example 2 : No Creating a Mirrored Storage Pool +.Ss Example 2 : No Creating a Mirrored Storage Pool The following command creates a pool with two mirrors, where each mirror contains two disks: .Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy mirror Pa sdc sdd . -.It Sy Example 3 : No Creating a ZFS Storage Pool by Using Partitions +.Ss Example 3 : No Creating a ZFS Storage Pool by Using Partitions The following command creates a non-redundant pool using two disk partitions: .Dl # Nm zpool Cm create Ar tank Pa sda1 sdb2 . -.It Sy Example 4 : No Creating a ZFS Storage Pool by Using Files +.Ss Example 4 : No Creating a ZFS Storage Pool by Using Files The following command creates a non-redundant pool using files. While not recommended, a pool based on files can be useful for experimental purposes. .Dl # Nm zpool Cm create Ar tank Pa /path/to/file/a /path/to/file/b . -.It Sy Example 5 : No Adding a Mirror to a ZFS Storage Pool +.Ss Example 5 : No Adding a Mirror to a ZFS Storage Pool The following command adds two mirrored disks to the pool .Ar tank , assuming the pool is already made up of two-way mirrors. The additional space is immediately available to any datasets within the pool. .Dl # Nm zpool Cm add Ar tank Sy mirror Pa sda sdb . -.It Sy Example 6 : No Listing Available ZFS Storage Pools +.Ss Example 6 : No Listing Available ZFS Storage Pools The following command lists all available pools on the system. In this case, the pool .Ar zion @@ -272,19 +271,19 @@ tank 61.5G 20.0G 41.5G - 48% 32% 1.00x ONLINE - zion - - - - - - - FAULTED - .Ed . -.It Sy Example 7 : No Destroying a ZFS Storage Pool +.Ss Example 7 : No Destroying a ZFS Storage Pool The following command destroys the pool .Ar tank and any datasets contained within: .Dl # Nm zpool Cm destroy Fl f Ar tank . -.It Sy Example 8 : No Exporting a ZFS Storage Pool +.Ss Example 8 : No Exporting a ZFS Storage Pool The following command exports the devices in pool .Ar tank so that they can be relocated or later imported: .Dl # Nm zpool Cm export Ar tank . -.It Sy Example 9 : No Importing a ZFS Storage Pool +.Ss Example 9 : No Importing a ZFS Storage Pool The following command displays available pools, and then imports the pool .Ar tank for use on the system. @@ -305,7 +304,7 @@ config: .No # Nm zpool Cm import Ar tank .Ed . -.It Sy Example 10 : No Upgrading All ZFS Storage Pools to the Current Version +.Ss Example 10 : No Upgrading All ZFS Storage Pools to the Current Version The following command upgrades all ZFS Storage pools to the current version of the software: .Bd -literal -compact -offset Ds @@ -313,7 +312,7 @@ the software: This system is currently running ZFS version 2. .Ed . -.It Sy Example 11 : No Managing Hot Spares +.Ss Example 11 : No Managing Hot Spares The following command creates a new pool with an available hot spare: .Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy spare Pa sdc .Pp @@ -328,12 +327,12 @@ The hot spare can be permanently removed from the pool using the following command: .Dl # Nm zpool Cm remove Ar tank Pa sdc . -.It Sy Example 12 : No Creating a ZFS Pool with Mirrored Separate Intent Logs +.Ss Example 12 : No Creating a ZFS Pool with Mirrored Separate Intent Logs The following command creates a ZFS storage pool consisting of two, two-way mirrors and mirrored log devices: .Dl # Nm zpool Cm create Ar pool Sy mirror Pa sda sdb Sy mirror Pa sdc sdd Sy log mirror Pa sde sdf . -.It Sy Example 13 : No Adding Cache Devices to a ZFS Pool +.Ss Example 13 : No Adding Cache Devices to a ZFS Pool The following command adds two disks for use as cache devices to a ZFS storage pool: .Dl # Nm zpool Cm add Ar pool Sy cache Pa sdc sdd @@ -346,7 +345,7 @@ Capacity and reads can be monitored using the subcommand as follows: .Dl # Nm zpool Cm iostat Fl v Ar pool 5 . -.It Sy Example 14 : No Removing a Mirrored top-level (Log or Data) Device +.Ss Example 14 : No Removing a Mirrored top-level (Log or Data) Device The following commands remove the mirrored log device .Sy mirror-2 and mirrored top-level data device @@ -381,7 +380,7 @@ The command to remove the mirrored data .Ar mirror-1 No is: .Dl # Nm zpool Cm remove Ar tank mirror-1 . -.It Sy Example 15 : No Displaying expanded space on a device +.Ss Example 15 : No Displaying expanded space on a device 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 @@ -398,7 +397,7 @@ data 23.9G 14.6G 9.30G - 48% 61% 1.00x ONLINE - sdc - - - - - .Ed . -.It Sy Example 16 : No Adding output columns +.Ss Example 16 : No Adding output columns Additional columns can be added to the .Nm zpool Cm status No and Nm zpool Cm iostat No output with Fl c . .Bd -literal -compact -offset Ds @@ -421,7 +420,6 @@ rpool 14.6G 54.9G 4 55 250K 2.69M sda1 14.6G 54.9G 4 55 250K 2.69M 70G ---------- ----- ----- ----- ----- ----- ----- ---- .Ed -.El . .Sh ENVIRONMENT VARIABLES .Bl -tag -compact -width "ZPOOL_IMPORT_UDEV_TIMEOUT_MS" @@ -432,7 +430,7 @@ to dump core on exit for the purposes of running .Sy ::findleaks . .It Sy ZFS_COLOR Use ANSI color in -.Nm zpool status +.Nm zpool Cm status output. .It Sy ZPOOL_IMPORT_PATH The search path for devices or files to use with the pool. @@ -449,7 +447,7 @@ The maximum time in milliseconds that will wait for an expected device to be available. .It Sy ZPOOL_STATUS_NON_NATIVE_ASHIFT_IGNORE If set, suppress warning about non-native vdev ashift in -.Nm zpool status . +.Nm zpool Cm status . The value is not used, only the presence or absence of the variable matters. .It Sy ZPOOL_VDEV_NAME_GUID Cause @@ -481,7 +479,7 @@ NVP value is present in the pool's config. For example, a pool that originated on illumos platform would have a .Sy devid value in the config and -.Nm zpool status +.Nm zpool Cm status would fail when listing the config. This would also be true for future Linux-based pools. .Pp @@ -497,12 +495,12 @@ by setting .Pp .It Sy ZPOOL_SCRIPTS_AS_ROOT Allow a privileged user to run -.Nm zpool status/iostat Fl c . +.Nm zpool Cm status Ns / Ns Cm iostat Fl c . Normally, only unprivileged users are allowed to run .Fl c . .It Sy ZPOOL_SCRIPTS_PATH The search path for scripts when running -.Nm zpool status/iostat Fl c . +.Nm zpool Cm status Ns / Ns Cm iostat Fl c . This is a colon-separated list of directories and overrides the default .Pa ~/.zpool.d and @@ -510,7 +508,7 @@ and search paths. .It Sy ZPOOL_SCRIPTS_ENABLED Allow a user to run -.Nm zpool status/iostat Fl c . +.Nm zpool Cm status Ns / Ns Cm iostat Fl c . If .Sy ZPOOL_SCRIPTS_ENABLED is not set, it is assumed that the user is allowed to run