diff options
Diffstat (limited to 'usr/src/man/man1m')
-rw-r--r-- | usr/src/man/man1m/acpidump.1m | 7 | ||||
-rw-r--r-- | usr/src/man/man1m/acpixtract.1m | 13 | ||||
-rw-r--r-- | usr/src/man/man1m/automount.1m | 252 | ||||
-rw-r--r-- | usr/src/man/man1m/automountd.1m | 18 | ||||
-rw-r--r-- | usr/src/man/man1m/catman.1m | 4 | ||||
-rw-r--r-- | usr/src/man/man1m/diskinfo.1m | 8 | ||||
-rw-r--r-- | usr/src/man/man1m/dns-sd.1m | 85 | ||||
-rw-r--r-- | usr/src/man/man1m/installboot.1m | 45 | ||||
-rw-r--r-- | usr/src/man/man1m/ipadm.1m | 122 | ||||
-rw-r--r-- | usr/src/man/man1m/lofiadm.1m | 116 | ||||
-rw-r--r-- | usr/src/man/man1m/mount_nfs.1m | 286 | ||||
-rw-r--r-- | usr/src/man/man1m/mountd.1m | 37 | ||||
-rw-r--r-- | usr/src/man/man1m/ndp.1m | 48 | ||||
-rw-r--r-- | usr/src/man/man1m/nfsd.1m | 55 | ||||
-rw-r--r-- | usr/src/man/man1m/nfsmapid.1m | 16 | ||||
-rw-r--r-- | usr/src/man/man1m/share_nfs.1m | 217 | ||||
-rw-r--r-- | usr/src/man/man1m/sharectl.1m | 30 | ||||
-rw-r--r-- | usr/src/man/man1m/stmfadm.1m | 153 | ||||
-rw-r--r-- | usr/src/man/man1m/zfs.1m | 1404 | ||||
-rw-r--r-- | usr/src/man/man1m/zpool.1m | 843 |
20 files changed, 2210 insertions, 1549 deletions
diff --git a/usr/src/man/man1m/acpidump.1m b/usr/src/man/man1m/acpidump.1m index 5d93abbcbe..577a1deaef 100644 --- a/usr/src/man/man1m/acpidump.1m +++ b/usr/src/man/man1m/acpidump.1m @@ -29,8 +29,8 @@ The .Nm utility is used to dump the system's Advanced Configuration and Power Interface -(ACPI) tables that are provided by system firmware. The dumped tables can be -used by other utilities, such as +(ACPI) tables that are provided by system firmware. +The dumped tables can be used by other utilities, such as .Xr acpixtract 1M or .Sy iasl . @@ -42,7 +42,8 @@ Get the table at the given physical address. .It Fl b Dump all tables to binary files. .It Fl c Ar on|off -Enable dumping customized tables. The default is off. +Enable dumping customized tables. +The default is off. .It Fl f Ar file Read the table from the given binary file. .It Fl h diff --git a/usr/src/man/man1m/acpixtract.1m b/usr/src/man/man1m/acpixtract.1m index cc844c78d0..309056c459 100644 --- a/usr/src/man/man1m/acpixtract.1m +++ b/usr/src/man/man1m/acpixtract.1m @@ -25,19 +25,22 @@ The .Nm utility extracts the binary data from a dump of the system's Advanced -Configuration and Power Interface (ACPI) tables. The dump is usually obtained -via the +Configuration and Power Interface (ACPI) tables. +The dump is usually obtained via the .Xr acpidump 1M -command. The resulting binary file(s) are represented in the ACPI +command. +The resulting binary file(s) are represented in the ACPI .Sy ASL -assembly language. For each table extracted, a corresponding +assembly language. +For each table extracted, a corresponding .Em table.dat file will be created. .Sh OPTIONS The following options are supported: .Bl -tag -width Ds .It Fl a -Extract all of the tables found. By default only the +Extract all of the tables found. +By default only the .Sy DSDT and .Sy SSDT diff --git a/usr/src/man/man1m/automount.1m b/usr/src/man/man1m/automount.1m index 3ce74a5b1d..717d4fafe1 100644 --- a/usr/src/man/man1m/automount.1m +++ b/usr/src/man/man1m/automount.1m @@ -34,18 +34,21 @@ The .Nm utility installs .Nm autofs -mount points and associates an automount map with each mount point. It starts -the +mount points and associates an automount map with each mount point. +It starts the .Xr automountd 1M daemon if it finds any non-trivial entries in either local or distributed -automount maps and if the daemon is not already running. The +automount maps and if the daemon is not already running. +The .Nm autofs file system monitors attempts to access directories within it and notifies the .Xr automountd 1M -daemon. The daemon uses the map to locate a file system, which it then mounts at -the point of reference within the +daemon. +The daemon uses the map to locate a file system, which it then mounts at the +point of reference within the .Nm autofs -file system. A map can be assigned to an +file system. +A map can be assigned to an .Nm autofs mount using an entry in the .Pa /etc/auto_master @@ -61,7 +64,8 @@ The file .Pa /etc/auto_master determines the locations of all .Nm autofs -mount points. By default, this file contains three entries: +mount points. +By default, this file contains three entries: .Bd -literal -offset indent # Master map for automounter # @@ -72,17 +76,21 @@ mount points. By default, this file contains three entries: .Pp The .Sy +auto_master -entry is a reference to an external NIS master map. If one exists, then -its entries are read as if they occurred in place of the +entry is a reference to an external NIS master map. +If one exists, then its entries are read as if they occurred in place of the .Sy +auto_master -entry. The remaining entries in the master file specify a directory on which an +entry. +The remaining entries in the master file specify a directory on which an .Nm autofs mount will be made followed by the automounter map to be associated with it. Optional mount options may be supplied as an optional third field in the each -entry. These options are used for any entries in the map that do not specify -mount options explicitly. The +entry. +These options are used for any entries in the map that do not specify mount +options explicitly. +The .Nm -command is usually run without arguments. It compares the entries +command is usually run without arguments. +It compares the entries .Pa /etc/auto_master with the current list of .Nm autofs @@ -96,33 +104,37 @@ up to date with the .Pa /etc/auto_master . At boot time it installs all .Nm autofs -mounts from the master map. Subsequently, it may be run to install +mounts from the master map. +Subsequently, it may be run to install .Nm autofs mounts for new entries in the master map or the direct map, or to perform unmounts for entries that have been removed from these maps. .Ss Automount with Solaris Trusted Extensions If a system is configured with Solaris Trusted Extensions, additional -processing is performed to facilitate multilevel home directory access. A list -of zones whose labels are dominated by the current zone is generated and +processing is performed to facilitate multilevel home directory access. +A list of zones whose labels are dominated by the current zone is generated and default .Sy auto_home -automount maps are generated if they do not currently exist. These automount -maps are named +automount maps are generated if they do not currently exist. +These automount maps are named .Sy auto_home_ Ns Ar zonename , where .Ar zonename -is the name of each zone's lower-level zone. An +is the name of each zone's lower-level zone. +An .Nm autofs mount of each such .Sy auto_home map is then performed, regardless of whether it is explicitly or implicitly -listed in the master map. Instead of +listed in the master map. +Instead of .Nm autofs mounting the standard .Sy auto_home map, the zone uses an .Pa auto_home -file appended with its own zone name. Each zone's +file appended with its own zone name. +Each zone's .Sy auto_home map is uniquely named so that it can be maintained and shared by all zones using a common name server. @@ -130,7 +142,8 @@ a common name server. By default, the home directories of lower-level zones are mounted read-only under .Pa /zone/ Ns Ar zonename Ns Pa /export/home -when each zone is booted. The default +when each zone is booted. +The default .Sy auto_home_ Ns Ar zonename automount map specifies that path as the source directory for an .Nm lofs @@ -147,22 +160,23 @@ as generated from a higher level zone would contain: When a home directory is referenced and the name does not match any other keys in the .Sy auto_home_public -map, it will match this loopback mount specification. If this loopback match -occurs and the name corresponds to a valid user whose home directory does not -exist in the public zone, the directory is automatically created on behalf of -the user. +map, it will match this loopback mount specification. +If this loopback match occurs and the name corresponds to a valid user whose +home directory does not exist in the public zone, the directory is automatically +created on behalf of the user. .Sh OPTIONS The following options are supported: .Bl -tag -width Ds .It Fl v -Verbose mode. Notifies of +Verbose mode. +Notifies of .Nm autofs mounts, unmounts, or other non-essential information. .It Fl t Ar duration Specifies a .Ar duration , -in seconds, that a file system is to remain mounted when not in use. The default -is +in seconds, that a file system is to remain mounted when not in use. +The default is .Sy 10 minutes. .El @@ -184,8 +198,8 @@ is a comma-separated list of .Nm mount options, and .Ar location -specifies a file system from which the directory may be mounted. In the case of -a simple NFS mount, the options that can be used are specified in +specifies a file system from which the directory may be mounted. +In the case of a simple NFS mount, the options that can be used are specified in .Xr mount_nfs 1M , and .Ar location @@ -211,17 +225,19 @@ If the read-only flag is set in the map entry, .Nm automountd mounts a list of locations that the kernel may use, sorted by several criteria. Only locations available at mount time will be mounted, and thus be available to -the kernel. When a server does not respond, the kernel will switch to an -alternate server. The sort ordering of +the kernel. +When a server does not respond, the kernel will switch to an alternate server. +The sort ordering of .Nm -is used to determine how the next server is chosen. If the read-only flag is not -set, +is used to determine how the next server is chosen. +If the read-only flag is not set, .Nm will mount the best single location, chosen by the same sort ordering, and new servers will only be chosen when an unmount has been possible, and a remount is -done. Servers on the same local subnet are given the strongest preference, and -servers on the local net are given the second strongest preference. Among -servers equally far away, response times will determine the order if no +done. +Servers on the same local subnet are given the strongest preference, and servers +on the local net are given the second strongest preference. +Among servers equally far away, response times will determine the order if no weighting factors .Pq see below are used. @@ -230,9 +246,10 @@ If the list includes server locations using both the NFS Version 2 Protocol and the NFS Version 3 Protocol, .Nm will choose only a subset of the server locations on the list, so that all -entries will be the same protocol. It will choose servers with the NFS Version 3 -Protocol so long as an NFS Version 2 Protocol server on a local subnet will not -be ignored. See the FIXME for additional details. +entries will be the same protocol. +It will choose servers with the NFS Version 3 Protocol so long as an NFS Version +2 Protocol server on a local subnet will not be ignored. +See the FIXME for additional details. .Pp If each .Ar location @@ -246,11 +263,11 @@ may be used with a comma-separated list of hostnames: .Ed .Pp Requests for a server may be weighted, with the weighting factor appended to -the server name as an integer in parentheses. Servers without a weighting are -assumed to have a value of zero +the server name as an integer in parentheses. +Servers without a weighting are assumed to have a value of zero .Pq most likely to be selected . -Progressively higher values decrease the chance of being selected. In the -example, +Progressively higher values decrease the chance of being selected. +In the example, .Bd -literal -offset indent man -ro alpha,bravo,charlie(1),delta(4):/usr/man .Ed @@ -263,19 +280,21 @@ have the highest priority; host .Sy delta has the lowest. .Pp -Server proximity takes priority in the selection process. In the example above, -if the server +Server proximity takes priority in the selection process. +In the example above, if the server .Sy delta is on the same network segment as the client, but the others are on different network segments, then .Sy delta -will be selected; the weighting value is ignored. The weighting has effect only -when selecting between servers with the same network proximity. The automounter -always selects the localhost over other servers on the same network segment, -regardless of weighting. +will be selected; the weighting value is ignored. +The weighting has effect only when selecting between servers with the same +network proximity. +The automounter always selects the localhost over other servers on the same +network segment, regardless of weighting. .Pp In cases where each server has a different export point, the weighting can -still be applied. For example: +still be applied. +For example: .Bd -literal -offset indent man -ro alpha:/usr/man bravo,charlie(1):/usr/share/man \e delta(3):/export/man @@ -292,7 +311,8 @@ The ampersand .Pq Qq Sy \*(Am character is expanded to the value of the .Ar key -field for the entry in which it occurs. In this case: +field for the entry in which it occurs. +In this case: .Bd -literal -offset indent jane sparcserver:/home/& .Ed @@ -306,9 +326,9 @@ The asterisk .Pq Qq Sy * character, when supplied as the .Ar key -field, is recognized as the catch-all entry. Such an entry will match any key -not previously matched. For instance, if the following entry appeared in the -indirect map for +field, is recognized as the catch-all entry. +Such an entry will match any key not previously matched. +For instance, if the following entry appeared in the indirect map for .Pa /config : .Bd -literal -offset indent * &:/export/config/& @@ -327,12 +347,13 @@ option. .Ss Variable Substitution Client specific variables can be used within an .Nm -map. For instance, if +map. +For instance, if .Sy $HOST appeared within a map, .Nm -would expand it to its current value for the client's host name. Supported -variables are: +would expand it to its current value for the client's host name. +Supported variables are: .Bl -column "PLATFORM" "arch -k or uname -m" .It Sy NAME Ta Sy OUTPUT OF Ta Sy DESCRIPTION (EXAMPLE) .It Ev ARCH @@ -385,8 +406,8 @@ A multiple mount entry takes the form: .Pp The initial .Ar mountpoint -is optional for the first mount and mandatory for all subsequent mounts. The -optional +is optional for the first mount and mandatory for all subsequent mounts. +The optional .Ar mountpoint is taken as a pathname relative to the directory named by .Ar key . @@ -422,15 +443,16 @@ or .Sy svr2 , whichever host is nearest and responds first. .Ss Other File System Types -The automounter assumes NFS mounts as a default file system type. Other file -system types can be described using the +The automounter assumes NFS mounts as a default file system type. +Other file system types can be described using the .Sy fstype -mount option. Other mount options specific to this file system type can be -combined with the +mount option. +Other mount options specific to this file system type can be combined with the .Sy fstype -option. The location field must contain information specific to the file system -type. If the location field begins with a slash, a colon character must be -prepended, for instance, to mount a CD file system: +option. +The location field must contain information specific to the file system type. +If the location field begins with a slash, a colon character must be prepended, +for instance, to mount a CD file system: .Bd -literal -offset indent cdrom -fstype=hsfs,ro :/dev/sr0 .Ed @@ -451,23 +473,26 @@ section for information on option inheritance. An indirect map allows you to specify mappings for the subdirectories you wish to mount under the .Ar directory -indicated on the command line. In an indirect map, each +indicated on the command line. +In an indirect map, each .Ar key consists of a simple name that refers to one or more file systems that are to be mounted as needed. .Ss Direct Maps Entries in a direct map are associated directly with .Nm autofs -mount points. Each +mount points. +Each .Ar key is the full pathname of an .Nm autofs -mount point. The direct map as a whole is not associated with any single -directory. +mount point. +The direct map as a whole is not associated with any single directory. .Pp Direct maps are distinguished from indirect maps by the .Sy \- -key. For example: +key. +For example: .Bd -literal -offset indent # Master map for automounter # @@ -509,10 +534,12 @@ The .Sy -hosts map is used with the .Pa /net -directory and assumes that the map key is the hostname of an NFS server. The +directory and assumes that the map key is the hostname of an NFS server. +The .Nm automountd daemon dynamically constructs a map entry from the server's list of exported -file systems. References to a directory under +file systems. +References to a directory under .Pa /net/hermes will refer to the corresponding directory relative to .Sy hermes @@ -520,26 +547,29 @@ root. .Pp The .Sy -null -map cancels a previous map for the directory indicated. This is most useful in -the +map cancels a previous map for the directory indicated. +This is most useful in the .Pa /etc/auto_master for cancelling entries that would otherwise be inherited from the .Sy +auto_master -include entry. To be effective, the +include entry. +To be effective, the .Sy -null entries must be inserted before the included map entry. .Ss Executable Maps Local maps that have the execute bit set in their file permissions will be executed by the automounter and provided with a key to be looked up as an -argument. The executable map is expected to return the content of an -automounter map entry on its stdout or no output if the entry cannot be -determined. A direct map cannot be made executable. +argument. +The executable map is expected to return the content of an automounter map entry +on its stdout or no output if the entry cannot be determined. +A direct map cannot be made executable. .Ss Configuration and the auto_master Map When initiated without arguments, .Nm consults the master map for a list of .Nm autofs -mount points and their maps. It mounts any +mount points and their maps. +It mounts any .Nm autofs mounts that are not already mounted, and unmounts .Nm autofs @@ -547,18 +577,21 @@ mounts that have been removed from the master map or direct map. .Pp The master map is assumed to be called .Sy auto_master -and its location is determined by the name service switch policy. Normally the -master map is located initially as a local file +and its location is determined by the name service switch policy. +Normally the master map is located initially as a local file .Pa /etc/auto_master . .Ss Browsing The .Nm automountd -daemon supports browsability of indirect maps. This allows all of the potential -mount points to be visible, whether or not they are mounted. The +daemon supports browsability of indirect maps. +This allows all of the potential mount points to be visible, whether or not they +are mounted. +The .Sy -nobrowse option can be added to any indirect .Nm autofs -map to disable browsing. For example: +map to disable browsing. +For example: .Bd -literal -offset indent /net -hosts -nosuid,nobrowse /home auto_home @@ -574,21 +607,23 @@ The .Sy -browse option enables browsability of .Nm autofs -file systems. This is the default for all indirect maps. +file systems. +This is the default for all indirect maps. .Pp The .Sy -browse option does not work in conjunction with the wildcard key. .Ss Restricting Mount Maps Options specified for a map are used as the default options for all the entries -in that map. They are ignored when map entries specify their own mount options. +in that map. +They are ignored when map entries specify their own mount options. .Pp In some cases, however, it is desirable to force .Sy nosuid , nodevices , nosetuid , or .Sy noexec -for a complete mount map and its submounts. This can be done by specifying the -additional mount option, +for a complete mount map and its submounts. +This can be done by specifying the additional mount option, .Sy -restrict . .Bd -literal -offset indent /home auto_home -restrict,nosuid,hard @@ -600,13 +635,15 @@ option forces the inheritance of all the restrictive options .Sy nosuid , nodevices , nosetuid , and .Sy noexec -as well as the restrict option itself. In this particular example, the +as well as the restrict option itself. +In this particular example, the .Sy nosuid and .Sy restrict option are inherited but the .Sy hard -option is not. The +option is not. +The .Sy restrict option also prevents the execution of .Qq executable maps @@ -619,7 +656,8 @@ Master automount map. .It Pa /etc/auto_home Map to support automounted home directories. .It Pa /etc/nsswitch.conf -Name service switch configuration file. See +Name service switch configuration file. +See .Xr nsswitch.conf 4 . .El .Sh EXIT STATUS @@ -651,15 +689,16 @@ Since each direct map entry results in a new .Nm autofs mount such maps should be kept short. .Pp -Entries in both direct and indirect maps can be modified at any time. The new -information is used when +Entries in both direct and indirect maps can be modified at any time. +The new information is used when .Nm automountd next uses the map entry to do a mount. .Pp New entries added to a master map or direct map will not be useful until the automount command is run to install them as new .Nm autofs -mount points. New entries added to an indirect map may be used immediately. +mount points. +New entries added to an indirect map may be used immediately. .Pp As of the Solaris 2.6 release, a listing .Po see @@ -668,19 +707,22 @@ As of the Solaris 2.6 release, a listing of the .Nm autofs directory associated with an indirect map shows all potential mountable -entries. The attributes associated with the potential mountable entries are -temporary. The real file system attributes will only be shown once the file -system has been mounted. +entries. +The attributes associated with the potential mountable entries are temporary. +The real file system attributes will only be shown once the file system has been +mounted. .Pp Default mount options can be assigned to an entire map when specified as an -optional third field in the master map. These options apply only to map entries -that have no mount options. Note that map entities with options override the -default options, as at this time, the options do not concatenate. The -concatenation feature is planned for a future release. +optional third field in the master map. +These options apply only to map entries that have no mount options. +Note that map entities with options override the default options, as at this +time, the options do not concatenate. +The concatenation feature is planned for a future release. .Pp When operating on a map that invokes an NFS mount, the default number of retries for the automounter is 0, that is, a single mount attempt, with no -retries. Note that this is significantly different from the default +retries. +Note that this is significantly different from the default .Pq 10000 for the .Xr mount_nfs 1M diff --git a/usr/src/man/man1m/automountd.1m b/usr/src/man/man1m/automountd.1m index 65f59d37b6..033bc50875 100644 --- a/usr/src/man/man1m/automountd.1m +++ b/usr/src/man/man1m/automountd.1m @@ -33,8 +33,9 @@ .Nm is an RPC server that answers file system mount and unmount requests from the .Nm autofs -file system. It uses local files or name service maps to locate file systems to -be mounted. These maps are described with the +file system. +It uses local files or name service maps to locate file systems to be mounted. +These maps are described with the .Xr automount 1M command. .Pp @@ -59,20 +60,23 @@ Assign .Ar value to the indicated .Nm automount -map substitution variable. These assignments cannot be used to substitute -variables in the master map +map substitution variable. +These assignments cannot be used to substitute variables in the master map .Sy auto_master . .It Fl n Turn off browsing for all .Nm autofs -mount points. This option overrides the +mount points. +This option overrides the .Sy -browse .Nm autofs map option on the local host. .It Fl T -Trace. Expand each RPC call and display it on the standard output. +Trace. +Expand each RPC call and display it on the standard output. .It Fl v -Verbose. Log status messages to the console. +Verbose. +Log status messages to the console. .El .Sh USAGE See diff --git a/usr/src/man/man1m/catman.1m b/usr/src/man/man1m/catman.1m index 5a79706553..9a49874838 100644 --- a/usr/src/man/man1m/catman.1m +++ b/usr/src/man/man1m/catman.1m @@ -32,8 +32,8 @@ database files suitable for use with .Xr apropos 1 and .Xr whatis 1 . -It is supplied for compatibility reasons. The same databases can -be generated using the +It is supplied for compatibility reasons. +The same databases can be generated using the .Fl w option with .Xr man 1 , diff --git a/usr/src/man/man1m/diskinfo.1m b/usr/src/man/man1m/diskinfo.1m index 867592fef9..8218c7f1ad 100644 --- a/usr/src/man/man1m/diskinfo.1m +++ b/usr/src/man/man1m/diskinfo.1m @@ -47,8 +47,8 @@ option selects physical mode. In this mode, each line of output likewise describes one disk device; however, the fields provided indicate the base name of the device in the .Pa /dev/dsk -directory, the disk's vendor and product identification strings, the serial number of the -device, whether the device is faulty as diagnosed by +directory, the disk's vendor and product identification strings, the serial +number of the device, whether the device is faulty as diagnosed by .Xr fmd 1M , whether the locate or identification indicator is on for the device .Pq if one is present , @@ -156,8 +156,8 @@ that report themselves as removable will be identified as such. .Pp This field is available only in default output mode. .It Sy SERIAL -The serial number of the device. The entire serial number is reported if the -device and its drivers provide it. +The serial number of the device. +The entire serial number is reported if the device and its drivers provide it. .Pp This field is available in compact and physical output modes. .It Sy SIZE diff --git a/usr/src/man/man1m/dns-sd.1m b/usr/src/man/man1m/dns-sd.1m index 5fa529bfcc..df37743662 100644 --- a/usr/src/man/man1m/dns-sd.1m +++ b/usr/src/man/man1m/dns-sd.1m @@ -79,18 +79,18 @@ The .Nm command is primarily intended for interactive use. Because its command-line arguments and output format are subject to change, -invoking it from a shell script will generally be fragile. Additionally, -the asynchronous nature of DNS Service Discovery does -not lend itself easily to script-oriented programming. For example, -calls like "browse" never complete; the action of performing a "browse" -sets in motion machinery to notify the client whenever instances of -that service type appear or disappear from the network. These -notifications continue to be delivered indefinitely, for minutes, +invoking it from a shell script will generally be fragile. +Additionally, the asynchronous nature of DNS Service Discovery does +not lend itself easily to script-oriented programming. +For example, calls like "browse" never complete; the action of performing a +"browse" sets in motion machinery to notify the client whenever instances of +that service type appear or disappear from the network. +These notifications continue to be delivered indefinitely, for minutes, hours, or even days, as services come and go, until the client -explicitly terminates the call. This style of asynchronous interaction -works best with applications that are either multi-threaded, or use a -main event-handling loop to receive keystrokes, network data, and other -asynchronous event notifications as they happen. +explicitly terminates the call. +This style of asynchronous interaction works best with applications that are +either multi-threaded, or use a main event-handling loop to receive keystrokes, +network data, and other asynchronous event notifications as they happen. .br If you wish to perform DNS Service Discovery operations from a scripting language, then the best way to do this is not to execute the @@ -109,7 +109,8 @@ return a list of domains recommended for registering(advertising) services. .It Nm Fl F return a list of domains recommended for browsing services. .Pp -Normally, on your home network, the only domain you are likely to see is "local". +Normally, on your home network, the only domain you are likely to see is +"local". However if your network administrator has created Domain Enumeration records, then you may also see other recommended domains for registering and browsing. .It Nm Fl R Ar name type domain port Op Ar key=value ... @@ -134,8 +135,10 @@ must be of the form "_app-proto._tcp" or "_app-proto._udp", where .Ar domain is the domain in which to register the service. In current implementations, only the local multicast domain "local" is -supported. In the future, registering will be supported in any arbitrary -domain that has a working DNS Update server [RFC 2136]. The +supported. +In the future, registering will be supported in any arbitrary domain that has a +working DNS Update server [RFC 2136]. +The .Ar domain "." is a synonym for "pick a sensible default" which today means "local". @@ -146,8 +149,8 @@ which the service is listening. .Pp Additional attributes of the service may optionally be described by key/value pairs, which are stored in the advertised service's DNS TXT -record. Allowable keys and values are listed with the service -registration at +record. +Allowable keys and values are listed with the service registration at .Pa http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml . .It Nm Fl B Ar type domain browse for instances of service @@ -159,7 +162,8 @@ For valid .Ar type Ns s see .Pa http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml . -as described above. Omitting the +as described above. +Omitting the .Ar domain or using "." means "pick a sensible default." .It Nm Fl L Ar name type domain @@ -168,32 +172,36 @@ named service: the hostname of the machine where that service is available, the port number on which the service is listening, and (if present) TXT record attributes describing properties of the service. .Pp -Note that in a typical application, browsing may only happen rarely, while lookup -(or "resolving") happens every time the service is used. For example, a -user browses the network to pick a default printer fairly rarely, but once -a default printer has been picked, that named service is resolved to its -current IP address and port number every time the user presses Cmd-P to +Note that in a typical application, browsing may only happen rarely, while +lookup (or "resolving") happens every time the service is used. +For example, a user browses the network to pick a default printer fairly rarely, +but once a default printer has been picked, that named service is resolved to +its current IP address and port number every time the user presses Cmd-P to print. .It Nm Fl P Ar name type domain port host IP Op Ar key=value ... -create a proxy advertisement for a service running on(offered by) some other machine. +create a proxy advertisement for a service running on(offered by) some other +machine. The two new options are Host, a name for the device and IP, the address of it. .Pp -The service for which you create a proxy advertisement does not necessarily have to be on your local network. +The service for which you create a proxy advertisement does not necessarily have +to be on your local network. You can set up a local proxy for a website on the Internet. .It Nm Fl q Ar name rrtype rrclass look up any DNS name, resource record type, and resource record class, not necessarily DNS-SD names and record types. If rrtype is not specified, it queries for the IPv4 address of the name, -if rrclass is not specified, IN class is assumed. If the name is not a fully -qualified domain name, then search domains may be appended. +if rrclass is not specified, IN class is assumed. +If the name is not a fully qualified domain name, then search domains may be +appended. .It Nm Fl Z Ar type domain browse for service instances and display output in zone file format. .It Nm Fl G Ns \ v4/v6/v4v6 Ar name look up the IP address information of the name. If v4 is specified, the IPv4 address of the name is looked up, -if v6 is specified the IPv6 address is looked up. If v4v6 is specified both the IPv4 and IPv6 -address is looked up. If the name is not a fully qualified domain name, -then search domains may be appended. +if v6 is specified the IPv6 address is looked up. +If v4v6 is specified both the IPv4 and IPv6 address is looked up. +If the name is not a fully qualified domain name, then search domains may be +appended. .It Nm Fl V return the version of the currently running daemon/system service. .El @@ -208,9 +216,9 @@ and other DNS-SD compatible printing clients, use: .Dl Nm Fl R Ns \ \&"My Test\&" _printer._tcp. \&. 515 pdl=application/postscript .Pp For this registration to be useful, you need to actually have LPR service -available on port 515. Advertising a service that does not exist is not -very useful, and will be confusing and annoying to other people on the -network. +available on port 515. +Advertising a service that does not exist is not very useful, and will be +confusing and annoying to other people on the network. .Pp Similarly, to advertise a web page being served by an HTTP server on port 80 on this machine, such that it will show up in the @@ -228,21 +236,23 @@ While that command is running, in another window, try the example given above to advertise a web page, and you should see the "Add" event reported to the .Nm Fl B -window. Now press Ctrl-C in the +window. +Now press Ctrl-C in the .Nm Fl R window and you should see the "Remove" event reported to the .Nm Fl B window. .Pp -In the example below, the www.apple.com web page is advertised as a service called "apple", +In the example below, the www.apple.com web page is advertised as a service +called "apple", running on a target host called apple.local, which resolves to 17.149.160.49. .Pp .Dl Nm Fl P Ns \ apple _http._tcp \&"\&"\& 80 apple.local 17.149.160.49 .Pp The Bonjour menu in the Safari web browser will now show "apple". The same IP address can be reached by entering apple.local in the web browser. -In either case, the request will be resolved to the IP address and browser will show -contents associated with www.apple.com. +In either case, the request will be resolved to the IP address and browser will +show contents associated with www.apple.com. .Pp If a client wants to be notified of changes in server state, it can initiate a query for the service's particular record and leave it running. @@ -250,7 +260,8 @@ For example, to monitor the status of an iChat user you can use: .Pp .Dl Nm Fl q Ns \ someone@ex1._presence._tcp.local txt .Pp -Everytime status of that user(someone) changes, you will see a new TXT record result reported. +Everytime status of that user(someone) changes, you will see a new TXT record +result reported. .Pp You can also query for a unicast name like www.apple.com and monitor its status. .Pp diff --git a/usr/src/man/man1m/installboot.1m b/usr/src/man/man1m/installboot.1m index d17d800f2f..0c1dd82c76 100644 --- a/usr/src/man/man1m/installboot.1m +++ b/usr/src/man/man1m/installboot.1m @@ -54,8 +54,9 @@ boot program is loaded from disk and is responsible of loading kernel and its support files from specific file system. .Pp The SPARC systems have one boot loader program file to be installed on the boot -area of a disk slice. As the SPARC zfs boot loader is too large to fit into -boot area at the start of the disk slice, +area of a disk slice. +As the SPARC zfs boot loader is too large to fit into boot area at the start of +the disk slice, .Nm command will split the zfs boot loader between disk slice boot area, and zfs pool boot area. @@ -69,7 +70,8 @@ is used as master boot record and partition boot program. .It Sy stage2 .Pa /boot/gptzfsboot -is responsible for loading files from file system. The +is responsible for loading files from file system. +The .Sy stage2 on x86 systems is always installed to zfs pool boot area, and therefore only zfs boot is supported. @@ -99,8 +101,9 @@ and starting the operating system kernel. In case of GPT partitioning scheme, if the file system to boot from is either UFS or PCFS, there must be .Sy boot -partition defined to store stage2 boot program. This is needed because UFS and -PCFS do not have sufficient space reserved to store boot programs. +partition defined to store stage2 boot program. +This is needed because UFS and PCFS do not have sufficient space reserved to +store boot programs. .Pp The boot partition must use following GPT UUID: .Bd -literal -offset indent @@ -123,19 +126,22 @@ Prints short usage message. .It Fl m Installs .Sy stage1 -on the master boot sector interactively. You must use this option if OS is -installed on an extended FDISK or an EFI/GPT partition. +on the master boot sector interactively. +You must use this option if OS is installed on an extended FDISK or an EFI/GPT +partition. .It Fl f Suppresses interaction when overwriting the master boot sector on x86. Force update on SPARC. .It Fl n -Dry run session. Will not write to disk. +Dry run session. +Will not write to disk. .It Fl F -On SPARC, specify file system type. On x86, inhibit version check and enforce -boot loader update. +On SPARC, specify file system type. +On x86, inhibit version check and enforce boot loader update. .It Fl u Ar verstr -Specify custom version string. Can be used to add version on non-versioned -boot loader or change built in version string. +Specify custom version string. +Can be used to add version on non-versioned boot loader or change built in +version string. .It Fl i Print version string from installed boot loader or from indicated file. .It Fl e @@ -157,8 +163,9 @@ The name of the loader stage 1 file. .It Ar stage2 The name of the loader stage 2 file. .It Ar raw-device -The name of the device onto which bootloader code is to be installed. It must be -a character device that is readable and writable and part of boot pool. +The name of the device onto which bootloader code is to be installed. +It must be a character device that is readable and writable and part of boot +pool. .El .Sh FILES .Bl -tag -width Ds @@ -199,11 +206,11 @@ on the master boot sector .Fl m option .Pc -overrides any boot loader currently installed on the machine. The system will -always boot the current OS partition regardless of which fdisk partition is -active. +overrides any boot loader currently installed on the machine. +The system will always boot the current OS partition regardless of which fdisk +partition is active. .Pp If version string indicates the source boot loader might be more recent, .Nm -will also verify md5 checksums to determine if update is really necessary. If -checksums match, the install will not be performed. +will also verify md5 checksums to determine if update is really necessary. +If checksums match, the install will not be performed. diff --git a/usr/src/man/man1m/ipadm.1m b/usr/src/man/man1m/ipadm.1m index 06e5f87cc2..dc3ea104c9 100644 --- a/usr/src/man/man1m/ipadm.1m +++ b/usr/src/man/man1m/ipadm.1m @@ -145,19 +145,22 @@ command is a stable replacement for the .Xr ifconfig 1M and .Xr ndd 1M -commands. It is used to create IP interfaces and to configure IP addresses on -those interfaces. It is also used to get, set or reset properties on interfaces, -addresses and protocols. +commands. +It is used to create IP interfaces and to configure IP addresses on those +interfaces. +It is also used to get, set or reset properties on interfaces, addresses and +protocols. .Pp For subcommands that take an .Em addrobj , the .Em addrobj -specifies a unique address on the system. It is made up of two parts, delimited -by a +specifies a unique address on the system. +It is made up of two parts, delimited by a .Sq / . The first part is the name of the interface and the second part is a string up -to 32 characters long. For example, +to 32 characters long. +For example, .Qq lo0/v4 is a loopback interface .Em addrobj @@ -183,9 +186,10 @@ The following subcommands are supported: .Op Fl t .Ar interface .Xc -Create an IP interface that will handle both IPv4 and IPv6 packets. The -interface will be enabled as part of the creation process. The IPv4 interface -will have the address 0.0.0.0. The IPv6 interface will have the address ::. +Create an IP interface that will handle both IPv4 and IPv6 packets. +The interface will be enabled as part of the creation process. +The IPv4 interface will have the address 0.0.0.0. +The IPv6 interface will have the address ::. .Bl -tag -width "" .It Fl t Ns , Ns Fl -temporary Temporary, not persistent across reboots. @@ -227,8 +231,8 @@ Permanently delete an IP interface. Show the current IP interface configuration. .Bl -tag -width "" .It Fl o Ns , Ns Fl -output -Select which fields will be shown. The field value can be one of the following -names: +Select which fields will be shown. +The field value can be one of the following names: .Bl -tag -compact -width "PERSISTENT" .It Cm ALL Display all fields. @@ -304,8 +308,8 @@ Set a property's value(s) on the IP interface. .It Fl m Ns , Ns Fl -module Specify which protocol the setting applies to. .It Fl p Ns , Ns Fl -prop -Specify the property name and value(s). The property name can be one of the -following: +Specify the property name and value(s). +The property name can be one of the following: .Bl -tag -compact -width "exchange_routes" .It Cm arp Address resolution protocol @@ -317,15 +321,16 @@ Exchange of routing data IP Forwarding .Pq Cm on Ns / Ns Cm off .It Cm metric -Set the routing metric to the numeric value. The value is treated as extra -hops to the destination. +Set the routing metric to the numeric value. +The value is treated as extra hops to the destination. .It Cm mtu Set the maximum transmission unit to the numeric value. .It Cm nud Neighbor unreachability detection .Pq Cm on Ns / Ns Cm off .It Cm usesrc -Indicates which interface to use for source address selection. A value +Indicates which interface to use for source address selection. +A value .Cm none may also be used. .El @@ -345,7 +350,8 @@ Reset an IP interface's property value to the default. .It Fl m Ns , Ns Fl -module Specify which protocol the setting applies to. .It Fl p Ns , Ns Fl -prop -Specify the property name. See the +Specify the property name. +See the .Nm ipadm Ic set-ifprop subcommand for the list of property names. .It Fl t Ns , Ns Fl -temporary @@ -366,8 +372,8 @@ Print the output in a parsable format. .It Fl m Ns , Ns Fl -module Specify which protocol to display. .It Fl o Ns , Ns Fl -output -Select which fields will be shown. The field value can be one of the following -names: +Select which fields will be shown. +The field value can be one of the following names: .Bl -tag -compact -width "PERSISTENT" .It Cm ALL Display all fields. @@ -392,7 +398,8 @@ The default value of the property. The possible values for the property. .El .It Fl p Ns , Ns Fl -prop -Specify which properties to display. See the +Specify which properties to display. +See the .Nm ipadm Ic set-ifprop subcommand for the list of property names. .El @@ -422,28 +429,32 @@ subcommand for the list of property names. .Bro Cm yes Ns | Ns Cm no Brc Oc Ns ... .Ar addrobj .Xc -Create an address on an IP interface. The address will be enabled but can -disabled using the +Create an address on an IP interface. +The address will be enabled but can disabled using the .Nm ipadm Ic disable-addr -subcommand. This subcommand has three different forms, depending on the -value of the +subcommand. +This subcommand has three different forms, depending on the value of the .Fl T option. .Bl -tag -width "" .It Fl T Cm static -Create a static addrobj. Note that +Create a static addrobj. +Note that .Cm addrconf address configured on an interface is required to configure .Cm static -IPv6 address on the same interface. This takes the following options: +IPv6 address on the same interface. +This takes the following options: .Bl -tag -width "" .It Fl a Ns , Ns Fl -address -Specify the address. The +Specify the address. +The .Cm local or .Cm remote -prefix can be used for a point-to-point interface. In this case, both addresses -must be given. Otherwise, the equal sign +prefix can be used for a point-to-point interface. +In this case, both addresses must be given. +Otherwise, the equal sign .Pq Qq = should be omitted and the address should be provided by itself without second address. @@ -451,13 +462,15 @@ address. The address is down. .El .It Fl T Cm dhcp -Obtain the address via DHCP. This takes the following options: +Obtain the address via DHCP. +This takes the following options: .Bl -tag -width "" .It Fl w Ns , Ns Fl -wait Specify the time, in seconds, that the command should wait to obtain an address. .El .It Fl T Cm addrconf -Create an auto-configured address. This takes the following options: +Create an auto-configured address. +This takes the following options: .Bl -tag -width "" .It Fl i Ns , Ns Fl -interface-id Specify the interface ID to be used. @@ -473,7 +486,8 @@ Temporary, not persistent across reboots. .Op Fl t .Ar addrobj .Xc -Down the address. This will stop packets from being sent or received. +Down the address. +This will stop packets from being sent or received. .Bl -tag -width "" .It Fl t Ns , Ns Fl -temporary Temporary, not persistent across reboots. @@ -484,7 +498,8 @@ Temporary, not persistent across reboots. .Op Fl t .Ar addrobj .Xc -Up the address. This will enable packets to be sent and received. +Up the address. +This will enable packets to be sent and received. .Bl -tag -width "" .It Fl t Ns , Ns Fl -temporary Temporary, not persistent across reboots. @@ -519,8 +534,8 @@ Temporary, not persistent across reboots. .Xc Extend the lease for .Sy DHCP -addresses. It also restarts duplicate address -detection for +addresses. +It also restarts duplicate address detection for .Cm static addresses. .Bl -tag -width "" @@ -547,8 +562,8 @@ Indicate that the DHCP-assigned address should be released. Show the current address properties. .Bl -tag -width "" .It Fl o Ns , Ns Fl -output -Select which fields will be shown. The field value can be one of the following -names: +Select which fields will be shown. +The field value can be one of the following names: .Bl -tag -compact -width "PERSISTENT" .It Cm ALL Display all fields. @@ -558,7 +573,8 @@ The name of the address. The type of the address .Pq Sy static Ns / Ns Sy dhcp Ns / Ns Sy addrconf . .It Cm STATE -The state of the address. It can be one of the following values: +The state of the address. +It can be one of the following values: .Bl -tag -compact -width "inaccessible" .It Sy disabled see the @@ -621,8 +637,8 @@ Print the output in a parsable format. Set a property's value(s) on the addrobj. .Bl -tag -width "" .It Fl p Ns , Ns Fl -prop -Specify the property name and value(s). The property name can be one of the -following: +Specify the property name and value(s). +The property name can be one of the following: .Bl -tag -compact -width "deprecated" .It Cm broadcast The broadcast address (read-only). @@ -653,7 +669,8 @@ Temporary, not persistent across reboots. Reset an addrobj's property value to the default. .Bl -tag -width "" .It Fl p Ns , Ns Fl -prop -Specify the property name. See the +Specify the property name. +See the .Nm ipadm Ic set-addrprop subcommand for the list of property names. .It Fl t Ns , Ns Fl -temporary @@ -671,8 +688,8 @@ Display the property values for one or all of the addrobjs. .It Fl c Ns , Ns Fl -parsable Print the output in a parsable format. .It Fl o Ns , Ns Fl -output -Select which fields will be shown. The field value can be one of the following -names: +Select which fields will be shown. +The field value can be one of the following names: .Bl -tag -compact -width "PERSISTENT" .It Cm ALL Display all fields. @@ -695,7 +712,8 @@ The default value of the property. The possible values for the property. .El .It Fl p Ns , Ns Fl -prop -Specify which properties to display. See the +Specify which properties to display. +See the .Nm ipadm Ic set-addrprop subcommand for the list of property names. .El @@ -709,10 +727,12 @@ subcommand for the list of property names. Set a property's value(s) on the protocol. .Bl -tag -width "" .It Fl p Ns , Ns Fl -prop -Specify the property name and value(s). The optional +Specify the property name and value(s). +The optional .Sy + Ns | Ns Sy - syntax can be used to add/remove values from the current list of values on the -property. The property name can be one of the following: +property. +The property name can be one of the following: .Bl -tag -compact -width "smallest_nonpriv_port" .It Cm ecn Explicit congestion control @@ -775,7 +795,8 @@ Temporary, not persistent across reboots. Reset a protocol's property value to the default. .Bl -tag -width "" .It Fl p Ns , Ns Fl -prop -Specify the property name. See the +Specify the property name. +See the .Nm ipadm Ic set-prop subcommand for the list of property names. .It Fl t Ns , Ns Fl -temporary @@ -793,8 +814,8 @@ Display the property values for one or all of the protocols. .It Fl c Ns , Ns Fl -parsable Print the output in a parsable format. .It Fl o Ns , Ns Fl -output -Select which fields will be shown. The field value can be one of the following -names: +Select which fields will be shown. +The field value can be one of the following names: .Bl -tag -compact -width "PERSISTENT" .It Cm ALL Display all fields. @@ -817,7 +838,8 @@ The default value of the property. The possible values for the property. .El .It Fl p Ns , Ns Fl -prop -Specify which properties to display. See the +Specify which properties to display. +See the .Nm ipadm Ic set-prop subcommand for the list of property names. .El diff --git a/usr/src/man/man1m/lofiadm.1m b/usr/src/man/man1m/lofiadm.1m index 5eede96b52..750e2c732a 100644 --- a/usr/src/man/man1m/lofiadm.1m +++ b/usr/src/man/man1m/lofiadm.1m @@ -59,12 +59,14 @@ administers .Sy lofi , the loopback file driver. .Sy lofi -allows a file to be associated with a block device. That file can then be -accessed through the block device. This is useful when the file contains an -image of some filesystem (such as a floppy or +allows a file to be associated with a block device. +That file can then be accessed through the block device. +This is useful when the file contains an image of some filesystem (such as a +floppy or .Sy CD-ROM image), because the block device can then be used with the normal system -utilities for mounting, checking or repairing filesystems. See +utilities for mounting, checking or repairing filesystems. +See .Xr fsck 1M and .Xr mount 1M . @@ -98,16 +100,19 @@ partitioning by using partition management tools such as .Xr fdisk 1M . Once the device has been appropriately partitioned, the labeled device can be used as normal disk to create and mount file systems and to store -data. Mappings created by +data. +Mappings created by .Nm -are not permanent and not persisted by the system. If power is lost or the system -is rebooted, then the mappings will need to be created again. +are not permanent and not persisted by the system. +If power is lost or the system is rebooted, then the mappings will need to be +created again. .Pp The partition table requires space from the mapped file. .Sy lofi does not support converting previously created unlabeled loopback device images -to labeled loopback devices. If an unlabeled device is used as a labeled device, -writing to it will corrupt it. +to labeled loopback devices. +If an unlabeled device is used as a labeled device, writing to it will corrupt +it. .Sh OPTIONS The following options are supported: .Bl -tag -width Ds @@ -129,8 +134,9 @@ attempts to assign it to .Sy device must be available or .Nm -will fail. The ability to specify a device is provided for use in scripts that -wish to reestablish a particular set of associations. +will fail. +The ability to specify a device is provided for use in scripts that wish to +reestablish a particular set of associations. A device may not be specified when using a labeled lofi device. .It Fl C Ar {gzip | gzip-N | lzma} Compress the file with the specified compression algorithm. @@ -139,10 +145,12 @@ The .Sy gzip compression algorithm uses the same compression as the open-source .Sy gzip -command. You can specify the +command. +You can specify the .Sy gzip level by using the value gzip-\fR\fIN\fR where \fIN\fR is 6 (fast) or 9 -(best compression ratio). Currently, +(best compression ratio). +Currently, .Sy gzip , without a number, is equivalent to .Sy gzip-6 @@ -165,8 +173,8 @@ device. .It Fl l This option should be used with .Fl a -option to create labeled loopback device. If created in local zone, the device -has to be enabled in zone configuration. +option to create labeled loopback device. +If created in local zone, the device has to be enabled in zone configuration. .It Fl r If the .Fl r @@ -186,8 +194,9 @@ Uncompress a compressed file. The following options are used when the file is encrypted: .Bl -tag -width Ds .It Fl c Ar crypto_algorithm -Select the encryption algorithm. The algorithm must be specified when -encryption is enabled because the algorithm is not stored in the disk image. +Select the encryption algorithm. +The algorithm must be specified when encryption is enabled because the algorithm +is not stored in the disk image. .Pp If none of .Fl e , @@ -200,10 +209,11 @@ prompts for a passphrase, with a minimum length of eight characters, to be entered. The passphrase is used to derive a symmetric encryption key using PKCS#5 PBKD2. .It Fl k Ar raw_key_file | Ar wrapped_key_file -Path to raw or wrapped symmetric encryption key. If a PKCS#11 object is also -given with the +Path to raw or wrapped symmetric encryption key. +If a PKCS#11 object is also given with the .Fl T -option, then the key is wrapped by that object. If +option, then the key is wrapped by that object. +If .Fl T is not specified, the key is used raw. .It Fl T Ar token_key @@ -232,15 +242,15 @@ One of: Display the file name associated with the block device .Sy device . .Pp -Without arguments, print a list of the current associations. Filenames must be -valid absolute pathnames. +Without arguments, print a list of the current associations. +Filenames must be valid absolute pathnames. .Pp -When a file is added, it is opened for reading or writing by root. Any -restrictions apply (such as restricted root access over +When a file is added, it is opened for reading or writing by root. +Any restrictions apply (such as restricted root access over .Sy NFS Ns ). -The file is held open until the association is removed. It is not actually -accessed until the block device is used, so it will never be written to if the -block device is only opened read-only. +The file is held open until the association is removed. +It is not actually accessed until the block device is used, so it will never be +written to if the block device is only opened read-only. .Pp Note that the filename may appear as "?" if it is not possible to resolve the path in the current context (for example, if it's an NFS path in a non-global @@ -256,8 +266,8 @@ PKCS#11 token object in the format: .Pp .Ar token_name Ns : Ns Ar manufacturer_id Ns : Ns Ar serial_number Ns : Ns Ar key_label .Pp -All but the key label are optional and can be empty. For example, to specify a -token object with only its key label +All but the key label are optional and can be empty. +For example, to specify a token object with only its key label .Sy MylofiKey , use: .Pp @@ -300,8 +310,8 @@ image .Pf ( Sy sparc.iso Ns ), of the .Sy Red Hat 6.0 CD -which was downloaded from the Internet. It was created -with the +which was downloaded from the Internet. +It was created with the .Sy mkisofs utility from the Internet. .Pp @@ -315,7 +325,8 @@ to attach a block device to it: .Pp .Nm picks the device and prints the device name to the standard -output. You can run +output. +You can run .Nm again by issuing the following command: .Bd -literal @@ -352,8 +363,8 @@ README boot.cat* kernels/ modules/ RPM-PGP-KEY dev@ lib@ proc/ .Ed .Pp -Solaris can mount the CD-ROM image, and understand the filenames. The image was -created properly, and you can now create the +Solaris can mount the CD-ROM image, and understand the filenames. +The image was created properly, and you can now create the .Sy CD-ROM with confidence. .Pp @@ -371,8 +382,8 @@ Using .Sy lofi to help you mount files that contain floppy images is helpful if a floppy disk contains a file that you need, but the machine which you are -on does not have a floppy drive. It is also helpful if you do not want to take -the time to use the +on does not have a floppy drive. +It is also helpful if you do not want to take the time to use the .Sy dd command to copy the image to a floppy. .Pp @@ -394,8 +405,10 @@ APPEND.BAT* MAKEDIR.BAT* SOLARIS/ Making a .Sy UFS filesystem on a file can be useful, particularly if a test -suite requires a scratch filesystem. It can be painful (or annoying) to have to -repartition a disk just for the test suite, but you do not have to. You can +suite requires a scratch filesystem. +It can be painful (or annoying) to have to repartition a disk just for the test +suite, but you do not have to. +You can .Sy newfs a file with .Sy lofi . @@ -405,7 +418,8 @@ Create the file: # mkfile 35m /export/home/test .Ed .Pp -Attach it to a block device. You also get the character device that +Attach it to a block device. +You also get the character device that .Sy newfs requires, so .Sy newfs @@ -423,7 +437,8 @@ super-block backups (for fsck -F ufs -o b=#) at: .Pp Note that .Sy ufs -might not be able to use the entire file. Mount and use the filesystem: +might not be able to use the entire file. +Mount and use the filesystem: .Bd -literal # mount /dev/lofi/1 /mnt # df -k /mnt @@ -437,7 +452,8 @@ Filesystem kbytes used avail capacity Mounted on .It Sy Example 4 No Creating a PC (FAT) File System on a Unix File The following series of commands creates a .Sy FAT -file system on a Unix file. The file is associated with a block device created by +file system on a Unix file. +The file is associated with a block device created by .Nm . .Bd -literal @@ -575,8 +591,9 @@ Just as you would not directly access a disk device that has mounted file systems, you should not access a file associated with a block device except through the .Sy lofi -file driver. It might also be appropriate to ensure that -the file has appropriate permissions to prevent such access. +file driver. +It might also be appropriate to ensure that the file has appropriate permissions +to prevent such access. .Pp The abilities of .Nm @@ -584,8 +601,10 @@ The abilities of permissions of .Pa /dev/lofictl . Read-access allows query operations, such as -listing all the associations. Write-access is required to do any state-changing -operations, like adding an association. As shipped, +listing all the associations. +Write-access is required to do any state-changing operations, like adding an +association. +As shipped, .Pa /dev/lofictl is owned by .Sy root , @@ -603,15 +622,16 @@ In particular, the .Sy nosuid mount option might be appropriate for .Sy UFS -images whose origin is unknown. Also, some options might not be useful or -appropriate, like +images whose origin is unknown. +Also, some options might not be useful or appropriate, like .Sy logging or .Sy forcedirectio for .Sy UFS . For compatibility purposes, a raw device is also exported along with the block -device. For example, +device. +For example, .Xr newfs 1M requires one. .Pp diff --git a/usr/src/man/man1m/mount_nfs.1m b/usr/src/man/man1m/mount_nfs.1m index 7c26819813..4992fa1b7b 100644 --- a/usr/src/man/man1m/mount_nfs.1m +++ b/usr/src/man/man1m/mount_nfs.1m @@ -48,7 +48,8 @@ utility attaches a named .Ar resource to the file system hierarchy at the pathname location .Ar mount_point , -which must already exist. If +which must already exist. +If .Ar mount_point has any contents prior to the .Nm mount @@ -73,7 +74,8 @@ and .Nm mount consults .Pa /etc/vfstab -for more information. If the +for more information. +If the .Fl F option is omitted, .Nm mount @@ -88,12 +90,12 @@ and the .Ar mount_point . .Pp .Ar host -can be an IPv4 or IPv6 address string. As IPv6 addresses already contain colons, -enclose +can be an IPv4 or IPv6 address string. +As IPv6 addresses already contain colons, enclose .Ar host -in a pair of square brackets when specifying an IPv6 address string. Otherwise -the first occurrence of a colon can be interpreted as the separator between the -host name and path, for example, +in a pair of square brackets when specifying an IPv6 address string. +Otherwise the first occurrence of a colon can be interpreted as the separator +between the host name and path, for example, .Li [1080::8:800:200C:417A]:tmp/file . See .Xr inet 7P @@ -105,9 +107,10 @@ Where .Ar host is the name of the NFS server host, and .Ar pathname -is the path name of the directory on the server being mounted. The path name is -interpreted according to the server's path name parsing rules and is not -necessarily slash-separated, though on most servers, this is the case. +is the path name of the directory on the server being mounted. +The path name is interpreted according to the server's path name parsing rules +and is not necessarily slash-separated, though on most servers, this is the +case. .It No nfs:// Ns Ar host Ns Oo : Ns Ar port Oc Ns / Ns Ar pathname This is an NFS URL and follows the standard convention for NFS URLs as described in @@ -130,8 +133,8 @@ See the discussion of replicated file systems and failover under for a more detailed discussion. .It Ar hostlist pathname .Ar hostlist -is a comma-separated list of hosts. See the discussion of replicated file -systems and failover under +is a comma-separated list of hosts. +See the discussion of replicated file systems and failover under .Sx NFS FILE SYSTEMS for a more detailed discussion. .El @@ -144,7 +147,8 @@ described in .Xr mnttab 4 . .Pp .Nm mount_nfs -supports both NFSv3 and NFSv4 mounts. The default NFS version is NFSv4. +supports both NFSv3 and NFSv4 mounts. +The default NFS version is NFSv4. .Ss Options See .Xr mount 1M @@ -170,15 +174,18 @@ The default value is 60. .It Sy acdirmin Ns = Ns Ar n Hold cached attributes for at least .Ar n -seconds after directory update. The default value is 30. +seconds after directory update. +The default value is 30. .It Sy acregmax Ns = Ns Ar n Hold cached attributes for no more than .Ar n -seconds after file modification. The default value is 60. +seconds after file modification. +The default value is 60. .It Sy acregmin Ns = Ns Ar n Hold cached attributes for at least .Ar n -seconds after file modification. The default value is 3. +seconds after file modification. +The default value is 3. .It Sy actimeo Ns = Ns n Set .Sy min @@ -186,7 +193,8 @@ and .Sy max times for regular files and directories to .Ar n -seconds. See +seconds. +See .Sx File Attributes , below, for a description of the effect of setting this option to 0. .Pp @@ -200,22 +208,24 @@ are parsed on a .Nm mount command line. .It Sy bg Ns | Ns Sy fg -If the first attempt fails, retry in the background, or, in the foreground. The -default is +If the first attempt fails, retry in the background, or, in the foreground. +The default is .Sy fg . .It Sy forcedirectio Ns | Ns Sy noforcedirectio If .Sy forcedirectio -is specified, then for the duration of the mount, forced direct I/O is used. If -the filesystem is mounted using +is specified, then for the duration of the mount, forced direct I/O is used. +If the filesystem is mounted using .Sy forcedirectio , data is transferred directly between client and server, with no buffering on the -client. If the filesystem is mounted using +client. +If the filesystem is mounted using .Sy noforcedirectio , data is buffered on the client. .Sy forcedirectio is a performance option that is of benefit only in large sequential data -transfers. The default behavior is +transfers. +The default behavior is .Sy noforcedirectio . .It Sy grpid By default, the GID associated with a newly created file obeys the System V @@ -245,32 +255,37 @@ Note that NFSv4 clients do not support soft mounts. Allow .Pq do not allow keyboard interrupts to kill a process that is hung while waiting for a response -on a hard-mounted file system. The default is +on a hard-mounted file system. +The default is .Sy intr , which makes it possible for clients to interrupt applications that can be waiting for a remote mount. .It Sy noac -Suppress data and attribute caching. The data caching that is suppressed is the -write-behind. The local page cache is still maintained, but data copied into it -is immediately written to the server. +Suppress data and attribute caching. +The data caching that is suppressed is the write-behind. +The local page cache is still maintained, but data copied into it is immediately +written to the server. .It Sy nocto -Do not perform the normal close-to-open consistency. When a file is closed, all -modified data associated with the file is flushed to the server and not held on -the client. When a file is opened the client sends a request to the server to -validate the client's local caches. This behavior ensures a file's consistency -across multiple NFS clients. When +Do not perform the normal close-to-open consistency. +When a file is closed, all modified data associated with the file is flushed to +the server and not held on the client. +When a file is opened the client sends a request to the server to validate the +client's local caches. +This behavior ensures a file's consistency across multiple NFS clients. +When .Sy nocto is in effect, the client does not perform the flush on close and the request for validation, allowing the possibility of differences among copies of the same file as stored on multiple clients. .Pp This option can be used where it can be guaranteed that accesses to a specified -file system are made from only one client and only that client. Under such a -condition, the effect of +file system are made from only one client and only that client. +Under such a condition, the effect of .Sy nocto can be a slight performance gain. .It Sy port Ns = Ns Ar n -The server IP port number. The default is +The server IP port number. +The default is .Dv NFS_PORT . If the .Sy port @@ -278,20 +293,23 @@ option is specified, and if the resource includes one or more NFS URLs, and if any of the URLs include a port number, then the port number in the option and in the URL must be the same. .It Sy posix -Request POSIX.1 semantics for the file system. Requires a mount Version 2 +Request POSIX.1 semantics for the file system. +Requires a mount Version 2 .Xr mountd 1M -on the server. See +on the server. +See .Xr standards 5 for information regarding POSIX. .It Sy proto Ns = Ns Ar netid Ns | Ns Sy rdma By default, the transport protocol that the NFS mount uses is the first -available RDMA transport supported both by the client and the server. If no RDMA -transport is found, then it attempts to use a TCP transport or, failing that, a -UDP transport, as ordered in the +available RDMA transport supported both by the client and the server. +If no RDMA transport is found, then it attempts to use a TCP transport or, +failing that, a UDP transport, as ordered in the .Pa /etc/netconfig -file. If it does not find a connection oriented transport, it uses the first -available connectionless transport. Use this option to override the default -behavior. +file. +If it does not find a connection oriented transport, it uses the first available +connectionless transport. +Use this option to override the default behavior. .Pp .Sy proto is set to the value of @@ -305,16 +323,17 @@ field entry in the .Pa /etc/netconfig file. .Pp -The UDP protocol is not supported for NFS Version 4. If you specify a UDP -protocol with the +The UDP protocol is not supported for NFS Version 4. +If you specify a UDP protocol with the .Sy proto option, NFS version 4 is not used. .It Sy public The .Sy public option forces the use of the public file handle when connecting to the NFS -server. The resource specified might not have an NFS URL. See the discussion of -URLs and the public option under +server. +The resource specified might not have an NFS URL. +See the discussion of URLs and the public option under .Sx NFS FILE SYSTEMS for a more detailed discussion. .It Sy quota Ns | Ns Sy noquota @@ -341,29 +360,33 @@ assumed that the transport performs retransmissions on behalf of NFS. .It Sy retry Ns = Ns Ar n The number of times to retry the .Nm mount -operation. The default for the +operation. +The default for the .Nm mount command is 10000. .Pp -The default for the automounter is 0, in other words, do not retry. You might -find it useful to increase this value on heavily loaded servers, where +The default for the automounter is 0, in other words, do not retry. +You might find it useful to increase this value on heavily loaded servers, where automounter traffic is dropped, causing unnecessary .Qq server not responding errors. .It Sy rsize Ns = Ns Ar n Set the read buffer size to a maximum of .Ar n -bytes. The default value is 1048576 when using connection-oriented transports -with Version 3 or Version 4 of the NFS protocol, and 32768 when using -connection-less transports. The default can be negotiated down if the server -prefers a smaller transfer size. +bytes. +The default value is 1048576 when using connection-oriented transports with +Version 3 or Version 4 of the NFS protocol, and 32768 when using connection-less +transports. +The default can be negotiated down if the server prefers a smaller transfer +size. .Qq Read -operations may not necessarily use the maximum buffer size. When using Version -2, the default value is 32768 for all transports. +operations may not necessarily use the maximum buffer size. +When using Version 2, the default value is 32768 for all transports. .It Sy sec Ns = Ns Ar mode Set the security .Ar mode -for NFS transactions. If +for NFS transactions. +If .Sy sec Ns = is not specified, then the default action is to use AUTH_SYS over NFS Version 2 mounts, use a user-configured default @@ -375,19 +398,22 @@ The preferred mode for NFS Version 3 mounts is the default mode specified in .Po see .Xr nfssec.conf 4 .Pc -on the client. If there is no default configured in this file or if the server -does not export using the client's default mode, then the client picks the first -mode that it supports in the array of modes returned by the server. These -alternatives are limited to the security flavors listed in +on the client. +If there is no default configured in this file or if the server does not export +using the client's default mode, then the client picks the first mode that it +supports in the array of modes returned by the server. +These alternatives are limited to the security flavors listed in .Pa /etc/nfssec.conf . .Pp NFS Version 4 mounts negotiate a security mode when the server returns an array -of security modes. The client attempts the mount with each security mode, in -order, until one is successful. +of security modes. +The client attempts the mount with each security mode, in order, until one is +successful. .Pp Only one mode can be specified with the .Sy sec Ns = -option. See +option. +See .Xr nfssec 5 for the available .Ar mode @@ -399,30 +425,35 @@ option. .It Sy timeo Ns = Ns Ar n Set the NFS timeout to .Ar n -tenths of a second. The default value is 11 tenths of a second for -connectionless transports, and 600 tenths of a second for connection-oriented -transports. This value is ignored for connectionless transports. Such transports -might implement their own timeouts, which are outside the control of NFS. +tenths of a second. +The default value is 11 tenths of a second for connectionless transports, and +600 tenths of a second for connection-oriented transports. +This value is ignored for connectionless transports. +Such transports might implement their own timeouts, which are outside the +control of NFS. .It Sy vers Ns = Ns Ar "NFS version number" By default, the version of NFS protocol used between the client and the server -is the highest one available on both systems. If the NFS server does not support -the client's default maximum, the next lowest version attempted until a matching -version is found. See +is the highest one available on both systems. +If the NFS server does not support the client's default maximum, the next lowest +version attempted until a matching version is found. +See .Xr nfs 4 for more information on setting default minimum and maximum client versions. .It Sy wsize Ns = Ns Ar n Set the write buffer size to a maximum of .Ar n -bytes. The default value is 1048576 when using connection-oriented transports -with Version 3 or Version 4 of the NFS protocol, and 32768 when using -connection-less transports. The default can be negotiated down if the server -prefers a smaller transfer size. +bytes. +The default value is 1048576 when using connection-oriented transports with +Version 3 or Version 4 of the NFS protocol, and 32768 when using connection-less +transports. +The default can be negotiated down if the server prefers a smaller transfer +size. .Qq Write -operations may not necessarily use the maximum buffer size. When using Version -2, the default value is 32768 for all transports. +operations may not necessarily use the maximum buffer size. +When using Version 2, the default value is 32768 for all transports. .It Sy xattr Ns | Ns Sy noxattr -Allow or disallow the creation and manipulation of extended attributes. The -default is +Allow or disallow the creation and manipulation of extended attributes. +The default is .Sy xattr . See .Xr fsattr 5 @@ -453,9 +484,10 @@ above .Pc . Once the file system is mounted, each NFS request made in the kernel waits .Sy timeo Ns = Ns Ar n -tenths of a second for a response. If no response arrives, the time-out is -multiplied by 2 and the request is retransmitted. When the number of -retransmissions has reached the number specified in the +tenths of a second for a response. +If no response arrives, the time-out is multiplied by 2 and the request is +retransmitted. +When the number of retransmissions has reached the number specified in the .Sy retrans Ns = Ns Ar n option, a file system mounted with the .Sy soft @@ -466,16 +498,19 @@ option prints a warning message and continues to retry the request. File systems that are mounted read-write or that contain executable files should always be mounted with the .Sy hard -option. Applications using +option. +Applications using .Sy soft mounted file systems can incur unexpected I/O errors, file corruption, and -unexpected program core dumps. The +unexpected program core dumps. +The .Sy soft option is not recommended. .Ss Authenticated requests The server can require authenticated NFS requests from the client. .Sy sec Ns = Ns Sy dh -authentication might be required. See +authentication might be required. +See .Xr nfssec 5 . .Ss URLs and the public option If the @@ -500,12 +535,13 @@ daemons to get the port number of the .Nm mount server and the initial file handle of .Ar pathname , -respectively. If the NFS client and server are separated by a firewall that -allows all outbound connections through specific ports, such as +respectively. +If the NFS client and server are separated by a firewall that allows all +outbound connections through specific ports, such as .Dv NFS_PORT , -then this enables NFS operations through the firewall. The public option and the -NFS URL can be specified independently or together. They interact as specified -in the following matrix: +then this enables NFS operations through the firewall. +The public option and the NFS URL can be specified independently or together. +They interact as specified in the following matrix: .Bd -literal Resource Style @@ -525,40 +561,45 @@ default Use MOUNT protocol. Try public file handle .Ed .Pp A Native path is a path name that is interpreted according to conventions used -on the native operating system of the NFS server. A Canonical path is a -path name that is interpreted according to the URL rules. See +on the native operating system of the NFS server. +A Canonical path is a path name that is interpreted according to the URL rules. +See .Rs .%R Uniform Resource Locators (URL) .%T RFC 1738 .Re .Ss Replicated file systems and failover .Ar resource -can list multiple read-only file systems to be used to provide data. These file -systems should contain equivalent directory structures and identical files. It -is also recommended that they be created by a utility such as +can list multiple read-only file systems to be used to provide data. +These file systems should contain equivalent directory structures and identical +files. +It is also recommended that they be created by a utility such as .Xr rdist 1 . The file systems can be specified either with a comma-separated list of .Pa host:/pathname entries and/or NFS URL entries, or with a comma-separated list of hosts, if all -file system names are the same. If multiple file systems are named and the first -server in the list is down, failover uses the next alternate server to access -files. If the read-only option is not chosen, replication is disabled. File -access, for NFS Versions 2 and 3, is blocked on the original if NFS locks are -active for that file. +file system names are the same. +If multiple file systems are named and the first server in the list is down, +failover uses the next alternate server to access files. +If the read-only option is not chosen, replication is disabled. +File access, for NFS Versions 2 and 3, is blocked on the original if NFS locks +are active for that file. .Ss File Attributes -To improve NFS read performance, files and file attributes are cached. File -modification times get updated whenever a write occurs. However, file access -times can be temporarily out-of-date until the cache gets refreshed. +To improve NFS read performance, files and file attributes are cached. +File modification times get updated whenever a write occurs. +However, file access times can be temporarily out-of-date until the cache gets +refreshed. .Pp -The attribute cache retains file attributes on the client. Attributes for a -file are assigned a time to be flushed. If the file is modified before the -flush time, then the flush time is extended by the time since the last -modification +The attribute cache retains file attributes on the client. +Attributes for a file are assigned a time to be flushed. +If the file is modified before the flush time, then the flush time is extended +by the time since the last modification .Po under the assumption that files that changed recently are likely to change soon .Pc . There is a minimum and maximum flush time extension for regular files and for -directories. Setting +directories. +Setting .Sy actimeo Ns = Ns Ar n sets flush time to .Ar n @@ -566,19 +607,21 @@ seconds for both regular files and directories. .Pp Setting .Sy actimeo Ns = Ns Sy 0 -disables attribute caching on the client. This means that every reference to -attributes is satisfied directly from the server though file data is still -cached. While this guarantees that the client always has the latest file -attributes from the server, it has an adverse effect on performance through -additional latency, network load, and server load. +disables attribute caching on the client. +This means that every reference to attributes is satisfied directly from the +server though file data is still cached. +While this guarantees that the client always has the latest file attributes from +the server, it has an adverse effect on performance through additional latency, +network load, and server load. .Pp Setting the .Sy noac option also disables attribute caching, but has the further effect of disabling -client write caching. While this guarantees that data written by an application -is written directly to a server, where it can be viewed immediately by other -clients, it has a significant adverse effect on client write performance. Data -written into memory-mapped file pages +client write caching. +While this guarantees that data written by an application is written directly to +a server, where it can be viewed immediately by other clients, it has a +significant adverse effect on client write performance. +Data written into memory-mapped file pages .Pq Xr mmap 2 are not written directly to this server. .Ss Specifying Values for Attribute Cache Duration Options @@ -595,7 +638,8 @@ options specified following .Sy actimeo on a .Nm mount -command line. For example, consider the following command: +command line. +For example, consider the following command: .Bd -literal -offset indent example# mount -o acdirmax=10,actimeo=1000 server:/path /localpath .Ed @@ -748,7 +792,8 @@ example# mount serv-x:/usr/man,serv-y:/var/man,nfs://serv-z/man /usr/man .%D December 1994 .Re .Sh NOTES -An NFS server should not attempt to mount its own file systems. See +An NFS server should not attempt to mount its own file systems. +See .Xr lofs 7FS . .Pp If the directory on which a file system is to be mounted is a symbolic link, @@ -758,7 +803,8 @@ rather than being mounted on top of the symbolic link itself. SunOS 4.x used the .Sy biod maintenance procedure to perform parallel read-ahead and write-behind on NFS -clients. SunOS 5.x made +clients. +SunOS 5.x made .Sy biod obsolete with multi-threaded processing, which transparently performs parallel read-ahead and write-behind. diff --git a/usr/src/man/man1m/mountd.1m b/usr/src/man/man1m/mountd.1m index d33aefdffb..a38cf00d32 100644 --- a/usr/src/man/man1m/mountd.1m +++ b/usr/src/man/man1m/mountd.1m @@ -31,22 +31,26 @@ .Sh DESCRIPTION .Nm is an RPC server that answers requests for NFS access information and file -system mount requests. It reads the file +system mount requests. +It reads the file .Pa /etc/dfs/sharetab to determine which file systems are available for mounting by which remote -machines. See +machines. +See .Xr sharetab 4 . .Nm nfsd running on the local server will contact .Nm the first time an NFS client tries to access the file system to determine -whether the client should get read-write, read-only, or no access. This access -can be dependent on the security mode used in the remoted procedure call from -the client. See +whether the client should get read-write, read-only, or no access. +This access can be dependent on the security mode used in the remoted procedure +call from the client. +See .Xr share_nfs 1M . .Pp The command also provides information as to what file systems are mounted by -which clients. This information can be printed using the +which clients. +This information can be printed using the .Xr showmount 1M command. .Pp @@ -62,14 +66,15 @@ See for available configuration properties for .Nm . .Ss Options -The options shown below are supported for NFSv2/v3 clients. They are not -supported for NFSv4 clients. +The options shown below are supported for NFSv2/v3 clients. +They are not supported for NFSv4 clients. .Bl -tag -width Ds .It Fl r -Reject mount requests from clients. Clients that have file systems mounted will -not be affected. +Reject mount requests from clients. +Clients that have file systems mounted will not be affected. .It Fl v -Run the command in verbose mode. Each time +Run the command in verbose mode. +Each time .Nm determines what access a client should get, it will log the result to the console, as well as how it got that result. @@ -97,10 +102,12 @@ to function properly, .Nm is automatically started by the .Sy svc:/network/nfs/server -service. See +service. +See .Xr nfs 4 . .Pp Some routines that compare hostnames use case-sensitive string comparisons; -some do not. If an incoming request fails, verify that the case of the hostname -in the file to be parsed matches the case of the hostname called for, and -attempt the request again. +some do not. +If an incoming request fails, verify that the case of the hostname in the file +to be parsed matches the case of the hostname called for, and attempt the +request again. diff --git a/usr/src/man/man1m/ndp.1m b/usr/src/man/man1m/ndp.1m index 6301181f5f..57285b003f 100644 --- a/usr/src/man/man1m/ndp.1m +++ b/usr/src/man/man1m/ndp.1m @@ -52,9 +52,9 @@ tables used by the Neighbor Discovery Protocol .Pp Given just a hostname, .Nm -will display the current entry. Note that when getting, setting or deleting, -if a hostname refers to multiple IPv6 addresses, the operation will apply to -all of them. +will display the current entry. +Note that when getting, setting or deleting, if a hostname refers to multiple +IPv6 addresses, the operation will apply to all of them. .Pp The NDP translation tables can be modified with .Fl d , @@ -65,7 +65,8 @@ These flags can only be used when .Nm is given the .Sy PRIV_SYS_NET_CONFIG -privilege. See +privilege. +See .Xr privileges 5 for further information. .Pp @@ -75,11 +76,13 @@ modified or deleted. .Sh OPTIONS .Bl -tag -width 6m .It Fl a -Display all NDP entries. Entries can be one of several types: +Display all NDP entries. +Entries can be one of several types: .Bl -tag -offset indent -width 7n .It Sy dynamic -This is a normal NDP mapping and will eventually expire. This is the most -common type of mapping for non-local addresses that will be displayed. +This is a normal NDP mapping and will eventually expire. +This is the most common type of mapping for non-local addresses that will be +displayed. .It Sy local The IPv6 address is local to the machine. .It Sy other @@ -129,15 +132,16 @@ Delete NDP mappings for the host called .It Fl f Read in the lines from .Ar filename -and use each one to set a mapping. The syntax of each line is the -same as the arguments to +and use each one to set a mapping. +The syntax of each line is the same as the arguments to .Fl s . Lines beginning with `#' will be ignored. .It Fl i By default, .Nm will use the routing table to determine the appropriate interface to place the -mapping on. This flag allows forcing a specific interface +mapping on. +This flag allows forcing a specific interface .Ar iface . This argument will be ignored when using the .Fl a @@ -148,25 +152,27 @@ flags. Disable the default translation of numeric IP addresses to host names when printing. .It Fl s -Add or update an NDP mapping, and set the desired properties for the entry. The -list of flags should be the full set of flags desired on the entry, i.e., not -listing a flag will remove it if it already exists. The following flags can be -used: +Add or update an NDP mapping, and set the desired properties for the entry. +The list of flags should be the full set of flags desired on the entry, i.e., +not listing a flag will remove it if it already exists. +The following flags can be used: .Bl -tag -offset indent -width Ds .It Cm temp The entry should be temporary and eventually expire like a normal NDP -entry. By default, all entries created with the +entry. +By default, all entries created with the .Nm -command are static, and will not be deleted. To make a static entry temporary, -it should be deleted and recreated with the +command are static, and will not be deleted. +To make a static entry temporary, it should be deleted and recreated with the .Cm temp flag. .It Cm any -The address should be treated like an anycast address. This will prevent the -system from sending Neighbor Advertisements with the Override flag. +The address should be treated like an anycast address. +This will prevent the system from sending Neighbor Advertisements with the +Override flag. .It Cm router -The address should be treated like a router address. This cause the system to -send Neighbor Advertisements with the Router flag. +The address should be treated like a router address. +This cause the system to send Neighbor Advertisements with the Router flag. .El .El .Sh EXAMPLES diff --git a/usr/src/man/man1m/nfsd.1m b/usr/src/man/man1m/nfsd.1m index 70b4379bdd..e188fdd29b 100644 --- a/usr/src/man/man1m/nfsd.1m +++ b/usr/src/man/man1m/nfsd.1m @@ -35,7 +35,8 @@ .Op Ar nservers .Sh DESCRIPTION .Nm -is the daemon that handles client file system requests. Only users with +is the daemon that handles client file system requests. +Only users with .Brq Sy PRIV_SYS_NFS and sufficient privileges to write to .Pa /var/run @@ -51,9 +52,9 @@ option. .Pp By default, .Nm -starts over the TCP and UDP transports for versions 2 and 3. By default, it -starts over the TCP for version 4. You can change this -with the +starts over the TCP and UDP transports for versions 2 and 3. +By default, it starts over the TCP for version 4. +You can change this with the .Fl p option. .Pp @@ -72,28 +73,33 @@ The following options are supported: .Bl -tag -width Ds .It Fl a Start a NFS daemon over all available connectionless and connection-oriented -transports, including UDP and TCP. Equivalent of setting the +transports, including UDP and TCP. +Equivalent of setting the .Sy protocol property to .Sy all . .It Fl c Ar max_conn Set the maximum number of connections allowed to the NFS server over -connection-oriented transports. By default, the number of connections is -unlimited. Equivalent of the +connection-oriented transports. +By default, the number of connections is unlimited. +Equivalent of the .Sy max_connections property. .It Fl l Set connection queue length for the NFS server over a connection-oriented -transport. The default value is 32 entries. Equivalent of the +transport. +The default value is 32 entries. +Equivalent of the .Sy listen_backlog property. .It Fl p Ar protocol -Start a NFS daemon over the specified protocol. Equivalent of the +Start a NFS daemon over the specified protocol. +Equivalent of the .Sy protocol property. .It Fl t Ar device -Start a NFS daemon for the transport specified by the given device. Equivalent -of the +Start a NFS daemon for the transport specified by the given device. +Equivalent of the .Sy device property. .El @@ -102,16 +108,19 @@ The following operands are supported: .Bl -tag -width Ds .It Ar nservers This sets the maximum number of concurrent NFS requests that the server can -handle. This concurrency is achieved by up to +handle. +This concurrency is achieved by up to .Ar nservers threads created as needed in the kernel. .Ar nservers -should be based on the load expected on this server. 16 is the usual number of +should be based on the load expected on this server. +16 is the usual number of .Ar nservers . If .Ar nservers is not specified, the maximum number of concurrent NFS requests will default to -1. Equivalent of the +1. +Equivalent of the .Sy servers property. .El @@ -124,12 +133,14 @@ then clients are required to use privileged ports .Po ports < .Dv IPPORT_RESERVED .Pc -to get NFS services. This variable is equal to zero by default. This variable -has been moved from the +to get NFS services. +This variable is equal to zero by default. +This variable has been moved from the .Qq nfs module to the .Qq nfssrv -module. To set the variable, edit the +module. +To set the variable, edit the .Pa /etc/system file and add this entry: .Bd -literal -offset indent @@ -146,8 +157,8 @@ System configuration information file. .br .Pa /var/nfs/v4_oldstate .Xc -Directories used by the server to manage client state information. These -directories should not be removed. +Directories used by the server to manage client state information. +These directories should not be removed. .El .Sh EXIT STATUS .Bl -tag -width Ds @@ -171,7 +182,8 @@ Daemon failed to start. .Sh NOTES Manually starting and restarting .Nm -is not recommended. If it is necessary to do so, use +is not recommended. +If it is necessary to do so, use .Nm svcadm to enable or disable the nfs service .Pq svc:/network/nfs/server . @@ -205,7 +217,8 @@ If .Nm is killed with .Sy SIGTERM , -it will not be restarted by the service management facility. Instead, +it will not be restarted by the service management facility. +Instead, .Nm can be restarted by other signals, such as .Sy SIGINT . diff --git a/usr/src/man/man1m/nfsmapid.1m b/usr/src/man/man1m/nfsmapid.1m index 7b7eee6cb4..1eaed5f0fc 100644 --- a/usr/src/man/man1m/nfsmapid.1m +++ b/usr/src/man/man1m/nfsmapid.1m @@ -47,8 +47,8 @@ file to direct how it performs the mappings. .Pp The .Nm -daemon has no external, customer-accessible interfaces. You can, however, -administratively configure +daemon has no external, customer-accessible interfaces. +You can, however, administratively configure .Nm in one of the following ways: .Bl -bullet @@ -107,12 +107,14 @@ property is set to .Sy false . .Pp .Nm -caches a user's UID and GID. If a user subsequently changes a UID or GID, using -one of the utilities listed below, the +caches a user's UID and GID. +If a user subsequently changes a UID or GID, using one of the utilities listed +below, the .Nm -cache becomes stale. At this point, any NFS operation that gets or set -attributes will result in the exchange of this stale information. To resolve -this situation, restart +cache becomes stale. +At this point, any NFS operation that gets or set attributes will result in the +exchange of this stale information. +To resolve this situation, restart .Nm , as follows: .Bd -literal -offset indent diff --git a/usr/src/man/man1m/share_nfs.1m b/usr/src/man/man1m/share_nfs.1m index 9daaed00f9..8a2770cb79 100644 --- a/usr/src/man/man1m/share_nfs.1m +++ b/usr/src/man/man1m/share_nfs.1m @@ -38,8 +38,8 @@ .Sh DESCRIPTION The .Nm share -utility makes local file systems available for mounting by remote systems. It -starts the +utility makes local file systems available for mounting by remote systems. +It starts the .Xr nfsd 1M and .Xr mountd 1M @@ -60,7 +60,8 @@ Share NFS file system type. Specify .Ar specific_options in a comma-separated list of keywords and attribute-value-assertions for -interpretation by the file-system-type-specific command. If +interpretation by the file-system-type-specific command. +If .Ar specific_options is not specified, then by default sharing is read-write to all clients. .Ar specific_options @@ -68,18 +69,22 @@ can be any combination of the following: .Bl -tag -width "indented" .It Sy aclok Allows the NFS server to do access control for NFS Version 2 clients (running -SunOS 2.4 or earlier). When +SunOS 2.4 or earlier). +When .Sy aclok -is set on the server, maximal access is given to all clients. For example, with +is set on the server, maximal access is given to all clients. +For example, with .Sy aclok -set, if anyone has read permissions, then everyone does. If +set, if anyone has read permissions, then everyone does. +If .Sy aclok is not set, minimal access is given to all clients. .It Sy anon Ns = Ns Ar uid Set .Ar uid -to be the effective user ID of unknown users. By default, unknown users are -given the effective user ID UID_NOBODY. If uid is set to -1, access is denied. +to be the effective user ID of unknown users. +By default, unknown users are given the effective user ID UID_NOBODY. +If uid is set to -1, access is denied. .It Ar charset Ns = Ns Ar access_list Where .Ar charset @@ -106,13 +111,17 @@ For clients where the gid in the incoming request is and the client matches the .Ar access_list Ns , change the group ID to -.Ar srv Ns . If +.Ar srv Ns . +If .Ar clnt -is asterisk (*), all groups are mapped by this rule. If +is asterisk (*), all groups are mapped by this rule. +If .Ar clnt -is omitted, all unknown groups are mapped by this rule. If +is omitted, all unknown groups are mapped by this rule. +If .Ar srv -is set to -1, access is denied. If +is set to -1, access is denied. +If .Ar srv is omitted, the gid is mapped to UID_NOBODY. .Pp @@ -121,13 +130,15 @@ The particular are separated in the .Sy gidmap Ns = option by tilde (~) and are evaluated in the specified order until a match is -found. Both +found. +Both .Sy root Ns = and .Sy root_mapping Ns = options (if specified) are evaluated before the .Sy gidmap Ns = -option. The +option. +The .Sy gidmap Ns = option is skipped in the case where the client matches the .Sy root Ns = @@ -146,9 +157,11 @@ Load rather than a listing of the directory containing this file when the directory is referenced by an NFS URL. .It Sy log Ns Oo = Ns Ar tag Oc -Enables NFS server logging for the specified file system. The optional +Enables NFS server logging for the specified file system. +The optional .Ar tag -determines the location of the related log files. The +determines the location of the related log files. +The .Ar tag is defined in .Pa /etc/nfs/nfslog.conf . @@ -156,7 +169,8 @@ If no .Ar tag is specified, the default values associated with the global tag in .Pa /etc/nfs/nfslog.conf -are used. Support of NFS server logging is only available for NFS Version 2 and +are used. +Support of NFS server logging is only available for NFS Version 2 and Version 3 requests. .It Sy noaclfab By default, the NFS server will fabricate POSIX-draft style ACLs in response @@ -166,16 +180,16 @@ Specifying .Sy noaclfab disables this behavior. .It Sy none Ns = Ns Ar access_list -Access is not allowed to any client that matches the access list. The exception -is when the access list is an asterisk (*), in which case +Access is not allowed to any client that matches the access list. +The exception is when the access list is an asterisk (*), in which case .Sy ro or .Sy rw can override .Sy none . .It Sy nosub -Prevents clients from mounting subdirectories of shared directories. For -example, if +Prevents clients from mounting subdirectories of shared directories. +For example, if .Pa /export is shared with the .Sy nosub @@ -186,21 +200,24 @@ then a NFS client cannot do: mount -F nfs fooey:/export/home/mnt .Ed .Pp -NFS Version 4 does not use the MOUNT protocol. The +NFS Version 4 does not use the MOUNT protocol. +The .Sy nosub option only applies to NFS Version 2 and Version 3 requests. .It Sy nosuid By default, clients are allowed to create files on the shared file system with -the setuid or setgid mode enabled. Specifying +the setuid or setgid mode enabled. +Specifying .Sy nosuid causes the server file system to silently ignore any attempt to enable the setuid or setgid mode bits. .It Sy public Moves the location of the public file handle from root .Pa ( / ) -to the exported directory for WebNFS-enabled browsers and clients. This option -does not enable WebNFS service; WebNFS is always on. Only one file system per -server may use this option. Any other option, including the +to the exported directory for WebNFS-enabled browsers and clients. +This option does not enable WebNFS service; WebNFS is always on. +Only one file system per server may use this option. +Any other option, including the .Sy ro Ns = Ns Ar list and .Sy rw Ns = Ns Ar list @@ -214,19 +231,23 @@ Sharing is read-only to the clients listed in .Ar access_list ; overrides the .Sy rw -suboption for the clients specified. See +suboption for the clients specified. +See .Sx access_list below. .It Sy root Ns = Ns Ar access_list Only root users from the hosts specified in .Ar access_list -have root access. See +have root access. +See .Sx access_list -below. By default, no host has root access, so root users are mapped to an -anonymous user ID (see the +below. +By default, no host has root access, so root users are mapped to an anonymous +user ID (see the .Sy anon Ns = Ns Ar uid -option described above). Netgroups can be used if the file system shared is -using UNIX authentication (AUTH_SYS). +option described above). +Netgroups can be used if the file system shared is using UNIX authentication +(AUTH_SYS). .It Sy root_mapping Ns = Ns Ar uid For a client that is allowed root access, map the root UID to the specified user id. @@ -237,20 +258,25 @@ Sharing is read-write to the clients listed in .Ar access_list ; overrides the .Sy ro -suboption for the clients specified. See +suboption for the clients specified. +See .Sx access_list below. .It Sy sec Ns = Ns Ar mode Ns Oo : Ns Ar mode Oc Ns ... -Sharing uses one or more of the specified security modes. The +Sharing uses one or more of the specified security modes. +The .Ar mode in the .Sy sec Ns = Ns Ar mode -option must be a mode name supported on the client. If the +option must be a mode name supported on the client. +If the .Sy sec Ns = -option is not specified, the default security mode used is AUTH_SYS. Multiple +option is not specified, the default security mode used is AUTH_SYS. +Multiple .Sy sec Ns = options can be specified on the command line, although each mode can appear -only once. The security modes are defined in +only once. +The security modes are defined in .Xr nfssec 5 . .Pp Each @@ -282,7 +308,8 @@ If the option .Sy sec Ns = Ns Sy none is specified when the client uses AUTH_NONE, or if the client uses a security mode that is not one that the file system is shared with, then the credential -of each NFS request is treated as unauthenticated. See the +of each NFS request is treated as unauthenticated. +See the .Sy anon Ns = Ns Ar uid option for a description of how unauthenticated requests are handled. .It Sy secure @@ -304,13 +331,17 @@ For clients where the uid in the incoming request is and the client matches the .Ar access_list Ns , change the user ID to -.Ar srv Ns . If +.Ar srv Ns . +If .Ar clnt -is asterisk (*), all users are mapped by this rule. If +is asterisk (*), all users are mapped by this rule. +If .Ar clnt -is omitted, all unknown users are mapped by this rule. If +is omitted, all unknown users are mapped by this rule. +If .Ar srv -is set to -1, access is denied. If +is set to -1, access is denied. +If .Ar srv is omitted, the uid is mapped to UID_NOBODY. .Pp @@ -319,13 +350,15 @@ The particular are separated in the .Sy uidmap Ns = option by tilde (~) and are evaluated in the specified order until a match is -found. Both +found. +Both .Sy root Ns = and .Sy root_mapping Ns = options (if specified) are evaluated before the .Sy uidmap Ns = -option. The +option. +The .Sy uidmap Ns = option is skipped in the case where the client matches the .Sy root Ns = @@ -342,9 +375,10 @@ This option is supported only for AUTH_SYS. When sharing with .Sy sec Ns = Ns Sy dh , set the maximum life time (in seconds) of the RPC request's credential (in the -authentication header) that the NFS server allows. If a credential arrives with -a life time larger than what is allowed, the NFS server rejects the request. The -default value is 30000 seconds (8.3 hours). +authentication header) that the NFS server allows. +If a credential arrives with a life time larger than what is allowed, the NFS +server rejects the request. +The default value is 30000 seconds (8.3 hours). .El .El .Ss access_list @@ -354,13 +388,13 @@ argument is a colon-separated list whose components may be any number of the following: .Bl -tag -width "indented" .It Sy hostname -The name of a host. With a server configured for DNS or LDAP naming in the -nsswitch +The name of a host. +With a server configured for DNS or LDAP naming in the nsswitch .Sy hosts entry, any hostname must be represented as a fully qualified DNS or LDAP name. .It Sy netgroup -A netgroup contains a number of hostnames. With a server configured for DNS or -LDAP naming in the nsswitch +A netgroup contains a number of hostnames. +With a server configured for DNS or LDAP naming in the nsswitch .Sy hosts entry, any hostname in a netgroup must be represented as a fully qualified DNS or LDAP name. @@ -376,10 +410,11 @@ or .Sy ldap ahead of .Sy nis -since only DNS and LDAP return the full domain name of the host. Other name -services like NIS cannot be used to resolve hostnames on the server +since only DNS and LDAP return the full domain name of the host. +Other name services like NIS cannot be used to resolve hostnames on the server because when mapping an IP address to a hostname they do not return domain -information. For example, +information. +For example, .Bd -literal -offset indent NIS 172.16.45.9 --> "myhost" .Ed @@ -390,12 +425,14 @@ DNS or LDAP 172.16.45.9 --> "myhost.mydomain.mycompany.com" .Ed .Pp The domain name suffix is distinguished from hostnames and netgroups by a -prefixed dot. For example, +prefixed dot. +For example, .Bd -literal -offset indent rw=.mydomain.mycompany.com .Ed .Pp -A single dot can be used to match a hostname with no suffix. For example, +A single dot can be used to match a hostname with no suffix. +For example, .Bd -literal -offset indent rw=. .Ed @@ -407,8 +444,9 @@ but not This feature can be used to match hosts resolved through NIS rather than DNS and LDAP. .It Sy network -The network or subnet component is preceded by an at-sign (@). It can be either -a name or a dotted address. If a name, it is converted to a dotted address by +The network or subnet component is preceded by an at-sign (@). +It can be either a name or a dotted address. +If a name, it is converted to a dotted address by .Xr getnetbyname 3SOCKET . For example, .Bd -literal -offset indent @@ -422,9 +460,10 @@ would be equivalent to: .Pp The network prefix assumes an octet-aligned netmask determined from the zeroth octet in the low-order part of the address up to and including the high-order -octet, if you want to specify a single IP address (see below). In the case -where network prefixes are not byte-aligned, the syntax allows a mask length to -be specified explicitly following a slash (/) delimiter. For example, +octet, if you want to specify a single IP address (see below). +In the case where network prefixes are not byte-aligned, the syntax allows a +mask length to be specified explicitly following a slash (/) delimiter. +For example, .Bd -literal -offset indent =@theothernet/17 or =@172.16.132/22 .Ed @@ -433,7 +472,8 @@ where the mask is the number of leftmost contiguous significant bits in the corresponding IP address. .Pp When specifying individual IP addresses, use the same @ notation described -above, without a netmask specification. For example: +above, without a netmask specification. +For example: .Bd -literal -offset indent =@172.16.132.14 .Ed @@ -447,7 +487,8 @@ root=@172.16.132.20:@172.16.134.20 A prefixed minus sign (-) denies access to that component of .Ar access_list . The list is searched sequentially until a match is found that either grants or -denies access, or until the end of the list is reached. For example, if host +denies access, or until the end of the list is reached. +For example, if host .Qq terra is in the .Qq engineering @@ -494,16 +535,17 @@ share -o log /export .Ed .Pp The default global logging parameters are used since no tag identifier is -specified. The location of the log file, as well as the necessary logging work +specified. +The location of the log file, as well as the necessary logging work files, is specified by the global entry in .Pa /etc/nfs/nfslog.conf . The .Xr nfslogd 1M daemon runs only if at least one file system entry in .Pa /etc/dfs/dfstab -is shared with logging enabled upon starting or rebooting the system. Simply -sharing a file system with logging enabled from the command line does not start -the +is shared with logging enabled upon starting or rebooting the system. +Simply sharing a file system with logging enabled from the command line does not +start the .Xr nfslogd 1M . .Ss Example 2 Remap A User Coming From The Particular NFS Client The following example remaps the user with uid @@ -541,7 +583,8 @@ and .Sy root Ns = options must come after the first .Sy sec Ns = -option. If the +option. +If the .Sy sec Ns = option is not presented, then .Sy sec Ns = Ns Sy sys @@ -552,7 +595,8 @@ If one or more explicit options are presented, .Sy sys must appear in one of the options mode lists for accessing using the AUTH_SYS -security mode to be allowed. For example: +security mode to be allowed. +For example: .Bd -literal -offset indent share -F nfs /var share -F nfs -o sec=sys /var @@ -581,7 +625,8 @@ the .Sy ro Ns = and .Sy rw Ns = -options are used to control access to weaker security modes. In this example, +options are used to control access to weaker security modes. +In this example, .Bd -literal -offset indent share -F nfs -o sec=dh,rw,sec=sys,rw=hosta /var .Ed @@ -595,9 +640,10 @@ share -F nfs -o sec=dh,rw,sec=sys,ro /var .Ed .Pp is safer, because any client (intruder or legitimate) that avoids AUTH_DES only -gets read-only access. In general, multiple security modes per share command -should only be used in situations where the clients using more secure modes get -stronger access than clients using less secure modes. +gets read-only access. +In general, multiple security modes per share command should only be used in +situations where the clients using more secure modes get stronger access than +clients using less secure modes. .Pp If .Sy rw Ns = @@ -606,7 +652,8 @@ and options are specified in the same .Sy sec Ns = clause, and a client is in both lists, the order of the two options determines -the access the client gets. If client +the access the client gets. +If client .Qq hosta is in two netgroups, .Qq group1 @@ -631,8 +678,10 @@ clause, both the and .Sy rw Ns = options are specified, for compatibility, the order of the options rule is not -enforced. All hosts would get read-only access, with the exception to those in -the read-write list. Likewise, if the +enforced. +All hosts would get read-only access, with the exception to those in the +read-write list. +Likewise, if the .Sy ro Ns = and .Sy rw @@ -663,10 +712,13 @@ option and the .Sy rw Ns = , and .Sy ro Ns = -options. Putting a host in the root list does not override the semantics of the -other options. The access the host gets is the same as when the +options. +Putting a host in the root list does not override the semantics of the other +options. +The access the host gets is the same as when the .Sy root Ns = -option is absent. For example, the following share command denies access to +option is absent. +For example, the following share command denies access to .Qq hostb : .Bd -literal -offset indent share -F nfs -o ro=hosta,root=hostb /var @@ -685,8 +737,8 @@ share -F nfs -o ro=hosta,rw=hostb,root=hostb /var .Ed .Pp If the file system being shared is a symbolic link to a valid pathname, the -canonical path (the path which the symbolic link follows) is shared. For -example, if +canonical path (the path which the symbolic link follows) is shared. +For example, if .Pa /export/foo is a symbolic link to .Pa /export/bar , @@ -723,7 +775,8 @@ For example, .Pa /export/foo might be a symbolic link that refers to .Pa /export/bar -which has been specifically shared. When the client mounts +which has been specifically shared. +When the client mounts .Pa /export/foo the mountd processing follows the symbolic link and responds with the .Pa /export/bar . diff --git a/usr/src/man/man1m/sharectl.1m b/usr/src/man/man1m/sharectl.1m index e754a602b4..74d260d4e7 100644 --- a/usr/src/man/man1m/sharectl.1m +++ b/usr/src/man/man1m/sharectl.1m @@ -45,9 +45,10 @@ .Sh DESCRIPTION The .Nm -command operates on file sharing services. The command sets the client and -server operational properties, takes and restores configuration snapshots, and -gets status of the protocol service. Currently supported services are +command operates on file sharing services. +The command sets the client and server operational properties, takes and +restores configuration snapshots, and gets status of the protocol service. +Currently supported services are .Xr autofs 4 , .Xr nfs 4 , .Xr smb 4 @@ -64,9 +65,11 @@ authorizations, see appropriate sharing protocol man page. The following options are supported where applicable: .Bl -tag -width Ds .It Fl h -Displays usage message. Supported for all subcommands. +Displays usage message. +Supported for all subcommands. .It Fl p Ar property Ns Op = Ns Ar value -Specifies a property. See +Specifies a property. +See .Sx Subcommands , below. .El @@ -79,8 +82,8 @@ supports the subcommands described below: .Cm delsect .Ar section protocol .Xc -Delete configuration section for the specified protocol. Currently only protocol -that has configuration sections is +Delete configuration section for the specified protocol. +Currently only protocol that has configuration sections is .Nm smbfs .Po see .Xr nsmbrc 4 @@ -93,12 +96,14 @@ and .Oo Fl p Ar property Oc Ns ... .Ar protocol .Xc -Get the property values for the specified protocol. If no +Get the property values for the specified protocol. +If no .Fl p -option is provided, get all the properties for the specified protocol. For NFS, -properties correspond to entries in the +option is provided, get all the properties for the specified protocol. +For NFS, properties correspond to entries in the .Pa /etc/default/nfs -file. See +file. +See .Xr nfs 4 . .It Xo .Nm @@ -192,7 +197,8 @@ The following command shows how an authorized user can use the .Nm sharectl Cm get command to view the global settings for .Nm smbfs -in the SMF. The values shown are those set by the previous example. +in the SMF. +The values shown are those set by the previous example. .Bd -literal # sharectl get smbfs [default] diff --git a/usr/src/man/man1m/stmfadm.1m b/usr/src/man/man1m/stmfadm.1m index 8493c20d04..d99c31c3b3 100644 --- a/usr/src/man/man1m/stmfadm.1m +++ b/usr/src/man/man1m/stmfadm.1m @@ -121,7 +121,8 @@ The .Nm command configures logical units within the SCSI Target Mode Framework .Pq STMF -framework. The framework and this man page use the following terminology: +framework. +The framework and this man page use the following terminology: .Bl -tag -width Ds .It Sy initiator A device responsible for issuing SCSI I/O commands to a SCSI target and logical @@ -147,15 +148,16 @@ The set of logical units that a particular SCSI initiator can see is determined by the combined set of views. .Pp Each logical unit has a set of view entries, and each view entry specifies a -target group, host group, and a LUN. An initiator from that host group, when -connecting through that target group, is able to identify and connect to that -logical unit using the specified LUN. You can use views to restrict the set of -logical units that a specific initiator can see, and assign the set of LUNs -that will be used. +target group, host group, and a LUN. +An initiator from that host group, when connecting through that target group, is +able to identify and connect to that logical unit using the specified LUN. +You can use views to restrict the set of logical units that a specific initiator +can see, and assign the set of LUNs that will be used. .It Sy view A view defines the association of a host group, a target group, and a logical -unit number with a specified logical unit. Any view entry added to a logical -unit must not be in conflict with existing view entries for that logical unit. +unit number with a specified logical unit. +Any view entry added to a logical unit must not be in conflict with existing +view entries for that logical unit. A view entry is considered to be in conflict when an attempt is made to duplicate the association of any given host, target and logical unit number. .El @@ -165,31 +167,41 @@ The following logical unit properties can be set only when creating LU using subcommand: .Bl -tag -width Ds .It Sy blk Ns = Ns Ar num -Specifies the block size for the device. The default is 512. +Specifies the block size for the device. +The default is 512. .It Sy guid Ns = Ns Ar string 32 hexadecimal ASCII characters representing a valid NAA Registered Extended -Identifier. The default is set by the STMF to a generated value. +Identifier. +The default is set by the STMF to a generated value. .It Sy meta Ns = Ns Ar path -Metadata file name. When specified, will be used to hold the SCSI metadata for -the logical unit. There is no default. +Metadata file name. +When specified, will be used to hold the SCSI metadata for the logical unit. +There is no default. .It Sy oui Ns = Ns Ar string -Organizational Unique Identifier. Six hexadecimal ASCII characters representing -the IEEE OUI company ID assignment. This will be used to generate the device -identifier +Organizational Unique Identifier. +Six hexadecimal ASCII characters representing the IEEE OUI company ID +assignment. +This will be used to generate the device identifier .Pq GUID . The default is .Sy 00144F . .It Sy pid Ns = Ns Ar string -16 bytes ASCII string defining Product ID per SCSI SPC-3. This value will be -reflected in the Standard INQUIRY data returned for the device. The default is +16 bytes ASCII string defining Product ID per SCSI SPC-3. +This value will be reflected in the Standard INQUIRY data returned for the +device. +The default is .Sy COMSTAR . .It Sy serial Ns = Ns Ar string -Serial Number. Specifies the SCSI Vital Product Data Serial Number +Serial Number. +Specifies the SCSI Vital Product Data Serial Number .Pq page 80h . -It is a character value up to 252 bytes in length. There is no default value. +It is a character value up to 252 bytes in length. +There is no default value. .It Sy vid Ns = Ns Ar string -8 bytes ASCII string defining Vendor ID per SCSI SPC-3. This value will be -reflected in the Standard INQUIRY data returned for the device. The default is +8 bytes ASCII string defining Vendor ID per SCSI SPC-3. +This value will be reflected in the Standard INQUIRY data returned for the +device. +The default is .Sy SUN . .El .Pp @@ -200,22 +212,24 @@ subcommand or modified using subcommand: .Bl -tag -width Ds .It Sy alias Ns = Ns Ar string -Up to 255 characters, representing a user-defined name for the device. The -default is the name of the backing store. +Up to 255 characters, representing a user-defined name for the device. +The default is the name of the backing store. .It Sy mgmt-url Ns = Ns Ar string -Up to 1024 characters representing a Management Network Address URL. More than -one URL can be passed as a single parameter by using space-delimited URLs -enclosed inside a single pair of quotation marks +Up to 1024 characters representing a Management Network Address URL. +More than one URL can be passed as a single parameter by using space-delimited +URLs enclosed inside a single pair of quotation marks .Pq Sy \(dq . .It Sy wcd Ns = Ns Sy true Ns | Ns Sy false -Write-back cache disable. Determines write-back cache disable behavior. The -default is the write-back cache setting of the backing store device specified by -the +Write-back cache disable. +Determines write-back cache disable behavior. +The default is the write-back cache setting of the backing store device +specified by the .Ar lu-file argument. .It Sy wp Ns = Ns Sy true Ns | Ns Sy false -Write-protect bit. Determines whether the device reports as write-protected. The -default is +Write-protect bit. +Determines whether the device reports as write-protected. +The default is .Sy false . .El .Ss Subcommands @@ -271,14 +285,16 @@ where .Ar lu-name is the STMF name for the logical unit as displayed by the .Cm list-lu -subcommand. The +subcommand. +The .Cm add-view subcommand provides the user with a mechanism to implement access control for a logical unit and also provides a means of assigning a logical unit number to a -logical unit for a given set of initiators and targets. A logical unit will not -be available to any initiators until at least one view is applied. Each view -entry gets assigned an entry name, which can be used to reference the entry in -the +logical unit for a given set of initiators and targets. +A logical unit will not be available to any initiators until at least one view +is applied. +Each view entry gets assigned an entry name, which can be used to reference the +entry in the .Cm list-view and .Cm remove-view @@ -288,19 +304,22 @@ subcommands. .Ar host-group is the name of an host group previously created using .Cm create-hg -subcommand. If this option is not specified, the logical unit will be available -to all initiators that log in to the STMF framework. +subcommand. +If this option is not specified, the logical unit will be available to all +initiators that log in to the STMF framework. .It Fl n Ns , Ns Fl -lun Ar lu-number .Ar lu-number is an integer in the range 0-16383 to be assigned to the logical unit for this -view entry. If this option is not specified, a logical unit number will be -assigned by the STMF framework. +view entry. +If this option is not specified, a logical unit number will be assigned by the +STMF framework. .It Fl t Ns , Ns Fl -target-group Ar target-group .Ar target-group is the name of a target group previously created using .Cm create-tg -subcommand. If this option is not specified, the logical unit will be available -through all targets. +subcommand. +If this option is not specified, the logical unit will be available through all +targets. .El .It Xo .Nm @@ -310,8 +329,8 @@ through all targets. Create a host group with the name .Ar group-name . .Ar group-name -is a string of Unicode characters with a maximum length of 255. The group name -must be unique within the STMF system. +is a string of Unicode characters with a maximum length of 255. +The group name must be unique within the STMF system. .It Xo .Nm .Cm create-lu @@ -321,29 +340,34 @@ must be unique within the STMF system. .Xc Create a logical unit that can be registered with STMF. .Ar lu-file -is the file to be used as the backing store for the logical unit. If the +is the file to be used as the backing store for the logical unit. +If the .Fl s option is not specified, the size of the specified .Ar lu-file will be used as the size of the logical unit. .Pp Logical units registered with the STMF require space for the metadata to be -stored. When a +stored. +When a .Sy zvol is specified as the backing store device, the default will be to use a special property of the .Sy zvol -to contain the metadata. For all other devices, the default behavior will be to -use the first 64k of the device. An alternative approach would be to use the +to contain the metadata. +For all other devices, the default behavior will be to use the first 64k of the +device. +An alternative approach would be to use the .Sy meta property in a .Cm create-lu -subcommand to specify an alternate file to contain the metadata. It is advisable -to use a file that can provide sufficient storage of the logical unit metadata, -preferably 64k. +subcommand to specify an alternate file to contain the metadata. +It is advisable to use a file that can provide sufficient storage of the logical +unit metadata, preferably 64k. .Bl -tag -width Ds .It Fl p Ns , Ns Fl -lu-prop Ar property Ns = Ns Ar value -Set specified logical unit property. Check +Set specified logical unit property. +Check .Sx Logical Unit Properties for the list of available properties. .It Fl s Ns , Ns Fl -size Ar size @@ -362,8 +386,8 @@ respectively. Create a target group with the name .Ar group-name . .Ar group-name -is a string of Unicode characters with a maximum length of 255. The group name -must be unique within the STMF system. +is a string of Unicode characters with a maximum length of 255. +The group name must be unique within the STMF system. .It Xo .Nm .Cm delete-hg @@ -379,7 +403,8 @@ Delete the host group identified by .Xc Delete an existing logical unit that was created using .Cm create-lu -subcommand. This effectively unloads the logical unit from the STMF framework. +subcommand. +This effectively unloads the logical unit from the STMF framework. Any existing data on the logical unit remains intact. .Bl -tag -width Ds .It Fl k Ns , Ns Fl -keep-views @@ -401,12 +426,13 @@ Import and load a logical unit into the STMF that was previously created using .Cm create-lu subcommand and was then deleted from the STMF using .Cm delete-lu -subcommand. On success, the logical unit is again made available to the STMF. +subcommand. +On success, the logical unit is again made available to the STMF. .Ar lu-file is the filename used in the .Cm create-lu -subcommand. If this logical unit is using a separate metadata file, the filename -in the +subcommand. +If this logical unit is using a separate metadata file, the filename in the .Sy meta property value that was used in the .Cm create-lu @@ -501,7 +527,8 @@ Specify logical unit. .Xc Modify attributes of a logical unit created using the .Cm create-lu -subcommand. If +subcommand. +If .Fl f is not specified, .Ar lu-arg @@ -511,10 +538,12 @@ is interpreted as .It Fl f Ns , Ns Fl -file If specified, .Ar lu-arg -is interpreted as file name. This provides the ability to modify a logical unit -that is not currently imported into the STMF. +is interpreted as file name. +This provides the ability to modify a logical unit that is not currently +imported into the STMF. .It Fl p Ns , Ns Fl -lu-prop Ar property -Modify specified logical unit property. See +Modify specified logical unit property. +See .Sx Logical Unit Properties for the list of available properties. .It Fl s Ns , Ns Fl -size Ar size diff --git a/usr/src/man/man1m/zfs.1m b/usr/src/man/man1m/zfs.1m index 2f24b89339..6b872c5ac7 100644 --- a/usr/src/man/man1m/zfs.1m +++ b/usr/src/man/man1m/zfs.1m @@ -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. -.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 +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 .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 system. .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 snapshot .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 that represent the mode. .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 represent the current mode. 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 dataset. .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 are unaffected. 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. .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none The minimum amount of space guaranteed to a dataset, not including its -descendents. When the amount of space used is below this value, the dataset is -treated as if it were taking up the amount of space specified by +descendents. +When the amount of space used is below this value, the dataset is treated as if +it were taking up the amount of space specified by .Sy refreservation . The .Sy refreservation @@ -1265,11 +1352,11 @@ bytes in the dataset. This property can also be referred to by its shortened column name, .Sy refreserv . .It Sy reservation Ns = Ns Em size Ns | Ns Sy none -The minimum amount of space guaranteed to a dataset and its descendents. When -the amount of space used is below this value, the dataset is treated as if it -were taking up the amount of space specified by its reservation. Reservations -are accounted for in the parent datasets' space used, and count against the -parent datasets' quotas and reservations. +The minimum amount of space guaranteed to a dataset and its descendents. +When the amount of space used is below this value, the dataset is treated as if +it were taking up the amount of space specified by its reservation. +Reservations are accounted for in the parent datasets' space used, and count +against the parent datasets' quotas and reservations. .Pp This property can also be referred to by its shortened column name, .Sy reserv . @@ -1278,19 +1365,23 @@ Controls what is cached in the secondary cache .Pq L2ARC . 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 setuid Ns = Ns Sy on Ns | Ns Sy off -Controls whether the setuid bit is respected for the file system. The default -value is +Controls whether the setuid bit is respected for the file system. +The default value is .Sy on . .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts Controls whether the file system is shared via SMB, and what options are to be -used. A file system with the +used. +A file system with the .Sy sharesmb property set to .Sy off @@ -1300,24 +1391,30 @@ Otherwise, the file system is automatically shared and unshared with the .Nm zfs Cm share and .Nm zfs Cm unshare -commands. If the property is set to +commands. +If the property is set to .Sy on , the .Xr sharemgr 1M -command is invoked with no options. Otherwise, the +command is invoked with no options. +Otherwise, the .Xr sharemgr 1M command is invoked with options equivalent to the contents of this property. .Pp Because SMB shares requires a resource name, a unique resource name is -constructed from the dataset name. The constructed name is a copy of the dataset -name except that the characters in the dataset name, which would be illegal in -the resource name, are replaced with underscore +constructed from the dataset name. +The constructed name is a copy of the dataset name except that the characters in +the dataset name, which would be illegal in the resource name, are replaced with +underscore .Pq Sy _ -characters. A pseudo property +characters. +A pseudo property .Qq name is also supported that allows you to replace the data set name with a specified -name. The specified name is then used to replace the prefix dataset in the case -of inheritance. For example, if the dataset +name. +The specified name is then used to replace the prefix dataset in the case of +inheritance. +For example, if the dataset .Em data/home/john is set to .Sy name Ns = Ns Sy john , @@ -1332,7 +1429,8 @@ is shared, it has a resource name of .Pp When SMB shares are created, the SMB share name appears as an entry in the .Pa .zfs/shares -directory. You can use the +directory. +You can use the .Nm ls or .Nm chmod @@ -1344,13 +1442,14 @@ property is changed for a dataset, the dataset and any children inheriting the property are re-shared with the new options, only if the property was previously set to .Sy off , -or if they were shared before the property was changed. If the new property is -set to +or if they were shared before the property was changed. +If the new property is set to .Sy off , the file systems are unshared. .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts Controls whether the file system is shared via NFS, and what options are to be -used. A file system with a +used. +A file system with a .Sy sharenfs property of .Sy off @@ -1363,10 +1462,12 @@ Otherwise, the file system is automatically shared and unshared with the .Nm zfs Cm share and .Nm zfs Cm unshare -commands. If the property is set to +commands. +If the property is set to .Sy on , .Xr share 1M -command is invoked with no options. Otherwise, the +command is invoked with no options. +Otherwise, the .Xr share 1M command is invoked with options equivalent to the contents of this property. .Pp @@ -1375,31 +1476,35 @@ When the property is changed for a dataset, the dataset and any children inheriting the property are re-shared with the new options, only if the property was previously .Sy off , -or if they were shared before the property was changed. If the new property is +or if they were shared before the property was changed. +If the new property is .Sy off , the file systems are unshared. .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput -Provide a hint to ZFS about handling of synchronous requests in this dataset. If +Provide a hint to ZFS about handling of synchronous requests in this dataset. +If .Sy logbias is set to .Sy latency .Pq the default , ZFS will use pool log devices .Pq if configured -to handle the requests at low latency. If +to handle the requests at low latency. +If .Sy logbias is set to .Sy throughput , -ZFS will not use configured pool log devices. ZFS will instead optimize -synchronous operations for global pool throughput and efficient use of -resources. +ZFS will not use configured pool log devices. +ZFS will instead optimize synchronous operations for global pool throughput and +efficient use of resources. .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible Controls whether the .Pa .zfs directory is hidden or visible in the root of the file system as discussed in the .Sx Snapshots -section. The default value is +section. +The default value is .Sy hidden . .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled Controls the behavior of synchronous requests @@ -1413,24 +1518,29 @@ controllers .Pq this is the default . .Sy always causes every file system transaction to be written and flushed before its -system call returns. This has a large performance penalty. +system call returns. +This has a large performance penalty. .Sy disabled -disables synchronous requests. File system transactions are only committed to -stable storage periodically. This option will give the highest performance. +disables synchronous requests. +File system transactions are only committed to stable storage periodically. +This option will give the highest performance. However, it is very dangerous as ZFS would be ignoring the synchronous -transaction demands of applications such as databases or NFS. Administrators -should only use this option when the risks are understood. +transaction demands of applications such as databases or NFS. +Administrators should only use this option when the risks are understood. .It Sy version Ns = Ns Em N Ns | Ns Sy current The on-disk version of this file system, which is independent of the pool -version. This property can only be set to later supported versions. See the +version. +This property can only be set to later supported versions. +See the .Nm zfs Cm upgrade command. .It Sy volsize Ns = Ns Em size -For volumes, specifies the logical size of the volume. By default, creating a -volume establishes a reservation of equal size. For storage pools with a version -number of 9 or higher, a +For volumes, specifies the logical size of the volume. +By default, creating a volume establishes a reservation of equal size. +For storage pools with a version number of 9 or higher, a .Sy refreservation -is set instead. Any changes to +is set instead. +Any changes to .Sy volsize are reflected in an equivalent change to the reservation .Po or @@ -1443,10 +1553,10 @@ can only be set to a multiple of and cannot be zero. .Pp The reservation is kept equal to the volume's logical size to prevent unexpected -behavior for consumers. Without the reservation, the volume could run out of -space, resulting in undefined behavior or data corruption, depending on how the -volume is used. These effects can also occur when the volume size is changed -while it is in use +behavior for consumers. +Without the reservation, the volume could run out of space, resulting in +undefined behavior or data corruption, depending on how the volume is used. +These effects can also occur when the volume size is changed while it is in use .Pq particularly when shrinking the size . Extreme care should be used when adjusting the volume size. .Pp @@ -1459,40 +1569,46 @@ can be created by specifying the .Fl s option to the .Nm zfs Cm create Fl V -command, or by changing the reservation after the volume has been created. A +command, or by changing the reservation after the volume has been created. +A .Qq sparse volume -is a volume where the reservation is less then the volume size. Consequently, -writes to a sparse volume can fail with +is a volume where the reservation is less then the volume size. +Consequently, writes to a sparse volume can fail with .Er ENOSPC -when the pool is low on space. For a sparse volume, changes to +when the pool is low on space. +For a sparse volume, changes to .Sy volsize are not reflected in the reservation. .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off Controls whether regular files should be scanned for viruses when a file is -opened and closed. In addition to enabling this property, the virus scan -service must also be enabled for virus scanning to occur. The default value is +opened and closed. +In addition to enabling this property, the virus scan service must also be +enabled for virus scanning to occur. +The default value is .Sy off . .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off -Controls whether extended attributes are enabled for this file system. The -default value is +Controls whether extended attributes are enabled for this file system. +The default value is .Sy on . .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off -Controls whether the dataset is managed from a non-global zone. See the +Controls whether the dataset is managed from a non-global zone. +See the .Sx Zones -section for more information. The default value is +section for more information. +The default value is .Sy off . .El .Pp The following three properties cannot be changed after the file system is -created, and therefore, should be set when the file system is created. If the -properties are not set with the +created, and therefore, should be set when the file system is created. +If the properties are not set with the .Nm zfs Cm create or .Nm zpool Cm create -commands, these properties are inherited from the parent dataset. If the parent -dataset lacks these properties due to having been created prior to these -features being supported, the new file system will have the default values for -these properties. +commands, these properties are inherited from the parent dataset. +If the parent dataset lacks these properties due to having been created prior to +these features being supported, the new file system will have the default values +for these properties. .Bl -tag -width "" .It Xo .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns @@ -1500,7 +1616,8 @@ these properties. .Xc Indicates whether the file name matching algorithm used by the file system should be case-sensitive, case-insensitive, or allow a combination of both -styles of matching. The default value for the +styles of matching. +The default value for the .Sy casesensitivity property is .Sy sensitive . @@ -1515,9 +1632,10 @@ The value for the .Sy casesensitivity property indicates that the file system can support requests for both -case-sensitive and case-insensitive matching behavior. Currently, -case-insensitive matching behavior on a file system that supports mixed behavior -is limited to the SMB server product. For more information about the +case-sensitive and case-insensitive matching behavior. +Currently, case-insensitive matching behavior on a file system that supports +mixed behavior is limited to the SMB server product. +For more information about the .Sy mixed value behavior, see the "ZFS Administration Guide". .It Xo @@ -1527,9 +1645,10 @@ value behavior, see the "ZFS Administration Guide". Indicates whether the file system should perform a .Sy unicode normalization of file names whenever two file names are compared, and which -normalization algorithm should be used. File names are always stored unmodified, -names are normalized as part of any comparison process. If this property is set -to a legal value other than +normalization algorithm should be used. +File names are always stored unmodified, names are normalized as part of any +comparison process. +If this property is set to a legal value other than .Sy none , and the .Sy utf8only @@ -1546,7 +1665,8 @@ This property cannot be changed after the file system is created. Indicates whether the file system should reject file names that include characters that are not present in the .Sy UTF-8 -character code set. If this property is explicitly set to +character code set. +If this property is explicitly set to .Sy off , the normalization property must either not be explicitly set or be set to .Sy none . @@ -1570,7 +1690,8 @@ When a file system is mounted, either through for legacy mounts or the .Nm zfs Cm mount command for normal file systems, its mount options are set according to its -properties. The correlation between properties and mount options is as follows: +properties. +The correlation between properties and mount options is as follows: .Bd -literal PROPERTY MOUNT OPTION devices devices/nodevices @@ -1582,8 +1703,10 @@ properties. The correlation between properties and mount options is as follows: .Pp In addition, these options can be set on a per-mount basis using the .Fl o -option, without affecting the property that is stored on disk. The values -specified on the command line override the values stored in the dataset. The +option, without affecting the property that is stored on disk. +The values specified on the command line override the values stored in the +dataset. +The .Sy nosuid option is an alias for .Sy nodevices Ns , Ns Sy nosetuid . @@ -1591,18 +1714,21 @@ These properties are reported as .Qq temporary by the .Nm zfs Cm get -command. If the properties are changed while the dataset is mounted, the new -setting overrides any temporary settings. +command. +If the properties are changed while the dataset is mounted, the new setting +overrides any temporary settings. .Ss "User Properties" In addition to the standard native properties, ZFS supports arbitrary user -properties. User properties have no effect on ZFS behavior, but applications or +properties. +User properties have no effect on ZFS behavior, but applications or administrators can use them to annotate datasets .Pq file systems, volumes, and snapshots . .Pp User property names must contain a colon .Pq Qq Sy \&: -character to distinguish them from native properties. They may contain lowercase -letters, numbers, and the following punctuation characters: colon +character to distinguish them from native properties. +They may contain lowercase letters, numbers, and the following punctuation +characters: colon .Pq Qq Sy \&: , dash .Pq Qq Sy - , @@ -1627,23 +1753,29 @@ independently-developed packages use the same property name for different purposes. .Pp The values of user properties are arbitrary strings, are always inherited, and -are never validated. All of the commands that operate on properties +are never validated. +All of the commands that operate on properties .Po Nm zfs Cm list , .Nm zfs Cm get , .Nm zfs Cm set , and so forth .Pc -can be used to manipulate both native properties and user properties. Use the +can be used to manipulate both native properties and user properties. +Use the .Nm zfs Cm inherit -command to clear a user property. If the property is not defined in any parent -dataset, it is removed entirely. Property values are limited to 8192 bytes. +command to clear a user property. +If the property is not defined in any parent dataset, it is removed entirely. +Property values are limited to 8192 bytes. .Ss ZFS Volumes as Swap or Dump Devices During an initial installation a swap device and dump device are created on ZFS -volumes in the ZFS root pool. By default, the swap area size is based on 1/2 the -size of physical memory up to 2 Gbytes. The size of the dump device depends on -the kernel's requirements at installation time. Separate ZFS volumes must be -used for the swap area and dump devices. Do not swap to a file on a ZFS file -system. A ZFS swap file configuration is not supported. +volumes in the ZFS root pool. +By default, the swap area size is based on 1/2 the size of physical memory up to +2 Gbytes. +The size of the dump device depends on the kernel's requirements at installation +time. +Separate ZFS volumes must be used for the swap area and dump devices. +Do not swap to a file on a ZFS file system. +A ZFS swap file configuration is not supported. .Pp If you need to change your swap area or dump device after the system is installed or upgraded, use the @@ -1664,30 +1796,31 @@ Displays a help message. .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... .Ar filesystem .Xc -Creates a new ZFS file system. The file system is automatically mounted -according to the +Creates a new ZFS file system. +The file system is automatically mounted according to the .Sy mountpoint property inherited from the parent. .Bl -tag -width "-o" .It Fl o Ar property Ns = Ns Ar value Sets the specified property as if the command .Nm zfs Cm set Ar property Ns = Ns Ar value -was invoked at the same time the dataset was created. Any editable ZFS property -can also be set at creation time. Multiple +was invoked at the same time the dataset was created. +Any editable ZFS property can also be set at creation time. +Multiple .Fl o -options can be specified. An error results if the same property is specified in -multiple +options can be specified. +An error results if the same property is specified in multiple .Fl o options. .It Fl p -Creates all the non-existing parent datasets. Datasets created in this manner -are automatically mounted according to the +Creates all the non-existing parent datasets. +Datasets created in this manner are automatically mounted according to the .Sy mountpoint -property inherited from their parent. Any property specified on the command line -using the +property inherited from their parent. +Any property specified on the command line using the .Fl o -option is ignored. If the target filesystem already exists, the operation -completes successfully. +option is ignored. +If the target filesystem already exists, the operation completes successfully. .El .It Xo .Nm @@ -1697,13 +1830,14 @@ completes successfully. .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... .Fl V Ar size Ar volume .Xc -Creates a volume of the given size. The volume is exported as a block device in +Creates a volume of the given size. +The volume is exported as a block device in .Pa /dev/zvol/{dsk,rdsk}/path , where .Em path -is the name of the volume in the ZFS namespace. The size represents the logical -size as exported by the device. By default, a reservation of equal size is -created. +is the name of the volume in the ZFS namespace. +The size represents the logical size as exported by the device. +By default, a reservation of equal size is created. .Pp .Ar size is automatically rounded up to the nearest 128 Kbytes to ensure that the volume @@ -1719,24 +1853,26 @@ the resulting behavior is undefined. .It Fl o Ar property Ns = Ns Ar value Sets the specified property as if the .Nm zfs Cm set Ar property Ns = Ns Ar value -command was invoked at the same time the dataset was created. Any editable ZFS -property can also be set at creation time. Multiple +command was invoked at the same time the dataset was created. +Any editable ZFS property can also be set at creation time. +Multiple .Fl o -options can be specified. An error results if the same property is specified in -multiple +options can be specified. +An error results if the same property is specified in multiple .Fl o options. .It Fl p -Creates all the non-existing parent datasets. Datasets created in this manner -are automatically mounted according to the +Creates all the non-existing parent datasets. +Datasets created in this manner are automatically mounted according to the .Sy mountpoint -property inherited from their parent. Any property specified on the command line -using the +property inherited from their parent. +Any property specified on the command line using the .Fl o -option is ignored. If the target filesystem already exists, the operation -completes successfully. +option is ignored. +If the target filesystem already exists, the operation completes successfully. .It Fl s -Creates a sparse volume with no reservation. See +Creates a sparse volume with no reservation. +See .Sy volsize in the .Sx Native Properties @@ -1748,9 +1884,10 @@ section for more information about sparse volumes. .Op Fl Rfnprv .Ar filesystem Ns | Ns Ar volume .Xc -Destroys the given dataset. By default, the command unshares any file systems -that are currently shared, unmounts any file systems that are currently -mounted, and refuses to destroy a dataset that has active dependents +Destroys the given dataset. +By default, the command unshares any file systems that are currently shared, +unmounts any file systems that are currently mounted, and refuses to destroy a +dataset that has active dependents .Pq children or clones . .Bl -tag -width "-R" .It Fl R @@ -1759,12 +1896,14 @@ target hierarchy. .It Fl f Force an unmount of any file systems using the .Nm unmount Fl f -command. This option has no effect on non-file systems or unmounted file -systems. +command. +This option has no effect on non-file systems or unmounted file systems. .It Fl n Do a dry-run .Pq Qq No-op -deletion. No data will be deleted. This is useful in conjunction with the +deletion. +No data will be deleted. +This is useful in conjunction with the .Fl v or .Fl p @@ -1794,22 +1933,25 @@ The given snapshots are destroyed immediately if and only if the .Nm zfs Cm destroy command without the .Fl d -option would have destroyed it. Such immediate destruction would occur, for -example, if the snapshot had no clones and the user-initiated reference count -were zero. +option would have destroyed it. +Such immediate destruction would occur, for example, if the snapshot had no +clones and the user-initiated reference count were zero. .Pp If a snapshot does not qualify for immediate destruction, it is marked for -deferred deletion. In this state, it exists as a usable, visible snapshot until -both of the preconditions listed above are met, at which point it is destroyed. +deferred deletion. +In this state, it exists as a usable, visible snapshot until both of the +preconditions listed above are met, at which point it is destroyed. .Pp An inclusive range of snapshots may be specified by separating the first and -last snapshots with a percent sign. The first and/or last snapshots may be left -blank, in which case the filesystem's oldest or newest snapshot will be implied. +last snapshots with a percent sign. +The first and/or last snapshots may be left blank, in which case the +filesystem's oldest or newest snapshot will be implied. .Pp Multiple snapshots .Pq or ranges of snapshots of the same filesystem or volume may be specified in a comma-separated list of -snapshots. Only the snapshot's short name +snapshots. +Only the snapshot's short name .Po the part after the .Sy @ .Pc @@ -1818,7 +1960,8 @@ multiple snapshots. .Bl -tag -width "-R" .It Fl R Recursively destroy all clones of these snapshots, including the clones, -snapshots, and children. If this flag is specified, the +snapshots, and children. +If this flag is specified, the .Fl d flag will have no effect. .It Fl d @@ -1826,8 +1969,9 @@ Defer snapshot deletion. .It Fl n Do a dry-run .Pq Qq No-op -deletion. No data will be deleted. This is -useful in conjunction with the +deletion. +No data will be deleted. +This is useful in conjunction with the .Fl p or .Fl v @@ -1861,9 +2005,12 @@ The given bookmark is destroyed. .Oo Fl o Ar property Ns = Ns value Oc Ns ... .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... .Xc -Creates snapshots with the given names. All previous modifications by successful -system calls to the file system are part of the snapshots. Snapshots are taken -atomically, so that all snapshots correspond to the same moment in time. See the +Creates snapshots with the given names. +All previous modifications by successful system calls to the file system are +part of the snapshots. +Snapshots are taken atomically, so that all snapshots correspond to the same +moment in time. +See the .Sx Snapshots section for details. .Bl -tag -width "-o" @@ -1880,12 +2027,13 @@ Recursively create snapshots of all descendent datasets .Op Fl Rfr .Ar snapshot .Xc -Roll back the given dataset to a previous snapshot. When a dataset is rolled -back, all data that has changed since the snapshot is discarded, and the dataset -reverts to the state at the time of the snapshot. By default, the command -refuses to roll back to a snapshot other than the most recent one. In order to -do so, all intermediate snapshots and bookmarks must be destroyed by specifying -the +Roll back the given dataset to a previous snapshot. +When a dataset is rolled back, all data that has changed since the snapshot is +discarded, and the dataset reverts to the state at the time of the snapshot. +By default, the command refuses to roll back to a snapshot other than the most +recent one. +In order to do so, all intermediate snapshots and bookmarks must be destroyed by +specifying the .Fl r option. .Pp @@ -1893,8 +2041,9 @@ The .Fl rR options do not recursively destroy the child snapshots of a recursive snapshot. Only direct snapshots of the specified filesystem are destroyed by either of -these options. To completely roll back a recursive snapshot, you must rollback -the individual child snapshots. +these options. +To completely roll back a recursive snapshot, you must rollback the individual +child snapshots. .Bl -tag -width "-R" .It Fl R Destroy any more recent snapshots and bookmarks, as well as any clones of those @@ -1913,21 +2062,24 @@ Destroy any snapshots and bookmarks more recent than the one specified. .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... .Ar snapshot Ar filesystem Ns | Ns Ar volume .Xc -Creates a clone of the given snapshot. See the +Creates a clone of the given snapshot. +See the .Sx Clones -section for details. The target dataset can be located anywhere in the ZFS -hierarchy, and is created as the same type as the original. +section for details. +The target dataset can be located anywhere in the ZFS hierarchy, and is created +as the same type as the original. .Bl -tag -width "-o" .It Fl o Ar property Ns = Ns Ar value Sets the specified property; see .Nm zfs Cm create for details. .It Fl p -Creates all the non-existing parent datasets. Datasets created in this manner -are automatically mounted according to the +Creates all the non-existing parent datasets. +Datasets created in this manner are automatically mounted according to the .Sy mountpoint -property inherited from their parent. If the target filesystem or volume already -exists, the operation completes successfully. +property inherited from their parent. +If the target filesystem or volume already exists, the operation completes +successfully. .El .It Xo .Nm @@ -1936,16 +2088,20 @@ exists, the operation completes successfully. .Xc Promotes a clone file system to no longer be dependent on its .Qq origin -snapshot. This makes it possible to destroy the file system that the clone was -created from. The clone parent-child dependency relationship is reversed, so -that the origin file system becomes a clone of the specified file system. +snapshot. +This makes it possible to destroy the file system that the clone was created +from. +The clone parent-child dependency relationship is reversed, so that the origin +file system becomes a clone of the specified file system. .Pp The snapshot that was cloned, and any snapshots previous to this snapshot, are -now owned by the promoted clone. The space they use moves from the origin file -system to the promoted clone, so enough space must be available to accommodate -these snapshots. No new space is consumed by this operation, but the space -accounting is adjusted. The promoted clone must not have any conflicting -snapshot names of its own. The +now owned by the promoted clone. +The space they use moves from the origin file system to the promoted clone, so +enough space must be available to accommodate these snapshots. +No new space is consumed by this operation, but the space accounting is +adjusted. +The promoted clone must not have any conflicting snapshot names of its own. +The .Cm rename subcommand can be used to rename any conflicting snapshots. .It Xo @@ -1961,18 +2117,20 @@ subcommand can be used to rename any conflicting snapshots. .Ar filesystem Ns | Ns Ar volume .Ar filesystem Ns | Ns Ar volume .Xc -Renames the given dataset. The new target can be located anywhere in the ZFS -hierarchy, with the exception of snapshots. Snapshots can only be renamed within -the parent file system or volume. When renaming a snapshot, the parent file -system of the snapshot does not need to be specified as part of the second -argument. Renamed file systems can inherit new mount points, in which case they -are unmounted and remounted at the new mount point. +Renames the given dataset. +The new target can be located anywhere in the ZFS hierarchy, with the exception +of snapshots. +Snapshots can only be renamed within the parent file system or volume. +When renaming a snapshot, the parent file system of the snapshot does not need +to be specified as part of the second argument. +Renamed file systems can inherit new mount points, in which case they are +unmounted and remounted at the new mount point. .Bl -tag -width "-a" .It Fl f Force unmount any filesystems that need to be unmounted in the process. .It Fl p -Creates all the nonexistent parent datasets. Datasets created in this manner are -automatically mounted according to the +Creates all the nonexistent parent datasets. +Datasets created in this manner are automatically mounted according to the .Sy mountpoint property inherited from their parent. .El @@ -1982,8 +2140,8 @@ property inherited from their parent. .Fl r .Ar snapshot Ar snapshot .Xc -Recursively rename the snapshots of all descendent datasets. Snapshots are the -only dataset that can be renamed recursively. +Recursively rename the snapshots of all descendent datasets. +Snapshots are the only dataset that can be renamed recursively. .It Xo .Nm .Cm list @@ -1995,9 +2153,10 @@ only dataset that can be renamed recursively. .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... .Xc -Lists the property information for the given datasets in tabular form. If -specified, you can list property information by the absolute pathname or the -relative pathname. By default, all file systems and volumes are displayed. +Lists the property information for the given datasets in tabular form. +If specified, you can list property information by the absolute pathname or the +relative pathname. +By default, all file systems and volumes are displayed. Snapshots are displayed if the .Sy listsnaps property is @@ -2010,8 +2169,9 @@ The following fields are displayed, .Sy mountpoint . .Bl -tag -width "-H" .It Fl H -Used for scripting mode. Do not print headers and separate fields by a single -tab instead of arbitrary white space. +Used for scripting mode. +Do not print headers and separate fields by a single tab instead of arbitrary +white space. .It Fl S Ar property Same as the .Fl s @@ -2025,7 +2185,8 @@ of .Sy 1 will display only the dataset and its direct children. .It Fl o Ar property -A comma-separated list of properties to display. The property must be: +A comma-separated list of properties to display. +The property must be: .Bl -bullet .It One of the properties described in the @@ -2040,8 +2201,8 @@ to display the dataset name .It The value .Sy space -to display space usage properties on file systems and volumes. This is a -shortcut for specifying +to display space usage properties on file systems and volumes. +This is a shortcut for specifying .Fl o Sy name Ns , Ns Sy avail Ns , Ns Sy used Ns , Ns Sy usedsnap Ns , Ns .Sy usedds Ns , Ns Sy usedrefreserv Ns , Ns Sy usedchild Fl t .Sy filesystem Ns , Ns Sy volume @@ -2055,18 +2216,19 @@ values. Recursively display any children of the dataset on the command line. .It Fl s Ar property A property for sorting the output by column in ascending order based on the -value of the property. The property must be one of the properties described in -the +value of the property. +The property must be one of the properties described in the .Sx Properties section, or the special value .Sy name -to sort by the dataset name. Multiple properties can be specified at one time -using multiple +to sort by the dataset name. +Multiple properties can be specified at one time using multiple .Fl s -property options. Multiple +property options. +Multiple .Fl s -options are evaluated from left to right in decreasing order of importance. The -following is a list of sorting criteria: +options are evaluated from left to right in decreasing order of importance. +The following is a list of sorting criteria: .Bl -bullet .It Numeric types sort in numeric order. @@ -2101,16 +2263,19 @@ displays only snapshots. .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... .Xc Sets the property or list of properties to the given value(s) for each dataset. -Only some properties can be edited. See the +Only some properties can be edited. +See the .Sx Properties section for more information on what properties can be set and acceptable -values. Numeric values can be specified as exact values, or in a human-readable -form with a suffix of +values. +Numeric values can be specified as exact values, or in a human-readable form +with a suffix of .Sy B , K , M , G , T , P , E , Z .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, or zettabytes, respectively .Pc . -User properties can be set on snapshots. For more information, see the +User properties can be set on snapshots. +For more information, see the .Sx User Properties section. .It Xo @@ -2124,21 +2289,22 @@ section. .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ... .Xc -Displays properties for the given datasets. If no datasets are specified, then -the command displays properties for all datasets on the system. For each -property, the following columns are displayed: +Displays properties for the given datasets. +If no datasets are specified, then the command displays properties for all +datasets on the system. +For each property, the following columns are displayed: .Bd -literal name Dataset name property Property name value Property value - source Property source. Can either be local, default, + source Property source. Can either be local, default, temporary, inherited, or none (-). .Ed .Pp All columns are displayed by default, though this can be controlled by using the .Fl o -option. This command takes a comma-separated list of properties as described in -the +option. +This command takes a comma-separated list of properties as described in the .Sx Native Properties and .Sx User Properties @@ -2150,9 +2316,9 @@ can be used to display all properties that apply to the given dataset's type .Pq filesystem, volume, snapshot, or bookmark . .Bl -tag -width "-H" .It Fl H -Display output in a form more easily parsed by scripts. Any headers are omitted, -and fields are explicitly separated by a single tab instead of an arbitrary -amount of space. +Display output in a form more easily parsed by scripts. +Any headers are omitted, and fields are explicitly separated by a single tab +instead of an arbitrary amount of space. .It Fl d Ar depth Recursively display any children of the dataset, limiting the recursion to .Ar depth . @@ -2170,9 +2336,9 @@ values. .It Fl r Recursively display properties for any children. .It Fl s Ar source -A comma-separated list of sources to display. Those properties coming from a -source other than those in this list are ignored. Each source must be one of the -following: +A comma-separated list of sources to display. +Those properties coming from a source other than those in this list are ignored. +Each source must be one of the following: .Sy local , .Sy default , .Sy inherited , @@ -2200,7 +2366,8 @@ or Clears the specified property, causing it to be inherited from an ancestor, restored to default if no ancestor has the property set, or with the .Fl S -option reverted to the received value if one exists. See the +option reverted to the received value if one exists. +See the .Sx Properties section for a listing of default values, and details on which properties can be inherited. @@ -2231,28 +2398,31 @@ Displays a list of currently supported file system versions. .Op Fl V Ar version .Fl a | Ar filesystem .Xc -Upgrades file systems to a new on-disk version. Once this is done, the file -systems will no longer be accessible on systems running older versions of the -software. +Upgrades file systems to a new on-disk version. +Once this is done, the file systems will no longer be accessible on systems +running older versions of the software. .Nm zfs Cm send streams generated from new snapshots of these file systems cannot be accessed on systems running older versions of the software. .Pp -In general, the file system version is independent of the pool version. See +In general, the file system version is independent of the pool version. +See .Xr zpool 1M for information on the .Nm zpool Cm upgrade command. .Pp In some cases, the file system version and the pool version are interrelated and -the pool version must be upgraded before the file system version can be upgraded. +the pool version must be upgraded before the file system version can be +upgraded. .Bl -tag -width "-V" .It Fl V Ar version Upgrade to the specified .Ar version . If the .Fl V -flag is not specified, this command upgrades to the most recent version. This +flag is not specified, this command upgrades to the most recent version. +This option can only be used to increase the version number, and only up to the most recent version supported by this software. .It Fl a @@ -2273,7 +2443,8 @@ Upgrade the specified file system and all descendent file systems. .Ar filesystem Ns | Ns Ar snapshot .Xc Displays space consumed by, and quotas on, each user in the specified filesystem -or snapshot. This corresponds to the +or snapshot. +This corresponds to the .Sy userused@ Ns Em user and .Sy userquota@ Ns Em user @@ -2282,10 +2453,12 @@ properties. .It Fl H Do not print headers, use tab-delimited output. .It Fl S Ar field -Sort by this field in reverse order. See +Sort by this field in reverse order. +See .Fl s . .It Fl i -Translate SID to POSIX ID. The POSIX ID may be ephemeral if no mapping exists. +Translate SID to POSIX ID. +The POSIX ID may be ephemeral if no mapping exists. Normal POSIX interfaces .Po for example, .Xr stat 2 , @@ -2295,11 +2468,14 @@ perform this translation, so the .Fl i option allows the output from .Nm zfs Cm userspace -to be compared directly with those utilities. However, +to be compared directly with those utilities. +However, .Fl i may lead to confusion if some files were created by an SMB user before a -SMB-to-POSIX name mapping was established. In such a case, some files will be -owned by the SMB entity and some by the POSIX entity. However, the +SMB-to-POSIX name mapping was established. +In such a case, some files will be owned by the SMB entity and some by the POSIX +entity. +However, the .Fl i option will report that the POSIX entity has the total usage and quota for both. .It Fl n @@ -2316,12 +2492,14 @@ Use exact .Pq parsable numeric output. .It Fl s Ar field -Sort output by this field. The +Sort output by this field. +The .Fl s and .Fl S flags may be specified multiple times to sort first by one field, then by -another. The default is +another. +The default is .Fl s Sy type Fl s Sy name . .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Print only the specified types from the following set: @@ -2345,7 +2523,8 @@ The default can be changed to include group types. .Ar filesystem Ns | Ns Ar snapshot .Xc Displays space consumed by, and quotas on, each group in the specified -filesystem or snapshot. This subcommand is identical to +filesystem or snapshot. +This subcommand is identical to .Nm zfs Cm userspace , except that the default types to display are .Fl t Sy posixgroup Ns , Ns Sy smbgroup . @@ -2364,17 +2543,19 @@ Displays all ZFS file systems currently mounted. Mounts ZFS file systems. .Bl -tag -width "-O" .It Fl O -Perform an overlay mount. See +Perform an overlay mount. +See .Xr mount 1M for more information. .It Fl a -Mount all available ZFS file systems. Invoked automatically as part of the boot -process. +Mount all available ZFS file systems. +Invoked automatically as part of the boot process. .It Ar filesystem Mount the specified filesystem. .It Fl o Ar options An optional, comma-separated list of mount options to use temporarily for the -duration of the mount. See the +duration of the mount. +See the .Sx Temporary Mount Point Properties section for details. .It Fl v @@ -2389,11 +2570,12 @@ Report mount progress. Unmounts currently mounted ZFS file systems. .Bl -tag -width "-a" .It Fl a -Unmount all available ZFS file systems. Invoked automatically as part of the -shutdown process. +Unmount all available ZFS file systems. +Invoked automatically as part of the shutdown process. .It Ar filesystem Ns | Ns Ar mountpoint -Unmount the specified filesystem. The command can also be given a path to a ZFS -file system mount point on the system. +Unmount the specified filesystem. +The command can also be given a path to a ZFS file system mount point on the +system. .It Fl f Forcefully unmount the file system, even if it is currently in use. .El @@ -2405,14 +2587,15 @@ Forcefully unmount the file system, even if it is currently in use. Shares available ZFS file systems. .Bl -tag -width "-a" .It Fl a -Share all available ZFS file systems. Invoked automatically as part of the boot -process. +Share all available ZFS file systems. +Invoked automatically as part of the boot process. .It Ar filesystem Share the specified filesystem according to the .Sy sharenfs and .Sy sharesmb -properties. File systems are shared when the +properties. +File systems are shared when the .Sy sharenfs or .Sy sharesmb @@ -2426,23 +2609,25 @@ property is set. Unshares currently shared ZFS file systems. .Bl -tag -width "-a" .It Fl a -Unshare all available ZFS file systems. Invoked automatically as part of the -shutdown process. +Unshare all available ZFS file systems. +Invoked automatically as part of the shutdown process. .It Ar filesystem Ns | Ns Ar mountpoint -Unshare the specified filesystem. The command can also be given a path to a ZFS -file system shared on the system. +Unshare the specified filesystem. +The command can also be given a path to a ZFS file system shared on the system. .El .It Xo .Nm .Cm bookmark .Ar snapshot bookmark .Xc -Creates a bookmark of the given snapshot. Bookmarks mark the point in time when -the snapshot was created, and can be used as the incremental source for a +Creates a bookmark of the given snapshot. +Bookmarks mark the point in time when the snapshot was created, and can be used +as the incremental source for a .Nm zfs Cm send command. .Pp -This feature must be enabled to be used. See +This feature must be enabled to be used. +See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy bookmarks @@ -2456,18 +2641,20 @@ feature. .Xc Creates a stream representation of the second .Ar snapshot , -which is written to standard output. The output can be redirected to a file or -to a different system +which is written to standard output. +The output can be redirected to a file or to a different system .Po for example, using .Xr ssh 1 .Pc . By default, a full stream is generated. .Bl -tag -width "-D" .It Fl D, -dedup -Generate a deduplicated stream. Blocks which would have been sent multiple times -in the send stream will only be sent once. The receiving system must also -support this feature to receive a deduplicated stream. This flag can be used -regardless of the dataset's +Generate a deduplicated stream. +Blocks which would have been sent multiple times in the send stream will only be +sent once. +The receiving system must also support this feature to receive a deduplicated +stream. +This flag can be used regardless of the dataset's .Sy dedup property, but performance will be much better if the filesystem uses a dedup-capable checksum @@ -2476,7 +2663,8 @@ dedup-capable checksum .Pc . .It Fl I Ar snapshot Generate a stream package that sends all intermediary snapshots from the first -snapshot to the second snapshot. For example, +snapshot to the second snapshot. +For example, .Fl I Em @a Em fs@d is similar to .Fl i Em @a Em fs@b Ns ; Fl i Em @b Em fs@c Ns ; Fl i Em @c Em fs@d . @@ -2484,15 +2672,16 @@ 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. This flag has no -effect if the +Generate a stream which may contain blocks larger than 128KB. +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. The receiving system -must have the +property of this filesystem has never been set above 128KB. +The receiving system must have the .Sy large_blocks -pool feature enabled as well. See +pool feature enabled as well. +See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy large_blocks @@ -2501,9 +2690,9 @@ feature. Print machine-parsable verbose information about the stream package generated. .It Fl R, -replicate Generate a replication stream package, which will replicate the specified -file system, and all descendent file systems, up to the named snapshot. When -received, all properties, snapshots, descendent file systems, and clones are -preserved. +file system, and all descendent file systems, up to the named snapshot. +When received, all properties, snapshots, descendent file systems, and clones +are preserved. .Pp If the .Fl i @@ -2511,9 +2700,10 @@ or .Fl I flags are used in conjunction with the .Fl R -flag, an incremental replication stream is generated. The current values of -properties, and current snapshot and file system names are set when the stream -is received. If the +flag, an incremental replication stream is generated. +The current values of properties, and current snapshot and file system names are +set when the stream is received. +If the .Fl F flag is specified when this stream is received, snapshots and file systems that do not exist on the sending side are destroyed. @@ -2522,28 +2712,41 @@ Generate a more compact stream by using .Sy WRITE_EMBEDDED records for blocks which are stored more compactly on disk by the .Sy embedded_data -pool feature. This flag has no effect if the +pool feature. +This flag has no effect if the .Sy embedded_data -feature is disabled. The receiving system must have the +feature is disabled. +The receiving system must have the .Sy embedded_data -feature enabled. If the +feature enabled. +If the .Sy lz4_compress feature is active on the sending system, then the receiving system must have -that feature enabled as well. See +that feature enabled as well. +See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy embedded_data feature. .It Fl c, -compressed Generate a more compact stream by using compressed WRITE records for blocks -which are compressed on disk and in memory (see the -.Sy compression No property for details). If the Sy lz4_compress No feature -is active on the sending system, then the receiving system must have that -feature enabled as well. If the -.Sy large_blocks No feature is enabled on the sending system but the Fl L +which are compressed on disk and in memory +.Po see the +.Sy compression +property for details +.Pc . +If the +.Sy lz4_compress +feature is active on the sending system, then the receiving system must have +that feature enabled as well. +If the +.Sy large_blocks +feature is enabled on the sending system but the +.Fl L option is not supplied in conjunction with -.Fl c, No then the data will be decompressed before sending so it can be split -into smaller block sizes. +.Fl c , +then the data will be decompressed before sending so it can be split into +smaller block sizes. .It Fl i Ar snapshot Generate an incremental stream from the first .Ar snapshot @@ -2569,26 +2772,29 @@ not just .It Fl n, -dryrun Do a dry-run .Pq Qq No-op -send. Do not generate any actual send data. This is useful in conjunction with -the +send. +Do not generate any actual send data. +This is useful in conjunction with the .Fl v or .Fl P -flags to determine what data will be sent. In this case, the verbose output will -be written to standard output +flags to determine what data will be sent. +In this case, the verbose output will be written to standard output .Po contrast with a non-dry-run, where the stream is written to standard output and the verbose output goes to standard error .Pc . .It Fl p, -props -Include the dataset's properties in the stream. This flag is implicit when +Include the dataset's properties in the stream. +This flag is implicit when .Fl R -is specified. The receiving system must also support this feature. +is specified. +The receiving system must also support this feature. .It Fl v, -verbose -Print verbose information about the stream package generated. This information -includes a per-second report of how much data has been sent. +Print verbose information about the stream package generated. +This information includes a per-second report of how much data has been sent. .Pp -The format of the stream is committed. You will be able to receive your streams -on future versions of ZFS . +The format of the stream is committed. +You will be able to receive your streams on future versions of ZFS . .El .It Xo .Nm @@ -2598,57 +2804,73 @@ on future versions of ZFS . .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot .Xc Generate a send stream, which may be of a filesystem, and may be incremental -from a bookmark. If the destination is a filesystem or volume, the pool must be -read-only, or the filesystem must not be mounted. When the stream generated from -a filesystem or volume is received, the default snapshot name will be +from a bookmark. +If the destination is a filesystem or volume, the pool must be read-only, or the +filesystem must not be mounted. +When the stream generated from a filesystem or volume is received, the default +snapshot name will be .Qq --head-- . .Bl -tag -width "-L" .It Fl L, -large-block -Generate a stream which may contain blocks larger than 128KB. This flag has no -effect if the +Generate a stream which may contain blocks larger than 128KB. +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. The receiving system -must have the +property of this filesystem has never been set above 128KB. +The receiving system must have the .Sy large_blocks -pool feature enabled as well. See +pool feature enabled as well. +See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy large_blocks feature. .It Fl c, -compressed Generate a more compact stream by using compressed WRITE records for blocks -which are compressed on disk and in memory (see the -.Sy compression No property for details). If the Sy lz4_compress No feature is -active on the sending system, then the receiving system must have that feature -enabled as well. If the -.Sy large_blocks No feature is enabled on the sending system but the Fl L +which are compressed on disk and in memory +.Po see the +.Sy compression +property for details +.Pc . +If the +.Sy lz4_compress +feature is active on the sending system, then the receiving system must have +that feature enabled as well. +If the +.Sy large_blocks +feature is enabled on the sending system but the +.Fl L option is not supplied in conjunction with -.Fl c, No then the data will be decompressed before sending so it can be split -into smaller block sizes. +.Fl c , +then the data will be decompressed before sending so it can be split into +smaller block sizes. .It Fl e, -embed Generate a more compact stream by using .Sy WRITE_EMBEDDED records for blocks which are stored more compactly on disk by the .Sy embedded_data -pool feature. This flag has no effect if the +pool feature. +This flag has no effect if the .Sy embedded_data -feature is disabled. The receiving system must have the +feature is disabled. +The receiving system must have the .Sy embedded_data -feature enabled. If the +feature enabled. +If the .Sy lz4_compress feature is active on the sending system, then the receiving system must have -that feature enabled as well. See +that feature enabled as well. +See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy embedded_data feature. .It Fl i Ar snapshot Ns | Ns Ar bookmark -Generate an incremental send stream. The incremental source must be an earlier -snapshot in the destination's history. It will commonly be an earlier snapshot -in the destination's file system, in which case it can be specified as the last -component of the name +Generate an incremental send stream. +The incremental source must be an earlier snapshot in the destination's history. +It will commonly be an earlier snapshot in the destination's file system, in +which case it can be specified as the last component of the name .Po the .Sy # or @@ -2667,10 +2889,12 @@ origin, etc. .Fl t .Ar receive_resume_token .Xc -Creates a send stream which resumes an interrupted receive. The +Creates a send stream which resumes an interrupted receive. +The .Ar receive_resume_token -is the value of this property on the filesystem -or volume that was being received into. See the documentation for +is the value of this property on the filesystem or volume that was being +received into. +See the documentation for .Sy zfs receive -s for more details. .It Xo @@ -2688,8 +2912,9 @@ for more details. .Ar filesystem .Xc Creates a snapshot whose contents are as specified in the stream provided on -standard input. If a full stream is received, then a new file system is created -as well. Streams are created using the +standard input. +If a full stream is received, then a new file system is created as well. +Streams are created using the .Nm zfs Cm send subcommand, which by default creates a full stream. .Nm zfs Cm recv @@ -2698,7 +2923,8 @@ can be used as an alias for .Pp If an incremental stream is received, then the destination file system must already exist, and its most recent snapshot must match the incremental stream's -source. For +source. +For .Sy zvols , the destination device link is destroyed and recreated, which means the .Sy zvol @@ -2723,8 +2949,9 @@ options. .Pp If the argument is a snapshot name, the specified .Ar snapshot -is created. If the argument is a file system or volume name, a snapshot with the -same name as the sent snapshot is created within the specified +is created. +If the argument is a file system or volume name, a snapshot with the same name +as the sent snapshot is created within the specified .Ar filesystem or .Ar volume . @@ -2748,7 +2975,8 @@ option is specified, all but the first element of the sent snapshot's file system path .Pq usually the pool name is used and any required intermediate file systems within the specified one are -created. If the +created. +If the .Fl e option is specified, then only the last element of the sent snapshot's file system name @@ -2757,7 +2985,8 @@ is used as the target file system name. .Bl -tag -width "-F" .It Fl F Force a rollback of the file system to the most recent snapshot before -performing the receive operation. If receiving an incremental replication stream +performing the receive operation. +If receiving an incremental replication stream .Po for example, one generated by .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I .Pc , @@ -2771,16 +3000,18 @@ Discard all but the last element of the sent snapshot's file system name, using that element to determine the name of the target file system for the new snapshot as described in the paragraph above. .It Fl n -Do not actually receive the stream. This can be useful in conjunction with the +Do not actually receive the stream. +This can be useful in conjunction with the .Fl v option to verify the name the receive operation would use. .It Fl o Sy origin Ns = Ns Ar snapshot Forces the stream to be received as a clone of the given snapshot. If the stream is a full send stream, this will create the filesystem -described by the stream as a clone of the specified snapshot. Which -snapshot was specified will not affect the success or failure of the -receive, as long as the snapshot does exist. If the stream is an -incremental send stream, all the normal verification will be performed. +described by the stream as a clone of the specified snapshot. +Which snapshot was specified will not affect the success or failure of the +receive, as long as the snapshot does exist. +If the stream is an incremental send stream, all the normal verification will be +performed. .It Fl u File system that is associated with the received stream is not mounted. .It Fl v @@ -2788,8 +3019,8 @@ Print verbose information about the stream and the time required to perform the receive operation. .It Fl s If the receive is interrupted, save the partially received state, rather -than deleting it. Interruption may be due to premature termination of -the stream +than deleting it. +Interruption may be due to premature termination of the stream .Po e.g. due to network failure or failure of the remote system if the stream is being read over a network connection .Pc , @@ -2807,7 +3038,8 @@ property of the filesystem or volume which is received into. .Pp To use this flag, the storage pool must have the .Sy extensible_dataset -feature enabled. See +feature enabled. +See .Xr zpool-features 5 for details on ZFS feature flags. .El @@ -2826,7 +3058,8 @@ deleting its saved partially received state. .Ar filesystem Ns | Ns Ar volume .Xc Displays permissions that have been delegated on the specified filesystem or -volume. See the other forms of +volume. +See the other forms of .Nm zfs Cm allow for more information. .It Xo @@ -2862,32 +3095,36 @@ only for the specified file system. .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ... Explicitly specify that permissions are delegated to the user. .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... -Specifies to whom the permissions are delegated. Multiple entities can be -specified as a comma-separated list. If neither of the +Specifies to whom the permissions are delegated. +Multiple entities can be specified as a comma-separated list. +If neither of the .Fl gu options are specified, then the argument is interpreted preferentially as the keyword .Sy everyone , -then as a user name, and lastly as a group name. To specify a user or group -named +then as a user name, and lastly as a group name. +To specify a user or group named .Qq everyone , use the .Fl g or .Fl u -options. To specify a group with the same name as a user, use the +options. +To specify a group with the same name as a user, use the .Fl g options. .It Xo .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns .Ar setname Oc Ns ... .Xc -The permissions to delegate. Multiple permissions may be specified as a -comma-separated list. Permission names are the same as ZFS subcommand and -property names. See the property list below. Property set names, -which begin with +The permissions to delegate. +Multiple permissions may be specified as a comma-separated list. +Permission names are the same as ZFS subcommand and property names. +See the property list below. +Property set names, which begin with .Sy @ , -may be specified. See the +may be specified. +See the .Fl s form below for details. .El @@ -2898,7 +3135,8 @@ options are specified, or both are, then the permissions are allowed for the file system or volume, and all of its descendents. .Pp Permissions are generally the ability to use a ZFS subcommand or change a ZFS -property. The following permissions are available: +property. +The following permissions are available: .Bd -literal NAME TYPE NOTES allow subcommand Must also have the permission that is being @@ -2973,7 +3211,8 @@ zoned property .Xc Sets .Qq create time -permissions. These permissions are granted +permissions. +These permissions are granted .Pq locally to the creator of any newly-created descendent file system. .It Xo @@ -2984,12 +3223,13 @@ to the creator of any newly-created descendent file system. .Ar setname Oc Ns ... .Ar filesystem Ns | Ns Ar volume .Xc -Defines or adds permissions to a permission set. The set can be used by other +Defines or adds permissions to a permission set. +The set can be used by other .Nm zfs Cm allow -commands for the specified file system and its descendents. Sets are evaluated -dynamically, so changes to a set are immediately reflected. Permission sets -follow the same naming restrictions as ZFS file systems, but the name must begin -with +commands for the specified file system and its descendents. +Sets are evaluated dynamically, so changes to a set are immediately reflected. +Permission sets follow the same naming restrictions as ZFS file systems, but the +name must begin with .Sy @ , and can be no more than 64 characters long. .It Xo @@ -3019,21 +3259,25 @@ and can be no more than 64 characters long. .Xc Removes permissions that were granted with the .Nm zfs Cm allow -command. No permissions are explicitly denied, so other permissions granted are -still in effect. For example, if the permission is granted by an ancestor. If no -permissions are specified, then all permissions for the specified +command. +No permissions are explicitly denied, so other permissions granted are still in +effect. +For example, if the permission is granted by an ancestor. +If no permissions are specified, then all permissions for the specified .Ar user , .Ar group , or .Sy everyone -are removed. Specifying +are removed. +Specifying .Sy everyone .Po or using the .Fl e option .Pc only removes the permissions that were granted to everyone, not all permissions -for every user and group. See the +for every user and group. +See the .Nm zfs Cm allow command for a description of the .Fl ldugec @@ -3051,8 +3295,9 @@ Recursively remove the permissions from this file system and all descendents. .Ar setname Oc Ns ... Oc .Ar filesystem Ns | Ns Ar volume .Xc -Removes permissions from a permission set. If no permissions are specified, then -all permissions are removed, thus removing the set entirely. +Removes permissions from a permission set. +If no permissions are specified, then all permissions are removed, thus removing +the set entirely. .It Xo .Nm .Cm hold @@ -3061,8 +3306,9 @@ all permissions are removed, thus removing the set entirely. .Xc Adds a single reference, named with the .Ar tag -argument, to the specified snapshot or snapshots. Each snapshot has its own tag -namespace, and tags must be unique within that space. +argument, to the specified snapshot or snapshots. +Each snapshot has its own tag namespace, and tags must be unique within that +space. .Pp If a hold exists on a snapshot, attempts to destroy that snapshot by using the .Nm zfs Cm destroy @@ -3093,9 +3339,9 @@ listing the holds on the named snapshot. .Xc Removes a single reference, named with the .Ar tag -argument, from the specified snapshot or snapshots. The tag must already exist -for each snapshot. If a hold exists on a snapshot, attempts to destroy that -snapshot by using the +argument, from the specified snapshot or snapshots. +The tag must already exist for each snapshot. +If a hold exists on a snapshot, attempts to destroy that snapshot by using the .Nm zfs Cm destroy command return .Er EBUSY . @@ -3112,11 +3358,12 @@ descendent file systems. .Xc Display the difference between a snapshot of a given filesystem and another snapshot of that filesystem from a later time or the current contents of the -filesystem. The first column is a character indicating the type of change, the -other columns indicate pathname, new pathname +filesystem. +The first column is a character indicating the type of change, the other columns +indicate pathname, new pathname .Pq in case of rename , -change in link count, and optionally file type and/or change time. The types of -change are: +change in link count, and optionally file type and/or change time. +The types of change are: .Bd -literal - The path has been removed + The path has been created @@ -3184,11 +3431,11 @@ The following command creates snapshots named .Sy yesterday of .Em pool/home -and all of its descendent file systems. Each snapshot is mounted on demand in -the +and all of its descendent file systems. +Each snapshot is mounted on demand in the .Pa .zfs/snapshot -directory at the root of its file system. The second command destroys the newly -created snapshots. +directory at the root of its file system. +The second command destroys the newly created snapshots. .Bd -literal # zfs snapshot -r pool/home@yesterday # zfs destroy -r pool/home@yesterday @@ -3382,9 +3629,9 @@ property for a dataset. .Ed .It Sy 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, renames the remaining snapshots, and then creates -a new snapshot, as follows: +consistent naming scheme. +To keep a week's worth of snapshots, the user destroys the oldest snapshot, +renames the remaining snapshots, and then creates a new snapshot, as follows: .Bd -literal # zfs destroy -r pool/users@7daysago # zfs rename -r pool/users@6daysago @7daysago @@ -3447,7 +3694,8 @@ The following example shows how to grant anyone in the group to create file systems in .Em tank/users . This syntax also allows staff members to destroy their own file systems, but not -destroy anyone else's file system. The permissions on +destroy anyone else's file system. +The permissions on .Em tank/users are also displayed. .Bd -literal @@ -3463,7 +3711,8 @@ Local+Descendent permissions: .It Sy 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 .Em tank/users -file system. The permissions on +file system. +The permissions on .Em tank/users are also displayed. .Bd -literal @@ -3480,7 +3729,8 @@ Local+Descendent permissions: The following example shows to grant the ability to set quotas and reservations on the .Em users/home -file system. The permissions on +file system. +The permissions on .Em users/home are also displayed. .Bd -literal @@ -3499,7 +3749,8 @@ The following example shows how to remove the snapshot permission from the .Sy staff group on the .Em tank/users -file system. The permissions on +file system. +The permissions on .Em tank/users are also displayed. .Bd -literal @@ -3513,7 +3764,8 @@ Local+Descendent permissions: .Ed .It Sy 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 +snapshot of a ZFS dataset and its current state. +The .Fl F option is used to indicate type information for the files affected. .Bd -literal diff --git a/usr/src/man/man1m/zpool.1m b/usr/src/man/man1m/zpool.1m index ed2e98b68f..7ec16df3aa 100644 --- a/usr/src/man/man1m/zpool.1m +++ b/usr/src/man/man1m/zpool.1m @@ -168,22 +168,24 @@ .Sh DESCRIPTION The .Nm -command configures ZFS storage pools. A storage pool is a collection of devices -that provides physical storage and data replication for ZFS datasets. All -datasets within a storage pool share the same space. See +command configures ZFS storage pools. +A storage pool is a collection of devices that provides physical storage and +data replication for ZFS datasets. +All datasets within a storage pool share the same space. +See .Xr zfs 1M for information on managing datasets. .Ss Virtual Devices (vdevs) A "virtual device" describes a single device or a collection of devices -organized according to certain performance and fault characteristics. The -following virtual devices are supported: +organized according to certain performance and fault characteristics. +The following virtual devices are supported: .Bl -tag -width Ds .It Sy disk A block device, typically located under .Pa /dev/dsk . ZFS can use individual slices or partitions, though the recommended mode of -operation is to use whole disks. A disk can be specified by a full path, or it -can be a shorthand name +operation is to use whole disks. +A disk can be specified by a full path, or it can be a shorthand name .Po the relative portion of the path under .Pa /dev/dsk .Pc . @@ -194,15 +196,16 @@ is equivalent to .Pa /dev/dsk/c0t0d0s2 . When given a whole disk, ZFS automatically labels the disk, if necessary. .It Sy file -A regular file. The use of files as a backing store is strongly discouraged. It -is designed primarily for experimental purposes, as the fault tolerance of a -file is only as good as the file system of which it is a part. A file must be -specified by a full path. +A regular file. +The use of files as a backing store is strongly discouraged. +It is designed primarily for experimental purposes, as the fault tolerance of a +file is only as good as the file system of which it is a part. +A file must be specified by a full path. .It Sy mirror -A mirror of two or more devices. Data is replicated in an identical fashion -across all components of a mirror. A mirror with N disks of size X can hold X -bytes and can withstand (N-1) devices failing before data integrity is -compromised. +A mirror of two or more devices. +Data is replicated in an identical fashion across all components of a mirror. +A mirror with N disks of size X can hold X bytes and can withstand (N-1) devices +failing before data integrity is compromised. .It Sy raidz , raidz1 , raidz2 , raidz3 A variation on RAID-5 that allows for better distribution of parity and eliminates the RAID-5 @@ -212,43 +215,50 @@ Data and parity is striped across all disks within a raidz group. .Pp A raidz group can have single-, double-, or triple-parity, meaning that the raidz group can sustain one, two, or three failures, respectively, without -losing any data. The +losing any data. +The .Sy raidz1 vdev type specifies a single-parity raidz group; the .Sy raidz2 vdev type specifies a double-parity raidz group; and the .Sy raidz3 -vdev type specifies a triple-parity raidz group. The +vdev type specifies a triple-parity raidz group. +The .Sy raidz vdev type is an alias for .Sy raidz1 . .Pp A raidz group with N disks of size X with P parity disks can hold approximately (N-P)*X bytes and can withstand P device(s) failing before data integrity is -compromised. The minimum number of devices in a raidz group is one more than -the number of parity disks. The recommended number is between 3 and 9 to help -increase performance. +compromised. +The minimum number of devices in a raidz group is one more than the number of +parity disks. +The recommended number is between 3 and 9 to help increase performance. .It Sy spare -A special pseudo-vdev which keeps track of available hot spares for a pool. For -more information, see the +A special pseudo-vdev which keeps track of available hot spares for a pool. +For more information, see the .Sx Hot Spares section. .It Sy log -A separate intent log device. If more than one log device is specified, then -writes are load-balanced between devices. Log devices can be mirrored. However, -raidz vdev types are not supported for the intent log. For more information, -see the +A separate intent log device. +If more than one log device is specified, then writes are load-balanced between +devices. +Log devices can be mirrored. +However, raidz vdev types are not supported for the intent log. +For more information, see the .Sx Intent Log section. .It Sy cache -A device used to cache storage pool data. A cache device cannot be configured -as a mirror or raidz group. For more information, see the +A device used to cache storage pool data. +A cache device cannot be configured as a mirror or raidz group. +For more information, see the .Sx Cache Devices section. .El .Pp Virtual devices cannot be nested, so a mirror or raidz virtual device can only -contain files or disks. Mirrors of mirrors +contain files or disks. +Mirrors of mirrors .Pq or other combinations are not allowed. .Pp @@ -257,68 +267,72 @@ A pool can have any number of virtual devices at the top of the configuration .Qq root vdevs .Pc . Data is dynamically distributed across all top-level devices to balance data -among devices. As new virtual devices are added, ZFS automatically places data -on the newly available devices. +among devices. +As new virtual devices are added, ZFS automatically places data on the newly +available devices. .Pp Virtual devices are specified one at a time on the command line, separated by -whitespace. The keywords +whitespace. +The keywords .Sy mirror and .Sy raidz -are used to distinguish where a group ends and another begins. For example, -the following creates two root vdevs, each a mirror of two disks: +are used to distinguish where a group ends and another begins. +For example, the following creates two root vdevs, each a mirror of two disks: .Bd -literal # zpool create mypool mirror c0t0d0 c0t1d0 mirror c1t0d0 c1t1d0 .Ed .Ss Device Failure and Recovery ZFS supports a rich set of mechanisms for handling device failure and data -corruption. All metadata and data is checksummed, and ZFS automatically repairs -bad data from a good copy when corruption is detected. +corruption. +All metadata and data is checksummed, and ZFS automatically repairs bad data +from a good copy when corruption is detected. .Pp In order to take advantage of these features, a pool must make use of some form -of redundancy, using either mirrored or raidz groups. While ZFS supports -running in a non-redundant configuration, where each root vdev is simply a disk -or file, this is strongly discouraged. A single case of bit corruption can -render some or all of your data unavailable. +of redundancy, using either mirrored or raidz groups. +While ZFS supports running in a non-redundant configuration, where each root +vdev is simply a disk or file, this is strongly discouraged. +A single case of bit corruption can render some or all of your data unavailable. .Pp A pool's health status is described by one of three states: online, degraded, -or faulted. An online pool has all devices operating normally. A degraded pool -is one in which one or more devices have failed, but the data is still -available due to a redundant configuration. A faulted pool has corrupted -metadata, or one or more faulted devices, and insufficient replicas to continue -functioning. +or faulted. +An online pool has all devices operating normally. +A degraded pool is one in which one or more devices have failed, but the data is +still available due to a redundant configuration. +A faulted pool has corrupted metadata, or one or more faulted devices, and +insufficient replicas to continue functioning. .Pp The health of the top-level vdev, such as mirror or raidz device, is potentially impacted by the state of its associated vdevs, or component -devices. A top-level vdev or component device is in one of the following -states: +devices. +A top-level vdev or component device is in one of the following states: .Bl -tag -width "DEGRADED" .It Sy DEGRADED One or more top-level vdevs is in the degraded state because one or more -component devices are offline. Sufficient replicas exist to continue -functioning. +component devices are offline. +Sufficient replicas exist to continue functioning. .Pp One or more component devices is in the degraded or faulted state, but -sufficient replicas exist to continue functioning. The underlying conditions -are as follows: +sufficient replicas exist to continue functioning. +The underlying conditions are as follows: .Bl -bullet .It The number of checksum errors exceeds acceptable levels and the device is -degraded as an indication that something may be wrong. ZFS continues to use the -device as necessary. +degraded as an indication that something may be wrong. +ZFS continues to use the device as necessary. .It -The number of I/O errors exceeds acceptable levels. The device could not be -marked as faulted because there are insufficient replicas to continue -functioning. +The number of I/O errors exceeds acceptable levels. +The device could not be marked as faulted because there are insufficient +replicas to continue functioning. .El .It Sy FAULTED One or more top-level vdevs is in the faulted state because one or more -component devices are offline. Insufficient replicas exist to continue -functioning. +component devices are offline. +Insufficient replicas exist to continue functioning. .Pp One or more component devices is in the faulted state, and insufficient -replicas exist to continue functioning. The underlying conditions are as -follows: +replicas exist to continue functioning. +The underlying conditions are as follows: .Bl -bullet .It The device could be opened, but the contents did not match expected values. @@ -333,25 +347,29 @@ command. .It Sy ONLINE The device is online and functioning. .It Sy REMOVED -The device was physically removed while the system was running. Device removal -detection is hardware-dependent and may not be supported on all platforms. +The device was physically removed while the system was running. +Device removal detection is hardware-dependent and may not be supported on all +platforms. .It Sy UNAVAIL -The device could not be opened. If a pool is imported when a device was -unavailable, then the device will be identified by a unique identifier instead -of its path since the path was never correct in the first place. +The device could not be opened. +If a pool is imported when a device was unavailable, then the device will be +identified by a unique identifier instead of its path since the path was never +correct in the first place. .El .Pp If a device is removed and later re-attached to the system, ZFS attempts -to put the device online automatically. Device attach detection is -hardware-dependent and might not be supported on all platforms. +to put the device online automatically. +Device attach detection is hardware-dependent and might not be supported on all +platforms. .Ss Hot Spares ZFS allows devices to be associated with pools as .Qq hot spares . These devices are not actively used in the pool, but when an active device -fails, it is automatically replaced by a hot spare. To create a pool with hot -spares, specify a +fails, it is automatically replaced by a hot spare. +To create a pool with hot spares, specify a .Sy spare -vdev with any number of devices. For example, +vdev with any number of devices. +For example, .Bd -literal # zpool create pool mirror c0d0 c1d0 spare c2d0 c3d0 .Ed @@ -360,11 +378,12 @@ Spares can be shared across multiple pools, and can be added with the .Nm zpool Cm add command and removed with the .Nm zpool Cm remove -command. Once a spare replacement is initiated, a new +command. +Once a spare replacement is initiated, a new .Sy spare vdev is created within the configuration that will remain there until the -original device is replaced. At this point, the hot spare becomes available -again if another device fails. +original device is replaced. +At this point, the hot spare becomes available again if another device fails. .Pp If a pool has a shared spare that is currently being used, the pool can not be exported since other pools may use this shared spare, which may lead to @@ -378,74 +397,82 @@ pools. Spares cannot replace log devices. .Ss Intent Log The ZFS Intent Log (ZIL) satisfies POSIX requirements for synchronous -transactions. For instance, databases often require their transactions to be on -stable storage devices when returning from a system call. NFS and other -applications can also use +transactions. +For instance, databases often require their transactions to be on stable storage +devices when returning from a system call. +NFS and other applications can also use .Xr fsync 3C -to ensure data stability. By default, the intent log is allocated from blocks -within the main pool. However, it might be possible to get better performance -using separate intent log devices such as NVRAM or a dedicated disk. For -example: +to ensure data stability. +By default, the intent log is allocated from blocks within the main pool. +However, it might be possible to get better performance using separate intent +log devices such as NVRAM or a dedicated disk. +For example: .Bd -literal # zpool create pool c0d0 c1d0 log c2d0 .Ed .Pp -Multiple log devices can also be specified, and they can be mirrored. See the +Multiple log devices can also be specified, and they can be mirrored. +See the .Sx EXAMPLES section for an example of mirroring multiple log devices. .Pp Log devices can be added, replaced, attached, detached, and imported and -exported as part of the larger pool. Mirrored log devices can be removed by -specifying the top-level mirror for the log. +exported as part of the larger pool. +Mirrored log devices can be removed by specifying the top-level mirror for the +log. .Ss Cache Devices Devices can be added to a storage pool as .Qq cache devices . These devices provide an additional layer of caching between main memory and -disk. For read-heavy workloads, where the working set size is much larger than -what can be cached in main memory, using cache devices allow much more of this -working set to be served from low latency media. Using cache devices provides -the greatest performance improvement for random read-workloads of mostly static -content. +disk. +For read-heavy workloads, where the working set size is much larger than what +can be cached in main memory, using cache devices allow much more of this +working set to be served from low latency media. +Using cache devices provides the greatest performance improvement for random +read-workloads of mostly static content. .Pp To create a pool with cache devices, specify a .Sy cache -vdev with any number of devices. For example: +vdev with any number of devices. +For example: .Bd -literal # zpool create pool c0d0 c1d0 cache c2d0 c3d0 .Ed .Pp -Cache devices cannot be mirrored or part of a raidz configuration. If a read -error is encountered on a cache device, that read I/O is reissued to the -original storage pool device, which might be part of a mirrored or raidz +Cache devices cannot be mirrored or part of a raidz configuration. +If a read error is encountered on a cache device, that read I/O is reissued to +the original storage pool device, which might be part of a mirrored or raidz configuration. .Pp The content of the cache devices is considered volatile, as is the case with other system caches. .Ss Properties -Each pool has several properties associated with it. Some properties are -read-only statistics while others are configurable and change the behavior of -the pool. +Each pool has several properties associated with it. +Some properties are read-only statistics while others are configurable and +change the behavior of the pool. .Pp The following are read-only properties: .Bl -tag -width Ds .It Sy available -Amount of storage available within the pool. This property can also be referred -to by its shortened column name, +Amount of storage available within the pool. +This property can also be referred to by its shortened column name, .Sy avail . .It Sy bootsize -The size of the system boot partition. This property can only be set at pool -creation time and is read-only once pool is created. Setting this property -implies using the +The size of the system boot partition. +This property can only be set at pool creation time and is read-only once pool +is created. +Setting this property implies using the .Fl B option. .It Sy capacity -Percentage of pool space used. This property can also be referred to by its -shortened column name, +Percentage of pool space used. +This property can also be referred to by its shortened column name, .Sy cap . .It Sy expandsize Amount of uninitialized space within the pool or device that can be used to -increase the total capacity of the pool. Uninitialized space consists of -any space on an EFI labeled vdev which has not been brought online +increase the total capacity of the pool. +Uninitialized space consists of any space on an EFI labeled vdev which has not +been brought online .Po e.g, using .Nm zpool Cm online Fl e .Pc . @@ -458,20 +485,23 @@ The amount of free space available in the pool. After a file system or snapshot is destroyed, the space it was using is returned to the pool asynchronously. .Sy freeing -is the amount of space remaining to be reclaimed. Over time +is the amount of space remaining to be reclaimed. +Over time .Sy freeing will decrease while .Sy free increases. .It Sy health -The current health of the pool. Health can be one of +The current health of the pool. +Health can be one of .Sy ONLINE , DEGRADED , FAULTED , OFFLINE, REMOVED , UNAVAIL . .It Sy guid A unique identifier for the pool. .It Sy size Total size of the storage pool. .It Sy unsupported@ Ns Em feature_guid -Information about unsupported features that are enabled on the pool. See +Information about unsupported features that are enabled on the pool. +See .Xr zpool-features 5 for details. .It Sy used @@ -479,27 +509,32 @@ Amount of storage space used within the pool. .El .Pp The space usage properties report actual physical space available to the -storage pool. The physical space can be different from the total amount of -space that any contained datasets can actually use. The amount of space used in -a raidz configuration depends on the characteristics of the data being -written. In addition, ZFS reserves some space for internal accounting -that the +storage pool. +The physical space can be different from the total amount of space that any +contained datasets can actually use. +The amount of space used in a raidz configuration depends on the characteristics +of the data being written. +In addition, ZFS reserves some space for internal accounting that the .Xr zfs 1M command takes into account, but the .Nm -command does not. For non-full pools of a reasonable size, these effects should -be invisible. For small pools, or pools that are close to being completely -full, these discrepancies may become more noticeable. +command does not. +For non-full pools of a reasonable size, these effects should be invisible. +For small pools, or pools that are close to being completely full, these +discrepancies may become more noticeable. .Pp The following property can be set at creation time and import time: .Bl -tag -width Ds .It Sy altroot -Alternate root directory. If set, this directory is prepended to any mount -points within the pool. This can be used when examining an unknown pool where -the mount points cannot be trusted, or in an alternate boot environment, where -the typical paths are not valid. +Alternate root directory. +If set, this directory is prepended to any mount points within the pool. +This can be used when examining an unknown pool where the mount points cannot be +trusted, or in an alternate boot environment, where the typical paths are not +valid. .Sy altroot -is not a persistent property. It is valid only while the system is up. Setting +is not a persistent property. +It is valid only while the system is up. +Setting .Sy altroot defaults to using .Sy cachefile Ns = Ns Sy none , @@ -511,8 +546,8 @@ The following property can be set only at import time: .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off If set to .Sy on , -the pool will be imported in read-only mode. This property can also be referred -to by its shortened column name, +the pool will be imported in read-only mode. +This property can also be referred to by its shortened column name, .Sy rdonly . .El .Pp @@ -522,39 +557,46 @@ changed with the command: .Bl -tag -width Ds .It Sy autoexpand Ns = Ns Sy on Ns | Ns Sy off -Controls automatic pool expansion when the underlying LUN is grown. If set to +Controls automatic pool expansion when the underlying LUN is grown. +If set to .Sy on , -the pool will be resized according to the size of the expanded device. If the -device is part of a mirror or raidz then all devices within that mirror/raidz -group must be expanded before the new space is made available to the pool. The -default behavior is +the pool will be resized according to the size of the expanded device. +If the device is part of a mirror or raidz then all devices within that +mirror/raidz group must be expanded before the new space is made available to +the pool. +The default behavior is .Sy off . This property can also be referred to by its shortened column name, .Sy expand . .It Sy autoreplace Ns = Ns Sy on Ns | Ns Sy off -Controls automatic device replacement. If set to +Controls automatic device replacement. +If set to .Sy off , device replacement must be initiated by the administrator by using the .Nm zpool Cm replace -command. If set to +command. +If set to .Sy on , any new device, found in the same physical location as a device that previously -belonged to the pool, is automatically formatted and replaced. The default -behavior is +belonged to the pool, is automatically formatted and replaced. +The default behavior is .Sy off . This property can also be referred to by its shortened column name, .Sy replace . .It Sy bootfs Ns = Ns Ar pool Ns / Ns Ar dataset -Identifies the default bootable dataset for the root pool. This property is -expected to be set mainly by the installation and upgrade programs. +Identifies the default bootable dataset for the root pool. +This property is expected to be set mainly by the installation and upgrade +programs. .It Sy cachefile Ns = Ns Ar path Ns | Ns Sy none -Controls the location of where the pool configuration is cached. Discovering -all pools on system startup requires a cached copy of the configuration data -that is stored on the root file system. All pools in this cache are -automatically imported when the system boots. Some environments, such as -install and clustering, need to cache this information in a different location -so that pools are not automatically imported. Setting this property caches the -pool configuration in a different location that can later be imported with +Controls the location of where the pool configuration is cached. +Discovering all pools on system startup requires a cached copy of the +configuration data that is stored on the root file system. +All pools in this cache are automatically imported when the system boots. +Some environments, such as install and clustering, need to cache this +information in a different location so that pools are not automatically +imported. +Setting this property caches the pool configuration in a different location that +can later be imported with .Nm zpool Cm import Fl c . Setting it to the special value .Sy none @@ -563,43 +605,48 @@ creates a temporary pool that is never cached, and the special value .Pq empty string uses the default location. .Pp -Multiple pools can share the same cache file. Because the kernel destroys and -recreates this file when pools are added and removed, care should be taken when -attempting to access this file. When the last pool using a +Multiple pools can share the same cache file. +Because the kernel destroys and recreates this file when pools are added and +removed, care should be taken when attempting to access this file. +When the last pool using a .Sy cachefile is exported or destroyed, the file is removed. .It Sy comment Ns = Ns Ar text A text string consisting of printable ASCII characters that will be stored -such that it is available even if the pool becomes faulted. An administrator -can provide additional information about a pool using this property. +such that it is available even if the pool becomes faulted. +An administrator can provide additional information about a pool using this +property. .It Sy dedupditto Ns = Ns Ar number -Threshold for the number of block ditto copies. If the reference count for a -deduplicated block increases above this number, a new ditto copy of this block -is automatically stored. The default setting is +Threshold for the number of block ditto copies. +If the reference count for a deduplicated block increases above this number, a +new ditto copy of this block is automatically stored. +The default setting is .Sy 0 -which causes no ditto copies to be created for deduplicated blocks. The minimum -legal nonzero setting is +which causes no ditto copies to be created for deduplicated blocks. +The minimum legal nonzero setting is .Sy 100 . .It Sy delegation Ns = Ns Sy on Ns | Ns Sy off Controls whether a non-privileged user is granted access based on the dataset -permissions defined on the dataset. See +permissions defined on the dataset. +See .Xr zfs 1M for more information on ZFS delegated administration. .It Sy failmode Ns = Ns Sy wait Ns | Ns Sy continue Ns | Ns Sy panic -Controls the system behavior in the event of catastrophic pool failure. This -condition is typically a result of a loss of connectivity to the underlying -storage device(s) or a failure of all devices within the pool. The behavior of -such an event is determined as follows: +Controls the system behavior in the event of catastrophic pool failure. +This condition is typically a result of a loss of connectivity to the underlying +storage device(s) or a failure of all devices within the pool. +The behavior of such an event is determined as follows: .Bl -tag -width "continue" .It Sy wait Blocks all I/O access until the device connectivity is recovered and the errors -are cleared. This is the default behavior. +are cleared. +This is the default behavior. .It Sy continue Returns .Er EIO to any new write I/O requests but allows reads to any of the remaining healthy -devices. Any write requests that have yet to be committed to disk would be -blocked. +devices. +Any write requests that have yet to be committed to disk would be blocked. .It Sy panic Prints out a message to the console and generates a system crash dump. .El @@ -610,7 +657,8 @@ The only valid value when setting this property is .Sy enabled which moves .Ar feature_name -to the enabled state. See +to the enabled state. +See .Xr zpool-features 5 for details on feature states. .It Sy listsnaps Ns = Ns Sy on Ns | Ns Sy off @@ -619,15 +667,18 @@ output when .Nm zfs Cm list is run without the .Fl t -option. The default value is +option. +The default value is .Sy off . .It Sy version Ns = Ns Ar version -The current on-disk version of the pool. This can be increased, but never -decreased. The preferred method of updating pools is with the +The current on-disk version of the pool. +This can be increased, but never decreased. +The preferred method of updating pools is with the .Nm zpool Cm upgrade command, though this property can be used when a specific version is needed for -backwards compatibility. Once feature flags is enabled on a pool this property -will no longer have a value. +backwards compatibility. +Once feature flags is enabled on a pool this property will no longer have a +value. .El .Ss Subcommands All subcommands that modify state are logged persistently to the pool in their @@ -636,8 +687,8 @@ original form. The .Nm command provides subcommands to create and destroy storage pools, add capacity -to storage pools, and provide information about the storage pools. The -following subcommands are supported: +to storage pools, and provide information about the storage pools. +The following subcommands are supported: .Bl -tag -width Ds .It Xo .Nm @@ -650,11 +701,13 @@ Displays a help message. .Op Fl fn .Ar pool vdev Ns ... .Xc -Adds the specified virtual devices to the given pool. The +Adds the specified virtual devices to the given pool. +The .Ar vdev specification is described in the .Sx Virtual Devices -section. The behavior of the +section. +The behavior of the .Fl f option, and the device checks performed are described in the .Nm zpool Cm create @@ -663,8 +716,8 @@ subcommand. .It Fl f Forces use of .Ar vdev Ns s , -even if they appear in use or specify a conflicting replication level. Not all -devices can be overridden in this manner. +even if they appear in use or specify a conflicting replication level. +Not all devices can be overridden in this manner. .It Fl n Displays the configuration that would be used without actually adding the .Ar vdev Ns s . @@ -681,7 +734,8 @@ Attaches .Ar new_device to the existing .Ar device . -The existing device cannot be part of a raidz configuration. If +The existing device cannot be part of a raidz configuration. +If .Ar device is not currently part of a mirrored configuration, .Ar device @@ -693,15 +747,16 @@ If .Ar device is part of a two-way mirror, attaching .Ar new_device -creates a three-way mirror, and so on. In either case, +creates a three-way mirror, and so on. +In either case, .Ar new_device begins to resilver immediately. .Bl -tag -width Ds .It Fl f Forces use of .Ar new_device , -even if its appears to be in use. Not all devices can be overridden in this -manner. +even if its appears to be in use. +Not all devices can be overridden in this manner. .El .It Xo .Nm @@ -709,9 +764,10 @@ manner. .Ar pool .Op Ar device .Xc -Clears device errors in a pool. If no arguments are specified, all device -errors within the pool are cleared. If one or more devices is specified, only -those errors associated with the specified device or devices are cleared. +Clears device errors in a pool. +If no arguments are specified, all device errors within the pool are cleared. +If one or more devices is specified, only those errors associated with the +specified device or devices are cleared. .It Xo .Nm .Cm create @@ -724,7 +780,8 @@ those errors associated with the specified device or devices are cleared. .Ar pool vdev Ns ... .Xc Creates a new storage pool containing the virtual devices specified on the -command line. The pool name must begin with a letter, and can only contain +command line. +The pool name must begin with a letter, and can only contain alphanumeric characters as well as underscore .Pq Qq Sy _ , dash @@ -746,19 +803,22 @@ specification is described in the section. .Pp The command verifies that each device specified is accessible and not currently -in use by another subsystem. There are some uses, such as being currently -mounted, or specified as the dedicated dump device, that prevents a device from -ever being used by ZFS . Other uses, such as having a preexisting UFS file -system, can be overridden with the +in use by another subsystem. +There are some uses, such as being currently mounted, or specified as the +dedicated dump device, that prevents a device from ever being used by ZFS. +Other uses, such as having a preexisting UFS file system, can be overridden with +the .Fl f option. .Pp The command also checks that the replication strategy for the pool is -consistent. An attempt to combine redundant and non-redundant storage in a -single pool, or to mix disks and files, results in an error unless +consistent. +An attempt to combine redundant and non-redundant storage in a single pool, or +to mix disks and files, results in an error unless .Fl f -is specified. The use of differently sized devices within a single raidz or -mirror group is also flagged as an error unless +is specified. +The use of differently sized devices within a single raidz or mirror group is +also flagged as an error unless .Fl f is specified. .Pp @@ -767,7 +827,8 @@ Unless the option is specified, the default mount point is .Pa / Ns Ar pool . The mount point must not exist or must be empty, or else the root dataset -cannot be mounted. This can be overridden with the +cannot be mounted. +This can be overridden with the .Fl m option. .Pp @@ -777,36 +838,41 @@ option is specified. .Bl -tag -width Ds .It Fl B Create whole disk pool with EFI System partition to support booting system -with UEFI firmware. Default size is 256MB. To create boot partition with -custom size, set the +with UEFI firmware. +Default size is 256MB. +To create boot partition with custom size, set the .Sy bootsize property with the .Fl o -option. See the +option. +See the .Sx Properties section for details. .It Fl d -Do not enable any features on the new pool. Individual features can be enabled -by setting their corresponding properties to +Do not enable any features on the new pool. +Individual features can be enabled by setting their corresponding properties to .Sy enabled with the .Fl o -option. See +option. +See .Xr zpool-features 5 for details about feature properties. .It Fl f Forces use of .Ar vdev Ns s , -even if they appear in use or specify a conflicting replication level. Not all -devices can be overridden in this manner. +even if they appear in use or specify a conflicting replication level. +Not all devices can be overridden in this manner. .It Fl m Ar mountpoint -Sets the mount point for the root dataset. The default mount point is +Sets the mount point for the root dataset. +The default mount point is .Pa /pool or .Pa altroot/pool if .Ar altroot -is specified. The mount point must be an absolute path, +is specified. +The mount point must be an absolute path, .Sy legacy , or .Sy none . @@ -814,15 +880,17 @@ For more information on dataset mount points, see .Xr zfs 1M . .It Fl n Displays the configuration that would be used without actually creating the -pool. The actual pool creation can still fail due to insufficient privileges or +pool. +The actual pool creation can still fail due to insufficient privileges or device sharing. .It Fl o Ar property Ns = Ns Ar value -Sets the given pool properties. See the +Sets the given pool properties. +See the .Sx Properties section for a list of valid properties that can be set. .It Fl O Ar file-system-property Ns = Ns Ar value -Sets the given file system properties in the root file system of the pool. See -the +Sets the given file system properties in the root file system of the pool. +See the .Sx Properties section of .Xr zfs 1M @@ -837,8 +905,8 @@ Equivalent to .Op Fl f .Ar pool .Xc -Destroys the given pool, freeing up any devices for other use. This command -tries to unmount any active datasets before destroying the pool. +Destroys the given pool, freeing up any devices for other use. +This command tries to unmount any active datasets before destroying the pool. .Bl -tag -width Ds .It Fl f Forces any active datasets contained within the pool to be unmounted. @@ -850,28 +918,31 @@ Forces any active datasets contained within the pool to be unmounted. .Xc Detaches .Ar device -from a mirror. The operation is refused if there are no other valid replicas of -the data. +from a mirror. +The operation is refused if there are no other valid replicas of the data. .It Xo .Nm .Cm export .Op Fl f .Ar pool Ns ... .Xc -Exports the given pools from the system. All devices are marked as exported, -but are still considered in use by other subsystems. The devices can be moved -between systems +Exports the given pools from the system. +All devices are marked as exported, but are still considered in use by other +subsystems. +The devices can be moved between systems .Pq even those of different endianness and imported as long as a sufficient number of devices are present. .Pp -Before exporting the pool, all datasets within the pool are unmounted. A pool -can not be exported if it has a shared spare that is currently being used. +Before exporting the pool, all datasets within the pool are unmounted. +A pool can not be exported if it has a shared spare that is currently being +used. .Pp For pools to be portable, you must give the .Nm command whole disks, not just slices, so that ZFS can label the disks with -portable EFI labels. Otherwise, disk drivers on platforms of different -endianness will not recognize the disks. +portable EFI labels. +Otherwise, disk drivers on platforms of different endianness will not recognize +the disks. .Bl -tag -width Ds .It Fl f Forcefully unmount all datasets, using the @@ -879,7 +950,8 @@ Forcefully unmount all datasets, using the command. .Pp This command will forcefully export the pool even if it has a shared spare that -is currently being used. This may lead to potential data corruption. +is currently being used. +This may lead to potential data corruption. .El .It Xo .Nm @@ -895,8 +967,8 @@ or all properties if .Sy all is used .Pc -for the specified storage pool(s). These properties are displayed with -the following fields: +for the specified storage pool(s). +These properties are displayed with the following fields: .Bd -literal name Name of storage pool property Property name @@ -909,8 +981,9 @@ See the section for more information on the available pool properties. .Bl -tag -width Ds .It Fl H -Scripted mode. Do not display headers, and separate fields by a single tab -instead of arbitrary space. +Scripted mode. +Do not display headers, and separate fields by a single tab instead of arbitrary +space. .It Fl o Ar field A comma-separated list of columns to display. .Sy name Ns , Ns Sy property Ns , Ns Sy value Ns , Ns Sy source @@ -940,17 +1013,18 @@ performed. .Op Fl D .Op Fl d Ar dir .Xc -Lists pools available to import. If the +Lists pools available to import. +If the .Fl d option is not specified, this command searches for devices in .Pa /dev/dsk . The .Fl d -option can be specified multiple times, and all directories are searched. If the -device appears to be part of an exported pool, this command displays a summary -of the pool with the name of the pool, a numeric identifier, as well as the vdev -layout and current health of the device for each device or file. Destroyed -pools, pools that were previously destroyed with the +option can be specified multiple times, and all directories are searched. +If the device appears to be part of an exported pool, this command displays a +summary of the pool with the name of the pool, a numeric identifier, as well as +the vdev layout and current health of the device for each device or file. +Destroyed pools, pools that were previously destroyed with the .Nm zpool Cm destroy command, are not listed unless the .Fl D @@ -964,7 +1038,8 @@ Reads configuration from the given .Ar cachefile that was created with the .Sy cachefile -pool property. This +pool property. +This .Ar cachefile is used instead of searching for devices. .It Fl d Ar dir @@ -987,9 +1062,10 @@ Lists destroyed pools only. .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... .Op Fl R Ar root .Xc -Imports all pools found in the search directories. Identical to the previous -command, except that all pools with a sufficient number of devices available are -imported. Destroyed pools, pools that were previously destroyed with the +Imports all pools found in the search directories. +Identical to the previous command, except that all pools with a sufficient +number of devices available are imported. +Destroyed pools, pools that were previously destroyed with the .Nm zpool Cm destroy command, will not be imported unless the .Fl D @@ -1002,7 +1078,8 @@ Reads configuration from the given .Ar cachefile that was created with the .Sy cachefile -pool property. This +pool property. +This .Ar cachefile is used instead of searching for devices. .It Fl d Ar dir @@ -1010,41 +1087,47 @@ Searches for devices or files in .Ar dir . The .Fl d -option can be specified multiple times. This option is incompatible with the +option can be specified multiple times. +This option is incompatible with the .Fl c option. .It Fl D -Imports destroyed pools only. The +Imports destroyed pools only. +The .Fl f option is also required. .It Fl f Forces import, even if the pool appears to be potentially active. .It Fl F -Recovery mode for a non-importable pool. Attempt to return the pool to an -importable state by discarding the last few transactions. Not all damaged pools -can be recovered by using this option. If successful, the data from the -discarded transactions is irretrievably lost. This option is ignored if the pool -is importable or already imported. +Recovery mode for a non-importable pool. +Attempt to return the pool to an importable state by discarding the last few +transactions. +Not all damaged pools can be recovered by using this option. +If successful, the data from the discarded transactions is irretrievably lost. +This option is ignored if the pool is importable or already imported. .It Fl m -Allows a pool to import when there is a missing log device. Recent transactions -can be lost because the log device will be discarded. +Allows a pool to import when there is a missing log device. +Recent transactions can be lost because the log device will be discarded. .It Fl n Used with the .Fl F -recovery option. Determines whether a non-importable pool can be made importable -again, but does not actually perform the pool recovery. For more details about -pool recovery mode, see the +recovery option. +Determines whether a non-importable pool can be made importable again, but does +not actually perform the pool recovery. +For more details about pool recovery mode, see the .Fl F option, above. .It Fl N Import the pool without mounting any file systems. .It Fl o Ar mntopts Comma-separated list of mount options to use when mounting datasets within the -pool. See +pool. +See .Xr zfs 1M for a description of dataset properties and mount options. .It Fl o Ar property Ns = Ns Ar value -Sets the specified property on the imported pool. See the +Sets the specified property on the imported pool. +See the .Sx Properties section for more information on the available pool properties. .It Fl R Ar root @@ -1069,8 +1152,9 @@ property to .Ar pool Ns | Ns Ar id .Op Ar newpool .Xc -Imports a specific pool. A pool can be identified by its name or the numeric -identifier. If +Imports a specific pool. +A pool can be identified by its name or the numeric identifier. +If .Ar newpool is specified, the pool is imported using the name .Ar newpool . @@ -1078,9 +1162,10 @@ Otherwise, it is imported with the same name as its exported name. .Pp If a device is removed from a system without running .Nm zpool Cm export -first, the device appears as potentially active. It cannot be determined if -this was a failed export, or whether the device is really in use from another -host. To import a pool in this state, the +first, the device appears as potentially active. +It cannot be determined if this was a failed export, or whether the device is +really in use from another host. +To import a pool in this state, the .Fl f option is required. .Bl -tag -width Ds @@ -1089,7 +1174,8 @@ Reads configuration from the given .Ar cachefile that was created with the .Sy cachefile -pool property. This +pool property. +This .Ar cachefile is used instead of searching for devices. .It Fl d Ar dir @@ -1097,39 +1183,45 @@ Searches for devices or files in .Ar dir . The .Fl d -option can be specified multiple times. This option is incompatible with the +option can be specified multiple times. +This option is incompatible with the .Fl c option. .It Fl D -Imports destroyed pool. The +Imports destroyed pool. +The .Fl f option is also required. .It Fl f Forces import, even if the pool appears to be potentially active. .It Fl F -Recovery mode for a non-importable pool. Attempt to return the pool to an -importable state by discarding the last few transactions. Not all damaged pools -can be recovered by using this option. If successful, the data from the -discarded transactions is irretrievably lost. This option is ignored if the pool -is importable or already imported. +Recovery mode for a non-importable pool. +Attempt to return the pool to an importable state by discarding the last few +transactions. +Not all damaged pools can be recovered by using this option. +If successful, the data from the discarded transactions is irretrievably lost. +This option is ignored if the pool is importable or already imported. .It Fl m -Allows a pool to import when there is a missing log device. Recent transactions -can be lost because the log device will be discarded. +Allows a pool to import when there is a missing log device. +Recent transactions can be lost because the log device will be discarded. .It Fl n Used with the .Fl F -recovery option. Determines whether a non-importable pool can be made importable -again, but does not actually perform the pool recovery. For more details about -pool recovery mode, see the +recovery option. +Determines whether a non-importable pool can be made importable again, but does +not actually perform the pool recovery. +For more details about pool recovery mode, see the .Fl F option, above. .It Fl o Ar mntopts Comma-separated list of mount options to use when mounting datasets within the -pool. See +pool. +See .Xr zfs 1M for a description of dataset properties and mount options. .It Fl o Ar property Ns = Ns Ar value -Sets the specified property on the imported pool. See the +Sets the specified property on the imported pool. +See the .Sx Properties section for more information on the available pool properties. .It Fl R Ar root @@ -1150,29 +1242,35 @@ property to .Oo Ar pool Oc Ns ... .Op Ar interval Op Ar count .Xc -Displays I/O statistics for the given pools. When given an +Displays I/O statistics for the given pools. +When given an .Ar interval , the statistics are printed every .Ar interval -seconds until ^C is pressed. If no +seconds until ^C is pressed. +If no .Ar pool Ns s -are specified, statistics for every pool in the system is shown. If +are specified, statistics for every pool in the system is shown. +If .Ar count is specified, the command exits after .Ar count reports are printed. .Bl -tag -width Ds .It Fl T Sy u Ns | Ns Sy d -Display a time stamp. Specify +Display a time stamp. +Specify .Sy u -for a printed representation of the internal representation of time. See +for a printed representation of the internal representation of time. +See .Xr time 2 . Specify .Sy d -for standard date format. See +for standard date format. +See .Xr date 1 . .It Fl v -Verbose statistics. Reports usage statistics for individual vdevs within the +Verbose statistics Reports usage statistics for individual vdevs within the pool, in addition to the pool-wide statistics. .El .It Xo @@ -1199,25 +1297,31 @@ Treat exported or foreign devices as inactive. .Oo Ar pool Oc Ns ... .Op Ar interval Op Ar count .Xc -Lists the given pools along with a health status and space usage. If no +Lists the given pools along with a health status and space usage. +If no .Ar pool Ns s -are specified, all pools in the system are listed. When given an +are specified, all pools in the system are listed. +When given an .Ar interval , the information is printed every .Ar interval -seconds until ^C is pressed. If +seconds until ^C is pressed. +If .Ar count is specified, the command exits after .Ar count reports are printed. .Bl -tag -width Ds .It Fl H -Scripted mode. Do not display headers, and separate fields by a single tab -instead of arbitrary space. +Scripted mode. +Do not display headers, and separate fields by a single tab instead of arbitrary +space. .It Fl o Ar property -Comma-separated list of properties to display. See the +Comma-separated list of properties to display. +See the .Sx Properties -section for a list of valid properties. The default list is +section for a list of valid properties. +The default list is .Sy name , size , used , available , fragmentation , expandsize , capacity , .Sy dedupratio , health , altroot . .It Fl p @@ -1225,17 +1329,21 @@ Display numbers in parsable .Pq exact values. .It Fl T Sy u Ns | Ns Sy d -Display a time stamp. Specify +Display a time stamp. +Specify .Fl u -for a printed representation of the internal representation of time. See +for a printed representation of the internal representation of time. +See .Xr time 2 . Specify .Fl d -for standard date format. See +for standard date format. +See .Xr date 1 . .It Fl v -Verbose statistics. Reports usage statistics for individual vdevs within the -pool, in addition to the pool-wise statistics. +Verbose statistics. +Reports usage statistics for individual vdevs within the pool, in addition to +the pool-wise statistics. .El .It Xo .Nm @@ -1243,14 +1351,15 @@ pool, in addition to the pool-wise statistics. .Op Fl t .Ar pool Ar device Ns ... .Xc -Takes the specified physical device offline. While the +Takes the specified physical device offline. +While the .Ar device -is offline, no attempt is made to read or write to the device. This command is -not applicable to spares. +is offline, no attempt is made to read or write to the device. +This command is not applicable to spares. .Bl -tag -width Ds .It Fl t -Temporary. Upon reboot, the specified physical device reverts to its previous -state. +Temporary. +Upon reboot, the specified physical device reverts to its previous state. .El .It Xo .Nm @@ -1258,21 +1367,22 @@ state. .Op Fl e .Ar pool Ar device Ns ... .Xc -Brings the specified physical device online. This command is not applicable to -spares. +Brings the specified physical device online. +This command is not applicable to spares. .Bl -tag -width Ds .It Fl e -Expand the device to use all available space. If the device is part of a mirror -or raidz then all devices must be expanded before the new space will become -available to the pool. +Expand the device to use all available space. +If the device is part of a mirror or raidz then all devices must be expanded +before the new space will become available to the pool. .El .It Xo .Nm .Cm reguid .Ar pool .Xc -Generates a new unique identifier for the pool. You must ensure that all devices -in this pool are online and healthy before performing this action. +Generates a new unique identifier for the pool. +You must ensure that all devices in this pool are online and healthy before +performing this action. .It Xo .Nm .Cm reopen @@ -1284,12 +1394,16 @@ Reopen all the vdevs associated with the pool. .Cm remove .Ar pool Ar device Ns ... .Xc -Removes the specified device from the pool. This command currently only supports -removing hot spares, cache, and log devices. A mirrored log device can be -removed by specifying the top-level mirror for the log. Non-log devices that are -part of a mirrored configuration can be removed using the +Removes the specified device from the pool. +This command currently only supports removing hot spares, cache, and log +devices. +A mirrored log device can be removed by specifying the top-level mirror for the +log. +Non-log devices that are part of a mirrored configuration can be removed using +the .Nm zpool Cm detach -command. Non-redundant and raidz devices cannot be removed from a pool. +command. +Non-redundant and raidz devices cannot be removed from a pool. .It Xo .Nm .Cm replace @@ -1311,21 +1425,23 @@ must be greater than or equal to the minimum size of all the devices in a mirror or raidz configuration. .Pp .Ar new_device -is required if the pool is not redundant. If +is required if the pool is not redundant. +If .Ar new_device is not specified, it defaults to .Ar old_device . This form of replacement is useful after an existing disk has failed and has -been physically replaced. In this case, the new disk may have the same +been physically replaced. +In this case, the new disk may have the same .Pa /dev/dsk -path as the old device, even though it is actually a different disk. ZFS -recognizes this. +path as the old device, even though it is actually a different disk. +ZFS recognizes this. .Bl -tag -width Ds .It Fl f Forces use of .Ar new_device , -even if its appears to be in use. Not all devices can be overridden in this -manner. +even if its appears to be in use. +Not all devices can be overridden in this manner. .El .It Xo .Nm @@ -1333,16 +1449,20 @@ manner. .Op Fl s .Ar pool Ns ... .Xc -Begins a scrub. The scrub examines all data in the specified pools to verify -that it checksums correctly. For replicated +Begins a scrub. +The scrub examines all data in the specified pools to verify that it checksums +correctly. +For replicated .Pq mirror or raidz -devices, ZFS automatically repairs any damage discovered during the scrub. The +devices, ZFS automatically repairs any damage discovered during the scrub. +The .Nm zpool Cm status command reports the progress of the scrub and summarizes the results of the scrub upon completion. .Pp -Scrubbing and resilvering are very similar operations. The difference is that -resilvering only examines data that ZFS knows to be out of date +Scrubbing and resilvering are very similar operations. +The difference is that resilvering only examines data that ZFS knows to be out +of date .Po for example, when attaching a new device to a mirror or replacing an existing device @@ -1351,10 +1471,12 @@ whereas scrubbing examines all data to discover silent errors due to hardware faults or disk failure. .Pp Because scrubbing and resilvering are I/O-intensive operations, ZFS only allows -one at a time. If a scrub is already in progress, the +one at a time. +If a scrub is already in progress, the .Nm zpool Cm scrub -command terminates it and starts a new scrub. If a resilver is in progress, ZFS -does not allow a scrub to be started until the resilver completes. +command terminates it and starts a new scrub. +If a resilver is in progress, ZFS does not allow a scrub to be started until the +resilver completes. .Bl -tag -width Ds .It Fl s Stop scrubbing. @@ -1365,7 +1487,8 @@ Stop scrubbing. .Ar property Ns = Ns Ar value .Ar pool .Xc -Sets the given property on the specified pool. See the +Sets the given property on the specified pool. +See the .Sx Properties section for more information on what properties can be set and acceptable values. @@ -1383,14 +1506,15 @@ creating .Ar newpool . All vdevs in .Ar pool -must be mirrors. At the time of the split, +must be mirrors. +At the time of the split, .Ar newpool will be a replica of .Ar pool . .Bl -tag -width Ds .It Fl n -Do dry run, do not actually perform the split. Print out the expected -configuration of +Do dry run, do not actually perform the split. +Print out the expected configuration of .Ar newpool . .It Fl o Ar property Ns = Ns Ar value Sets the specified property for @@ -1415,17 +1539,18 @@ and automaticaly import it. .Oo Ar pool Oc Ns ... .Op Ar interval Op Ar count .Xc -Displays the detailed health status for the given pools. If no +Displays the detailed health status for the given pools. +If no .Ar pool -is specified, then the status of each pool in the system is displayed. For more -information on pool and device health, see the +is specified, then the status of each pool in the system is displayed. +For more information on pool and device health, see the .Sx Device Failure and Recovery section. .Pp If a scrub or resilver is in progress, this command reports the percentage done -and the estimated time to completion. Both of these are only approximate, -because the amount of data in the pool and the other workloads on the system can -change. +and the estimated time to completion. +Both of these are only approximate, because the amount of data in the pool and +the other workloads on the system can change. .Bl -tag -width Ds .It Fl D Display a histogram of deduplication statistics, showing the allocated @@ -1434,29 +1559,33 @@ and referenced .Pq logically referenced in the pool block counts and sizes by reference count. .It Fl T Sy u Ns | Ns Sy d -Display a time stamp. Specify +Display a time stamp. +Specify .Fl u -for a printed representation of the internal representation of time. See +for a printed representation of the internal representation of time. +See .Xr time 2 . Specify .Fl d -for standard date format. See +for standard date format. +See .Xr date 1 . .It Fl v Displays verbose data error information, printing out a complete list of all data errors since the last complete pool scrub. .It Fl x Only display status for pools that are exhibiting errors or are otherwise -unavailable. Warnings about pools not using the latest on-disk format will not -be included. +unavailable. +Warnings about pools not using the latest on-disk format will not be included. .El .It Xo .Nm .Cm upgrade .Xc Displays pools which do not have all supported features enabled and pools -formatted using a legacy ZFS version number. These pools can continue to be -used, but some features may not be available. Use +formatted using a legacy ZFS version number. +These pools can continue to be used, but some features may not be available. +Use .Nm zpool Cm upgrade Fl a to enable all features on all pools. .It Xo @@ -1464,7 +1593,8 @@ to enable all features on all pools. .Cm upgrade .Fl v .Xc -Displays legacy ZFS versions supported by the current software. See +Displays legacy ZFS versions supported by the current software. + See .Xr zpool-features 5 for a description of feature flags features supported by the current software. .It Xo @@ -1473,8 +1603,10 @@ for a description of feature flags features supported by the current software. .Op Fl V Ar version .Fl a Ns | Ns Ar pool Ns ... .Xc -Enables all supported features on the given pool. Once this is done, the pool -will no longer be accessible on systems that do not support feature flags. See +Enables all supported features on the given pool. +Once this is done, the pool will no longer be accessible on systems that do not +support feature flags. +See .Xr zpool-features 5 for details on compatibility with systems that support feature flags, but do not support all features enabled on the pool. @@ -1482,11 +1614,12 @@ support all features enabled on the pool. .It Fl a Enables all supported features on all pools. .It Fl V Ar version -Upgrade to the specified legacy version. If the +Upgrade to the specified legacy version. +If the .Fl V -flag is specified, no features will be enabled on the pool. This option can only -be used to increase the version number up to the last supported legacy version -number. +flag is specified, no features will be enabled on the pool. +This option can only be used to increase the version number up to the last +supported legacy version number. .El .El .Sh EXIT STATUS @@ -1519,25 +1652,26 @@ The following command creates an unmirrored pool using two disk slices. # zpool create tank /dev/dsk/c0t0d0s1 c0t1d0s4 .Ed .It Sy Example 4 No Creating a ZFS Storage Pool by Using Files -The following command creates an unmirrored pool using files. While not -recommended, a pool based on files can be useful for experimental purposes. +The following command creates an unmirrored pool using files. +While not recommended, a pool based on files can be useful for experimental +purposes. .Bd -literal # zpool create tank /path/to/file/a /path/to/file/b .Ed .It Sy Example 5 No Adding a Mirror to a ZFS Storage Pool The following command adds two mirrored disks to the pool .Em tank , -assuming the pool is already made up of two-way mirrors. The additional space -is immediately available to any datasets within the pool. +assuming the pool is already made up of two-way mirrors. +The additional space is immediately available to any datasets within the pool. .Bd -literal # zpool add tank mirror c1t0d0 c1t1d0 .Ed .It Sy Example 6 No Listing Available ZFS Storage Pools -The following command lists all available pools on the system. In this case, -the pool +The following command lists all available pools on the system. +In this case, the pool .Em zion -is faulted due to a missing device. The results from this command are similar -to the following: +is faulted due to a missing device. +The results from this command are similar to the following: .Bd -literal # zpool list NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT @@ -1562,8 +1696,8 @@ so that they can be relocated or later imported. .It Sy Example 9 No Importing a ZFS Storage Pool The following command displays available pools, and then imports the pool .Em tank -for use on the system. The results from this command are similar to the -following: +for use on the system. +The results from this command are similar to the following: .Bd -literal # zpool import pool: tank @@ -1593,14 +1727,16 @@ The following command creates a new pool with an available hot spare: .Ed .Pp If one of the disks were to fail, the pool would be reduced to the degraded -state. The failed device can be replaced using the following command: +state. +The failed device can be replaced using the following command: .Bd -literal # zpool replace tank c0t0d0 c0t3d0 .Ed .Pp Once the data has been resilvered, the spare is automatically removed and is -made available should another device fails. The hot spare can be permanently -removed from the pool using the following command: +made available should another device fails. +The hot spare can be permanently removed from the pool using the following +command: .Bd -literal # zpool remove tank c0t2d0 .Ed @@ -1620,7 +1756,8 @@ pool: .Pp Once added, the cache devices gradually fill with content from main memory. Depending on the size of your cache devices, it could take over an hour for -them to fill. Capacity and reads can be monitored using the +them to fill. +Capacity and reads can be monitored using the .Cm iostat option as follows: .Bd -literal @@ -1660,9 +1797,9 @@ is: The following command dipslays the detailed information for the pool .Em data . This pool is comprised of a single raidz vdev where one of its devices -increased its capacity by 10GB. 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. +increased its capacity by 10GB. +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 # zpool list -v data NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT |