diff --git a/sbin/geom/class/multipath/gmultipath.8 b/sbin/geom/class/multipath/gmultipath.8 index 94713a7bdeb3..f6e286a43c72 100644 --- a/sbin/geom/class/multipath/gmultipath.8 +++ b/sbin/geom/class/multipath/gmultipath.8 @@ -1,373 +1,377 @@ .\" Copyright (c) 2007 Matthew Jacob .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd July 18, 2015 +.Dd September 8, 2016 .Dt GMULTIPATH 8 .Os .Sh NAME .Nm gmultipath .Nd "disk multipath control utility" .Sh SYNOPSIS .Nm .Cm create .Op Fl ARv .Ar name .Ar prov ... .Nm .Cm label .Op Fl ARv .Ar name .Ar prov ... .Nm .Cm configure .Op Fl APRv .Ar name .Nm .Cm add .Op Fl v .Ar name prov .Nm .Cm remove .Op Fl v .Ar name prov .Nm .Cm fail .Op Fl v .Ar name prov .Nm .Cm restore .Op Fl v .Ar name prov .Nm .Cm rotate .Op Fl v .Ar name .Nm .Cm prefer .Op Fl v .Ar name .Ar prov .Nm .Cm getactive .Op Fl v .Ar name .Nm .Cm destroy .Op Fl v .Ar name .Nm .Cm stop .Op Fl v .Ar name .Nm .Cm clear .Op Fl v .Ar prov ... .Nm .Cm list .Nm .Cm status .Nm .Cm load .Nm .Cm unload .Sh DESCRIPTION The .Nm utility is used for device multipath configuration. .Pp The multipath device can be configured using two different methods: .Dq manual or .Dq automatic . When using the .Dq manual method, no metadata are stored on the devices, so the multipath device has to be configured by hand every time it is needed. Additional device paths also will not be detected automatically. The .Dq automatic method uses on-disk metadata to detect device and all its paths. Metadata use the last sector of the underlying disk device and include device name and UUID. The UUID guarantees uniqueness in a shared storage environment but is in general too cumbersome to use. The name is what is exported via the device interface. .Pp The first argument to .Nm indicates an action to be performed: .Bl -tag -width ".Cm destroy" .It Cm create Create multipath device with .Dq manual method without writing any on-disk metadata. It is up to administrator, how to properly identify device paths. Kernel will only check that all given providers have same media and sector sizes. .Pp .Fl A option enables Active/Active mode, .Fl R option enables Active/Read mode, otherwise Active/Passive mode is used by default. .It Cm label Create multipath device with .Dq automatic method. Label the first given provider with on-disk metadata using the specified .Ar name . The rest of given providers will be retasted to detect these metadata. It reliably protects against specifying unrelated providers. Providers with no matching metadata detected will not be added to the device. .Pp .Fl A option enables Active/Active mode, .Fl R option enables Active/Read mode, otherwise Active/Passive mode is used by default. .It Cm configure Configure the given multipath device. .Pp .Fl A option enables Active/Active mode, .Fl P option enables Active/Passive mode, .Fl R option enables Active/Read mode. .It Cm add Add the given provider as a path to the given multipath device. Should normally be used only for devices created with .Dq manual method, unless you know what you are doing (you are sure that it is another device path, but tasting its metadata in regular .Dq automatic way is not possible). .It Cm remove Remove the given provider as a path from the given multipath device. If the last path removed, the multipath device will be destroyed. .It Cm fail Mark specified provider as a path of the specified multipath device as failed. If there are other paths present, new requests will be forwarded there. .It Cm restore Mark specified provider as a path of the specified multipath device as operational, allowing it to handle requests. .It Cm rotate Change the active provider/path to the next available provider in Active/Passive mode. .It Cm prefer Change the active provider/path to the specified provider in Active/Passive mode. .It Cm getactive Get the currently active provider(s)/path(s). .It Cm destroy Destroy the given multipath device clearing metadata. .It Cm stop Stop the given multipath device without clearing metadata. .It Cm clear Clear metadata on the given provider. .It Cm list See .Xr geom 8 . .It Cm status See .Xr geom 8 . .It Cm load See .Xr geom 8 . .It Cm unload See .Xr geom 8 . .El .Sh SYSCTL VARIABLES The following .Xr sysctl 8 variable can be used to control the behavior of the .Nm MULTIPATH GEOM class. .Bl -tag -width indent .It Va kern.geom.multipath.debug : No 0 Debug level of the .Nm MULTIPATH GEOM class. This can be set to 0 (default) or 1 to disable or enable various forms of chattiness. .It Va kern.geom.multipath.exclusive : No 1 Open underlying providers exclusively, preventing individual paths access. .El .Sh EXIT STATUS Exit status is 0 on success, and 1 if the command fails. .Sh MULTIPATH ARCHITECTURE This is a multiple path architecture with no device knowledge or presumptions other than size matching built in. Therefore the user must exercise some care in selecting providers that do indeed represent multiple paths to the same underlying disk device. The reason for this is that there are several criteria across multiple underlying transport types that can .Ar indicate identity, but in all respects such identity can rarely be considered .Ar definitive . .Pp For example, if you use the World Word Port Name of a Fibre Channel disk object you might believe that two disks that have the same WWPN on different paths (or even disjoint fabrics) might be considered the same disk. Nearly always this would be a safe assumption, until you realize that a WWPN, like an Ethernet MAC address, is a soft programmable entity, and that a misconfigured Director Class switch could lead you to believe incorrectly that you have found multiple paths to the same device. This is an extreme and theoretical case, but it is possible enough to indicate that the policy for deciding which of multiple pathnames refer to the same device should be left to the system operator who will use tools and knowledge of their own storage subsystem to make the correct configuration selection. .Pp There are Active/Passive, Active/Read and Active/Active operation modes supported. In Active/Passive mode only one path has I/O moving on it at any point in time. This I/O continues until an I/O is returned with a generic I/O error or a "Nonexistent Device" error. When this occurs, that path is marked FAIL, the next path in a list is selected as active and the failed I/O reissued. In Active/Active mode all paths not marked FAIL may handle I/O at the same time. Requests are distributed between paths to equalize load. -For capable devices it allows to utilize the bandwidth of all paths. +For capable devices it allows the utilisation of the bandwidth available on all paths. In Active/Read mode all paths not marked FAIL may handle reads at the same time, but unlike in Active/Active mode only one path handles write requests at any -point in time. -It allows to closer follow the original write request order if the layer above -needs it for data consistency (not waiting for requisite write completion +point in time; closely following the original write request order if the layer +above needs it for data consistency (not waiting for requisite write completion before sending dependent write). .Pp When new devices are added to the system the .Nm MULTIPATH GEOM class is given an opportunity to taste these new devices. If a new device has a .Nm MULTIPATH on-disk metadata label, the device is either used to create a new .Nm MULTIPATH GEOM, or added to the list of paths for an existing .Nm MULTIPATH GEOM. .Pp It is this mechanism that works reasonably with .Xr isp 4 and .Xr mpt 4 based Fibre Channel disk devices. For these devices, when a device disappears (due to e.g., a cable pull or power failure to a switch), the device is proactively marked as gone and I/O to it failed. This causes the .Nm MULTIPATH failure event just described. .Pp When Fibre Channel events inform either .Xr isp 4 or .Xr mpt 4 host bus adapters that new devices may have arrived (e.g., the arrival of an RSCN event from the Fabric Domain Controller), they can cause a rescan to occur and cause the attachment and configuration of any (now) new devices to occur, causing the taste event described above. .Pp This means that this multipath architecture is not a one-shot path failover, but can be considered to be steady state as long as failed paths are repaired (automatically or otherwise). .Pp Automatic rescanning is not a requirement. Nor is Fibre Channel. The same failover mechanisms work equally well for traditional "Parallel" SCSI but may require manual intervention with .Xr camcontrol 8 to cause the reattachment of repaired device links. .Sh EXAMPLES The following example shows how to use .Xr camcontrol 8 to find possible multiple path devices and to create a .Nm MULTIPATH GEOM class for them. .Bd -literal -offset indent mysys# camcontrol devlist at scbus0 target 0 lun 0 (da0,pass0) at scbus0 target 0 lun 1 (da1,pass1) at scbus1 target 0 lun 0 (da2,pass2) at scbus1 target 0 lun 1 (da3,pass3) mysys# camcontrol inquiry da0 -S ECNTX0LUN000000SER10ac0d01 mysys# camcontrol inquiry da2 -S ECNTX0LUN000000SER10ac0d01 .Ed .Pp Now that you have used the Serial Number to compare two disk paths it is not entirely unreasonable to conclude that these are multiple paths to the same device. However, only the user who is familiar with their storage is qualified to make this judgement. .Pp You can then use the .Nm command to label and create a .Nm MULTIPATH GEOM provider named .Ar FRED . .Bd -literal -offset indent gmultipath label -v FRED /dev/da0 /dev/da2 disklabel -Brw /dev/multipath/FRED auto newfs /dev/multipath/FREDa mount /dev/multipath/FREDa /mnt.... .Ed .Pp The resultant console output looks something like: .Bd -literal -offset indent GEOM_MULTIPATH: da0 added to FRED GEOM_MULTIPATH: da0 is now active path in FRED GEOM_MULTIPATH: da2 added to FRED .Ed .Pp To load the .Nm module at boot time, add this entry to .Pa /boot/loader.conf : .Bd -literal -offset ident geom_multipath_load="YES" .Ed .Sh SEE ALSO .Xr geom 4 , .Xr isp 4 , .Xr mpt 4 , .Xr loader.conf 5 , .Xr camcontrol 8 , .Xr geom 8 , .Xr mount 8 , .Xr newfs 8 , .Xr sysctl 8 +.Sh HISTORY +The +.Nm +utility first appeared in +.Fx 7.0 .Sh AUTHORS .An Matthew Jacob Aq Mt mjacob@FreeBSD.org .An Alexander Motin Aq Mt mav@FreeBSD.org diff --git a/sbin/ggate/ggatec/ggatec.8 b/sbin/ggate/ggatec/ggatec.8 index b3840008fe19..6f761dcfd99b 100644 --- a/sbin/ggate/ggatec/ggatec.8 +++ b/sbin/ggate/ggatec/ggatec.8 @@ -1,180 +1,185 @@ .\" Copyright (c) 2004 Pawel Jakub Dawidek .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd August 25, 2016 +.Dd September 8, 2016 .Dt GGATEC 8 .Os .Sh NAME .Nm ggatec .Nd "GEOM Gate network client and control utility" .Sh SYNOPSIS .Nm .Cm create .Op Fl n .Op Fl v .Op Fl o Cm ro | wo | rw .Op Fl p Ar port .Op Fl q Ar queue_size .Op Fl R Ar rcvbuf .Op Fl S Ar sndbuf .Op Fl s Ar sectorsize .Op Fl t Ar timeout .Op Fl u Ar unit .Ar host .Ar path .Nm .Cm rescue .Op Fl n .Op Fl v .Op Fl o Cm ro | wo | rw .Op Fl p Ar port .Op Fl R Ar rcvbuf .Op Fl S Ar sndbuf .Fl u Ar unit .Ar host .Ar path .Nm .Cm destroy .Op Fl f .Fl u Ar unit .Nm .Cm list .Op Fl v .Op Fl u Ar unit .Sh DESCRIPTION The .Nm utility is a network client for the GEOM Gate class. It is responsible for the creation of .Nm ggate devices and forwarding I/O requests between the .Nm GEOM Gate kernel subsystem and the .Xr ggated 8 network daemon. Available commands: .Bl -tag -width ".Cm destroy" .It Cm create Connect to a .Xr ggated 8 daemon on the specified host and create a .Nm ggate provider for the specified remote file or device. .It Cm rescue Create a new connection after the .Nm process has died or been killed. The new connection to the .Xr ggated 8 daemon handles pending and future requests. .It Cm destroy Destroy the given .Nm ggate provider. .It Cm list List .Nm ggate providers. .El .Pp Available options: .Bl -tag -width ".Fl s Cm ro | wo | rw" .It Fl f Forcibly destroy .Nm ggate provider (cancels all pending requests). .It Fl n Do not use .Dv TCP_NODELAY option on TCP sockets. .It Fl o Cm ro | wo | rw Specify permissions to use when opening the file or device: read-only .Pq Cm ro , write-only .Pq Cm wo , or read-write .Pq Cm rw . Default is .Cm rw . .It Fl p Ar port Port to connect to on the remote host. Default is 3080. .It Fl q Ar queue_size Number of pending I/O requests that can be queued before they will start to be canceled. Default is 1024. .It Fl R Ar rcvbuf Size of receive buffer to use. Default is 131072 (128kB). .It Fl S Ar sndbuf Size of send buffer to use. Default is 131072 (128kB). .It Fl s Ar sectorsize Sector size for .Nm ggate provider. If not specified, it is taken from the device, or set to 512 bytes for files. .It Fl t Ar timeout Number of seconds to wait before an I/O request will be canceled. Default is 0, which means no timeout. .It Fl u Ar unit Unit number to use. .It Fl v Do not fork, run in foreground and print debug information on standard output. .It Ar host Remote host to connect to. .It Ar path Path to a regular file or device. .El .Sh EXIT STATUS Exit status is 0 on success, or 1 if the command fails. To get details about the failure, .Nm should be called with the .Fl v option. .Sh EXAMPLES Use a CD-ROM device on a remote host. .Bd -literal -offset indent server# cat /etc/gg.exports client RO /dev/cd0 server# ggated client# ggatec create -o ro server /dev/cd0 ggate0 client# mount_cd9660 /dev/ggate0 /cdrom .Ed .Sh SEE ALSO .Xr geom 4 , .Xr ggated 8 , .Xr ggatel 8 , .Xr mount_cd9660 8 +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 5.3 . .Sh AUTHORS The .Nm utility as well as this manual page was written by .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/sbin/ggate/ggated/ggated.8 b/sbin/ggate/ggated/ggated.8 index 77bd026d4336..fc4fb0326bb2 100644 --- a/sbin/ggate/ggated/ggated.8 +++ b/sbin/ggate/ggated/ggated.8 @@ -1,123 +1,128 @@ .\" Copyright (c) 2004 Pawel Jakub Dawidek .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd August 25, 2016 +.Dd September 8, 2016 .Dt GGATED 8 .Os .Sh NAME .Nm ggated .Nd "GEOM Gate network daemon" .Sh SYNOPSIS .Nm .Op Fl h .Op Fl n .Op Fl v .Op Fl a Ar address .Op Fl p Ar port .Op Fl F Ar pidfile .Op Fl R Ar rcvbuf .Op Fl S Ar sndbuf .Op Ar "exports file" .Sh DESCRIPTION The .Nm utility is a network server for the GEOM Gate class. It runs on a server machine to service GEOM Gate requests from workers placed on a client machine. Keep in mind, that connections between .Xr ggatec 8 and .Nm are not encrypted. .Pp Available options: .Bl -tag -width ".Ar exports\ file" .It Fl a Ar address Specifies an IP address to bind to. .It Fl h Print available options. .It Fl n Do not use .Dv TCP_NODELAY option on TCP sockets. .It Fl p Ar port Port on which .Nm listens for connections. Default is 3080. .It Fl F Ar pidfile PID file that .Nm uses. .It Fl R Ar rcvbuf Size of receive buffer to use. Default is 131072 (128kB). .It Fl S Ar sndbuf Size of send buffer to use. Default is 131072 (128kB). .It Fl v Do not fork, run in foreground and print debug information on standard output. .It Ar "exports file" An alternate location for the exports file. .El .Pp The format of an exports file is as follows: .Bd -literal -offset indent 1.2.3.4 RO /dev/cd0 1.2.3.0/24 RW /tmp/test.img hostname WO /tmp/image .Ed .Sh FILES .Bl -tag -width ".Pa /var/run/ggated.pid" -compact .It Pa /var/run/ggated.pid The default location of the .Nm PID file. .El .Sh EXIT STATUS Exit status is 0 on success, or 1 if the command fails. To get details about the failure, .Nm should be called with the .Fl v option. .Sh EXAMPLES Export CD-ROM device and a file: .Bd -literal -offset indent # echo "1.2.3.0/24 RO /dev/cd0" > /etc/gg.exports # echo "client RW /image" >> /etc/gg.exports # ggated .Ed .Sh SEE ALSO .Xr geom 4 , .Xr ggatec 8 , .Xr ggatel 8 +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 5.3 . .Sh AUTHORS The .Nm utility as well as this manual page was written by .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/sbin/ggate/ggatel/ggatel.8 b/sbin/ggate/ggatel/ggatel.8 index f2eea7cf3fd5..7facee0c5369 100644 --- a/sbin/ggate/ggatel/ggatel.8 +++ b/sbin/ggate/ggatel/ggatel.8 @@ -1,158 +1,164 @@ .\" Copyright (c) 2004 Pawel Jakub Dawidek .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd July 14, 2015 +.Dd September 8, 2016 .Dt GGATEL 8 .Os .Sh NAME .Nm ggatel .Nd "GEOM Gate local control utility" .Sh SYNOPSIS .Nm .Cm create .Op Fl v .Op Fl o Cm ro | wo | rw .Op Fl s Ar sectorsize .Op Fl t Ar timeout .Op Fl u Ar unit .Ar path .Nm .Cm destroy .Op Fl f .Fl u Ar unit .Nm .Cm list .Op Fl v .Op Fl u Ar unit .Nm .Cm rescue .Op Fl v .Op Fl o Cm ro | wo | rw .Fl u Ar unit .Ar path .Sh DESCRIPTION The .Nm utility is a local GEOM Gate class consumer. It can be used as a replacement for .Xr md 4 devices or as a .Dq GEOMificator for non GEOM-aware devices, but it was mainly created as an example on how to use and how to communicate with the GEOM Gate kernel subsystem. .Pp Available commands: .Bl -tag -width ".Cm destroy" .It Cm create Create a .Nm ggate provider related to the given regular file or device. .It Cm destroy Destroy the given .Nm ggate provider. .It Cm list List .Nm ggate providers. .It Cm rescue Take over a previously created provider and handle pending and future -requests. This is useful if the initial +requests. +This is useful if the initial .Nm process died. To prevent data loss, the given path must lead to the regular file or device that was used to create the provider. .El .Pp Available options: .Bl -tag -width ".Fl s Cm ro | wo | rw" .It Fl f Forcibly destroy .Nm ggate provider (cancels all pending requests). .It Fl o Cm ro | wo | rw Specify permissions to use when opening the file or device: read-only .Pq Cm ro , write-only .Pq Cm wo , or read-write .Pq Cm rw . Default is .Cm rw . .It Fl s Ar sectorsize Sector size for .Nm ggate provider. If not specified, it is taken from the device, or set to 512 bytes for files. .It Fl t Ar timeout Number of seconds to wait before an I/O request will be canceled. 0 means no timeout. Default is 30. .It Fl u Ar unit Unit number to use. .It Fl v Do not fork, run in foreground and print debug information on standard output. .It Ar path Path to a regular file or device. .El .Sh EXIT STATUS Exit status is 0 on success, or 1 if the command fails. To get details about the failure, .Nm should be called with the .Fl v option. .Sh EXAMPLES .Dq GEOMify the .Dq Li fd0 device and use .Xr gbde 8 to encrypt data on a floppy disk. .Bd -literal -offset indent ggatel create -u 5 /dev/fd0 gbde init /dev/ggate5 gbde attach ggate5 newfs /dev/ggate5.bde mount /dev/ggate5.bde /secret cp /private/foo /secret/ umount /secret gbde detach ggate5 ggatel destroy -u 5 .Ed .Sh SEE ALSO .Xr geom 4 , .Xr gbde 8 , .Xr ggatec 8 , .Xr ggated 8 , .Xr mount 8 , .Xr newfs 8 +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 5.3 . .Sh AUTHORS The .Nm utility as well as this manual page was written by .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/sbin/hastctl/hastctl.8 b/sbin/hastctl/hastctl.8 index 397d4cfec0a3..0b8204d00b99 100644 --- a/sbin/hastctl/hastctl.8 +++ b/sbin/hastctl/hastctl.8 @@ -1,228 +1,233 @@ .\" Copyright (c) 2010 The FreeBSD Foundation .\" All rights reserved. .\" .\" This software was developed by Pawel Jakub Dawidek under sponsorship from .\" the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd March 14, 2013 +.Dd September 8, 2016 .Dt HASTCTL 8 .Os .Sh NAME .Nm hastctl .Nd "Highly Available Storage control utility" .Sh SYNOPSIS .Nm .Cm create .Op Fl d .Op Fl c Ar config .Op Fl e Ar extentsize .Op Fl k Ar keepdirty .Op Fl m Ar mediasize .Ar name ... .Nm .Cm role .Op Fl d .Op Fl c Ar config .Aq init | primary | secondary .Ar all | name ... .Nm .Cm list .Op Fl d .Op Fl c Ar config .Op Ar all | name ... .Nm .Cm status .Op Fl d .Op Fl c Ar config .Op Ar all | name ... .Nm .Cm dump .Op Fl d .Op Fl c Ar config .Op Ar all | name ... .Sh DESCRIPTION The .Nm utility is used to control the behaviour of the .Xr hastd 8 daemon. .Pp This utility should be used by HA software like .Nm heartbeat or .Nm ucarp to setup HAST resources role when changing from primary mode to secondary or vice versa. Be aware that if a file system like UFS exists on HAST provider and primary node dies, file system has to be checked for inconsistencies with the .Xr fsck 8 utility after switching secondary node to primary role. .Pp The first argument to .Nm indicates an action to be performed: .Bl -tag -width ".Cm create" .It Cm create Initialize local provider configured for the given resource. Additional options include: .Bl -tag -width ".Fl e Ar extentsize" .It Fl e Ar extentsize Size of an extent. Extent is a block which is used for synchronization. .Xr hastd 8 maintains a map of dirty extents and extent is the smallest region that can be marked as dirty. If any part of an extent is modified, entire extent will be synchronized when nodes connect. If extent size is too small, there will be too much disk activity related to dirty map updates, which will degrade performance of the given resource. If extent size is too large, synchronization, even in case of short outage, can take a long time increasing the risk of losing up-to-date node before synchronization process is completed. The default extent size is .Va 2MB . .It Fl k Ar keepdirty Maximum number of dirty extents to keep dirty all the time. Most recently used extents are kept dirty to reduce number of metadata updates. The default number of most recently used extents which will be kept dirty is .Va 64 . .It Fl m Ar mediasize Size of the smaller provider used as backend storage on both nodes. This option can be omitted if node providers have the same size on both sides. .El .Pp If size is suffixed with a k, M, G or T, it is taken as a kilobyte, megabyte, gigabyte or terabyte measurement respectively. .It Cm role Change role of the given resource. The role can be one of: .Bl -tag -width ".Cm secondary" .It Cm init Resource is turned off. .It Cm primary Local .Xr hastd 8 daemon will act as primary node for the given resource. System on which resource role is set to primary can use .Pa /dev/hast/ GEOM provider. .It Cm secondary Local .Xr hastd 8 daemon will act as secondary node for the given resource - it will wait for connection from the primary node and will handle I/O requests received from it. GEOM provider .Pa /dev/hast/ will not be created on secondary node. .El .It Cm list Present verbose status of the configured resources. .It Cm status Present terse (and more easy machine-parseable) status of the configured resources. .It Cm dump Dump metadata stored on local component for the configured resources. .El .Pp In addition, every subcommand can be followed by the following options: .Bl -tag -width ".Fl c Ar config" .It Fl c Ar config Specify alternative location of the configuration file. The default location is .Pa /etc/hast.conf . .It Fl d Print debugging information. This option can be specified multiple times to raise the verbosity level. .El .Sh FILES .Bl -tag -width ".Pa /var/run/hastctl" -compact .It Pa /etc/hast.conf Configuration file for .Nm and .Xr hastd 8 . .It Pa /var/run/hastctl Control socket used by .Nm to communicate with the .Xr hastd 8 daemon. .El .Sh EXIT STATUS Exit status is 0 on success, or one of the values described in .Xr sysexits 3 on failure. .Sh EXAMPLES Initialize HAST provider, create file system on it and mount it. .Bd -literal -offset indent nodeB# hastctl create shared nodeB# hastd nodeB# hastctl role secondary shared nodeA# hastctl create shared nodeA# hastd nodeA# hastctl role primary shared nodeA# newfs -U /dev/hast/shared nodeA# mount -o noatime /dev/hast/shared /shared nodeA# application_start .Ed .Pp Switch roles for the .Nm shared HAST resource. .Bd -literal -offset indent nodeA# application_stop nodeA# umount -f /shared nodeA# hastctl role secondary shared nodeB# hastctl role primary shared nodeB# fsck -t ufs /dev/hast/shared nodeB# mount -o noatime /dev/hast/shared /shared nodeB# application_start .Ed .Sh SEE ALSO .Xr sysexits 3 , .Xr geom 4 , .Xr hast.conf 5 , .Xr fsck 8 , .Xr ggatec 8 , .Xr ggatel 8 , .Xr hastd 8 , .Xr mount 8 , .Xr newfs 8 +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 8.1 . .Sh AUTHORS The .Nm was developed by .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org under sponsorship of the FreeBSD Foundation. diff --git a/sbin/hastd/hastd.8 b/sbin/hastd/hastd.8 index e30a11a46334..5ddf5e8eb2d0 100644 --- a/sbin/hastd/hastd.8 +++ b/sbin/hastd/hastd.8 @@ -1,232 +1,237 @@ .\" Copyright (c) 2010 The FreeBSD Foundation .\" All rights reserved. .\" .\" This software was developed by Pawel Jakub Dawidek under sponsorship from .\" the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd February 1, 2010 +.Dd September 8, 2016 .Dt HASTD 8 .Os .Sh NAME .Nm hastd .Nd "Highly Available Storage daemon" .Sh SYNOPSIS .Nm .Op Fl dFh .Op Fl c Ar config .Op Fl P Ar pidfile .Sh DESCRIPTION The .Nm daemon is responsible for managing highly available GEOM providers. .Pp .Nm -allows to transparently store data on two physically separated machines -connected over the TCP/IP network. +allows the transpaent storage of data on two physically separated machines +connected over a TCP/IP network. Only one machine (cluster node) can actively use storage provided by .Nm . This machine is called primary. The .Nm daemon operates on block level, which makes it transparent to file systems and applications. .Pp There is one main .Nm daemon which starts new worker process as soon as a role for the given resource is changed to primary or as soon as a role for the given resource is changed to secondary and remote (primary) node will successfully connect to it. Every worker process gets a new process title (see .Xr setproctitle 3 ) , which describes its role and resource it controls. The exact format is: .Bd -literal -offset indent hastd: () .Ed .Pp If (and only if) .Nm operates in primary role for the given resource, a corresponding .Pa /dev/hast/ disk-like device (GEOM provider) is created. File systems and applications can use this provider to send I/O requests to. Every write, delete and flush operation .Dv ( BIO_WRITE , BIO_DELETE , BIO_FLUSH ) is sent to the local component and replicated on the remote (secondary) node if it is available. Read operations .Dv ( BIO_READ ) are handled locally unless an I/O error occurs or the local version of the data is not up-to-date yet (synchronization is in progress). .Pp The .Nm daemon uses the GEOM Gate class to receive I/O requests from the in-kernel GEOM infrastructure. The .Nm geom_gate.ko module is loaded automatically if the kernel was not compiled with the following option: .Bd -ragged -offset indent .Cd "options GEOM_GATE" .Ed .Pp The connection between two .Nm daemons is always initiated from the one running as primary to the one running as secondary. When the primary .Nm is unable to connect or the connection fails, it will try to re-establish the connection every few seconds. Once the connection is established, the primary .Nm will synchronize every extent that was modified during connection outage to the secondary .Nm . .Pp It is possible that in the case of a connection outage between the nodes the .Nm primary role for the given resource will be configured on both nodes. This in turn leads to incompatible data modifications. Such a condition is called a split-brain and cannot be automatically resolved by the .Nm daemon as this will lead most likely to data corruption or loss of important changes. Even though it cannot be fixed by .Nm itself, it will be detected and a further connection between independently modified nodes will not be possible. Once this situation is manually resolved by an administrator, the resource on one of the nodes can be initialized (erasing local data), which makes a connection to the remote node possible again. Connection of the freshly initialized component will trigger full resource synchronization. .Pp A .Nm daemon never picks its role automatically. The role has to be configured with the .Xr hastctl 8 control utility by additional software like .Nm ucarp or .Nm heartbeat that can reliably manage role separation and switch secondary node to primary role in case of the primary's failure. .Pp The .Nm daemon can be started with the following command line arguments: .Bl -tag -width ".Fl P Ar pidfile" .It Fl c Ar config Specify alternative location of the configuration file. The default location is .Pa /etc/hast.conf . .It Fl d Print or log debugging information. This option can be specified multiple times to raise the verbosity level. .It Fl F Start the .Nm daemon in the foreground. By default .Nm starts in the background. .It Fl h Print the .Nm usage message. .It Fl P Ar pidfile Specify alternative location of a file where main process PID will be stored. The default location is .Pa /var/run/hastd.pid . .El .Sh FILES .Bl -tag -width ".Pa /var/run/hastd.pid" -compact .It Pa /etc/hast.conf The configuration file for .Nm and .Xr hastctl 8 . .It Pa /var/run/hastctl Control socket used by the .Xr hastctl 8 control utility to communicate with .Nm . .It Pa /var/run/hastd.pid The default location of the .Nm PID file. .El .Sh EXIT STATUS Exit status is 0 on success, or one of the values described in .Xr sysexits 3 on failure. .Sh EXAMPLES Launch .Nm on both nodes. Set role for resource .Nm shared to primary on .Nm nodeA and to secondary on .Nm nodeB . Create file system on .Pa /dev/hast/shared provider and mount it. .Bd -literal -offset indent nodeB# hastd nodeB# hastctl role secondary shared nodeA# hastd nodeA# hastctl role primary shared nodeA# newfs -U /dev/hast/shared nodeA# mount -o noatime /dev/hast/shared /shared .Ed .Sh SEE ALSO .Xr sysexits 3 , .Xr geom 4 , .Xr hast.conf 5 , .Xr ggatec 8 , .Xr ggated 8 , .Xr ggatel 8 , .Xr hastctl 8 , .Xr mount 8 , .Xr newfs 8 , .Xr g_bio 9 +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 8.1 . .Sh AUTHORS The .Nm was developed by .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org under sponsorship of the FreeBSD Foundation. diff --git a/sbin/iscontrol/iscontrol.8 b/sbin/iscontrol/iscontrol.8 index 36e0c471289f..f9d15f2b9192 100644 --- a/sbin/iscontrol/iscontrol.8 +++ b/sbin/iscontrol/iscontrol.8 @@ -1,137 +1,141 @@ .\" Copyright (c) 2007-2010 Daniel Braniss .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd October 9, 2014 +.Dd September 9, 2016 .Dt ISCONTROL 8 .Os .Sh NAME .Nm iscontrol .Nd login/negotiator/control for an iSCSI initiator session .Sh SYNOPSIS .Nm .Op Fl dv .Oo .Fl c Ar file .Op Fl n Ar nickname .Oc .Op Fl p Ar pidfile .Op Fl t Ar target .Op Ar variable Ns = Ns Ar value .Sh DESCRIPTION .Bf -symbolic This command, along with its kernel counterpart .Xr iscsi_initiator 4 , is obsolete. Users are advised to use .Xr iscsictl 8 instead. .Ef .Pp Internet SCSI (iSCSI) is a network protocol standard, that allows the use of the SCSI protocol over TCP/IP networks, the .Nm program is the userland side of an iSCSI session, see .Xr iscsi_initiator 4 . It has 2 modes of operation, if -d (discovery session) is specified, it will print out the .Em target names returned by the target and exit. In the second mode, it will, after a successful login/negotiation, run in daemon mode, monitoring the connection, and will try to reconnect in case of a network/target failure. It will terminate/logout the session when a SIGHUP signal is received. The flags are as follows: .Bl -tag -width variable=value .It Fl c Ar file a file containing configuration .Em key-options , see .Xr iscsi.conf 5 . .It Fl d do a .Em discovery session and exit. .It Fl n Ar nickname if .Sy -c file is specified, then search for the block named .Em nickname in that file, see .Xr iscsi.conf 5 . .It Fl p Ar pidfile will write the process ID of the session to the specified .Em pidfile .It Fl t Ar target the target's IP address or name. .It Fl v verbose mode. .It Ar variable Ns = Ns Ar value see .Xr iscsi.conf 5 for the complete list of variables/options and their possible values. .El .Sh EXAMPLES .Dl iscontrol -dt myiscsitarget .Pp will start a .Em discovery session with the target and print to stdout the list of available targetnames/targetadresses. Note: this listing does not necessarily mean availability, since depending on the target configuration, a discovery session might not need login/access permission, but a .Em full session certainly does. .sp .Dl iscontrol -c /etc/iscsi.conf -n myiscsi .Pp will read options from .Pa /etc/iscsi.conf , use the targetaddress found in the block nicknamed myiscsi, login and negotiate whatever options are specified, and start an iscsi-session. .Sh SEE ALSO .Xr da 4 , .Xr iscsi_initiator 4 , .Xr sa 4 , .Xr iscsi.conf 5 , .Xr camcontrol 8 , .Xr iscsictl 8 .Sh STANDARDS RFC 3720 -.\"Sh HISTORY +.Sh HISTORY +The +.Nm +utility appeared in +Fx 7.0 . .Sh BUGS .Nm should probably load the iscsi_initiator module if needed. .br Not all functions/specifications have been implemented yet, noticeably missing are the Task Management Functions. The error recovery, though not .Em fully compliant does a brave effort to recover from network disconnects. diff --git a/sbin/mdmfs/mdmfs.8 b/sbin/mdmfs/mdmfs.8 index a91cab260dc8..30a81fa49cf6 100644 --- a/sbin/mdmfs/mdmfs.8 +++ b/sbin/mdmfs/mdmfs.8 @@ -1,398 +1,404 @@ .\" .\" Copyright (c) 2001 Dima Dorfman. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd March 9, 2016 +.Dd September 9, 2016 .Dt MDMFS 8 .Os .Sh NAME .Nm mdmfs , .Nm mount_mfs .Nd configure and mount an in-memory file system using the .Xr md 4 driver .Sh SYNOPSIS .Nm .Op Fl DLlMNnPStTUX .Op Fl a Ar maxcontig .Op Fl b Ar block-size .Op Fl c Ar blocks-per-cylinder-group .Op Fl d Ar max-extent-size .Op Fl E Ar path-mdconfig .Op Fl e Ar maxbpg .Op Fl F Ar file .Op Fl f Ar frag-size .Op Fl i Ar bytes .Op Fl m Ar percent-free .Op Fl O Ar optimization .Op Fl o Ar mount-options .Op Fl p Ar permissions .Op Fl s Ar size .Op Fl T Ar fstype .Op Fl v Ar version .Op Fl w Ar user : Ns Ar group .Ar md-device .Ar mount-point .Sh DESCRIPTION The .Nm utility is designed to be a work-alike and look-alike of the deprecated .Xr mount_mfs 8 . The end result is essentially the same, but is accomplished in a completely different way. The .Nm utility configures an .Xr md 4 disk using .Xr mdconfig 8 , puts a UFS file system on it (unless .Fl P was specified) using .Xr newfs 8 , and mounts it using .Xr mount 8 . It can handle .Xr geom_uzip 4 compressed disk images, as long as the kernel supports this GEOM class. All the command line options are passed to the appropriate program at the appropriate stage in order to achieve the desired effect. .Pp By default, .Nm creates a swap-based .Pq Dv MD_SWAP disk with soft-updates enabled and mounts it on .Ar mount-point . It uses the .Xr md 4 device specified by .Ar md-device . If .Ar md-device is .Ql md (no unit number), it will use .Xr md 4 Ns 's auto-unit feature to automatically select an unused device. Unless otherwise specified with one of the options below, it uses the default arguments to all the helper programs. .Pp The following options are available. Where possible, the option letter matches the one used by .Xr mount_mfs 8 for the same thing. .Bl -tag -width indent .It Fl a Ar maxcontig Specify the maximum number of contiguous blocks that will be laid out before forcing a rotational delay (see the .Fl d option). .It Fl b Ar block-size The block size of the file system, in bytes. .It Fl c Ar blocks-per-cylinder-group The number of blocks per cylinder group in the file system. .It Fl D If not using auto-unit, do not run .Xr mdconfig 8 to try to detach the unit before attaching it. .It Fl d Ar max-extent-size The file system may choose to store large files using extents. This parameter specifies the largest extent size that may be -used. It is presently limited to its default value which is 16 +used. +It is presently limited to its default value which is 16 times the file system blocksize. .It Fl E Ar path-mdconfig Use .Ar path-mdconfig as a location of the .Xr mdconfig 8 utility. .It Fl e Ar maxbpg Indicate the maximum number of blocks any single file can allocate out of a cylinder group before it is forced to begin allocating blocks from another cylinder group. .It Fl F Ar file Create a vnode-backed .Pq Dv MD_VNODE memory disk backed by .Ar file . .It Fl f Ar frag-size The fragment size of the file system in bytes. .It Fl i Ar bytes Number of bytes per inode. .It Fl l Enable multilabel MAC on the new file system. .It Fl L Show the output of the helper programs. By default, it is sent to .Pa /dev/null . .It Fl M Create a .Xr malloc 9 backed disk .Pq Dv MD_MALLOC instead of a swap-backed disk. .It Fl m Ar percent-free The percentage of space reserved for the superuser. .It Fl N Do not actually run the helper programs. This is most useful in conjunction with .Fl X . .It Fl n Do not create a .Pa .snap directory on the new file system. .It Fl O Ar optimization Select the optimization preference; valid choices are .Cm space and .Cm time , which will optimize for minimum space fragmentation and minimum time spent allocating blocks, respectively. .It Fl o Ar mount-options Specify the mount options with which to mount the file system. See .Xr mount 8 for more information. .It Fl P Preserve the existing file system; do not run .Xr newfs 8 . This only makes sense if .Fl F is specified to create a vnode-backed disk. .It Fl p Ar permissions Set the file (directory) permissions of the mount point .Ar mount-point to .Ar permissions . The .Ar permissions argument can be in any of the mode formats recognized by .Xr chmod 1 . If symbolic permissions are specified, the operation characters .Dq + and .Dq - are interpreted relative to the initial permissions of .Dq a=rwx . .It Fl S Do not enable soft-updates on the file system. .It Fl s Ar size Specify the size of the disk to create. This only makes sense if .Fl F is .Em not specified. That is, this will work for the default swap-backed .Pq Dv MD_SWAP disks, and the optional .Pq Fl M .Xr malloc 9 backed disks .Pq Dv MD_MALLOC . .It Fl t Turn on the TRIM enable flag for .Xr newfs 8 . When used with a file system that issue BIO_DELETE bio requests, .Xr md 4 returns deleted blocks to the system memory pool. .It Fl T Ar fstype Specify a file system type for a vnode-backed memory disk. Any file system supported by .Xr mount 8 command can be specified. This option only makes sense when .Fl F and .Fl P are used. .It Fl U Enable soft-updates on the file system. This is the default, and is accepted only for compatibility. It is only really useful to negate the .Fl S flag, should such a need occur. .It Fl v Ar version Specify the UFS version number for use on the file system; it may be either .Dv 1 or .Dv 2 . The default is derived from the default of the .Xr newfs 8 command. .It Fl w Ar user : Ns Ar group Set the owner and group to .Ar user and .Ar group , respectively. The arguments have the same semantics as with .Xr chown 8 , but specifying just a .Ar user or just a .Ar group is not supported. .It Fl X Print what command will be run before running it, and other assorted debugging information. .El .Pp The .Fl F and .Fl s options are passed to .Xr mdconfig 8 as .Fl f and .Fl s , respectively. The .Fl a , b , c , d , e , f , i , m and .Fl n options are passed to .Xr newfs 8 with the same letter. The .Fl O option is passed to .Xr newfs 8 as .Fl o . The .Fl o option is passed to .Xr mount 8 with the same letter. The .Fl T option is passed to .Xr mount 8 as .Fl t . -See the programs that the options are passed to for more information -on their semantics. +For information on semantics, refer to the documentation of the programs +that the options are passed to. .Sh EXAMPLES Create and mount a 32 megabyte swap-backed file system on .Pa /tmp : .Pp .Dl "mdmfs -s 32m md /tmp" .Pp The same file system created as an entry in .Pa /etc/fstab : .Pp .Dl "md /tmp mfs rw,-s32m 2 0" .Pp Create and mount a 16 megabyte malloc-backed file system on .Pa /tmp using the .Pa /dev/md1 device; furthermore, do not use soft-updates on it and mount it .Cm async : .Pp .Dl "mdmfs -M -S -o async -s 16m md1 /tmp" .Pp Create and mount a .Xr geom_uzip 4 based compressed disk image: .Pp .Dl "mdmfs -P -F foo.uzip -oro md.uzip /tmp/" .Pp Mount the same image, specifying the .Pa /dev/md1 device: .Pp .Dl "mdmfs -P -F foo.uzip -oro md1.uzip /tmp/" .Pp Configure a vnode-backed file system and mount its first partition, using automatic device numbering: .Pp .Dl "mdmfs -P -F foo.img mds1a /tmp/" .Pp Mount a vnode-backed cd9660 file system using automatic device numbering: .Pp .Dl "mdmfs -T cd9660 -P -F foo.iso md /tmp" .Sh COMPATIBILITY The .Nm utility, while designed to be compatible with .Xr mount_mfs 8 , can be useful by itself. Since .Xr mount_mfs 8 had some silly defaults, a .Dq compatibility mode is provided for the case where bug-to-bug compatibility is desired. .Pp Compatibility is enabled by starting .Nm with the name .Li mount_mfs or .Li mfs (as returned by .Xr getprogname 3 ) . In this mode, the following behavior, as done by .Xr mount_mfs 8 , is duplicated: .Bl -bullet -offset indent .It The file mode of .Ar mount-point is set by default to .Li 01777 as if .Fl p Ar 1777 was given on the command line. .El .Sh SEE ALSO .Xr md 4 , .Xr fstab 5 , .Xr mdconfig 8 , .Xr mount 8 , .Xr newfs 8 +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 5.0 . .Sh AUTHORS .An Dima Dorfman diff --git a/sbin/mount_nfs/mount_nfs.8 b/sbin/mount_nfs/mount_nfs.8 index 3a9cff54c883..6dc2c0d79fb1 100644 --- a/sbin/mount_nfs/mount_nfs.8 +++ b/sbin/mount_nfs/mount_nfs.8 @@ -1,526 +1,532 @@ .\" Copyright (c) 1992, 1993, 1994, 1995 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)mount_nfs.8 8.3 (Berkeley) 3/29/95 .\" $FreeBSD$ .\" -.Dd October 30, 2014 +.Dd September 10, 2016 .Dt MOUNT_NFS 8 .Os .Sh NAME .Nm mount_nfs .Nd mount NFS file systems .Sh SYNOPSIS .Nm .Op Fl 23bcdiLlNPsTU .Op Fl a Ar maxreadahead .Op Fl D Ar deadthresh .Op Fl g Ar maxgroups .Op Fl I Ar readdirsize .Op Fl o Ar options .Op Fl R Ar retrycnt .Op Fl r Ar readsize .Op Fl t Ar timeout .Op Fl w Ar writesize .Op Fl x Ar retrans .Ar rhost : Ns Ar path node .Sh DESCRIPTION The .Nm utility calls the .Xr nmount 2 system call to prepare and graft a remote NFS file system .Pq Ar rhost : Ns Ar path on to the file system tree at the point .Ar node . This command is normally executed by .Xr mount 8 . It implements the mount protocol as described in RFC 1094, Appendix A and .%T "NFS: Network File System Version 3 Protocol Specification" , Appendix I. .Pp By default, .Nm keeps retrying until the mount succeeds. This behaviour is intended for file systems listed in .Xr fstab 5 that are critical to the boot process. For non-critical file systems, the .Cm bg and .Cm retrycnt options provide mechanisms to prevent the boot process from hanging if the server is unavailable. .Pp If the server becomes unresponsive while an NFS file system is mounted, any new or outstanding file operations on that file system will hang uninterruptibly until the server comes back. To modify this default behaviour, see the .Cm intr and .Cm soft options. .Pp The options are: .Bl -tag -width indent .It Fl o Options are specified with a .Fl o flag followed by a comma separated string of options. See the .Xr mount 8 man page for possible options and their meanings. The following NFS specific options are also available: .Bl -tag -width indent .It Cm acregmin Ns = Ns Aq Ar seconds .It Cm acregmax Ns = Ns Aq Ar seconds .It Cm acdirmin Ns = Ns Aq Ar seconds .It Cm acdirmax Ns = Ns Aq Ar seconds When attributes of files are cached, a timeout calculated to determine whether a given cache entry has expired. These four values determine the upper and lower bounds of the timeouts for .Dq directory attributes and .Dq regular (ie: everything else). The default values are 3 -> 60 seconds for regular files, and 30 -> 60 seconds for directories. The algorithm to calculate the timeout is based on the age of the file. The older the file, the longer the cache is considered valid, subject to the limits above. .It Cm actimeo Ns = Ns Aq Ar seconds Set four cache timeouts above to specified value. .It Cm allgssname This option can be used along with .Fl o Cm gssname to specify that all operations should use the host-based initiator credential. This may be used for clients that run system daemons that need to access files on the NFSv4 mounted volume. .It Cm bg If an initial attempt to contact the server fails, fork off a child to keep trying the mount in the background. Useful for .Xr fstab 5 , where the file system mount is not critical to multiuser operation. .It Cm deadthresh Ns = Ns Aq Ar value Set the .Dq "dead server threshold" to the specified number of round trip timeout intervals before a .Dq "server not responding" message is displayed. .It Cm dumbtimer Turn off the dynamic retransmit timeout estimator. This may be useful for UDP mounts that exhibit high retry rates, since it is possible that the dynamically estimated timeout interval is too short. .It Cm fg Same as not specifying .Cm bg . .It Cm gssname Ns = Ns Aq Ar service-principal-name This option can be used with the KerberosV security flavors for NFSv4 mounts to specify the .Dq "service-principal-name" of a host-based entry in the default keytab file that is used for system operations. It allows the mount to be performed by .Dq "root" and avoids problems with cached credentials for the system operations expiring. The .Dq "service-prinicpal-name" should be specified without instance or domain and is typically .Dq "host" , .Dq "nfs" or .Dq "root" . .It Cm hard Same as not specifying .Cm soft . .It Cm intr Make the mount interruptible, which implies that file system calls that are delayed due to an unresponsive server will fail with EINTR when a termination signal is posted for the process. .It Cm maxgroups Ns = Ns Aq Ar value Set the maximum size of the group list for the credentials to the specified value. This should be used for mounts on old servers that cannot handle a group list size of 16, as specified in RFC 1057. Try 8, if users in a lot of groups cannot get response from the mount point. .It Cm mntudp Force the mount protocol to use UDP transport, even for TCP NFS mounts. (Necessary for some old .Bx servers.) .It Cm nametimeo Ns = Ns Aq Ar value Override the default of NFS_DEFAULT_NAMETIMEO for the timeout (in seconds) for positive name cache entries. If this is set to 0 it disables positive name caching for the mount point. .It Cm negnametimeo Ns = Ns Aq Ar value Override the default of NFS_DEFAULT_NEGNAMETIMEO for the timeout (in seconds) -for negative name cache entries. If this is set to 0 it disables negative -name caching for the mount point. +for negative name cache entries. +If this is set to 0 it disables negative name caching for the mount point. .It Cm nfsv2 Use the NFS Version 2 protocol (the default is to try version 3 first then version 2). Note that NFS version 2 has a file size limit of 2 gigabytes. .It Cm nfsv3 Use the NFS Version 3 protocol. .It Cm nfsv4 Use the NFS Version 4 protocol. This option will force the mount to use TCP transport. .It Cm minorversion Ns = Ns Aq Ar value Override the default of 0 for the minor version of the NFS Version 4 protocol. The only minor version currently supported is 1. This option is only meaningful when used with the .Cm nfsv4 option. .It Cm pnfs Enable support for parallel NFS (pNFS) for minor version 1 of the NFS Version 4 protocol. This option is only meaningful when used with the .Cm minorversion option. .It Cm noac Disable attribute caching. .It Cm noconn For UDP mount points, do not do a .Xr connect 2 . This must be used if the server does not reply to requests from the standard NFS port number 2049 or replies to requests using a different IP address (which can occur if the server is multi-homed). Setting the .Va vfs.nfs.nfs_ip_paranoia sysctl to 0 will make this option the default. .It Cm nocto Normally, NFS clients maintain the close-to-open cache coherency. This works by flushing at close time and checking at open time. Checking at open time is implemented by getting attributes from the server and purging the data cache if they do not match attributes cached by the client. .Pp This option disables checking at open time. It may improve performance for read-only mounts, but should only be used if the data on the server changes rarely. Be sure to understand the consequences before enabling this option. .It Cm noinet4 , noinet6 Disables .Dv AF_INET or .Dv AF_INET6 connections. Useful for hosts that have both an A record and an AAAA record for the same name. .It Cm nolockd Do .Em not forward .Xr fcntl 2 locks over the wire. All locks will be local and not seen by the server and likewise not seen by other NFS clients. This removes the need to run the .Xr rpcbind 8 service and the .Xr rpc.statd 8 and .Xr rpc.lockd 8 servers on the client. Note that this option will only be honored when performing the initial mount, it will be silently ignored if used while updating the mount options. .It Cm noncontigwr This mount option allows the NFS client to combine non-contiguous byte ranges being written such that the dirty byte range becomes a superset of the bytes that are dirty. This reduces the number of writes significantly for software builds. -The merging of byte ranges isn't done if the file has been file +The merging of byte ranges is not done if the file has been file locked, since most applications modifying a file from multiple clients will use file locking. As such, this option could result in a corrupted file for the rare case of an application modifying the file from multiple clients concurrently without using file locking. .It Cm principal For the RPCSEC_GSS security flavors, such as krb5, krb5i and krb5p, this option sets the name of the host based principal name expected -by the server. This option overrides the default, which will be -``nfs@'' and should normally be sufficient. +by the server. +This option overrides the default, which will be ``nfs@'' +and should normally be sufficient. .It Cm noresvport Do .Em not use a reserved socket port number (see below). .It Cm port Ns = Ns Aq Ar port_number Use specified port number for NFS requests. The default is to query the portmapper for the NFS port. .It Cm proto Ns = Ns Aq Ar protocol Specify transport protocol version to use. Currently, they are: .Bd -literal udp - Use UDP over IPv4 tcp - Use TCP over IPv4 udp6 - Use UDP over IPv6 tcp6 - Use TCP over IPv6 .Ed .It Cm rdirplus Used with NFSV3 to specify that the \fBReaddirPlus\fR RPC should be used. For NFSV4, setting this option has a similar effect, in that it will make the Readdir Operation get more attributes. This option reduces RPC traffic for cases such as .Dq "ls -l" , but tends to flood the attribute and name caches with prefetched entries. Try this option and see whether performance improves or degrades. Probably most useful for client to server network interconnects with a large bandwidth times delay product. .It Cm readahead Ns = Ns Aq Ar value Set the read-ahead count to the specified value. This may be in the range of 0 - 4, and determines how many blocks will be read ahead when a large file is being read sequentially. Trying a value greater than 1 for this is suggested for mounts with a large bandwidth * delay product. .It Cm readdirsize Ns = Ns Aq Ar value Set the readdir read size to the specified value. The value should normally be a multiple of .Dv DIRBLKSIZ that is <= the read size for the mount. .It Cm resvport Use a reserved socket port number. This flag is obsolete, and only retained for compatibility reasons. Reserved port numbers are used by default now. (For the rare case where the client has a trusted root account but untrustworthy users and the network cables are in secure areas this does help, but for normal desktop clients this does not apply.) .It Cm retrans Ns = Ns Aq Ar value Set the retransmit timeout count for soft mounts to the specified value. .It Cm retrycnt Ns = Ns Aq Ar count Set the mount retry count to the specified value. The default is a retry count of zero, which means to keep retrying forever. There is a 60 second delay between each attempt. .It Cm rsize Ns = Ns Aq Ar value Set the read data size to the specified value. It should normally be a power of 2 greater than or equal to 1024. This should be used for UDP mounts when the .Dq "fragments dropped due to timeout" value is getting large while actively using a mount point. (Use .Xr netstat 1 with the .Fl s option to see what the .Dq "fragments dropped due to timeout" value is.) .It Cm sec Ns = Ns Aq Ar flavor This option specifies what security flavor should be used for the mount. Currently, they are: .Bd -literal krb5 - Use KerberosV authentication krb5i - Use KerberosV authentication and apply integrity checksums to RPCs krb5p - Use KerberosV authentication and encrypt the RPC data sys - The default AUTH_SYS, which uses a uid + gid list authenticator .Ed .It Cm soft A soft mount, which implies that file system calls will fail after .Ar retrycnt round trip timeout intervals. .It Cm tcp Use TCP transport. This is the default option, as it provides for increased reliability on both LAN and WAN configurations compared to UDP. Some old NFS servers do not support this method; UDP mounts may be required for interoperability. .It Cm timeout Ns = Ns Aq Ar value Set the initial retransmit timeout to the specified value, expressed in tenths of a second. May be useful for fine tuning UDP mounts over internetworks with high packet loss rates or an overloaded server. Try increasing the interval if .Xr nfsstat 1 shows high retransmit rates while the file system is active or reducing the value if there is a low retransmit rate but long response delay observed. (Normally, the .Cm dumbtimer option should be specified when using this option to manually tune the timeout interval.) .It Cm timeo Ns = Ns Aq Ar value Alias for .Cm timeout . .It Cm udp Use UDP transport. .It Cm vers Ns = Ns Aq Ar vers_number Use the specified version number for NFS requests. See the .Cm nfsv2 , .Cm nfsv3 , and .Cm nfsv4 options for details. .It Cm wcommitsize Ns = Ns Aq Ar value Set the maximum pending write commit size to the specified value. This determines the maximum amount of pending write data that the NFS client is willing to cache for each file. .It Cm wsize Ns = Ns Aq Ar value Set the write data size to the specified value. Ditto the comments w.r.t.\& the .Cm rsize option, but using the .Dq "fragments dropped due to timeout" value on the server instead of the client. Note that both the .Cm rsize and .Cm wsize options should only be used as a last ditch effort at improving performance when mounting servers that do not support TCP mounts. .El .El .Sh COMPATIBILITY The following command line flags are equivalent to .Fl o named options and are supported for compatibility with older installations. .Bl -tag -width indent .It Fl 2 Same as .Fl o Cm nfsv2 .It Fl 3 Same as .Fl o Cm nfsv3 .It Fl D Same as .Fl o Cm deadthresh .It Fl I Same as .Fl o Cm readdirsize Ns = Ns Aq Ar value .It Fl L Same as .Fl o Cm nolockd .It Fl N Same as .Fl o Cm noresvport .It Fl P Use a reserved socket port number. This flag is obsolete, and only retained for compatibility reasons. (For the rare case where the client has a trusted root account but untrustworthy users and the network cables are in secure areas this does help, but for normal desktop clients this does not apply.) .It Fl R Same as .Fl o Cm retrycnt Ns = Ns Aq Ar value .It Fl T Same as .Fl o Cm tcp .It Fl U Same as .Fl o Cm mntudp .It Fl a Same as .Fl o Cm readahead Ns = Ns Aq Ar value .It Fl b Same as .Fl o Cm bg .It Fl c Same as .Fl o Cm noconn .It Fl d Same as .Fl o Cm dumbtimer .It Fl g Same as .Fl o Cm maxgroups .It Fl i Same as .Fl o Cm intr .It Fl l Same as .Fl o Cm rdirplus .It Fl r Same as .Fl o Cm rsize Ns = Ns Aq Ar value .It Fl s Same as .Fl o Cm soft .It Fl t Same as .Fl o Cm retransmit Ns = Ns Aq Ar value .It Fl w Same as .Fl o Cm wsize Ns = Ns Aq Ar value .It Fl x Same as .Fl o Cm retrans Ns = Ns Aq Ar value .El .Pp The following .Fl o named options are equivalent to other .Fl o named options and are supported for compatibility with other operating systems (e.g., Linux, Solaris, and OSX) to ease usage of .Xr autofs 5 support. .Bl -tag -width indent .It Fl o Cm vers Ns = Ns 2 Same as .Fl o Cm nfsv2 .It Fl o Cm vers Ns = Ns 3 Same as .Fl o Cm nfsv3 .It Fl o Cm vers Ns = Ns 4 Same as .Fl o Cm nfsv4 .El .Sh SEE ALSO .Xr nmount 2 , .Xr unmount 2 , .Xr nfsv4 4 , .Xr fstab 5 , .Xr gssd 8 , .Xr mount 8 , .Xr nfsd 8 , .Xr nfsiod 8 , .Xr showmount 8 +.Sh HISTORY +A version of the +.Nm +utility appeared in +.Bx 4.4 . .Sh BUGS Since nfsv4 performs open/lock operations that have their ordering strictly enforced by the server, the options .Cm intr and .Cm soft cannot be safely used. .Cm hard nfsv4 mounts are strongly recommended. diff --git a/sbin/nandfs/nandfs.8 b/sbin/nandfs/nandfs.8 index e54f9f81ef63..9995905d3c68 100644 --- a/sbin/nandfs/nandfs.8 +++ b/sbin/nandfs/nandfs.8 @@ -1,74 +1,79 @@ .\" .\" Copyright (c) 2012 The FreeBSD Foundation .\" All rights reserved. .\" .\" This software was developed by Semihalf under sponsorship .\" from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd February 28, 2012 +.Dd September 10, 2016 .Dt NANDFS 8 .Os .Sh NAME .Nm nandfs .Nd manage mounted NAND FS .Sh SYNOPSIS .Nm .Cm lssnap .Ar node .Nm .Cm mksnap .Ar node .Nm .Cm rmsnap .Ar snapshot node .Sh DESCRIPTION The .Nm -utility allows to manage snapshots of a mounted NAND FS. +utility allows the management of snapshots on a mounted NAND FS. .Sh EXAMPLES Create a snapshot of filesystem mounted on .Em /nand . .Bd -literal -offset 2n .Li # Ic nandfs mksnap /nand 1 .Ed .Pp List snapshots of filesystem mounted on .Em /nand . .Bd -literal -offset 2n .Li # Ic nandfs lssnap /nand 1 2012-02-28 18:49:45 ss 138 2 .Ed .Pp Remove snapshot 1 of filesystem mounted on .Em /nand . .Bd -literal -offset 2n .Li # Ic nandfs rmsnap 1 /nand .Ed +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 10.0 . .Sh AUTHORS This utility and manual page were written by .An Mateusz Guzik . diff --git a/sbin/nvmecontrol/nvmecontrol.8 b/sbin/nvmecontrol/nvmecontrol.8 index 9ac87f151656..73842212da31 100644 --- a/sbin/nvmecontrol/nvmecontrol.8 +++ b/sbin/nvmecontrol/nvmecontrol.8 @@ -1,147 +1,152 @@ .\" .\" Copyright (c) 2012 Intel Corporation .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions, and the following disclaimer, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" substantially similar to the "NO WARRANTY" disclaimer below .\" ("Disclaimer") and any redistribution must be conditioned upon .\" including a substantially similar Disclaimer requirement for further .\" binary redistribution. .\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGES. .\" .\" nvmecontrol man page. .\" .\" Author: Jim Harris .\" .\" $FreeBSD$ .\" -.Dd March 26, 2013 +.Dd September 10, 2016 .Dt NVMECONTROL 8 .Os .Sh NAME .Nm nvmecontrol .Nd NVM Express control utility .Sh SYNOPSIS .Nm .Ic devlist .Nm .Ic identify .Op Fl v .Op Fl x .Aq device id .Nm .Ic perftest .Aq Fl n Ar num_threads .Aq Fl o Ar read|write .Op Fl p .Aq Fl s Ar size_in_bytes .Aq Fl t Ar time_in_sec .Aq namespace id .Nm .Ic reset .Aq controller id .Nm .Ic logpage .Aq Fl p Ar page_id .Op Fl x .Aq device id .Aq namespace id .Nm .Ic firmware .Op Fl s Ar slot .Op Fl f Ar path_to_firmware .Op Fl a .Aq device id .Nm .Ic power .Op Fl l .Op Fl p power_state .Op fl w workload_hint .Sh DESCRIPTION NVM Express (NVMe) is a storage protocol standard, for SSDs and other high-speed storage devices over PCI Express. .Sh EXAMPLES .Dl nvmecontrol devlist .Pp Display a list of NVMe controllers and namespaces along with their device nodes. .Pp .Dl nvmecontrol identify nvme0 .Pp Display a human-readable summary of the nvme0 IDENTIFY_CONTROLLER data. .Pp .Dl nvmecontrol identify -x -v nvme0ns1 .Pp Display an hexadecimal dump of the nvme0 IDENTIFY_NAMESPACE data for namespace 1. .Pp .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1 .Pp -Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds. Each -thread will issue a single 512 byte read command. Results are printed to -stdout when 30 seconds expires. +Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds. +Each thread will issue a single 512 byte read command. +Results are printed to stdout when 30 seconds expires. .Pp .Dl nvmecontrol reset nvme0 .Pp Perform a controller-level reset of the nvme0 controller. .Pp .Dl nvmecontrol logpage -p 1 nvme0 .Pp Display a human-readable summary of the nvme0 controller's Error Information Log. Log pages defined by the NVMe specification include Error Information Log (ID=1), SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3). .Pp .Dl nvmecontrol logpage -p 1 -x nvme0 .Pp Display a hexadecimal dump of the nvme0 controller's Error Information Log. .Pp .Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0 .Pp Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the nvme0 controller, but do not activate the image. .Pp .Dl nvmecontrol firmware -s 4 -a nvme0 .Pp Activate the firmware in slot 4 of the nvme0 controller on the next reset. .Pp .Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0 .Pp Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the nvme0 controller and activate it on the next reset. .Pp .Dl nvmecontrol power -l nvme0 .Pp List all the current power modes. .Pp .Dl nvmecontrol power -p 3 nvme0 .Pp Set the current power mode. .Pp .Dl nvmecontrol power nvme0 .Pp Get the current power mode. +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 9.2 . .Sh AUTHORS .An -nosplit .Nm was developed by Intel and originally written by .An Jim Harris Aq Mt jimharris@FreeBSD.org . .Pp This man page was written by .An Jim Harris Aq Mt jimharris@FreeBSD.org .