Date: Fri, 1 Sep 2017 17:37:10 +0000 (UTC) From: Andriy Gapon <avg@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-vendor@freebsd.org Subject: svn commit: r323105 - in vendor/illumos/dist/man: man1m man4 Message-ID: <201709011737.v81HbAmd025511@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: avg Date: Fri Sep 1 17:37:10 2017 New Revision: 323105 URL: https://svnweb.freebsd.org/changeset/base/323105 Log: 8300 fix man page issues found by mandoc 1.14.1 illumos/illumos-gate@72d3dbb9ab4481606cb93caca98ba3b3a8eb6ce2 https://github.com/illumos/illumos-gate/commit/72d3dbb9ab4481606cb93caca98ba3b3a8eb6ce2 https://www.illumos.org/issues/8300 Prior to integrating the mdocml update to 1.14.1, fix issues found by new version, especially the "new sentence, new line" style rule. Reviewed by: Robert Mustacchi <rm@joyent.com> Reviewed by: Toomas Soome <tsoome@me.com> Approved by: Gordon Ross <gwr@nexenta.com> Author: Yuri Pankov <yuri.pankov@nexenta.com> Modified: vendor/illumos/dist/man/man1m/zfs.1m vendor/illumos/dist/man/man1m/zpool.1m vendor/illumos/dist/man/man4/ctf.4 Modified: vendor/illumos/dist/man/man1m/zfs.1m ============================================================================== --- vendor/illumos/dist/man/man1m/zfs.1m Fri Sep 1 17:35:27 2017 (r323104) +++ vendor/illumos/dist/man/man1m/zfs.1m Fri Sep 1 17:37:10 2017 (r323105) @@ -270,7 +270,8 @@ The .Nm command configures ZFS datasets within a ZFS storage pool, as described in .Xr zpool 1M . -A dataset is identified by a unique path within the ZFS namespace. For example: +A dataset is identified by a unique path within the ZFS namespace. +For example: .Bd -literal pool/{filesystem,volume,snapshot} .Ed @@ -285,28 +286,30 @@ A dataset can be one of the following: A ZFS dataset of type .Sy filesystem can be mounted within the standard system namespace and behaves like other file -systems. While ZFS file systems are designed to be POSIX compliant, known issues -exist that prevent compliance in some cases. Applications that depend on -standards conformance might fail due to non-standard behavior when checking file -system free space. +systems. +While ZFS file systems are designed to be POSIX compliant, known issues exist +that prevent compliance in some cases. +Applications that depend on standards conformance might fail due to non-standard +behavior when checking file system free space. .It Sy volume -A logical volume exported as a raw or block device. This type of dataset should -only be used under special circumstances. File systems are typically used in -most environments. +A logical volume exported as a raw or block device. +This type of dataset should only be used under special circumstances. +File systems are typically used in most environments. .It Sy snapshot -A read-only version of a file system or volume at a given point in time. It is -specified as +A read-only version of a file system or volume at a given point in time. +It is specified as .Ar filesystem Ns @ Ns Ar name or .Ar volume Ns @ Ns Ar name . .El .Ss ZFS File System Hierarchy A ZFS storage pool is a logical collection of devices that provide space for -datasets. A storage pool is also the root of the ZFS file system hierarchy. +datasets. +A storage pool is also the root of the ZFS file system hierarchy. .Pp The root of the pool can be accessed as a file system, such as mounting and -unmounting, taking snapshots, and setting properties. The physical storage -characteristics, however, are managed by the +unmounting, taking snapshots, and setting properties. +The physical storage characteristics, however, are managed by the .Xr zpool 1M command. .Pp @@ -314,31 +317,38 @@ See .Xr zpool 1M for more information on creating and administering pools. .Ss Snapshots -A snapshot is a read-only copy of a file system or volume. Snapshots can be -created extremely quickly, and initially consume no additional space within the -pool. As data within the active dataset changes, the snapshot consumes more -data than would otherwise be shared with the active dataset. +A snapshot is a read-only copy of a file system or volume. +Snapshots can be created extremely quickly, and initially consume no additional +space within the pool. +As data within the active dataset changes, the snapshot consumes more data than +would otherwise be shared with the active dataset. .Pp -Snapshots can have arbitrary names. Snapshots of volumes can be cloned or -rolled back, but cannot be accessed independently. +Snapshots can have arbitrary names. +Snapshots of volumes can be cloned or rolled back, but cannot be accessed +independently. .Pp File system snapshots can be accessed under the .Pa .zfs/snapshot -directory in the root of the file system. Snapshots are automatically mounted on -demand and may be unmounted at regular intervals. The visibility of the +directory in the root of the file system. +Snapshots are automatically mounted on demand and may be unmounted at regular +intervals. +The visibility of the .Pa .zfs directory can be controlled by the snapdir property. .Ss Clones A clone is a writable volume or file system whose initial contents are the same -as another dataset. As with snapshots, creating a clone is nearly instantaneous, -and initially consumes no additional space. +as another dataset. +As with snapshots, creating a clone is nearly instantaneous, and initially +consumes no additional space. .Pp -Clones can only be created from a snapshot. When a snapshot is cloned, it -creates an implicit dependency between the parent and child. Even though the -clone is created somewhere else in the dataset hierarchy, the original snapshot -cannot be destroyed as long as a clone exists. The +Clones can only be created from a snapshot. +When a snapshot is cloned, it creates an implicit dependency between the parent +and child. +Even though the clone is created somewhere else in the dataset hierarchy, the +original snapshot cannot be destroyed as long as a clone exists. +The .Sy origin property exposes this dependency, and the .Cm destroy @@ -346,28 +356,32 @@ command lists any such dependencies, if they exist. .Pp The clone parent-child dependency relationship can be reversed by using the .Cm promote -subcommand. This causes the +subcommand. +This causes the .Qq origin file system to become a clone of the specified file system, which makes it possible to destroy the file system that the clone was created from. .Ss "Mount Points" Creating a ZFS file system is a simple operation, so the number of file systems -per system is likely to be numerous. To cope with this, ZFS automatically -manages mounting and unmounting file systems without the need to edit the +per system is likely to be numerous. +To cope with this, ZFS automatically manages mounting and unmounting file +systems without the need to edit the .Pa /etc/vfstab -file. All automatically managed file systems are mounted by ZFS at boot time. +file. +All automatically managed file systems are mounted by ZFS at boot time. .Pp By default, file systems are mounted under .Pa /path , where .Ar path -is the name of the file system in the ZFS namespace. Directories are created and -destroyed as needed. +is the name of the file system in the ZFS namespace. +Directories are created and destroyed as needed. .Pp A file system can also have a mount point set in the .Sy mountpoint -property. This directory is created as needed, and ZFS automatically mounts the -file system when the +property. +This directory is created as needed, and ZFS automatically mounts the file +system when the .Nm zfs Cm mount Fl a command is invoked .Po without editing @@ -403,20 +417,25 @@ responsible for mounting and unmounting the file syste .Ss "Zones" A ZFS file system can be added to a non-global zone by using the .Nm zonecfg Cm add Sy fs -subcommand. A ZFS file system that is added to a non-global zone must have its +subcommand. +A ZFS file system that is added to a non-global zone must have its .Sy mountpoint property set to .Sy legacy . .Pp The physical properties of an added file system are controlled by the global -administrator. However, the zone administrator can create, modify, or destroy -files within the added file system, depending on how the file system is mounted. +administrator. +However, the zone administrator can create, modify, or destroy files within the +added file system, depending on how the file system is mounted. .Pp A dataset can also be delegated to a non-global zone by using the .Nm zonecfg Cm add Sy dataset -subcommand. You cannot delegate a dataset to one zone and the children of the -same dataset to another zone. The zone administrator can change properties of -the dataset or any of its children. However, the +subcommand. +You cannot delegate a dataset to one zone and the children of the same dataset +to another zone. +The zone administrator can change properties of the dataset or any of its +children. +However, the .Sy quota , .Sy filesystem_limit and @@ -426,7 +445,8 @@ administrator. .Pp A ZFS volume can be added as a device to a non-global zone by using the .Nm zonecfg Cm add Sy device -subcommand. However, its physical properties can be modified only by the global +subcommand. +However, its physical properties can be modified only by the global administrator. .Pp For more information about @@ -436,32 +456,33 @@ syntax, see .Pp After a dataset is delegated to a non-global zone, the .Sy zoned -property is automatically set. A zoned file system cannot be mounted in the -global zone, since the zone administrator might have to set the mount point to -an unacceptable value. +property is automatically set. +A zoned file system cannot be mounted in the global zone, since the zone +administrator might have to set the mount point to an unacceptable value. .Pp The global administrator can forcibly clear the .Sy zoned -property, though this should be done with extreme care. The global administrator -should verify that all the mount points are acceptable before clearing the -property. +property, though this should be done with extreme care. +The global administrator should verify that all the mount points are acceptable +before clearing the property. .Ss Native Properties Properties are divided into two types, native properties and user-defined .Po or .Qq user .Pc -properties. Native properties either export internal statistics or control ZFS -behavior. In addition, native properties are either editable or read-only. User -properties have no effect on ZFS behavior, but you can use them to annotate -datasets in a way that is meaningful in your environment. For more information -about user properties, see the +properties. +Native properties either export internal statistics or control ZFS behavior. +In addition, native properties are either editable or read-only. +User properties have no effect on ZFS behavior, but you can use them to annotate +datasets in a way that is meaningful in your environment. +For more information about user properties, see the .Sx User Properties section, below. .Pp Every dataset has a set of properties that export statistics about the dataset -as well as control various behaviors. Properties are inherited from the parent -unless overridden by the child. Some properties apply only to certain types of -datasets +as well as control various behaviors. +Properties are inherited from the parent unless overridden by the child. +Some properties apply only to certain types of datasets .Pq file systems, volumes, or snapshots . .Pp The values of numeric properties can be specified using human-readable suffixes @@ -487,28 +508,33 @@ and .Sy sharesmb . .Pp The following native properties consist of read-only statistics about the -dataset. These properties can be neither set, nor inherited. Native properties -apply to all dataset types unless otherwise noted. +dataset. +These properties can be neither set, nor inherited. +Native properties apply to all dataset types unless otherwise noted. .Bl -tag -width "usedbyrefreservation" .It Sy available The amount of space available to the dataset and all its children, assuming that -there is no other activity in the pool. Because space is shared within a pool, -availability can be limited by any number of factors, including physical pool -size, quotas, reservations, or other datasets within the pool. +there is no other activity in the pool. +Because space is shared within a pool, availability can be limited by any number +of factors, including physical pool size, quotas, reservations, or other +datasets within the pool. .Pp This property can also be referred to by its shortened column name, .Sy avail . .It Sy compressratio For non-snapshots, the compression ratio achieved for the .Sy used -space of this dataset, expressed as a multiplier. The +space of this dataset, expressed as a multiplier. +The .Sy used property includes descendant datasets, and, for clones, does not include the -space shared with the origin snapshot. For snapshots, the +space shared with the origin snapshot. +For snapshots, the .Sy compressratio is the same as the .Sy refcompressratio -property. Compression can be turned on by running: +property. +Compression can be turned on by running: .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset . The default value is .Sy off . @@ -516,9 +542,11 @@ The default value is The time this dataset was created. .It Sy clones For snapshots, this property is a comma-separated list of filesystems or volumes -which are clones of this snapshot. The clones' +which are clones of this snapshot. +The clones' .Sy origin -property is this snapshot. If the +property is this snapshot. +If the .Sy clones property is not empty, then this snapshot can not be destroyed .Po even with the @@ -532,50 +560,59 @@ This property is .Sy on if the snapshot has been marked for deferred destroy by using the .Nm zfs Cm destroy Fl d -command. Otherwise, the property is +command. +Otherwise, the property is .Sy off . .It Sy filesystem_count The total number of filesystems and volumes that exist under this location in -the dataset tree. This value is only available when a +the dataset tree. +This value is only available when a .Sy filesystem_limit has been set somewhere in the tree under which the dataset resides. .It Sy logicalreferenced The amount of space that is .Qq logically -accessible by this dataset. See the +accessible by this dataset. +See the .Sy referenced -property. The logical space ignores the effect of the +property. +The logical space ignores the effect of the .Sy compression and .Sy copies properties, giving a quantity closer to the amount of data that applications -see. However, it does include space consumed by metadata. +see. +However, it does include space consumed by metadata. .Pp This property can also be referred to by its shortened column name, .Sy lrefer . .It Sy logicalused The amount of space that is .Qq logically -consumed by this dataset and all its descendents. See the +consumed by this dataset and all its descendents. +See the .Sy used -property. The logical space ignores the effect of the +property. +The logical space ignores the effect of the .Sy compression and .Sy copies properties, giving a quantity closer to the amount of data that applications -see. However, it does include space consumed by metadata. +see. +However, it does include space consumed by metadata. .Pp This property can also be referred to by its shortened column name, .Sy lused . .It Sy mounted -For file systems, indicates whether the file system is currently mounted. This -property can be either +For file systems, indicates whether the file system is currently mounted. +This property can be either .Sy yes or .Sy no . .It Sy origin For cloned file systems or volumes, the snapshot from which the clone was -created. See also the +created. +See also the .Sy clones property. .It Sy receive_resume_token @@ -587,21 +624,24 @@ to resume and complete the .Sy zfs receive . .It Sy referenced The amount of data that is accessible by this dataset, which may or may not be -shared with other datasets in the pool. When a snapshot or clone is created, it -initially references the same amount of space as the file system or snapshot it -was created from, since its contents are identical. +shared with other datasets in the pool. +When a snapshot or clone is created, it initially references the same amount of +space as the file system or snapshot it was created from, since its contents are +identical. .Pp This property can also be referred to by its shortened column name, .Sy refer . .It Sy refcompressratio The compression ratio achieved for the .Sy referenced -space of this dataset, expressed as a multiplier. See also the +space of this dataset, expressed as a multiplier. +See also the .Sy compressratio property. .It Sy snapshot_count The total number of snapshots that exist under this location in the dataset -tree. This value is only available when a +tree. +This value is only available when a .Sy snapshot_limit has been set somewhere in the tree under which the dataset resides. .It Sy type @@ -611,35 +651,39 @@ The type of dataset: or .Sy snapshot . .It Sy used -The amount of space consumed by this dataset and all its descendents. This is -the value that is checked against this dataset's quota and reservation. The -space used does not include this dataset's reservation, but does take into -account the reservations of any descendent datasets. The amount of space that a -dataset consumes from its parent, as well as the amount of space that is freed -if this dataset is recursively destroyed, is the greater of its space used and -its reservation. +The amount of space consumed by this dataset and all its descendents. +This is the value that is checked against this dataset's quota and reservation. +The space used does not include this dataset's reservation, but does take into +account the reservations of any descendent datasets. +The amount of space that a dataset consumes from its parent, as well as the +amount of space that is freed if this dataset is recursively destroyed, is the +greater of its space used and its reservation. .Pp The used space of a snapshot .Po see the .Sx Snapshots section .Pc -is space that is referenced exclusively by this snapshot. If this snapshot is -destroyed, the amount of +is space that is referenced exclusively by this snapshot. +If this snapshot is destroyed, the amount of .Sy used -space will be freed. Space that is shared by multiple snapshots isn't accounted -for in this metric. When a snapshot is destroyed, space that was previously -shared with this snapshot can become unique to snapshots adjacent to it, thus -changing the used space of those snapshots. The used space of the latest -snapshot can also be affected by changes in the file system. Note that the +space will be freed. +Space that is shared by multiple snapshots isn't accounted for in this metric. +When a snapshot is destroyed, space that was previously shared with this +snapshot can become unique to snapshots adjacent to it, thus changing the used +space of those snapshots. +The used space of the latest snapshot can also be affected by changes in the +file system. +Note that the .Sy used space of a snapshot is a subset of the .Sy written space of the snapshot. .Pp The amount of space used, available, or referenced does not take into account -pending changes. Pending changes are generally accounted for within a few -seconds. Committing a change to a disk using +pending changes. +Pending changes are generally accounted for within a few seconds. +Committing a change to a disk using .Xr fsync 3C or .Dv O_SYNC @@ -650,7 +694,8 @@ The .Sy usedby* properties decompose the .Sy used -properties into the various reasons that space is used. Specifically, +properties into the various reasons that space is used. +Specifically, .Sy used No = .Sy usedbychildren No + .Sy usedbydataset No + @@ -677,14 +722,15 @@ set on this dataset, which would be freed if the .Sy refreservation was removed. .It Sy usedbysnapshots -The amount of space consumed by snapshots of this dataset. In particular, it is -the amount of space that would be freed if all of this dataset's snapshots were -destroyed. Note that this is not simply the sum of the snapshots' +The amount of space consumed by snapshots of this dataset. +In particular, it is the amount of space that would be freed if all of this +dataset's snapshots were destroyed. +Note that this is not simply the sum of the snapshots' .Sy used properties because space can be shared by multiple snapshots. .It Sy userused Ns @ Ns Em user -The amount of space consumed by the specified user in this dataset. Space is -charged to the owner of each file, as displayed by +The amount of space consumed by the specified user in this dataset. +Space is charged to the owner of each file, as displayed by .Nm ls Fl l . The amount of space charged is displayed by .Nm du @@ -694,8 +740,8 @@ See the .Nm zfs Cm userspace subcommand for more information. .Pp -Unprivileged users can access only their own space usage. The root user, or a -user who has been granted the +Unprivileged users can access only their own space usage. +The root user, or a user who has been granted the .Sy userused privilege with .Nm zfs Cm allow , @@ -730,31 +776,34 @@ forms: .Pc .El .It Sy userrefs -This property is set to the number of user holds on this snapshot. User holds -are set by using the +This property is set to the number of user holds on this snapshot. +User holds are set by using the .Nm zfs Cm hold command. .It Sy groupused Ns @ Ns Em group -The amount of space consumed by the specified group in this dataset. Space is -charged to the group of each file, as displayed by +The amount of space consumed by the specified group in this dataset. +Space is charged to the group of each file, as displayed by .Nm ls Fl l . See the .Sy userused Ns @ Ns Em user property for more information. .Pp -Unprivileged users can only access their own groups' space usage. The root user, -or a user who has been granted the +Unprivileged users can only access their own groups' space usage. +The root user, or a user who has been granted the .Sy groupused privilege with .Nm zfs Cm allow , can access all groups' usage. .It Sy volblocksize -For volumes, specifies the block size of the volume. The +For volumes, specifies the block size of the volume. +The .Sy blocksize cannot be changed once the volume has been written, so it should be set at -volume creation time. The default +volume creation time. +The default .Sy blocksize -for volumes is 8 Kbytes. Any power of 2 from 512 bytes to 128 Kbytes is valid. +for volumes is 8 Kbytes. +Any power of 2 from 512 bytes to 128 Kbytes is valid. .Pp This property can also be referred to by its shortened column name, .Sy volblock . @@ -766,9 +815,9 @@ by this dataset, that was written since the previous s .It Sy written Ns @ Ns Em snapshot The amount of .Sy referenced -space written to this dataset since the specified snapshot. This is the space -that is referenced by this dataset but was not referenced by the specified -snapshot. +space written to this dataset since the specified snapshot. +This is the space that is referenced by this dataset but was not referenced by +the specified snapshot. .Pp The .Em snapshot @@ -777,7 +826,8 @@ may be specified as a short snapshot name .Sy @ .Pc , in which case it will be interpreted as a snapshot in the same filesystem as -this dataset. The +this dataset. +The .Em snapshot may be a full snapshot name .Po Em filesystem Ns @ Ns Em snapshot Pc , @@ -854,7 +904,8 @@ non-trivial ACL, with entries in addition to those tha .Pp .Xr chmod 2 is required to change the set user ID, set group ID, or sticky bit on a file or -directory, as they do not have equivalent ACEs. In order to use +directory, as they do not have equivalent ACEs. +In order to use .Xr chmod 2 on a file or directory with a non-trivial ACL when .Sy aclmode @@ -865,7 +916,8 @@ you must first remove all ACEs except for those that r Controls whether the access time for files is updated when they are read. Turning this property off avoids producing write traffic when reading files and can result in significant performance gains, though it might confuse mailers -and other similar utilities. The default value is +and other similar utilities. +The default value is .Sy on . .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto If this property is set to @@ -880,10 +932,11 @@ property to .Sy none , except that the dataset still has a normal .Sy mountpoint -property, which can be inherited. Setting this property to +property, which can be inherited. +Setting this property to .Sy off -allows datasets to be used solely as a mechanism to inherit properties. One -example of setting +allows datasets to be used solely as a mechanism to inherit properties. +One example of setting .Sy canmount Ns = Ns Sy off is to have two datasets with the same .Sy mountpoint , @@ -892,9 +945,9 @@ have different inherited characteristics. .Pp When set to .Sy noauto , -a dataset can only be mounted and unmounted explicitly. The dataset is not -mounted automatically when the dataset is created or imported, nor is it mounted -by the +a dataset can only be mounted and unmounted explicitly. +The dataset is not mounted automatically when the dataset is created or +imported, nor is it mounted by the .Nm zfs Cm mount Fl a command or unmounted by the .Nm zfs Cm unmount Fl a @@ -906,7 +959,8 @@ This property is not inherited. .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr .Xc -Controls the checksum used to verify data integrity. The default value is +Controls the checksum used to verify data integrity. +The default value is .Sy on , which automatically selects an appropriate algorithm .Po currently, @@ -915,11 +969,13 @@ but this may change in future releases .Pc . The value .Sy off -disables integrity checking on user data. The value +disables integrity checking on user data. +The value .Sy noparity not only disables integrity but also disables maintaining parity for user data. This setting is used internally by a dump device residing on a RAID-Z pool and -should not be used by any other dataset. Disabling checksums is +should not be used by any other dataset. +Disabling checksums is .Sy NOT a recommended practice. .Pp @@ -928,8 +984,8 @@ The .Sy skein , and .Sy edonr -checksum algorithms require enabling the appropriate features on the -pool. Please see +checksum algorithms require enabling the appropriate features on the pool. +Please see .Xr zpool-features 5 for more information on these algorithms. .Pp @@ -942,14 +998,15 @@ Controls the compression algorithm used for this datas .Pp Setting compression to .Sy on -indicates that the current default compression algorithm should be used. The -default balances compression and decompression speed, with compression ratio and -is expected to work well on a wide variety of workloads. Unlike all other -settings for this property, +indicates that the current default compression algorithm should be used. +The default balances compression and decompression speed, with compression ratio +and is expected to work well on a wide variety of workloads. +Unlike all other settings for this property, .Sy on -does not select a fixed compression type. As new compression algorithms are -added to ZFS and enabled on a pool, the default compression algorithm may -change. The current default compression algorithm is either +does not select a fixed compression type. +As new compression algorithms are added to ZFS and enabled on a pool, the +default compression algorithm may change. +The current default compression algorithm is either .Sy lzjb or, if the .Sy lz4_compress @@ -960,8 +1017,9 @@ The .Sy lz4 compression algorithm is a high-performance replacement for the .Sy lzjb -algorithm. It features significantly faster compression and decompression, as -well as a moderately higher compression ratio than +algorithm. +It features significantly faster compression and decompression, as well as a +moderately higher compression ratio than .Sy lzjb , but can only be used on pools with the .Sy lz4_compress @@ -982,7 +1040,8 @@ The .Sy gzip compression algorithm uses the same compression as the .Xr gzip 1 -command. You can specify the +command. +You can specify the .Sy gzip level by using the value .Sy gzip- Ns Em N , @@ -1005,31 +1064,35 @@ The compression algorithm compresses runs of zeros. .Pp This property can also be referred to by its shortened column name -\fBcompress\fR. Changing this property affects only newly-written data. +.Sy compress . +Changing this property affects only newly-written data. .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3 -Controls the number of copies of data stored for this dataset. These copies are -in addition to any redundancy provided by the pool, for example, mirroring or -RAID-Z. The copies are stored on different disks, if possible. The space used -by multiple copies is charged to the associated file and dataset, changing the +Controls the number of copies of data stored for this dataset. +These copies are in addition to any redundancy provided by the pool, for +example, mirroring or RAID-Z. +The copies are stored on different disks, if possible. +The space used by multiple copies is charged to the associated file and dataset, +changing the .Sy used property and counting against quotas and reservations. .Pp -Changing this property only affects newly-written data. Therefore, set this -property at file system creation time by using the +Changing this property only affects newly-written data. +Therefore, set this property at file system creation time by using the .Fl o Sy copies Ns = Ns Ar N option. .It Sy devices Ns = Ns Sy on Ns | Ns Sy off -Controls whether device nodes can be opened on this file system. The default -value is +Controls whether device nodes can be opened on this file system. +The default value is .Sy on . .It Sy exec Ns = Ns Sy on Ns | Ns Sy off -Controls whether processes can be executed from within this file system. The -default value is +Controls whether processes can be executed from within this file system. +The default value is .Sy on . .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none Limits the number of filesystems and volumes that can exist under this point in -the dataset tree. The limit is not enforced if the user is allowed to change -the limit. Setting a +the dataset tree. +The limit is not enforced if the user is allowed to change the limit. +Setting a .Sy filesystem_limit to .Sy on @@ -1037,33 +1100,40 @@ a descendent of a filesystem that already has a .Sy filesystem_limit does not override the ancestor's .Sy filesystem_limit , -but rather imposes an additional limit. This feature must be enabled to be used +but rather imposes an additional limit. +This feature must be enabled to be used .Po see .Xr zpool-features 5 .Pc . .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy -Controls the mount point used for this file system. See the +Controls the mount point used for this file system. +See the .Sx Mount Points section for more information on how this property is used. .Pp When the .Sy mountpoint property is changed for a file system, the file system and any children that -inherit the mount point are unmounted. If the new value is +inherit the mount point are unmounted. +If the new value is .Sy legacy , -then they remain unmounted. Otherwise, they are automatically remounted in the -new location if the property was previously +then they remain unmounted. +Otherwise, they are automatically remounted in the new location if the property +was previously .Sy legacy or .Sy none , -or if they were mounted before the property was changed. In addition, any shared -file systems are unshared and shared in the new location. +or if they were mounted before the property was changed. +In addition, any shared file systems are unshared and shared in the new +location. .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off Controls whether the file system should be mounted with .Sy nbmand .Pq Non Blocking mandatory locks . -This is used for SMB clients. Changes to this property only take effect when the -file system is umounted and remounted. See +This is used for SMB clients. +Changes to this property only take effect when the file system is umounted and +remounted. +See .Xr mount 1M for more information on .Sy nbmand @@ -1073,60 +1143,68 @@ Controls what is cached in the primary cache .Pq ARC . If this property is set to .Sy all , -then both user data and metadata is cached. If this property is set to +then both user data and metadata is cached. +If this property is set to .Sy none , -then neither user data nor metadata is cached. If this property is set to +then neither user data nor metadata is cached. +If this property is set to .Sy metadata , -then only metadata is cached. The default value is +then only metadata is cached. +The default value is .Sy all . .It Sy quota Ns = Ns Em size Ns | Ns Sy none -Limits the amount of space a dataset and its descendents can consume. This -property enforces a hard limit on the amount of space used. This includes all -space consumed by descendents, including file systems and snapshots. Setting a -quota on a descendent of a dataset that already has a quota does not override -the ancestor's quota, but rather imposes an additional limit. +Limits the amount of space a dataset and its descendents can consume. +This property enforces a hard limit on the amount of space used. +This includes all space consumed by descendents, including file systems and +snapshots. +Setting a quota on a descendent of a dataset that already has a quota does not +override the ancestor's quota, but rather imposes an additional limit. .Pp Quotas cannot be set on volumes, as the .Sy volsize property acts as an implicit quota. .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none Limits the number of snapshots that can be created on a dataset and its -descendents. Setting a +descendents. +Setting a .Sy snapshot_limit on a descendent of a dataset that already has a .Sy snapshot_limit does not override the ancestor's .Sy snapshot_limit , -but rather imposes an additional limit. The limit is not enforced if the user is -allowed to change the limit. For example, this means that recursive snapshots -taken from the global zone are counted against each delegated dataset within -a zone. This feature must be enabled to be used +but rather imposes an additional limit. +The limit is not enforced if the user is allowed to change the limit. +For example, this means that recursive snapshots taken from the global zone are +counted against each delegated dataset within a zone. +This feature must be enabled to be used .Po see .Xr zpool-features 5 .Pc . .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none -Limits the amount of space consumed by the specified user. User space -consumption is identified by the +Limits the amount of space consumed by the specified user. +User space consumption is identified by the .Sy userspace@ Ns Em user property. .Pp -Enforcement of user quotas may be delayed by several seconds. This delay means -that a user might exceed their quota before the system notices that they are -over quota and begins to refuse additional writes with the +Enforcement of user quotas may be delayed by several seconds. +This delay means that a user might exceed their quota before the system notices +that they are over quota and begins to refuse additional writes with the .Er EDQUOT -error message. See the +error message. +See the .Nm zfs Cm userspace subcommand for more information. .Pp -Unprivileged users can only access their own groups' space usage. The root -user, or a user who has been granted the +Unprivileged users can only access their own groups' space usage. +The root user, or a user who has been granted the .Sy userquota privilege with .Nm zfs Cm allow , can get and set everyone's quota. .Pp This property is not available on volumes, on file systems before version 4, or -on pools before version 15. The +on pools before version 15. +The .Sy userquota@ Ns Em ... properties are not displayed by .Nm zfs Cm get Sy all . @@ -1156,40 +1234,46 @@ symbol, using one of the following forms: .Pc .El .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none -Limits the amount of space consumed by the specified group. Group space -consumption is identified by the +Limits the amount of space consumed by the specified group. +Group space consumption is identified by the .Sy groupused@ Ns Em group property. .Pp -Unprivileged users can access only their own groups' space usage. The root -user, or a user who has been granted the +Unprivileged users can access only their own groups' space usage. +The root user, or a user who has been granted the .Sy groupquota privilege with .Nm zfs Cm allow , can get and set all groups' quotas. .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off -Controls whether this dataset can be modified. The default value is +Controls whether this dataset can be modified. +The default value is .Sy off . .Pp This property can also be referred to by its shortened column name, .Sy rdonly . .It Sy recordsize Ns = Ns Em size -Specifies a suggested block size for files in the file system. This property is -designed solely for use with database workloads that access files in fixed-size -records. ZFS automatically tunes block sizes according to internal algorithms -optimized for typical access patterns. +Specifies a suggested block size for files in the file system. +This property is designed solely for use with database workloads that access +files in fixed-size records. +ZFS automatically tunes block sizes according to internal algorithms optimized +for typical access patterns. .Pp For databases that create very large files but access them in small random -chunks, these algorithms may be suboptimal. Specifying a +chunks, these algorithms may be suboptimal. +Specifying a .Sy recordsize greater than or equal to the record size of the database can result in -significant performance gains. Use of this property for general purpose file -systems is strongly discouraged, and may adversely affect performance. +significant performance gains. +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 512 and less -than or equal to 128 Kbytes. If the +than or equal to 128 Kbytes. +If the .Sy large_blocks -feature is enabled on the pool, the size may be up to 1 Mbyte. See +feature is enabled on the pool, the size may be up to 1 Mbyte. +See .Xr zpool-features 5 for details on ZFS feature flags. .Pp @@ -1200,10 +1284,10 @@ affects only files created afterward; existing files a This property can also be referred to by its shortened column name, .Sy recsize . .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most -Controls what types of metadata are stored redundantly. ZFS stores an extra copy -of metadata, so that if a single block is corrupted, the amount of user data -lost is limited. This extra copy is in addition to any redundancy provided at -the pool level +Controls what types of metadata are stored redundantly. +ZFS stores an extra copy of metadata, so that if a single block is corrupted, +the amount of user data lost is limited. +This extra copy is in addition to any redundancy provided at the pool level .Pq e.g. by mirroring or RAID-Z , and is in addition to an extra copy specified by the .Sy copies @@ -1218,8 +1302,8 @@ metadata. .Pp When set to .Sy all , -ZFS stores an extra copy of all metadata. If a single on-disk block is corrupt, -at worst a single block of user data +ZFS stores an extra copy of all metadata. +If a single on-disk block is corrupt, at worst a single block of user data .Po which is .Sy recordsize bytes long @@ -1228,27 +1312,30 @@ can be lost. .Pp When set to .Sy most , -ZFS stores an extra copy of most types of metadata. This can improve performance -of random writes, because less metadata must be written. In practice, at worst -about 100 blocks +ZFS stores an extra copy of most types of metadata. +This can improve performance of random writes, because less metadata must be +written. +In practice, at worst about 100 blocks .Po of .Sy recordsize bytes each .Pc -of user data can be lost if a single on-disk block is corrupt. The exact -behavior of which metadata blocks are stored redundantly may change in future -releases. +of user data can be lost if a single on-disk block is corrupt. +The exact behavior of which metadata blocks are stored redundantly may change in +future releases. .Pp The default value is .Sy all . .It Sy refquota Ns = Ns Em size Ns | Ns Sy none -Limits the amount of space a dataset can consume. This property enforces a hard -limit on the amount of space used. This hard limit does not include space used -by descendents, including file systems and snapshots. +Limits the amount of space a dataset can consume. +This property enforces a hard limit on the amount of space used. +This hard limit does not include space used by descendents, including file +systems and snapshots. *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201709011737.v81HbAmd025511>