diff options
| author | ru <ru@FreeBSD.org> | 2004-07-02 21:45:06 +0000 |
|---|---|---|
| committer | ru <ru@FreeBSD.org> | 2004-07-02 21:45:06 +0000 |
| commit | 46fddaa54b09baa407fa66a14d46c0cc3a906e60 (patch) | |
| tree | 602e903272257a1c5b455a48800dcaa680741026 | |
| parent | 20fbd172b22ab587e9d796f4cb8664a235cebe78 (diff) | |
| download | FreeBSD-src-46fddaa54b09baa407fa66a14d46c0cc3a906e60.zip FreeBSD-src-46fddaa54b09baa407fa66a14d46c0cc3a906e60.tar.gz | |
Mechanically kill hard sentence breaks.
37 files changed, 1148 insertions, 585 deletions
diff --git a/sbin/atacontrol/atacontrol.8 b/sbin/atacontrol/atacontrol.8 index 2f69457..4bb18be 100644 --- a/sbin/atacontrol/atacontrol.8 +++ b/sbin/atacontrol/atacontrol.8 @@ -104,7 +104,7 @@ is done on boot. Detach an ATA .Ar channel . Devices on the channel are removed from the kernel, -and all outstanding transfers etc. are returned back to the system marked +and all outstanding transfers etc.\& are returned back to the system marked as failed. .It Ic reinit Reinitialize an ATA diff --git a/sbin/atm/fore_dnld/fore_dnld.8 b/sbin/atm/fore_dnld/fore_dnld.8 index a152e21..7ffd0d2 100644 --- a/sbin/atm/fore_dnld/fore_dnld.8 +++ b/sbin/atm/fore_dnld/fore_dnld.8 @@ -64,7 +64,8 @@ for PCA-200E adapters. .El .Sh NOTES For the PCA200E adapter, if no file is specified on the command -line a built-in copy of version 4.1.12 microcode is used. When the +line a built-in copy of version 4.1.12 microcode is used. +When the option .Fl 3 is specified version 3.0.1 microcode is used instead. diff --git a/sbin/badsect/badsect.8 b/sbin/badsect/badsect.8 index 3e387d3..be24feb 100644 --- a/sbin/badsect/badsect.8 +++ b/sbin/badsect/badsect.8 @@ -40,7 +40,8 @@ .Sh DESCRIPTION The .Nm -utility makes a file to contain a bad sector. Normally, bad sectors +utility makes a file to contain a bad sector. +Normally, bad sectors are made inaccessible by the standard formatter, which provides a forwarding table for bad sectors to the driver. If a driver supports the bad blocking standard it is much preferable to @@ -83,8 +84,10 @@ relative sector numbers in its console error messages.) Then change back to the root directory, unmount the file system and run .Xr fsck 8 -on the file system. The bad sectors should show up in two files -or in the bad sector files and the free list. Have +on the file system. +The bad sectors should show up in two files +or in the bad sector files and the free list. +Have .Xr fsck 8 remove files containing the offending bad sectors, but .Em do not diff --git a/sbin/camcontrol/camcontrol.8 b/sbin/camcontrol/camcontrol.8 index 84c3bf9..04eac548 100644 --- a/sbin/camcontrol/camcontrol.8 +++ b/sbin/camcontrol/camcontrol.8 @@ -152,38 +152,44 @@ CAM subsystem. The .Nm utility -can cause a loss of data and/or system crashes if used improperly. Even +can cause a loss of data and/or system crashes if used improperly. +Even expert users are encouraged to exercise caution when using this command. Novice users should stay away from this utility. .Pp The .Nm utility has a number of primary functions, many of which support an optional -device identifier. A device identifier can take one of three forms: +device identifier. +A device identifier can take one of three forms: .Bl -tag -width 14n .It deviceUNIT Specify a device name and unit number combination, like "da5" or "cd3". -Note that character device node names (e.g. /dev/da0) are +Note that character device node names (e.g.\& /dev/da0) are .Em not allowed here. .It bus:target -Specify a bus number and target id. The bus number can be determined from +Specify a bus number and target id. +The bus number can be determined from the output of .Dq camcontrol devlist . The lun defaults to 0. .It bus:target:lun -Specify the bus, target and lun for a device. (e.g. 1:2:0) +Specify the bus, target and lun for a device. +(e.g.\& 1:2:0) .El .Pp The device identifier, if it is specified, .Em must come immediately after the function name, and before any generic or -function-specific arguments. Note that the +function-specific arguments. +Note that the .Fl n and .Fl u arguments described below will override any device name or unit number -specified beforehand. The +specified beforehand. +The .Fl n and .Fl u @@ -196,24 +202,28 @@ Most of the primary functions support these generic arguments: .Bl -tag -width 14n .It Fl C Ar count -SCSI command retry count. In order for this to work, error recovery +SCSI command retry count. +In order for this to work, error recovery .Pq Fl E must be turned on. .It Fl E Instruct the kernel to perform generic SCSI error recovery for the given -command. This is needed in order for the retry count +command. +This is needed in order for the retry count .Pq Fl C -to be honored. Other than retrying commands, the generic error recovery in +to be honored. +Other than retrying commands, the generic error recovery in the code will generally attempt to spin up drives that are not spinning. It may take some other actions, depending upon the sense code returned from the command. .It Fl n Ar dev_name -Specify the device type to operate on, e.g. "da", "cd". +Specify the device type to operate on, e.g.\& "da", "cd". .It Fl t Ar timeout -SCSI command timeout in seconds. This overrides the default timeout for +SCSI command timeout in seconds. +This overrides the default timeout for any given command. .It Fl u Ar unit_number -Specify the device unit number, e.g. "1", "5". +Specify the device unit number, e.g.\& "1", "5". .It Fl v Be verbose, print out sense information for failed SCSI commands. .El @@ -236,16 +246,19 @@ The .Nm utility will report whether the device is ready or not. .It Ic inquiry -Send a SCSI inquiry command (0x12) to a device. By default, +Send a SCSI inquiry command (0x12) to a device. +By default, .Nm will print out the standard inquiry data, device serial number, and -transfer rate information. The user can specify that only certain types of +transfer rate information. +The user can specify that only certain types of inquiry data be printed: .Bl -tag -width 4n .It Fl D Get the standard inquiry data. .It Fl S -Print out the serial number. If this flag is the only one specified, +Print out the serial number. +If this flag is the only one specified, .Nm will not print out "Serial Number" before the value returned by the drive. This is to aid in script writing. @@ -268,8 +281,10 @@ start bit cleared and the load/eject bit set. Tell the kernel to scan all busses in the system (with the .Ar all argument), the given bus (XPT_SCAN_BUS), or bus:target:lun -(XPT_SCAN_LUN) for new devices or devices that have gone away. The user -may specify a scan of all busses, a single bus, or a lun. Scanning all luns +(XPT_SCAN_LUN) for new devices or devices that have gone away. +The user +may specify a scan of all busses, a single bus, or a lun. +Scanning all luns on a target isn't supported. .It Ic reset Tell the kernel to reset all busses in the system (with the @@ -292,9 +307,13 @@ to print out the list as logical blocks, .Em bfi , to print out the list in bytes from index format, and .Em phys , -to print out the list in physical sector format. The format argument is -required. Most drives support the physical sector format. Some drives -support the logical block format. Many drives, if they don't support the +to print out the list in physical sector format. +The format argument is +required. +Most drives support the physical sector format. +Some drives +support the logical block format. +Many drives, if they don't support the requested format, return the data in an alternate format, along with sense information indicating that the requested data format isn't supported. The @@ -306,7 +325,8 @@ support the requested format, .Nm will probably see the error as a failure to complete the request. .It Fl G -Print out the grown defect list. This is a list of bad blocks that have +Print out the grown defect list. +This is a list of bad blocks that have been remapped since the disk left the factory. .It Fl P Print out the primary defect list. @@ -321,7 +341,8 @@ is specified, will print out the number of defects given in the READ DEFECT DATA header returned from the drive. .It Ic modepage -Allows the user to display and optionally edit a SCSI mode page. The mode +Allows the user to display and optionally edit a SCSI mode page. +The mode page formats are located in .Pa /usr/share/misc/scsi_modes . This can be overridden by specifying a different file in the @@ -336,24 +357,28 @@ Disable block descriptors for mode sense. .It Fl b Displays mode page data in binary format. .It Fl e -This flag allows the user to edit values in the mode page. The user may +This flag allows the user to edit values in the mode page. +The user may either edit mode page values with the text editor pointed to by his .Ev EDITOR environment variable, or supply mode page values via standard input, using the same format that .Nm -uses to display mode page values. The editor will be invoked if +uses to display mode page values. +The editor will be invoked if .Nm detects that standard input is terminal. .It Fl l Lists all available mode pages. .It Fl m Ar mode_page This specifies the number of the mode page the user would like to view -and/or edit. This argument is mandatory unless +and/or edit. +This argument is mandatory unless .Fl l is specified. .It Fl P Ar pgctl -This allows the user to specify the page control field. Possible values are: +This allows the user to specify the page control field. +Possible values are: .Bl -tag -width xxx -compact .It 0 Current values @@ -371,8 +396,10 @@ The .Ic cmd function requires the .Fl c -argument to specify the CDB. Other arguments are optional, depending on -the command type. The command and data specification syntax is documented +argument to specify the CDB. +Other arguments are optional, depending on +the command type. +The command and data specification syntax is documented in .Xr cam_cdbparse 3 . NOTE: If the CDB specified causes data to be transfered to or from the @@ -382,7 +409,8 @@ or .Fl o . .Bl -tag -width 17n .It Fl c Ar cmd Op args -This specifies the SCSI CDB. CDBs may be 6, 10, 12 or 16 bytes. +This specifies the SCSI CDB. +CDBs may be 6, 10, 12 or 16 bytes. .It Fl i Ar len Ar fmt This specifies the amount of data to read, and how it should be displayed. If the format is @@ -391,15 +419,19 @@ If the format is bytes of data will be read from the device and written to standard output. .It Fl o Ar len Ar fmt Op args This specifies the amount of data to be written to a device, and the data -that is to be written. If the format is +that is to be written. +If the format is .Sq - , .Ar len bytes of data will be read from standard input and written to the device. .El .It Ic debug -Turn on CAM debugging printfs in the kernel. This requires options CAMDEBUG -in your kernel config file. WARNING: enabling debugging printfs currently -causes an EXTREME number of kernel printfs. You may have difficulty +Turn on CAM debugging printfs in the kernel. +This requires options CAMDEBUG +in your kernel config file. +WARNING: enabling debugging printfs currently +causes an EXTREME number of kernel printfs. +You may have difficulty turning off the debugging printfs once they start, since the kernel will be busy printing messages and unable to service other requests quickly. The @@ -417,46 +449,57 @@ Enable CAM_DEBUG_SUBTRACE printfs. .It Fl X Enable CAM_DEBUG_XPT printfs. .It Fl c -Enable CAM_DEBUG_CDB printfs. This will cause the kernel to print out the +Enable CAM_DEBUG_CDB printfs. +This will cause the kernel to print out the SCSI CDBs sent to the specified device(s). .It all Enable debugging for all devices. .It off Turn off debugging for all devices .It bus Ns Op :target Ns Op :lun -Turn on debugging for the given bus, target or lun. If the lun or target -and lun are not specified, they are wildcarded. (i.e., just specifying a +Turn on debugging for the given bus, target or lun. +If the lun or target +and lun are not specified, they are wildcarded. +(i.e., just specifying a bus turns on debugging printfs for all devices on that bus.) .El .It Ic tags Show or set the number of "tagged openings" or simultaneous transactions -we attempt to queue to a particular device. By default, the +we attempt to queue to a particular device. +By default, the .Ic tags -command, with no command-specific arguments (i.e. only generic arguments) +command, with no command-specific arguments (i.e., only generic arguments) prints out the "soft" maximum number of transactions that can be queued to -the device in question. For more detailed information, use the +the device in question. +For more detailed information, use the .Fl v argument described below. .Bl -tag -width 7n .It Fl N Ar tags -Set the number of tags for the given device. This must be between the -minimum and maximum number set in the kernel quirk table. The default for +Set the number of tags for the given device. +This must be between the +minimum and maximum number set in the kernel quirk table. +The default for most devices that support tagged queueing is a minimum of 2 and a maximum -of 255. The minimum and maximum values for a given device may be +of 255. +The minimum and maximum values for a given device may be determined by using the .Fl v -switch. The meaning of the +switch. +The meaning of the .Fl v switch for this .Nm subcommand is described below. .It Fl q -Be quiet, and don't report the number of tags. This is generally used when +Be quiet, and don't report the number of tags. +This is generally used when setting the number of tags. .It Fl v The verbose flag has special functionality for the .Em tags -argument. It causes +argument. +It causes .Nm to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB: .Bl -tag -width 13n @@ -465,55 +508,68 @@ This is the amount of capacity for transactions queued to a given device. .It dev_active This is the number of transactions currently queued to a device. .It devq_openings -This is the kernel queue space for transactions. This count usually mirrors +This is the kernel queue space for transactions. +This count usually mirrors dev_openings except during error recovery operations when the device queue is frozen (device is not allowed to receive commands), the number of dev_openings is reduced, or transaction replay is occurring. .It devq_queued This is the number of transactions waiting in the kernel queue for capacity -on the device. This number is usually zero unless error recovery is in +on the device. +This number is usually zero unless error recovery is in progress. .It held The held count is the number of CCBs held by peripheral drivers that have either just been completed or are about to be released to the transport -layer for service by a device. Held CCBs reserve capacity on a given +layer for service by a device. +Held CCBs reserve capacity on a given device. .It mintags This is the current "hard" minimum number of transactions that can be -queued to a device at once. The +queued to a device at once. +The .Ar dev_openings -value above cannot go below this number. The default value for +value above cannot go below this number. +The default value for .Ar mintags is 2, although it may be set higher or lower for various devices. .It maxtags This is the "hard" maximum number of transactions that can be queued to a -device at one time. The +device at one time. +The .Ar dev_openings -value cannot go above this number. The default value for +value cannot go above this number. +The default value for .Ar maxtags is 255, although it may be set higher or lower for various devices. .El .El .It Ic negotiate -Show or negotiate various communication parameters. Some controllers may -not support setting or changing some of these values. For instance, the +Show or negotiate various communication parameters. +Some controllers may +not support setting or changing some of these values. +For instance, the Adaptec 174x controllers do not support changing a device's sync rate or offset. The .Nm utility will not attempt to set the parameter if the controller indicates that it -does not support setting the parameter. To find out what the controller +does not support setting the parameter. +To find out what the controller supports, use the .Fl v -flag. The meaning of the +flag. +The meaning of the .Fl v flag for the .Ic negotiate -command is described below. Also, some controller drivers don't support +command is described below. +Also, some controller drivers don't support setting negotiation parameters, even if the underlying controller supports -negotiation changes. Some controllers, such as the Advansys wide +negotiation changes. +Some controllers, such as the Advansys wide controllers, support enabling and disabling synchronous negotiation for a device, but do not support setting the synchronous negotiation rate. .Bl -tag -width 17n @@ -521,41 +577,51 @@ a device, but do not support setting the synchronous negotiation rate. Attempt to make the negotiation settings take effect immediately by sending a Test Unit Ready command to the device. .It Fl c -Show or set current negotiation settings. This is the default. +Show or set current negotiation settings. +This is the default. .It Fl D Ar enable|disable Enable or disable disconnection. .It Fl O Ar offset Set the command delay offset. .It Fl q -Be quiet, don't print anything. This is generally useful when you want to +Be quiet, don't print anything. +This is generally useful when you want to set a parameter, but don't want any status information. .It Fl R Ar syncrate -Change the synchronization rate for a device. The sync rate is a floating -point value specified in MHz. So, for instance, +Change the synchronization rate for a device. +The sync rate is a floating +point value specified in MHz. +So, for instance, .Sq 20.000 is a legal value, as is .Sq 20 . .It Fl T Ar enable|disable Enable or disable tagged queueing for a device. .It Fl U -Show or set user negotiation settings. The default is to show or set +Show or set user negotiation settings. +The default is to show or set current negotiation settings. .It Fl v The verbose switch has special meaning for the .Ic negotiate -subcommand. It causes +subcommand. +It causes .Nm to print out the contents of a Path Inquiry (XPT_PATH_INQ) CCB sent to the controller driver. .It Fl W Ar bus_width -Specify the bus width to negotiate with a device. The bus width is -specified in bits. The only useful values to specify are 8, 16, and 32 -bits. The controller must support the bus width in question in order for +Specify the bus width to negotiate with a device. +The bus width is +specified in bits. +The only useful values to specify are 8, 16, and 32 +bits. +The controller must support the bus width in question in order for the setting to take effect. .El .Pp In general, sync rate and offset settings will not take effect for a -device until a command has been sent to the device. The +device until a command has been sent to the device. +The .Fl a switch above will automatically send a Test Unit Ready to the device so negotiation parameters will take effect. @@ -566,27 +632,36 @@ FORMAT UNIT command to the named device. .Pp .Em WARNING! WARNING! WARNING! .Pp -Low level formatting a disk will destroy ALL data on the disk. Use -extreme caution when issuing this command. Many users low-level format -disks that do not really need to be low-level formatted. There are +Low level formatting a disk will destroy ALL data on the disk. +Use +extreme caution when issuing this command. +Many users low-level format +disks that do not really need to be low-level formatted. +There are relatively few scenarios that call for low-level formatting a disk. One reason for low-level formatting a disk is to initialize the disk after changing -its physical sector size. Another reason for low-level formatting a disk +its physical sector size. +Another reason for low-level formatting a disk is to revive the disk if you are getting "medium format corrupted" errors from the disk in response to read and write requests. .Pp -Some disks take longer than others to format. Users should specify a -timeout long enough to allow the format to complete. The default format -timeout is 3 hours, which should be long enough for most disks. Some hard +Some disks take longer than others to format. +Users should specify a +timeout long enough to allow the format to complete. +The default format +timeout is 3 hours, which should be long enough for most disks. +Some hard disks will complete a format operation in a very short period of time -(on the order of 5 minutes or less). This is often because the drive +(on the order of 5 minutes or less). +This is often because the drive doesn't really support the FORMAT UNIT command -- it just accepts the command, waits a few minutes and then returns it. .Pp The .Sq format -subcommand takes several arguments that modify its default behavior. The +subcommand takes several arguments that modify its default behavior. +The .Fl q and .Fl y @@ -594,21 +669,27 @@ arguments can be useful for scripts. .Pp .Bl -tag -width 6n .It Fl q -Be quiet, don't print any status messages. This option will not disable -the questions, however. To disable questions, use the +Be quiet, don't print any status messages. +This option will not disable +the questions, however. +To disable questions, use the .Fl y argument, below. .It Fl w -Issue a non-immediate format command. By default, +Issue a non-immediate format command. +By default, .Nm -issues the FORMAT UNIT command with the immediate bit set. This tells the +issues the FORMAT UNIT command with the immediate bit set. +This tells the device to immediately return the format command, before the format has -actually completed. Then, +actually completed. +Then, .Nm gathers .Tn SCSI sense information from the device every second to determine how far along -in the format process it is. If the +in the format process it is. +If the .Fl w argument is specified, .Nm @@ -616,10 +697,12 @@ will issue a non-immediate format command, and will be unable to print any information to let the user know what percentage of the disk has been formatted. .It Fl y -Don't ask any questions. By default, +Don't ask any questions. +By default, .Nm will ask the user if he/she really wants to format the disk in question, -and also if the default format command timeout is acceptable. The user +and also if the default format command timeout is acceptable. +The user will not be asked about the timeout if a timeout is specified on the command line. .El @@ -665,11 +748,14 @@ switch was not specified. camcontrol tur da1 -E -C 4 -t 50 -v .Ed .Pp -Send a test unit ready command to da1. Enable kernel error recovery. -Specify a retry count of 4, and a timeout of 50 seconds. Enable sense +Send a test unit ready command to da1. +Enable kernel error recovery. +Specify a retry count of 4, and a timeout of 50 seconds. +Enable sense printing (with the .Fl v -flag) if the command fails. Since error recovery is turned on, the +flag) if the command fails. +Since error recovery is turned on, the disk will be spun up if it is not currently spinning. The .Nm @@ -679,8 +765,10 @@ camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e -i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1" .Ed .Pp -Issue a READ BUFFER command (0x3C) to cd1. Display the buffer size of cd1, -and display the first 10 bytes from the cache on cd1. Display SCSI sense +Issue a READ BUFFER command (0x3C) to cd1. +Display the buffer size of cd1, +and display the first 10 bytes from the cache on cd1. +Display SCSI sense information if the command fails. .Pp .Bd -literal -offset indent @@ -688,9 +776,12 @@ camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e -o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8 .Ed .Pp -Issue a WRITE BUFFER (0x3B) command to cd1. Write out 10 bytes of data, -not including the (reserved) 4 byte header. Print out sense information if -the command fails. Be very careful with this command, improper use may +Issue a WRITE BUFFER (0x3B) command to cd1. +Write out 10 bytes of data, +not including the (reserved) 4 byte header. +Print out sense information if +the command fails. +Be very careful with this command, improper use may cause data corruption. .Pp .Bd -literal -offset indent @@ -698,7 +789,8 @@ camcontrol modepage da3 -m 1 -e -P 3 .Ed .Pp Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the -settings on the drive. Mode page 1 contains a disk drive's auto read and +settings on the drive. +Mode page 1 contains a disk drive's auto read and write reallocation settings, among other things. .Pp .Dl camcontrol rescan all @@ -729,7 +821,8 @@ Disable tagged queueing for da4. camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a .Ed .Pp -Negotiate a sync rate of 20MHz and an offset of 15 with da3. Then send a +Negotiate a sync rate of 20MHz and an offset of 15 with da3. +Then send a Test Unit Ready command to make the settings take effect. .Sh SEE ALSO .Xr cam 3 , @@ -748,7 +841,8 @@ code in the old .Xr scsi 8 utility and .Xr scsi 3 -library, written by Julian Elischer and Peter Dufault. The +library, written by Julian Elischer and Peter Dufault. +The .Xr scsi 8 program first appeared in .Bx 386 0.1.2.4 , @@ -760,7 +854,8 @@ in .An Kenneth Merry Aq ken@FreeBSD.org .Sh BUGS The code that parses the generic command line arguments doesn't know that -some of the subcommands take multiple arguments. So if, for instance, you +some of the subcommands take multiple arguments. +So if, for instance, you tried something like this: .Bd -literal -offset indent camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v @@ -774,9 +869,11 @@ call in bails out when it sees the second argument to .Fl c (0x00), -above. Fixing this behavior would take some gross code, or changes to the +above. +Fixing this behavior would take some gross code, or changes to the .Xr getopt 3 -interface. The best way to circumvent this problem is to always make sure +interface. +The best way to circumvent this problem is to always make sure to specify generic .Nm arguments before any command-specific arguments. diff --git a/sbin/ccdconfig/ccdconfig.8 b/sbin/ccdconfig/ccdconfig.8 index fdba97b..ca79dc8 100644 --- a/sbin/ccdconfig/ccdconfig.8 +++ b/sbin/ccdconfig/ccdconfig.8 @@ -62,13 +62,15 @@ The .Nm utility is used to dynamically configure and unconfigure concatenated disk -devices, or ccds. For more information about the ccd, see +devices, or ccds. +For more information about the ccd, see .Xr ccd 4 . .Pp The options are as follows: .Bl -tag -width indent .It Fl c -Configure a ccd. This is the default behavior of +Configure a ccd. +This is the default behavior of .Nm . .It Fl C Configure all ccd devices listed in the ccd configuration file. @@ -79,8 +81,10 @@ instead of the default .Pa /etc/ccd.conf . .It Fl g Dump the current ccd configuration in a format suitable for use as the -ccd configuration file. If no arguments are specified, every configured -ccd is dumped. Otherwise, the configuration of each listed ccd is dumped. +ccd configuration file. +If no arguments are specified, every configured +ccd is dumped. +Otherwise, the configuration of each listed ccd is dumped. .It Fl u Unconfigure a ccd. .It Fl U @@ -93,7 +97,8 @@ to be verbose. .Pp A ccd is described on the command line and in the ccd configuration file by the name of the ccd, the interleave factor, the ccd configuration -flags, and a list of one or more devices. The flags may be represented +flags, and a list of one or more devices. +The flags may be represented as a decimal number, a hexadecimal number, a comma-separated list of strings, or the word .Dq none . @@ -127,17 +132,22 @@ as shown by .Sh EXAMPLES A number of .Nm -examples are shown below. The arguments passed +examples are shown below. +The arguments passed to .Nm are exactly the same as you might place in the .Pa /etc/ccd.conf -configuration file. The first example creates a 4-disk stripe out of -four scsi disk partitions. The stripe uses a 64 sector interleave. +configuration file. +The first example creates a 4-disk stripe out of +four scsi disk partitions. +The stripe uses a 64 sector interleave. The second example is an example of a complex stripe/mirror combination. It reads as a two disk stripe of da4 and da5 which is mirrored -to a two disk stripe of da6 and da7. The last example is a simple -mirror. The 2nd slice of /dev/da8 is mirrored with the 3rd slice of /dev/da9 +to a two disk stripe of da6 and da7. +The last example is a simple +mirror. +The 2nd slice of /dev/da8 is mirrored with the 3rd slice of /dev/da9 and assigned to ccd0. .Pp .Bd -unfilled -offset @@ -150,14 +160,19 @@ When you create a new ccd disk you generally want to .Xr fdisk 8 and .Xr disklabel 8 -it before doing anything else. Once you create the initial label you can -edit it, adding additional partitions. The label itself takes up the first -16 sectors of the ccd disk. If all you are doing is creating file systems +it before doing anything else. +Once you create the initial label you can +edit it, adding additional partitions. +The label itself takes up the first +16 sectors of the ccd disk. +If all you are doing is creating file systems with newfs, you do not have to worry about this as newfs will skip the -label area. However, if you intend to +label area. +However, if you intend to .Xr dd 1 to or from a ccd partition it is usually a good idea to construct the -partition such that it does not overlap the label area. For example, if +partition such that it does not overlap the label area. +For example, if you have A ccd disk with 10000 sectors you might create a 'd' partition with offset 16 and size 9984. .Pp @@ -173,16 +188,21 @@ the disklabel you had created before will still be there and not require reinitialization. Beware that changing any ccd parameters: interleave, flags, or the device list making up the ccd disk, will usually destroy any prior -data on that ccd disk. If this occurs it is usually a good idea to +data on that ccd disk. +If this occurs it is usually a good idea to reinitialize the label before [re]constructing your ccd disk. .Sh RECOVERY An error on a ccd disk is usually unrecoverable unless you are using the -mirroring option. But mirroring has its own perils: It assumes that -both copies of the data at any given sector are the same. This holds true +mirroring option. +But mirroring has its own perils: It assumes that +both copies of the data at any given sector are the same. +This holds true until a write error occurs or until you replace either side of the mirror. -This is a poor-man's mirroring implementation. It works well enough that if +This is a poor-man's mirroring implementation. +It works well enough that if you begin to get disk errors you should be able to backup the ccd disk, -replace the broken hardware, and then regenerate the ccd disk. If you need +replace the broken hardware, and then regenerate the ccd disk. +If you need more than this you should look into external hardware RAID SCSI boxes, RAID controllers (see GENERIC), or software RAID systems such as diff --git a/sbin/comcontrol/comcontrol.8 b/sbin/comcontrol/comcontrol.8 index 361ed68..bf719f9 100644 --- a/sbin/comcontrol/comcontrol.8 +++ b/sbin/comcontrol/comcontrol.8 @@ -60,5 +60,6 @@ dialout devices .Sh HISTORY Originally part of cgd's com package patches, version 0.2.1, to .Bx 386 0.1 . -Once controlled bidirectional capabilities. Little is left to control now +Once controlled bidirectional capabilities. +Little is left to control now that these capabilities are standard. diff --git a/sbin/dumpfs/dumpfs.8 b/sbin/dumpfs/dumpfs.8 index 3c3204e..8e701d5 100644 --- a/sbin/dumpfs/dumpfs.8 +++ b/sbin/dumpfs/dumpfs.8 @@ -45,7 +45,8 @@ utility prints out the super block and cylinder group information for the file system or special device specified, unless .Fl m is specified. -The listing is very long and detailed. This +The listing is very long and detailed. +This command is useful mostly for finding out certain file system information such as the file system block size and minimum free space percentage. diff --git a/sbin/fdisk/fdisk.8 b/sbin/fdisk/fdisk.8 index 7eda677..a7730ea 100644 --- a/sbin/fdisk/fdisk.8 +++ b/sbin/fdisk/fdisk.8 @@ -267,7 +267,7 @@ it will set up the last BIOS slice to use the whole disk for .Fx and make it active. .Sh NOTES -The automatic calculation of starting cylinder etc. uses +The automatic calculation of starting cylinder etc.\& uses a set of figures that represent what the BIOS thinks the geometry of the drive is. These figures are taken from the in-core disklabel by default, diff --git a/sbin/fdisk_pc98/fdisk.8 b/sbin/fdisk_pc98/fdisk.8 index ba15116..c4b25c7 100644 --- a/sbin/fdisk_pc98/fdisk.8 +++ b/sbin/fdisk_pc98/fdisk.8 @@ -24,7 +24,8 @@ Sector 0 of the disk must contain boot code, a partition table, and a magic number. BIOS partitions can be used to break the disk up into several pieces. -The BIOS brings in sector 0 and verifies the magic number. The sector +The BIOS brings in sector 0 and verifies the magic number. +The sector 0 boot code then searches the partition table to determine which partition is marked .Em active . @@ -42,23 +43,27 @@ utility can be used to divide space on the disk into partitions and set one The .Fx .Nm -utility serves a similar purpose to the DOS program. The first form is used to +utility serves a similar purpose to the DOS program. +The first form is used to display partition information or to interactively edit the partition -table. The second is used to write a partition table using a +table. +The second is used to write a partition table using a .Ar configfile and is designed to be used by other scripts/programs. .Pp Options are: .Bl -tag -width time .It Fl a -Change the active partition only. Ignored if +Change the active partition only. +Ignored if .Fl f is given. .It Fl b Ar bootcode Get the boot code from the file .Ar bootcode . .It Fl B -Reinitialize the boot code contained in sector 0 of the disk. Ignored +Reinitialize the boot code contained in sector 0 of the disk. +Ignored if .Fl f is given. @@ -72,11 +77,13 @@ always modifies existing partitions, unless is also given, in which case all existing partitions are deleted (marked as "unused") before the .Ar configfile -is read. The +is read. +The .Ar configfile can be "-", in which case .Ar stdin -is read. See +is read. +See .Sx CONFIGURATION FILE , below, for file syntax. .Pp @@ -84,7 +91,8 @@ below, for file syntax. when .Fl f is used, you are not asked if you really want to write the partition -table (as you are in the interactive mode). Use with caution! +table (as you are in the interactive mode). +Use with caution! .\" !PC98 .\" .It Fl i .\" Initialize sector 0 of the disk. This implies @@ -100,22 +108,27 @@ table (as you are in the interactive mode). Use with caution! .It Fl s Print summary information and exit. .It Fl t -Test mode; do not write partition values. Generally used with the +Test mode; do not write partition values. +Generally used with the .Fl f -option to see what would be written to the partition table. Implies +option to see what would be written to the partition table. +Implies .Fl v . .It Fl u -Is used for updating (editing) sector 0 of the disk. Ignored if +Is used for updating (editing) sector 0 of the disk. +Ignored if .Fl f is given. .It Fl v -Be verbose. When +Be verbose. +When .Fl f is used, .Nm prints out the partition table that is written to the disk. .It Fl 12345678 -Operate on a single fdisk entry only. Ignored if +Operate on a single fdisk entry only. +Ignored if .Fl f is given. .El @@ -219,7 +232,8 @@ The flags .Fl u are used to indicate that the partition data is to be updated, unless the .Fl f -option is used. If the +option is used. +If the .Fl f option is not used, the .Nm @@ -275,7 +289,7 @@ it will setup the last BIOS partition to use the whole disk for .Fx ; and make it active. .Sh NOTES -The automatic calculation of starting cylinder etc. uses +The automatic calculation of starting cylinder etc.\& uses a set of figures that represent what the BIOS thinks is the geometry of the drive. These figures are by default taken from the incore disklabel, @@ -294,8 +308,10 @@ Editing an existing partition will most likely cause you to lose all the data in that partition. .Pp You should run this program interactively once or twice to see how it -works. This is completely safe as long as you answer the last question -in the negative. There are subtleties that the program detects that are +works. +This is completely safe as long as you answer the last question +in the negative. +There are subtleties that the program detects that are not fully explained in this manual page. .Sh CONFIGURATION FILE When the @@ -303,7 +319,8 @@ When the option is given, a disk's partition table can be written using values from a .Ar configfile . -The syntax of this file is very simple. Each line is either a comment or +The syntax of this file is very simple. +Each line is either a comment or a specification, and whitespace (except for newlines) are ignored: .Bl -tag -width Ds .It Xo @@ -317,7 +334,8 @@ Lines beginning with a "#" are comments and are ignored. .Ar spec2 .Ar spec3 .Xc -Set the BIOS geometry used in partition calculations. There must be +Set the BIOS geometry used in partition calculations. +There must be three values specified, with a letter preceding each number: .Bl -tag -width Ds .Sm off @@ -351,7 +369,8 @@ It is an error if the following is not true: .Ed .Pp The number of cylinders should be less than or equal to 1024, but this -is not enforced, although a warning will be output. Note that bootable +is not enforced, although a warning will be output. +Note that bootable .Fx partitions (the "/" file system) must lie completely within the first 1024 cylinders; if this is not true, booting may fail. @@ -387,7 +406,8 @@ However, if an invalid partition table is present, or the .Fl i option is specified, all existing partition entries will be cleared (marked as unused), and these "p" lines will have to be used to -explicitly set partition information. If multiple partitions need to be +explicitly set partition information. +If multiple partitions need to be set, multiple "p" lines must be specified; one for each partition. .Pp These partition lines must occur after any geometry specification lines, @@ -397,7 +417,8 @@ The .Ar type is 165 for .Fx -partitions. Specifying a partition type of zero is +partitions. +Specifying a partition type of zero is the same as clearing the partition and marking it as unused; however, dummy values (such as "0") must still be specified for .Ar start @@ -427,7 +448,8 @@ p 1 165 1 2503871 .Xc Make .Ar partition -the active partition. Can occur anywhere in the config file, but only +the active partition. +Can occur anywhere in the config file, but only one must be present. .Pp Example: to make partition 1 the active partition: diff --git a/sbin/fsck/fsck.8 b/sbin/fsck/fsck.8 index 6caa47d..734c83c 100644 --- a/sbin/fsck/fsck.8 +++ b/sbin/fsck/fsck.8 @@ -112,7 +112,9 @@ to be the partition and slice designators. The options are as follows: .Bl -tag -width indent .It Fl d -Debugging mode. Just print the commands without executing them. Available +Debugging mode. +Just print the commands without executing them. +Available only if .Nm is compiled to support it. @@ -164,7 +166,8 @@ only one file system at a time will be checked. .It Fl t Ar fstype Invoke .Nm -only for the comma separated list of file system types. If the +only for the comma separated list of file system types. +If the list starts with .Dq no then invoke diff --git a/sbin/fsck_ffs/fsck_ffs.8 b/sbin/fsck_ffs/fsck_ffs.8 index 64b7430..4bfa11c 100644 --- a/sbin/fsck_ffs/fsck_ffs.8 +++ b/sbin/fsck_ffs/fsck_ffs.8 @@ -83,7 +83,8 @@ option will correct; if it encounters other inconsistencies, it exits with an abnormal return status and an automatic reboot will then fail. For each corrected inconsistency one or more lines will be printed identifying the file system on which the correction will take place, -and the nature of the correction. After successfully correcting a file system, +and the nature of the correction. +After successfully correcting a file system, .Nm will print the number of files on that file system, the number of used and free blocks, @@ -171,7 +172,8 @@ the file system is marked as needing a foreground check and exits without attempting any further cleaning. .It Fl b Use the block specified immediately after the flag as -the super block for the file system. Block 32 is usually +the super block for the file system. +Block 32 is usually an alternate super block. .It Fl c Convert the file system to the specified level. diff --git a/sbin/fsdb/fsdb.8 b/sbin/fsdb/fsdb.8 index 21b4b70..194ba83 100644 --- a/sbin/fsdb/fsdb.8 +++ b/sbin/fsdb/fsdb.8 @@ -46,12 +46,14 @@ The utility opens .Ar fsname (usually a raw disk partition) and runs a command loop -allowing manipulation of the file system's inode data. You are prompted +allowing manipulation of the file system's inode data. +You are prompted to enter a command with .Ic "fsdb (inum X)>" where .Va X -is the currently selected i-number. The initial selected inode is the +is the currently selected i-number. +The initial selected inode is the root of the file system (i-number 2). The command processor uses the .Xr editline 3 @@ -101,7 +103,8 @@ Find in the current directory and make its inode the current inode. .Ar Name may be a multi-component name or may begin with slash to indicate that -the root inode should be used to start the lookup. If some component +the root inode should be used to start the lookup. +If some component along the pathname is not found, the last valid directory encountered is left as the active inode. This command is valid only if the starting inode is a directory. @@ -125,14 +128,16 @@ Set the active inode's link count to .Ar number . .Pp .It Cm ls -List the current inode's directory entries. This command is valid only +List the current inode's directory entries. +This command is valid only if the current inode is a directory. .Pp .It Cm rm Ar name .It Cm del Ar name Remove the entry .Ar name -from the current directory inode. This command is valid only +from the current directory inode. +This command is valid only if the current inode is a directory. .Pp .It Cm ln Ar ino Ar name @@ -140,7 +145,8 @@ Create a link to inode .Ar ino under the name .Ar name -in the current directory inode. This command is valid only +in the current directory inode. +This command is valid only if the current inode is a directory. .Pp .It Cm chinum Ar dirslot Ar inum @@ -154,7 +160,8 @@ Change the name in directory entry .Ar dirslot to .Ar name . -This command cannot expand a directory entry. You can only rename an +This command cannot expand a directory entry. +You can only rename an entry if the name will fit into the existing directory slot. .Pp .It Cm chtype Ar type @@ -202,7 +209,8 @@ should be in the format .Em YYYYMMDDHHMMSS[.nsec] where .Em nsec -is an optional nanosecond specification. If no nanoseconds are specified, the +is an optional nanosecond specification. +If no nanoseconds are specified, the .Va mtimensec , .Va ctimensec , or @@ -231,7 +239,8 @@ The .Nm utility uses the source code for .Xr fsck 8 -to implement most of the file system manipulation code. The remainder of +to implement most of the file system manipulation code. +The remainder of .Nm first appeared in .Nx , diff --git a/sbin/fsirand/fsirand.8 b/sbin/fsirand/fsirand.8 index 1d7e56e..00f0eee 100644 --- a/sbin/fsirand/fsirand.8 +++ b/sbin/fsirand/fsirand.8 @@ -58,7 +58,8 @@ now does the equivalent of itself so it is no longer necessary to run .Nm -by hand on a new file system. It is only used to +by hand on a new file system. +It is only used to re-randomize or report on an existing file system. .Pp The diff --git a/sbin/ifconfig/ifconfig.8 b/sbin/ifconfig/ifconfig.8 index 24a954e..a9c6a21 100644 --- a/sbin/ifconfig/ifconfig.8 +++ b/sbin/ifconfig/ifconfig.8 @@ -135,7 +135,7 @@ The link-level address is specified as a series of colon-separated hex digits. This can be used to -e.g. set a new MAC address on an ethernet interface, though the +e.g.\& set a new MAC address on an ethernet interface, though the mechanism used is not ethernet-specific. If the interface is already up when this option is used, it will be briefly brought down and diff --git a/sbin/init/init.8 b/sbin/init/init.8 index 240bfed..3a64191 100644 --- a/sbin/init/init.8 +++ b/sbin/init/init.8 @@ -121,7 +121,8 @@ but also inhibits running while the system is multi-user. .Pp In addition, kernel time changes are restricted to less than or equal to one -second. Attempts to change the time by more than this will log the message +second. +Attempts to change the time by more than this will log the message .Dq Time adjustment clamped to +1 second . .It Ic 3 Network secure mode \- same as highly secure mode, plus @@ -189,7 +190,8 @@ program. The .Nm login program, when a valid user logs in, -executes a shell for that user. When this shell +executes a shell for that user. +When this shell dies, either because the user logged out or an abnormal termination occurred (a signal), the @@ -330,7 +332,7 @@ If run as a user process as shown in the second synopsis line, .Nm will emulate .At V -behavior, i.e. super-user can specify the desired +behavior, i.e., super-user can specify the desired .Em run-level on a command line, and .Nm @@ -413,7 +415,8 @@ behave as though they have security level \-1. Setting the security level above 1 too early in the boot sequence can prevent .Xr fsck 8 -from repairing inconsistent file systems. The +from repairing inconsistent file systems. +The preferred location to set the security level is at the end of .Pa /etc/rc after all multi-user startup actions are complete. diff --git a/sbin/ip6fw/ip6fw.8 b/sbin/ip6fw/ip6fw.8 index c036c23..c6dd84e 100644 --- a/sbin/ip6fw/ip6fw.8 +++ b/sbin/ip6fw/ip6fw.8 @@ -112,7 +112,7 @@ name search is performed. Care should be taken with this in environments where not all file systems are mounted (yet) by the time .Nm -is being run (e.g. when they are mounted over NFS). +is being run (e.g.\& when they are mounted over NFS). Once .Fl p has been specified, optional @@ -175,7 +175,8 @@ needs. The following options are available: .Bl -tag -width flag .It Fl a -While listing, show counter values. See also +While listing, show counter values. +See also .Dq show command. .It Fl f @@ -189,11 +190,14 @@ without actually passing them into the kernel. .It Fl q While adding, zeroing or flushing, be quiet about actions (implies '-f'). This is useful for adjusting rules by executing multiple ip6fw commands in a -script (e.g. sh /etc/rc.firewall), or by processing a file of many ip6fw rules, -across a remote login session. If a flush is performed in normal -(verbose) mode, it prints a message. Because all rules are flushed, the +script (e.g.\& sh /etc/rc.firewall), or by processing a file of many ip6fw rules, +across a remote login session. +If a flush is performed in normal +(verbose) mode, it prints a message. +Because all rules are flushed, the message cannot be delivered to the login session, the login session is -closed and the remainder of the ruleset is not processed. Access to the +closed and the remainder of the ruleset is not processed. +Access to the console is required to recover. .It Fl t While listing, show last match timestamp. @@ -257,7 +261,8 @@ then when a packet matches a rule with the .Dq log keyword or a clear/resetlog is performed, a message will be logged to .Xr syslogd 8 , -or, if that fails, to the console. If the kernel was compiled with the +or, if that fails, to the console. +If the kernel was compiled with the .Dv IPV6FIREWALL_VERBOSE_LIMIT option, then logging will cease after the number of packets specified by the option are received for that particular @@ -335,9 +340,10 @@ and the length of the port list is limited to .In netinet6/ip6_fw.h ) ports. .Pp -Fragmented packets which have a non-zero offset (i.e. not the first +Fragmented packets which have a non-zero offset (i.e., not the first fragment) will never match a rule which has one or more port -specifications. See the +specifications. +See the .Ar frag option for details on matching fragmented packets. .Pp @@ -405,7 +411,7 @@ or is invalid. .Pp A packet may not have a receive or transmit interface: packets originating -from the local host have no receive interface. while packets destined for +from the local host have no receive interface, while packets destined for the local host have no transmit interface. .Pp Additional @@ -469,7 +475,8 @@ with a A rule which contains a .Ar tcpflags specification can never match a fragmented packet which has -a non-zero offset. See the +a non-zero offset. +See the .Ar frag option for details on matching fragmented packets. .It icmptypes Ar types diff --git a/sbin/ipfw/ipfw.8 b/sbin/ipfw/ipfw.8 index 1845c68..9197b6b 100644 --- a/sbin/ipfw/ipfw.8 +++ b/sbin/ipfw/ipfw.8 @@ -151,7 +151,7 @@ option, then .Nm assumes a .Em stateful -behaviour, i.e. upon a match it will create dynamic rules matching +behaviour, i.e., upon a match it will create dynamic rules matching the exact parameters (addresses and ports) of the matching packet. .Pp These dynamic rules, which have a limited lifetime, are checked @@ -200,7 +200,8 @@ Also, each rule belongs to one of 32 different .Nm commands to atomically manipulate sets, such as enable, disable, swap sets, move all rules in a set to another -one, delete all rules in a set. These can be useful to +one, delete all rules in a set. +These can be useful to install temporary configurations, or to test them. See Section .Sx SETS OF RULES @@ -220,7 +221,7 @@ Implies .Fl c . .It Fl c When entering or showing rules, print them in compact form, -i.e. without the optional "ip from any to any" string +i.e., without the optional "ip from any to any" string when this does not carry any additional information. .It Fl d While listing, show dynamic rules in addition to static ones. @@ -310,7 +311,7 @@ name search is performed. Care should be taken with this in environments where not all file systems are mounted (yet) by the time .Nm -is being run (e.g. when they are mounted over NFS). +is being run (e.g.\& when they are mounted over NFS). Once .Fl p has been specified, any additional arguments as passed on to the preprocessor @@ -330,8 +331,10 @@ Section below. .Pp If the world and the kernel get out of sync the .Nm -ABI may break, preventing you from being able to add any rules. This can -adversely effect the booting process. You can use +ABI may break, preventing you from being able to add any rules. +This can +adversely effect the booting process. +You can use .Nm .Cm disable .Cm firewall @@ -377,7 +380,7 @@ is invoked from Also note that each packet is always checked against the complete ruleset, irrespective of the place where the check occurs, or the source of the packet. If a rule contains some match patterns or actions which are not valid -for the place of invocation (e.g. trying to match a MAC header within +for the place of invocation (e.g.\& trying to match a MAC header within .Cm ip_input() ), the match pattern will not match, but a .Cm not @@ -407,16 +410,18 @@ ether_demux and bdg_forward). .Sh SYNTAX In general, each keyword or argument must be provided as a separate command line argument, with no leading or trailing -spaces. Keywords are case-sensitive, whereas arguments may +spaces. +Keywords are case-sensitive, whereas arguments may or may not be case-sensitive depending on their nature -(e.g. uid's are, hostnames are not). +(e.g.\& uid's are, hostnames are not). .Pp In .Nm ipfw2 you can introduce spaces after commas ',' to make -the line more readable. You can also put the entire +the line more readable. +You can also put the entire command (including flags) into a single argument. -E.g. the following forms are equivalent: +E.g., the following forms are equivalent: .Bd -literal -offset indent ipfw -q add deny src-ip 10.0.0.0/24,127.0.0.1/8 ipfw -q add deny src-ip 10.0.0.0/24, 127.0.0.1/8 @@ -466,7 +471,7 @@ for ICMP packets When the packet can be associated with a local socket. .El .Pp -Note that some of the above information, e.g. source MAC or IP addresses and +Note that some of the above information, e.g.\& source MAC or IP addresses and TCP/UDP ports, could easily be spoofed, so filtering on those fields alone might not guarantee the desired results. .Bl -tag -width indent @@ -489,7 +494,7 @@ Automatic rule numbers are assigned by incrementing the last non-default rule number by the value of the sysctl variable .Ar net.inet.ip.fw.autoinc_step which defaults to 100. -If this is not possible (e.g. because we would go beyond the +If this is not possible (e.g.\& because we would go beyond the maximum allowed rule number), the number of the last non-default value is used instead. .It Cm set Ar set_number @@ -693,7 +698,7 @@ protocol options, incoming or outgoing interfaces, etc.) that the packet must match in order to be recognised. In general, the patterns are connected by (implicit) .Cm and -operators -- i.e. all must match in order for the +operators -- i.e., all must match in order for the rule to match. Individual patterns can be prefixed by the .Cm not @@ -813,7 +818,8 @@ specified as a dotted quad. As an example, 1.2.3.4:255.0.255.0 will match 1.*.3.*. This form is advised only for non-contiguous -masks. It is better to resort to the +masks. +It is better to resort to the .Ar addr Ns / Ns Ar masklen format for contiguous masks, which is more compact and less error-prone. @@ -831,11 +837,13 @@ or ranges. The .Ar masklen field is used to limit the size of the set of addresses, -and can have any value between 24 and 32. If not specified, +and can have any value between 24 and 32. +If not specified, it will be assumed as 24. .br This format is particularly useful to handle sparse address sets -within a single rule. Because the matching occurs using a +within a single rule. +Because the matching occurs using a bitmask, it takes constant time and dramatically reduces the complexity of rulesets. .br @@ -874,7 +882,7 @@ character). .Pp .Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any" .Pp -Fragmented packets which have a non-zero offset (i.e. not the first +Fragmented packets which have a non-zero offset (i.e., not the first fragment) will never match a rule which has one or more port specifications. See the @@ -883,7 +891,8 @@ option for details on matching fragmented packets. .El .Ss RULE OPTIONS (MATCH PATTERNS) Additional match patterns can be used within -rules. Zero or more of these so-called +rules. +Zero or more of these so-called .Em options can be present in a rule, optionally prefixed by the .Cm not @@ -910,8 +919,9 @@ specified as argument. Matches TCP packets that have the RST or ACK bits set. .It Cm frag Matches packets that are fragments and not the first -fragment of an IP datagram. Note that these packets will not have -the next protocol header (e.g. TCP, UDP) so options that look into +fragment of an IP datagram. +Note that these packets will not have +the next protocol header (e.g.\& TCP, UDP) so options that look into these headers cannot match. .It Cm gid Ar group Matches all TCP or UDP packets sent by or received for a @@ -978,7 +988,7 @@ specified in the same way as Matches IP packets whose total length, including header and data, is in the set .Ar len-list , -which is either a single value or a list of values or ranges +which is either a single value or a list of values or ranges specified in the same way as .Ar ports . .It Cm ipoptions Ar spec @@ -1003,7 +1013,7 @@ Matches IP packets whose precedence field is equal to .Ar precedence . .It Cm ipsec Matches packets that have IPSEC history associated with them -(i.e. the packet comes encapsulated in IPSEC, the kernel +(i.e., the packet comes encapsulated in IPSEC, the kernel has IPSEC support and IPSEC_FILTERGIF option, and can correctly decapsulate it). .Pp @@ -1059,7 +1069,7 @@ The rule has a limited lifetime (controlled by a set of variables), and the lifetime is refreshed every time a matching packet is found. .It Cm layer2 -Matches only layer2 packets, i.e. those passed to +Matches only layer2 packets, i.e., those passed to .Nm from ether_demux() and ether_output_frame(). .It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N @@ -1114,7 +1124,7 @@ corresponds to one of those specified as argument. .Ar mac-type is specified in the same way as .Cm port numbers -(i.e. one or more comma-separated single values or ranges). +(i.e., one or more comma-separated single values or ranges). You can use symbolic names for known values such as .Em vlan , ipv4, ipv6 . Values can be entered as decimal or hexadecimal (if prefixed by 0x), @@ -1337,7 +1347,8 @@ When you disable a set, its rules behave as if they do not exist in the firewall configuration, with only one exception: .Bd -ragged -offset indent dynamic rules created from a rule before it had been disabled -will still be active until they expire. In order to delete +will still be active until they expire. +In order to delete dynamic rules you have to explicitly delete the parent rule which generated them. .Ed @@ -1362,7 +1373,8 @@ Section on some possible uses of sets of rules. .Sh STATEFUL FIREWALL Stateful operation is a way for the firewall to dynamically create rules for specific flows when packets that -match a given pattern are detected. Support for stateful +match a given pattern are detected. +Support for stateful operation comes through the .Cm check-state , keep-state and @@ -1589,7 +1601,8 @@ where the latter means all bits in all fields are significant. .It Cm noerror When a packet is dropped by a dummynet queue or pipe, the error is normally reported to the caller routine in the kernel, in the -same way as it happens when a device queue fills up. Setting this +same way as it happens when a device queue fills up. +Setting this option reports the packet as successfully delivered, which can be needed for some experimental setups where you want to simulate loss or congestion at a remote router. @@ -1615,7 +1628,7 @@ queueing delay. E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit or 20s of queue on a 30Kbit/s pipe. Even worse effects can result if you get packets from an -interface with a much larger MTU, e.g. the loopback interface +interface with a much larger MTU, e.g.\& the loopback interface with its 16KB packets. .Pp .It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p @@ -1783,7 +1796,8 @@ Current number of dynamic rules .It Em net.inet.ip.fw.dyn_keepalive : No 1 Enables generation of keepalive packets for .Cm keep-state -rules on TCP sessions. A keepalive is generated to both +rules on TCP sessions. +A keepalive is generated to both sides of the connection every 5 seconds for the last 20 seconds of the lifetime of the rule. .It Em net.inet.ip.fw.dyn_max : No 8192 @@ -1806,7 +1820,8 @@ Both and .Em dyn_rst_lifetime must be strictly lower than 5 seconds, the period of -repetition of keepalives. The firewall enforces that. +repetition of keepalives. +The firewall enforces that. .It Em net.inet.ip.fw.enable : No 1 Enables the firewall. Setting this variable to 0 lets you run your machine without @@ -1911,7 +1926,8 @@ you can only specify ports when the rule is requesting .Cm tcp or .Cm udp -packets. With +packets. +With .Nm ipfw2 you can put port specifications in rules matching all packets, and the match will be attempted only on those packets carrying @@ -2035,7 +2051,8 @@ following to the top of a ruleset: .Dl "ipfw add deny ip from any to any not verrevpath in" .Pp This rule drops all incoming packets that appear to be coming to the -system on the wrong interface. For example, a packet with a source +system on the wrong interface. +For example, a packet with a source address belonging to a host on a protected internal network would be dropped if it tried to enter the system from an external interface. .Ss DYNAMIC RULES @@ -2115,7 +2132,7 @@ A similar effect can be achieved making use of dummynet pipes: .Dl "ipfw add pipe 10 ip from any to any" .Dl "ipfw pipe 10 config plr 0.05" .Pp -We can use pipes to artificially limit bandwidth, e.g. on a +We can use pipes to artificially limit bandwidth, e.g.\& on a machine acting as a router, if we want to limit traffic from local clients on 192.168.2.0/24 we do: .Pp @@ -2137,11 +2154,11 @@ limitations, the correct way is the following: .Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes" .Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes" .Pp -The above can be very useful, e.g. if you want to see how +The above can be very useful, e.g.\& if you want to see how your fancy Web page will look for a residential user who is connected only through a slow link. You should not use only one pipe for both directions, unless -you want to simulate a half-duplex medium (e.g. AppleTalk, +you want to simulate a half-duplex medium (e.g.\& AppleTalk, Ethernet, IRDA). It is not necessary that both pipes have the same configuration, so we can also simulate asymmetric links. @@ -2191,7 +2208,7 @@ on a net with per-host limits, rather than per-network limits: .Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" .Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" .Ss SETS OF RULES -To add a set of rules atomically, e.g. set 18: +To add a set of rules atomically, e.g.\& set 18: .Pp .Dl "ipfw set disable 18" .Dl "ipfw add NN set 18 ... # repeat as needed" @@ -2208,7 +2225,8 @@ To test a ruleset and disable it and regain control if something goes wrong: .Dl "ipfw set enable 18; echo done; sleep 30 && ipfw set disable 18" .Pp Here if everything goes well, you press control-C before the "sleep" -terminates, and your ruleset will be left active. Otherwise, e.g. if +terminates, and your ruleset will be left active. +Otherwise, e.g.\& if you cannot access your box, the ruleset will be disabled after the sleep terminates thus restoring the previous situation. .Sh SEE ALSO diff --git a/sbin/ldconfig/ldconfig.8 b/sbin/ldconfig/ldconfig.8 index 2c84f0e..007d30d 100644 --- a/sbin/ldconfig/ldconfig.8 +++ b/sbin/ldconfig/ldconfig.8 @@ -48,7 +48,8 @@ utility is used to prepare a set of .Dq hints for use by the dynamic linker to facilitate quick lookup of shared libraries available in multiple -directories. It scans a set of built-in system directories and any +directories. +It scans a set of built-in system directories and any .Ar directories specified on the command line (in the given order) looking for shared libraries and stores the results in a system file to forestall @@ -57,8 +58,10 @@ operations the dynamic linker would have to perform to load the required shared libraries. .Pp Files named on the command line are expected to contain directories -to scan for shared libraries. Each directory's pathname must start on a new -line. Blank lines and lines starting with the comment character +to scan for shared libraries. +Each directory's pathname must start on a new +line. +Blank lines and lines starting with the comment character .Ql \&# are ignored. Filenames must conform to the @@ -105,15 +108,18 @@ Generate the hints for a.out format shared libraries. .It Fl elf Generate the hints for ELF format shared libraries. .It Fl R -Rescan the previously configured directories. This opens the previous hints -file and fetches the directory list from the header. Any additional pathnames +Rescan the previously configured directories. +This opens the previous hints +file and fetches the directory list from the header. +Any additional pathnames on the command line are also processed. This is the default action when no parameters are given. .It Fl f Ar hints_file Read and/or update the specified hints file, instead of the standard file. This option is provided primarily for testing. .It Fl i -Run in insecure mode. The security checks will not be performed. +Run in insecure mode. +The security checks will not be performed. .It Fl m Instead of replacing the contents of the hints file with those found in the directories specified, @@ -125,7 +131,8 @@ are also rescanned for new shared libraries. .It Fl r List the current contents of the hints file on the standard output. -The hints file is not modified. The list of +The hints file is not modified. +The list of directories stored in the hints file is included. .It Fl s Do not scan the built-in system directory @@ -160,7 +167,8 @@ Overrides .Fl aout or .Fl elf -is the default. If set, its value should be either +is the default. +If set, its value should be either .Ql aout or .Ql elf . @@ -184,7 +192,8 @@ Determines whether .Fl aout or .Fl elf -is the default. If present, it must consist of a single line +is the default. +If present, it must consist of a single line containing either .Ql OBJFORMAT=aout or diff --git a/sbin/mdconfig/mdconfig.8 b/sbin/mdconfig/mdconfig.8 index 1e22dc4..fb2b406 100644 --- a/sbin/mdconfig/mdconfig.8 +++ b/sbin/mdconfig/mdconfig.8 @@ -105,7 +105,8 @@ Filename to use for the vnode type memory disk. .It Fl l List information about configured .Xr md 4 -devices. If the +devices. +If the .Fl u option is used in conjuction with this, the output is limited to information on the specified device. diff --git a/sbin/mknod/mknod.8 b/sbin/mknod/mknod.8 index 2bc91cd..7de2a1b 100644 --- a/sbin/mknod/mknod.8 +++ b/sbin/mknod/mknod.8 @@ -65,7 +65,8 @@ and pseudo devices, and are type .Cm c . .It Ar major The major device number is an integer number which tells the kernel -which device driver entry point to use. To learn what +which device driver entry point to use. +To learn what major device number to use for a particular device, check .Pa /usr/src/sys/conf/majors . .It Ar minor diff --git a/sbin/mount_cd9660/mount_cd9660.8 b/sbin/mount_cd9660/mount_cd9660.8 index 6f281fb..b72bd6e 100644 --- a/sbin/mount_cd9660/mount_cd9660.8 +++ b/sbin/mount_cd9660/mount_cd9660.8 @@ -105,12 +105,15 @@ Start the file system at Normally, if the underlying device is a CD-ROM drive, .Nm will try to figure out the last track from the CD-ROM containing -data, and start the file system there. If the device is not a CD-ROM, +data, and start the file system there. +If the device is not a CD-ROM, or the table of contents cannot be examined, the file system will be -started at sector 0. This option can be used to override the behaviour. +started at sector 0. +This option can be used to override the behaviour. Note that .Ar startsector -is measured in CD-ROM blocks, with 2048 bytes each. This is the same +is measured in CD-ROM blocks, with 2048 bytes each. +This is the same as for example the .Cm info command of diff --git a/sbin/mount_nfs/mount_nfs.8 b/sbin/mount_nfs/mount_nfs.8 index b12ddab..48c55ef 100644 --- a/sbin/mount_nfs/mount_nfs.8 +++ b/sbin/mount_nfs/mount_nfs.8 @@ -315,7 +315,7 @@ tune the timeout interval.) .It Fl w Set the write data size to the specified value. -Ditto the comments w.r.t. the +Ditto the comments w.r.t.\& the .Fl r option, but using the .Dq "fragments dropped due to timeout" diff --git a/sbin/mount_nullfs/mount_nullfs.8 b/sbin/mount_nullfs/mount_nullfs.8 index 43534f0..03060de 100644 --- a/sbin/mount_nullfs/mount_nullfs.8 +++ b/sbin/mount_nullfs/mount_nullfs.8 @@ -103,7 +103,8 @@ The .Nm utility takes two arguments, the pathname of the lower vfs (target-pn) and the pathname where the null -layer will appear in the namespace (mount-point-pn). After +layer will appear in the namespace (mount-point-pn). +After the null layer is put into place, the contents of target-pn subtree will be aliased under mount-point-pn. .\" @@ -111,15 +112,19 @@ of target-pn subtree will be aliased under mount-point-pn. .Sh OPERATION OF A NULL LAYER The null layer is the minimum file system layer, simply bypassing all possible operations to the lower layer -for processing there. The majority of its activity centers +for processing there. +The majority of its activity centers on the bypass routine, through which nearly all vnode operations pass. .Pp The bypass routine accepts arbitrary vnode operations for -handling by the lower layer. It begins by examining vnode +handling by the lower layer. +It begins by examining vnode operation arguments and replacing any null-nodes by their -lower-layer equivalents. It then invokes the operation -on the lower layer. Finally, it replaces the null-nodes +lower-layer equivalents. +It then invokes the operation +on the lower layer. +Finally, it replaces the null-nodes in the arguments and, if a vnode is returned by the operation, stacks a null-node on top of the returned vnode. .Pp @@ -144,11 +149,13 @@ information. .\" .Sh INSTANTIATING VNODE STACKS Mounting associates the null layer with a lower layer, -in effect stacking two VFSes. Vnode stacks are instead +in effect stacking two VFSes. +Vnode stacks are instead created on demand as files are accessed. .Pp The initial mount creates a single vnode stack for the -root of the new null layer. All other vnode stacks +root of the new null layer. +All other vnode stacks are created as a result of vnode operations on this or other null vnode stacks. .Pp @@ -168,7 +175,8 @@ the root null-node (which was created when the null layer was mounted). Now consider opening .Pa sys . A vop_lookup would be -done on the root null-node. This operation would bypass through +done on the root null-node. +This operation would bypass through to the lower layer which would return a vnode representing the UFS .Pa sys . @@ -197,8 +205,10 @@ null layer. .\" .Sh INVOKING OPERATIONS ON LOWER LAYERS There are two techniques to invoke operations on a lower layer -when the operation cannot be completely bypassed. Each method -is appropriate in different situations. In both cases, +when the operation cannot be completely bypassed. +Each method +is appropriate in different situations. +In both cases, it is the responsibility of the aliasing layer to make the operation arguments "correct" for the lower layer by mapping a vnode argument to the lower layer. @@ -217,7 +227,8 @@ the lower layer with the .Em VOP_OPERATIONNAME interface. The advantage of this method is that it is easy to invoke -arbitrary operations on the lower layer. The disadvantage +arbitrary operations on the lower layer. +The disadvantage is that vnode arguments must be manually mapped. .\" .\" @@ -228,8 +239,11 @@ UCLA Technical Report CSD-910056, .Em "Stackable Layers: an Architecture for File System Development" . .Sh BUGS THIS FILE SYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK) -AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. USE AT YOUR -OWN RISK. BEWARE OF DOG. SLIPPERY WHEN WET. +AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. +USE AT YOUR +OWN RISK. +BEWARE OF DOG. +SLIPPERY WHEN WET. .Pp This code also needs an owner in order to be less dangerous - serious hackers can apply by sending mail to diff --git a/sbin/mount_std/mount_std.8 b/sbin/mount_std/mount_std.8 index 56ff0ff..86284d6 100644 --- a/sbin/mount_std/mount_std.8 +++ b/sbin/mount_std/mount_std.8 @@ -53,7 +53,8 @@ file systems The .Nm utility is a generic mechanism for attaching ``standard'' file systems to -the file system. The +the file system. +The .Nm utility currently supports the following file systems: .Nm devfs , @@ -96,7 +97,8 @@ man page for possible options and their meanings. The .Nm utility examines its zeroth command-line argument (the name by which -it was called) to determine the type of file system to be mounted. If +it was called) to determine the type of file system to be mounted. +If it is called by a name which does not end in .Dq Li _ Ns Ar fsname , .Nm diff --git a/sbin/mount_umapfs/mount_umapfs.8 b/sbin/mount_umapfs/mount_umapfs.8 index 403b219..1fe4765 100644 --- a/sbin/mount_umapfs/mount_umapfs.8 +++ b/sbin/mount_umapfs/mount_umapfs.8 @@ -58,9 +58,11 @@ The .Nm utility uses a set of files provided by the user to make correspondences between uids and gids in the sub-tree's original environment and -some other set of ids in the local environment. For instance, user +some other set of ids in the local environment. +For instance, user smith might have uid 1000 in the original environment, while having -uid 2000 in the local environment. The +uid 2000 in the local environment. +The .Nm utility allows the subtree from smith's original environment to be mapped in such a way that all files with owning uid 1000 look like @@ -86,7 +88,8 @@ where the mapped subtree is to be placed. Describe the mappings to be made between identifiers. Briefly, the format of these files is a count of the number of mappings on the first line, with each subsequent line containing -a single mapping. Each of these mappings consists of an id in +a single mapping. +Each of these mappings consists of an id in the local environment and the corresponding id from the original environment, separated by white space. .Ar Uid-mapfile @@ -100,7 +103,8 @@ will be treated as user NOBODY, and any gids not mapped in .Ar gid-mapfile will be treated as group -NULLGROUP. At most 64 uids can be mapped for a given subtree, and +NULLGROUP. +At most 64 uids can be mapped for a given subtree, and at most 16 groups can be mapped by a given subtree. .El .Pp @@ -109,21 +113,26 @@ must be owned by root, and they must be writable only by root. The .Nm utility will refuse to map the sub-tree if the ownership or permissions on -these files are improper. It will also balk if the count of mappings +these files are improper. +It will also balk if the count of mappings in the first line of the map files is not correct. .Pp The layer created by the .Nm utility is meant to serve as a simple example of file system layering. -It is not meant for production use. The implementation is not very +It is not meant for production use. +The implementation is not very sophisticated. .Sh SEE ALSO .Xr mount 8 , .Xr mount_nullfs 8 .Sh BUGS THIS FILE SYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK) -AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. USE AT YOUR -OWN RISK. BEWARE OF DOG. SLIPPERY WHEN WET. +AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. +USE AT YOUR +OWN RISK. +BEWARE OF DOG. +SLIPPERY WHEN WET. .Pp This code also needs an owner in order to be less dangerous - serious hackers can apply by sending mail to diff --git a/sbin/mount_unionfs/mount_unionfs.8 b/sbin/mount_unionfs/mount_unionfs.8 index 2a939f9..2a41aa6 100644 --- a/sbin/mount_unionfs/mount_unionfs.8 +++ b/sbin/mount_unionfs/mount_unionfs.8 @@ -179,8 +179,11 @@ accessible via .Xr mount_nullfs 8 .Sh BUGS THIS FILE SYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK) -AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. USE AT YOUR -OWN RISK. BEWARE OF DOG. SLIPPERY WHEN WET. +AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. +USE AT YOUR +OWN RISK. +BEWARE OF DOG. +SLIPPERY WHEN WET. .Pp This code also needs an owner in order to be less dangerous - serious hackers can apply by sending mail to diff --git a/sbin/newfs_msdos/newfs_msdos.8 b/sbin/newfs_msdos/newfs_msdos.8 index 7d5718d..b4189a5 100644 --- a/sbin/newfs_msdos/newfs_msdos.8 +++ b/sbin/newfs_msdos/newfs_msdos.8 @@ -78,26 +78,32 @@ FAT type (one of 12, 16, or 32). .It Fl I Ar volid Volume ID. .It Fl L Ar label -Volume label (up to 11 characters). The label should consist of +Volume label (up to 11 characters). +The label should consist of only those characters permitted in regular DOS (8+3) filenames. .It Fl O Ar OEM -OEM string (up to 8 characters). The default is +OEM string (up to 8 characters). +The default is .Qq Li "BSD 4.4" . .It Fl S Ar sector-size -Number of bytes per sector. Acceptable values are powers of 2 +Number of bytes per sector. +Acceptable values are powers of 2 in the range 128 through 32768. .It Fl a Ar FAT-size Number of sectors per FAT. .It Fl b Ar block-size -File system block size (bytes per cluster). This should resolve to an +File system block size (bytes per cluster). +This should resolve to an acceptable number of sectors per cluster (see below). .It Fl c Ar cluster-size -Sectors per cluster. Acceptable values are powers of 2 in the range +Sectors per cluster. +Acceptable values are powers of 2 in the range 1 through 128. .It Fl e Ar dirents Number of root directory entries (FAT12 and FAT16 only). .It Fl f Ar format -Specify a standard (floppy disk) format. The standard formats +Specify a standard (floppy disk) format. +The standard formats are (capacities in kilobytes): 160, 180, 320, 360, 640, 720, 1200, 1232, 1440, 2880. .It Fl h Ar heads @@ -106,12 +112,14 @@ Number of drive heads. Location of the file system info sector (FAT32 only). A value of 0xffff signifies no info sector. .It Fl k Ar backup -Location of the backup boot sector (FAT32 only). A value +Location of the backup boot sector (FAT32 only). +A value of 0xffff signifies no backup sector. .It Fl m Ar media Media descriptor (acceptable range 0xf0 to 0xff). .It Fl n Ar FATs -Number of FATs. Acceptable values are 1 to 16 inclusive. +Number of FATs. +Acceptable values are 1 to 16 inclusive. The default is 2. .It Fl o Ar hidden @@ -126,7 +134,8 @@ Number of sectors per track. .Sh NOTES FAT file system parameters occupy a "Boot Sector BPB (BIOS Parameter Block)" in the first of the "reserved" sectors which precede the actual -file system. For reference purposes, this structure is presented +file system. +For reference purposes, this structure is presented below. .Bd -literal struct bsbpb { diff --git a/sbin/nos-tun/nos-tun.8 b/sbin/nos-tun/nos-tun.8 index 0cfdeb1..9e7b9ae 100644 --- a/sbin/nos-tun/nos-tun.8 +++ b/sbin/nos-tun/nos-tun.8 @@ -49,7 +49,8 @@ and are the addresses used on the tunnel device. If you configure the tunnel against a cisco router, use a netmask of .Dq 255.255.255.252 -on the cisco. This is because the tunnel is a point-to-point interface +on the cisco. +This is because the tunnel is a point-to-point interface in the .Fx end, a concept cisco doesn't really implement. diff --git a/sbin/reboot/boot_i386.8 b/sbin/reboot/boot_i386.8 index b5f86f5..7b98df0 100644 --- a/sbin/reboot/boot_i386.8 +++ b/sbin/reboot/boot_i386.8 @@ -51,7 +51,8 @@ and unless this fails, the system will resume multi-user operations. .Sy Cold starts . Most i386 PCs attempt to boot first from floppy disk drive 0 (sometimes known as drive A:) and, failing that, from hard disk drive 0 (sometimes -known as drive C:, or as drive 0x80 to the BIOS). Some BIOSes allow +known as drive C:, or as drive 0x80 to the BIOS). +Some BIOSes allow you to change this default sequence, and may also include a CD-ROM drive as a boot device. .Pp @@ -77,10 +78,12 @@ or .Sy / is displayed) before .Xr loader 8 -is invoked. Booting will also be attempted at stage two, if the +is invoked. +Booting will also be attempted at stage two, if the third stage cannot be loaded. .Pp -The remainder of this subsection deals only with the boot blocks. The +The remainder of this subsection deals only with the boot blocks. +The .Xr loader 8 program is documented separately. .Pp @@ -100,11 +103,13 @@ of either the floppy or the hard disk. This boot may be aborted by typing any character on the keyboard at the .Ql boot: -prompt. At this time, the following input will be accepted: +prompt. +At this time, the following input will be accepted: .Bl -tag -width indent .It Ic \&? Give a short listing of the files in the root directory of the default -boot device, as a hint about available boot files. (A +boot device, as a hint about available boot files. +(A .Ic ?\& may also be specified as the last segment of a path, in which case the listing will be of the relevant subdirectory.) @@ -122,7 +127,8 @@ Specify boot file and flags. The drive number as recognized by the BIOS. 0 for the first drive, 1 for the second drive, etc. .It Ar interface -The type of controller to boot from. Note that the controller is required +The type of controller to boot from. +Note that the controller is required to have BIOS support since the BIOS services are used to load the boot file image. .Pp @@ -145,11 +151,13 @@ The unit number of the drive on the interface being used. .It Oo Ar slice , Oc Ns Ar part The partition letter inside the .Bx -portion of the disk. See +portion of the disk. +See .Xr disklabel 8 . By convention, only partition .Ql a -contains a bootable image. If sliced disks are used +contains a bootable image. +If sliced disks are used .Pq Dq fdisk partitions , any .Ar slice @@ -167,7 +175,8 @@ slice (also known as slice) is booted from. .It Ar filename The pathname of the file to boot (relative to the root directory -on the specified partition). Defaults to +on the specified partition). +Defaults to .Pa /kernel . Symbolic links are not supported (hard links are). .It Fl aCcDdghmnPprsv @@ -181,23 +190,28 @@ ask for the device to mount as the root file system. boot from CDROM. .It Fl c run UserConfig to modify hardware parameters for the loaded -kernel. If the kernel was built with one of +kernel. +If the kernel was built with one of .Dv USERCONFIG , INTRO_USERCONFIG , VISUAL_USERCONFIG options, remain in UserConfig regardless of any .Ic quit commands present in the script. .It Fl D -toggle single and dual console configurations. In the single +toggle single and dual console configurations. +In the single configuration the console will be either the internal display or the serial port, depending on the state of the .Fl h -option below. In the dual console configuration, +option below. +In the dual console configuration, both the internal display and the serial port will become the console at the same time, regardless of the state of the .Fl h -option. However, the dual console configuration takes effect only during -the boot prompt. Once the kernel is loaded, the console specified +option. +However, the dual console configuration takes effect only during +the boot prompt. +Once the kernel is loaded, the console specified by the .Fl h option becomes the only console. @@ -209,12 +223,15 @@ as early as possible in kernel initialization. .It Fl g use the GDB remote debugging protocol. .It Fl h -toggle internal and serial consoles. You can use this to switch -console devices. For instance, if you boot from the internal console, +toggle internal and serial consoles. +You can use this to switch +console devices. +For instance, if you boot from the internal console, you can use the .Fl h option to force the kernel to use the serial port as its -console device. Alternatively, if you boot from the serial port, +console device. +Alternatively, if you boot from the serial port, you can use this option to force the kernel to use the internal display as the console instead. The serial port driver @@ -223,7 +240,8 @@ has a flag to override this option. If that flag is set, the serial port will always be used as the console, regardless of the .Fl h -option described here. See the man page for +option described here. +See the man page for .Xr sio 4 for more details. .It Fl m @@ -233,7 +251,8 @@ ignore key press to interrupt boot before .Xr loader 8 is invoked. .It Fl P -probe the keyboard. If no keyboard is found, the +probe the keyboard. +If no keyboard is found, the .Fl D and .Fl h @@ -262,7 +281,8 @@ be verbose during device probing (and later). You may put a BIOS drive number, a controller type, a unit number, a partition, a kernel file name, and any valid option in .Pa /boot.config -to set defaults. Enter them in one line just as you type at the +to set defaults. +Enter them in one line just as you type at the .Ql boot: prompt. .Sh FILES @@ -325,7 +345,8 @@ On older machines, or otherwise where EDD support (disk packet interface support) is not available, all boot-related files and structures (including the kernel) that need to be accessed during the boot phase must reside on the disk at or below cylinder 1023 (as the -BIOS understands the geometry). When a +BIOS understands the geometry). +When a .Dq Disk error 0x1 is reported by the second-stage bootstrap, it generally means that this requirement has not been adhered to. @@ -341,7 +362,8 @@ Due to space constraints, the keyboard probe initiated by the .Fl P option is simply a test that the BIOS has detected an .Dq extended -keyboard. If an +keyboard. +If an .Dq XT/AT keyboard (with no F11 and F12 keys, etc.) is attached, the probe will fail. diff --git a/sbin/restore/restore.8 b/sbin/restore/restore.8 index 445a157..1d57760 100644 --- a/sbin/restore/restore.8 +++ b/sbin/restore/restore.8 @@ -205,7 +205,8 @@ The .Fl r flag precludes an interactive file extraction and can be detrimental to one's health if not used carefully (not to mention -the disk). An example: +the disk). +An example: .Bd -literal -offset indent newfs /dev/da0s1a mount /dev/da0s1a /mnt @@ -279,7 +280,8 @@ tries to determine the media block size dynamically. Normally, .Nm will try to determine dynamically whether the dump was made from an -old (pre-4.4) or new format file system. The +old (pre-4.4) or new format file system. +The .Fl c flag disables this check, and only allows reading a dump in the old format. @@ -472,8 +474,10 @@ thus a full dump must be done to get a new set of directories reflecting the new inode numbering, even though the contents of the files is unchanged. .Pp -To do a network restore, you have to run restore as root. This is due -to the previous security history of dump and restore. (restore is +To do a network restore, you have to run restore as root. +This is due +to the previous security history of dump and restore. +(restore is written to be setuid root, but we are not certain all bugs are gone from the restore code - run setuid at your own risk.) .Pp diff --git a/sbin/route/route.8 b/sbin/route/route.8 index 335d072..30b807c 100644 --- a/sbin/route/route.8 +++ b/sbin/route/route.8 @@ -46,7 +46,8 @@ The .Nm utility is used to manually manipulate the network -routing tables. It normally is not needed, as a +routing tables. +It normally is not needed, as a system routing table management daemon, such as .Xr routed 8 , should tend to this task. @@ -65,7 +66,8 @@ The following options are available: Run in debug-only mode, i.e., do not actually modify the routing table. .It Fl n Bypass attempts to print host and network names symbolically -when reporting actions. (The process of translating between symbolic +when reporting actions. +(The process of translating between symbolic names and numerical equivalents can be quite time consuming, and may require correct operation of the network; thus it may be expedient to forget this, especially when attempting to repair networking operations). @@ -356,7 +358,8 @@ the routing tables. .Sh DIAGNOSTICS .Bl -diag .It "add [host \&| network ] %s: gateway %s flags %x" -The specified route is being added to the tables. The +The specified route is being added to the tables. +The values printed are from the routing table entry supplied in the .Xr ioctl 2 diff --git a/sbin/routed/routed.8 b/sbin/routed/routed.8 index f483ed9..afee816 100644 --- a/sbin/routed/routed.8 +++ b/sbin/routed/routed.8 @@ -211,9 +211,11 @@ It continues listening to RIP while using Router Discovery if multi-homed to ensure all interfaces are used. .Pp The Router Discovery standard requires that advertisements -have a default "lifetime" of 30 minutes. That means should +have a default "lifetime" of 30 minutes. +That means should something happen, a client can be without a good route for -30 minutes. It is a good idea to reduce the default to 45 +30 minutes. +It is a good idea to reduce the default to 45 seconds using .Fl P Cm rdisc_interval=45 on the command line or @@ -240,7 +242,7 @@ facility described below to support "legacy" systems that can handle neither RIPv2 nor Router Discovery. .Pp By default, neither Router Discovery advertisements nor solicitations -are sent over point to point links (e.g. PPP). +are sent over point to point links (e.g.\& PPP). The netmask associated with point-to-point links (such as SLIP or PPP, with the IFF_POINTOPOINT flag) is used by .Nm @@ -286,7 +288,8 @@ This is typically used on a gateway to the Internet, or on a gateway that uses another routing protocol whose routes are not reported to other local routers. Notice that because a metric of 1 is used, this feature is -dangerous. It is more commonly accidentally used to create chaos with a +dangerous. +It is more commonly accidentally used to create chaos with a routing loop than to solve problems. .It Fl h cause host or point-to-point routes to not be advertised, @@ -514,7 +517,7 @@ To set parameters for remote or external interfaces, a line starting with .Cm if=alias(Hname) , .Cm if=remote(Hname) , -etc. should be used. +etc.\& should be used. .Ss Parameters Lines that start with neither "net" nor "host" must consist of one or more of the following parameter settings, separated by commas or @@ -535,7 +538,8 @@ This parameter must appear by itself on a line. The network number must specify a full, 32-bit value, as in 192.0.2.0 instead of 192.0.2. .Pp -Do not use this feature unless necessary. It is dangerous. +Do not use this feature unless necessary. +It is dangerous. .It Cm ripv1_mask Ns = Ns Ar nname Ns / Ns Ar mask1 , Ns Ar mask2 specifies that netmask of the network of which .Ar nname Ns / Ns Ar mask1 diff --git a/sbin/shutdown/shutdown.8 b/sbin/shutdown/shutdown.8 index e0fa853..d7073b2 100644 --- a/sbin/shutdown/shutdown.8 +++ b/sbin/shutdown/shutdown.8 @@ -112,7 +112,8 @@ specify a future time in one of two formats: or .Ar yymmddhhmm , where the year, month, and day may be defaulted -to the current system values. The first form brings the system down in +to the current system values. +The first form brings the system down in .Ar number minutes and the second at the absolute time specified. .It Ar warning-message @@ -127,15 +128,18 @@ input. .Pp At intervals, becoming more frequent as apocalypse approaches and starting at ten hours before shutdown, warning messages are displayed -on the terminals of all users logged in. Five minutes before +on the terminals of all users logged in. +Five minutes before shutdown, or immediately if shutdown is in less than 5 minutes, logins are disabled by creating .Pa /var/run/nologin and copying the -warning message there. If this file exists when a user attempts to +warning message there. +If this file exists when a user attempts to log in, .Xr login 1 -prints its contents and exits. The file is +prints its contents and exits. +The file is removed just before .Nm exits. diff --git a/sbin/slattach/slattach.8 b/sbin/slattach/slattach.8 index 594c4b4..a6355d8 100644 --- a/sbin/slattach/slattach.8 +++ b/sbin/slattach/slattach.8 @@ -66,7 +66,8 @@ Autoenable the VJ header compression option, if the other end of the link is capable of VJ header compression then it will be used otherwise normal headers will be used. .It Fl c -Enable the VJ header compression option. Note that both ends of the link +Enable the VJ header compression option. +Note that both ends of the link must be able to use VJ header compression for this to work. .It Fl e Ar exit-command Specify a command to be invoked within a shell @@ -83,7 +84,8 @@ Turn on cts/rts style flow control on the slip port, by default no flow control is done. .It Fl l Disable modem control (CLOCAL) and ignore carrier detect on the slip -port. By default the +port. +By default the .Ar redial-command is invoked upon carrier drop and .Nm @@ -91,7 +93,8 @@ aborts if no .Ar redial-command is specified. .It Fl n -Throw away ICMP packets. The slip interface will ignore ICMP packets +Throw away ICMP packets. +The slip interface will ignore ICMP packets to prevent slow lines being saturated by ICMP responses. .It Fl r Ar redial-command Specify a command to be invoked within a shell @@ -116,7 +119,8 @@ and .Ar new are the slip unit numbers when the line was last opened and the unit number of the current slip connection -respectively. The unit number can change after redialing if you are +respectively. +The unit number can change after redialing if you are using more than one slip line. When .Nm @@ -150,7 +154,8 @@ If FRAME_END is not received in this amount of time, re-connect occurs. The default value is no timeout. .It Fl O Ar outfill -Set SLIP "out fill" timeout in seconds. It forces at least one FRAME_END +Set SLIP "out fill" timeout in seconds. +It forces at least one FRAME_END to be sent during this time period, which is necessary for the "keep alive" timeout on the remote side. The default value is no timeout. @@ -185,7 +190,8 @@ To setup to redial the phone when carrier is lost, use the .Fl r Ar redial-command option to specify a script or executable that will reconnect the -serial line to the slip server. For example, the script could redial +serial line to the slip server. +For example, the script could redial the server and log in, etc. .Pp To reconfigure the network interface in case the slip unit number @@ -198,8 +204,10 @@ where and .Ar new are the slip unit numbers before and after -reconnecting the line. The unit number can change if you have more -than one line disconnect at the same time. The first to succeed in +reconnecting the line. +The unit number can change if you have more +than one line disconnect at the same time. +The first to succeed in reconnecting will get the lowest unit number. .Pp To kill @@ -240,7 +248,8 @@ The .Nm utility also logs failure to set the controlling terminal or failure to install -signal handlers. Upon connection and redial the ttyname and baud rate +signal handlers. +Upon connection and redial the ttyname and baud rate are logged and on shutdown the ttyname is logged. .Sh FILES .Bl -tag -width /usr/share/examples/slattach/* -compact diff --git a/sbin/spppcontrol/spppcontrol.8 b/sbin/spppcontrol/spppcontrol.8 index 66896c3..0b038c2 100644 --- a/sbin/spppcontrol/spppcontrol.8 +++ b/sbin/spppcontrol/spppcontrol.8 @@ -117,11 +117,11 @@ In the latter case, the use of an authentication protocol will be turned off for the named interface. This has the side-effect of clearing the other authentication-related parameters for this -interface as well (i.e. system name and authentication secret will +interface as well (i.e., system name and authentication secret will be forgotten). .It Va myauthproto Ns Li = Ns Ar protoname Same as above, but only for my end of the link. -I.e. this is the +I.e., this is the protocol when remote is authenticator, and I am the peer required to authenticate. .It Va hisauthproto Ns Li = Ns Ar protoname @@ -221,7 +221,7 @@ Display the settings for .Li bppp0 . The interface is currently in .Em dead -phase, i.e. the LCP layer is down, and no traffic is possible. +phase, i.e., the LCP layer is down, and no traffic is possible. Both ends of the connection use the CHAP protocol, my end tells remote the system name diff --git a/sbin/startslip/startslip.1 b/sbin/startslip/startslip.1 index 4773873..e185065 100644 --- a/sbin/startslip/startslip.1 +++ b/sbin/startslip/startslip.1 @@ -121,7 +121,8 @@ the string is used to specify a dial sequence. No string written by default. You can specify several .Fl s Ar stringN -arguments to use with each try, f.e. several host phone numbers. +arguments to use with each try, f.e. +several host phone numbers. .It Fl A Ar annexname The .Nm @@ -144,11 +145,13 @@ Disable modem control (waiting for carrier and carrier drop sense) for .Ar device . Modem control is enabled by default. .It Fl U Ar upscript -Specify a script to run when a SLIP interface becomes connected. This may +Specify a script to run when a SLIP interface becomes connected. +This may contain .Xr ifconfig 8 , .Xr route 8 , -and other appropriate commands. The arguments that +and other appropriate commands. +The arguments that are passed to the script are "slX up". Default value is .Pa /sbin/ifconfig . @@ -158,8 +161,10 @@ passed via .Ev LINE environment variable. .It Fl D Ar downscript -Specify a script to run when a SLIP connection goes away. The arguments that -are passed to the script are "slX down". Default value is +Specify a script to run when a SLIP connection goes away. +The arguments that +are passed to the script are "slX down". +Default value is .Pa /sbin/ifconfig . Dial sequence number (see .Fl s ) diff --git a/sbin/vinum/vinum.8 b/sbin/vinum/vinum.8 index fd8db09..157b020 100644 --- a/sbin/vinum/vinum.8 +++ b/sbin/vinum/vinum.8 @@ -173,7 +173,8 @@ Write a copy of the current configuration to .It Ic quit Exit the .Nm -utility when running in interactive mode. Normally this would be done by +utility when running in interactive mode. +Normally this would be done by entering the .Dv EOF character. @@ -271,12 +272,14 @@ utility communicates with the kernel component of the Vinum logical volume manager. It is designed either for interactive use, when started without command line arguments, or to execute a single command if the command is supplied on the -command line. In interactive mode, +command line. +In interactive mode, .Nm maintains a command line history. .Sh OPTIONS .Nm -commands may optionally be followed by an option. Any of the following options +commands may optionally be followed by an option. +Any of the following options may be specified with any command, but in some cases the options are ignored. For example, the .Ic stop @@ -290,14 +293,18 @@ options. The .Fl f .Pq Dq force -option overrides safety checks. Use with extreme care. This option is for -emergency use only. For example, the command +option overrides safety checks. +Use with extreme care. +This option is for +emergency use only. +For example, the command .Pp .Dl rm -f myvolume .Pp removes .Ar myvolume -even if it is open. Any subsequent access to the volume will almost certainly +even if it is open. +Any subsequent access to the volume will almost certainly cause a panic. .It Fl i Ar millisecs When performing the @@ -306,7 +313,8 @@ and .Ic start commands, wait .Ar millisecs -milliseconds between copying each block. This lowers the load on the system. +milliseconds between copying each block. +This lowers the load on the system. .It Fl n Ar name Use the .Fl n @@ -319,7 +327,8 @@ The .Fl r .Pq Dq recursive option is used by the list commands to display information not -only about the specified objects, but also about subordinate objects. For +only about the specified objects, but also about subordinate objects. +For example, in conjunction with the .Ic lv command, the @@ -330,7 +339,8 @@ volume. The .Fl s .Pq Dq statistics -option is used by the list commands to display statistical information. The +option is used by the list commands to display statistical information. +The .Ic mirror command also uses this option to specify that it should create striped plexes. .It Fl S Ar size @@ -374,9 +384,12 @@ commands perform the following functions: .Op Cm rename .Xc .Nm Ic attach -inserts the specified plex or subdisk in a volume or plex. In the case of a -subdisk, an offset in the plex may be specified. If it is not, the subdisk will -be attached at the first possible location. After attaching a plex to a +inserts the specified plex or subdisk in a volume or plex. +In the case of a +subdisk, an offset in the plex may be specified. +If it is not, the subdisk will +be attached at the first possible location. +After attaching a plex to a non-empty volume, .Nm reintegrates the plex. @@ -388,7 +401,8 @@ is specified, renames the object (and in the case of a plex, any subordinate subdisks) to fit in with the default .Nm -naming convention. To rename the object to any other name, use the +naming convention. +To rename the object to any other name, use the .Ic rename command. .Pp @@ -402,18 +416,21 @@ failure), it should be replaced by a subdisk of the same size only. .It In order to add further subdisks to a striped or RAID-5 plex, use the .Fl f -(force) option. This will corrupt the data in the plex. +(force) option. +This will corrupt the data in the plex. .\"No other attachment of .\"subdisks is currently allowed for striped and RAID-5 plexes. .It For concatenated plexes, the .Ar offset -parameter specifies the offset in blocks from the beginning of the plex. For +parameter specifies the offset in blocks from the beginning of the plex. +For striped and RAID-5 plexes, it specifies the offset of the first block of the subdisk: in other words, the offset is the numerical position of the subdisk -multiplied by the stripe size. For example, in a plex with stripe size 271k, +multiplied by the stripe size. +For example, in a plex with stripe size 271k, the first subdisk will have offset 0, the second offset 271k, the third 542k, -etc. This calculation ignores parity blocks in RAID-5 plexes. +etc.\& This calculation ignores parity blocks in RAID-5 plexes. .El .Pp .It Xo @@ -422,9 +439,11 @@ etc. This calculation ignores parity blocks in RAID-5 plexes. .Op Fl v .Ar plex .Xc -Check the parity blocks on the specified RAID-4 or RAID-5 plex. This operation +Check the parity blocks on the specified RAID-4 or RAID-5 plex. +This operation maintains a pointer in the plex, so it can be stopped and later restarted from -the same position if desired. In addition, this pointer is used by the +the same position if desired. +In addition, this pointer is used by the .Ic rebuildparity command, so rebuilding the parity blocks need only start at the location where the first parity problem has been detected. @@ -433,7 +452,8 @@ If the .Fl f flag is specified, .Ic checkparity -starts checking at the beginning of the plex. If the +starts checking at the beginning of the plex. +If the .Fl v flag is specified, .Ic checkparity @@ -450,26 +470,31 @@ The .Ic concat command provides a simplified alternative to the .Ic create -command for creating volumes with a single concatenated plex. The largest +command for creating volumes with a single concatenated plex. +The largest contiguous space available on each drive is used to create the subdisks for the plexes. .Pp Normally, the .Ic concat -command creates an arbitrary name for the volume and its components. The name +command creates an arbitrary name for the volume and its components. +The name is composed of the text .Dq Li vinum and a small integer, for example .Dq Li vinum3 . You can override this with the .Fl n Ar name -option, which assigns the name specified to the volume. The plexes and subdisks +option, which assigns the name specified to the volume. +The plexes and subdisks are named after the volume in the default manner. .Pp -There is no choice of name for the drives. If the drives have already been +There is no choice of name for the drives. +If the drives have already been initialized as .Nm -drives, the name remains. Otherwise the drives are given names starting with +drives, the name remains. +Otherwise the drives are given names starting with the text .Dq Li vinumdrive and a small integer, for example @@ -478,7 +503,8 @@ As with the .Ic create command, the .Fl f -option can be used to specify that a previous name should be overwritten. The +option can be used to specify that a previous name should be overwritten. +The .Fl v is used to specify verbose output. .Pp @@ -493,17 +519,21 @@ command. .Ar description-file .Xc .Nm Ic create -is used to create any object. In view of the relatively complicated +is used to create any object. +In view of the relatively complicated relationship and the potential dangers involved in creating a .Nm -object, there is no interactive interface to this function. If you do not +object, there is no interactive interface to this function. +If you do not specify a file name, .Nm -starts an editor on a temporary file. If the environment variable +starts an editor on a temporary file. +If the environment variable .Ev EDITOR is set, .Nm -starts this editor. If not, it defaults to +starts this editor. +If not, it defaults to .Nm vi . See the section .Sx CONFIGURATION FILE @@ -519,31 +549,38 @@ Normally the .Ic create command will not change the names of existing .Nm -drives, in order to avoid accidentally erasing them. The correct way to dispose +drives, in order to avoid accidentally erasing them. +The correct way to dispose of no longer wanted .Nm drives is to reset the configuration with the .Ic resetconfig -command. In some cases, however, it may be necessary to create new data on +command. +In some cases, however, it may be necessary to create new data on .Nm -drives which can no longer be started. In this case, use the +drives which can no longer be started. +In this case, use the .Ic create Fl f command. .Pp .It Ic debug .Nm Ic debug , -without any arguments, is used to enter the remote kernel debugger. It is only +without any arguments, is used to enter the remote kernel debugger. +It is only activated if .Nm is built with the .Dv VINUMDEBUG -option. This option will stop the execution of the operating system until the -kernel debugger is exited. If remote debugging is set and there is no remote +option. +This option will stop the execution of the operating system until the +kernel debugger is exited. +If remote debugging is set and there is no remote connection for a kernel debugger, it will be necessary to reset the system and reboot in order to leave the debugger. .Pp .It Ic debug Ar flags -Set a bit mask of internal debugging flags. These will change without warning +Set a bit mask of internal debugging flags. +These will change without warning as the product matures; to be certain, read the header file .In sys/dev/vinumvar.h . The bit mask is composed of the following values: @@ -580,10 +617,12 @@ Print some warnings about minor problems in the implementation. .It Ic detach Oo Fl f Oc Ar subdisk .Nm Ic detach removes the specified plex or subdisk from the volume or plex to which it is -attached. If removing the object would impair the data integrity of the volume, +attached. +If removing the object would impair the data integrity of the volume, the operation will fail unless the .Fl f -option is specified. If the object is named after the object above it (for +option is specified. +If the object is named after the object above it (for example, subdisk .Li vol1.p7.s0 attached to plex @@ -597,7 +636,8 @@ If necessary, the name will be truncated in the process. .Pp .Ic detach -does not reduce the number of subdisks in a striped or RAID-5 plex. Instead, +does not reduce the number of subdisks in a striped or RAID-5 plex. +Instead, the subdisk is marked absent, and can later be replaced with the .Ic attach command. @@ -605,20 +645,25 @@ command. .It Ic dumpconfig Op Ar drive ... .Pp .Nm Ic dumpconfig -shows the configuration information stored on the specified drives. If no drive +shows the configuration information stored on the specified drives. +If no drive names are specified, .Ic dumpconfig searches all drives on the system for Vinum partitions and dumps the -information. If configuration updates are disabled, it is possible that this +information. +If configuration updates are disabled, it is possible that this information is not the same as the information returned by the .Ic list -command. This command is used primarily for maintenance and debugging. +command. +This command is used primarily for maintenance and debugging. .Pp .It Ic info .Nm Ic info displays information about .Nm -memory usage. This is intended primarily for debugging. With the +memory usage. +This is intended primarily for debugging. +With the .Fl v option, it will give detailed information about the memory areas in use. .Pp @@ -628,7 +673,9 @@ option, .Ic info displays information about the last up to 64 I/O requests handled by the .Nm -driver. This information is only collected if debug flag 8 is set. The format +driver. +This information is only collected if debug flag 8 is set. +The format looks like: .Bd -literal vinum -> info -V @@ -656,21 +703,25 @@ Time Event Buf Dev Offset Bytes SD .Pp The .Ar Buf -field always contains the address of the user buffer header. This can be used +field always contains the address of the user buffer header. +This can be used to identify the requests associated with a user request, though this is not 100% reliable: theoretically two requests in sequence could use the same buffer -header, though this is not common. The beginning of a request can be identified +header, though this is not common. +The beginning of a request can be identified by the event .Ar 1VS or .Ar 7VS . -The first example above shows the requests involved in a user request. The +The first example above shows the requests involved in a user request. +The second is a subdisk I/O request with locking. .Pp The .Ar Event field contains information related to the sequence of events in the request -chain. The digit +chain. +The digit .Ar 1 to .Ar 6 @@ -682,7 +733,8 @@ a mnemonic for the location: .Fn vinumstrategy . The device number is the .Nm -device, and offset and length are the user parameters. This is always the +device, and offset and length are the user parameters. +This is always the beginning of a request sequence. .It 2LR (launch_requests) shows the user request just prior to launching the low-level @@ -712,13 +764,15 @@ is the offset of the associated group request, where applicable. .It 3RQ (request) shows one of possibly several low-level .Nm -requests which are launched to satisfy the high-level request. This information +requests which are launched to satisfy the high-level request. +This information is also logged in .Fn launch_requests . .It 4DN (done) is called from .Fn complete_rqe , -showing the completion of a request. This completion should match a request +showing the completion of a request. +This completion should match a request launched either at stage .Ar 4DN from @@ -740,21 +794,25 @@ parity. and represents the data written to a RAID-5 parity stripe after calculating parity. .It 7VS -shows a subdisk I/O request. These requests are usually internal to +shows a subdisk I/O request. +These requests are usually internal to .Nm for operations like initialization or rebuilding plexes. .It 8LR shows the low-level operation generated for a subdisk I/O request. .It Lockwait -specifies that the process is waiting for a range lock. The parameters are the +specifies that the process is waiting for a range lock. +The parameters are the buffer header associated with the request, the plex number and the block number. For internal reasons the block number is one higher than the address of the beginning of the stripe. .It Lock -specifies that a range lock has been obtained. The parameters are the same as +specifies that a range lock has been obtained. +The parameters are the same as for the range lock. .It Unlock -specifies that a range lock has been released. The parameters are the same as +specifies that a range lock has been released. +The parameters are the same as for the range lock. .El .\" XXX @@ -766,13 +824,19 @@ for the range lock. .Ar plex | subdisk .Xc .Nm Ic init -initializes a subdisk by writing zeroes to it. You can initialize all subdisks -in a plex by specifying the plex name. This is the only way to ensure -consistent data in a plex. You must perform this initialization before using a -RAID-5 plex. It is also recommended for other new plexes. -.Nm -initializes all subdisks of a plex in parallel. Since this operation can take a -long time, it is normally performed in the background. If you want to wait for +initializes a subdisk by writing zeroes to it. +You can initialize all subdisks +in a plex by specifying the plex name. +This is the only way to ensure +consistent data in a plex. +You must perform this initialization before using a +RAID-5 plex. +It is also recommended for other new plexes. +.Nm +initializes all subdisks of a plex in parallel. +Since this operation can take a +long time, it is normally performed in the background. +If you want to wait for completion of the command, use the .Fl w (wait) option. @@ -789,7 +853,8 @@ The .Ic label command writes a .Em ufs -style volume label on a volume. It is a simple alternative to an appropriate +style volume label on a volume. +It is a simple alternative to an appropriate call to .Ic disklabel . This is needed because some @@ -848,7 +913,8 @@ This command is deprecated. .Op Ar volume .Xc .Ic list -is used to show information about the specified object. If the argument is +is used to show information about the specified object. +If the argument is omitted, information is shown about all objects known to .Nm . The @@ -860,11 +926,13 @@ The .Fl r option relates to volumes and plexes: if specified, it recursively lists information for the subdisks and (for a volume) plexes subordinate to the -objects. The commands +objects. +The commands .Ic lv , lp , ls and .Ic ld -list only volumes, plexes, subdisks and drives respectively. This is +list only volumes, plexes, subdisks and drives respectively. +This is particularly useful when used without parameters. .Pp The @@ -889,37 +957,47 @@ The .Ic mirror command provides a simplified alternative to the .Ic create -command for creating mirrored volumes. Without any options, it creates a RAID-1 -(mirrored) volume with two concatenated plexes. The largest contiguous space -available on each drive is used to create the subdisks for the plexes. The +command for creating mirrored volumes. +Without any options, it creates a RAID-1 +(mirrored) volume with two concatenated plexes. +The largest contiguous space +available on each drive is used to create the subdisks for the plexes. +The first plex is built from the odd-numbered drives in the list, and the second -plex is built from the even-numbered drives. If the drives are of different +plex is built from the even-numbered drives. +If the drives are of different sizes, the plexes will be of different sizes. .Pp If the .Fl s option is provided, .Ic mirror -builds striped plexes with a stripe size of 279 kB. The size of the subdisks in +builds striped plexes with a stripe size of 279 kB. +The size of the subdisks in each plex is the size of the smallest contiguous storage available on any of the -drives which form the plex. Again, the plexes may differ in size. +drives which form the plex. +Again, the plexes may differ in size. .Pp Normally, the .Ic mirror -command creates an arbitrary name for the volume and its components. The name +command creates an arbitrary name for the volume and its components. +The name is composed of the text .Dq Li vinum and a small integer, for example .Dq Li vinum3 . You can override this with the .Fl n Ar name -option, which assigns the name specified to the volume. The plexes and subdisks +option, which assigns the name specified to the volume. +The plexes and subdisks are named after the volume in the default manner. .Pp -There is no choice of name for the drives. If the drives have already been +There is no choice of name for the drives. +If the drives have already been initialized as .Nm -drives, the name remains. Otherwise the drives are given names starting with +drives, the name remains. +Otherwise the drives are given names starting with the text .Dq Li vinumdrive and a small integer, for example @@ -928,7 +1006,8 @@ As with the .Ic create command, the .Fl f -option can be used to specify that a previous name should be overwritten. The +option can be used to specify that a previous name should be overwritten. +The .Fl v is used to specify verbose output. .Pp @@ -939,14 +1018,18 @@ command. .Pp .It Ic mv Fl f Ar drive object ... .It Ic move Fl f Ar drive object ... -Move all the subdisks from the specified objects onto the new drive. The -objects may be subdisks, drives or plexes. When drives or plexes are specified, +Move all the subdisks from the specified objects onto the new drive. +The +objects may be subdisks, drives or plexes. +When drives or plexes are specified, all subdisks associated with the object are moved. .Pp The .Fl f option is required for this function, since it currently does not preserve the -data in the subdisk. This functionality will be added at a later date. In this +data in the subdisk. +This functionality will be added at a later date. +In this form, however, it is suited to recovering a failed disk drive. .Pp .It Ic printconfig Op Ar file @@ -954,8 +1037,10 @@ Write a copy of the current configuration to .Ar file in a format that can be used to recreate the .Nm -configuration. Unlike the configuration saved on disk, it includes definitions -of the drives. If you omit +configuration. +Unlike the configuration saved on disk, it includes definitions +of the drives. +If you omit .Ar file , .Nm writes the list to @@ -964,7 +1049,8 @@ writes the list to .It Ic quit Exit the .Nm -utility when running in interactive mode. Normally this would be done by +utility when running in interactive mode. +Normally this would be done by entering the .Dv EOF character. @@ -974,14 +1060,16 @@ The .Ic read command scans the specified disks for .Nm -partitions containing previously created configuration information. It reads +partitions containing previously created configuration information. +It reads the configuration in order from the most recently updated to least recently updated configuration. The .Nm utility maintains an up-to-date copy of all configuration information on each disk -partition. You must specify all of the slices in a configuration as the +partition. +You must specify all of the slices in a configuration as the parameter to this command. .Pp The @@ -990,7 +1078,8 @@ command is intended to selectively load a .Nm configuration on a system which has other .Nm -partitions. If you want to start all partitions on the system, it is easier to +partitions. +If you want to start all partitions on the system, it is easier to use the .Ic start command. @@ -998,14 +1087,17 @@ command. If .Nm encounters any errors during this command, it will turn off automatic -configuration update to avoid corrupting the copies on disk. This will also +configuration update to avoid corrupting the copies on disk. +This will also happen if the configuration on disk indicates a configuration error (for -example, subdisks which do not have a valid space specification). You can turn +example, subdisks which do not have a valid space specification). +You can turn the updates on again with the .Ic setdaemon and .Ic saveconfig -commands. Reset bit 2 (numerical value 4) of the daemon options mask to +commands. +Reset bit 2 (numerical value 4) of the daemon options mask to re-enable configuration saves. .Pp .It Xo @@ -1015,9 +1107,11 @@ re-enable configuration saves. .Op Fl V .Ar plex .Xc -Rebuild the parity blocks on the specified RAID-4 or RAID-5 plex. This +Rebuild the parity blocks on the specified RAID-4 or RAID-5 plex. +This operation maintains a pointer in the plex, so it can be stopped and later -restarted from the same position if desired. In addition, this pointer is used +restarted from the same position if desired. +In addition, this pointer is used by the .Ic checkparity command, so rebuilding the parity blocks need only start at the location where @@ -1027,12 +1121,14 @@ If the .Fl f flag is specified, .Ic rebuildparity -starts rebuilding at the beginning of the plex. If the +starts rebuilding at the beginning of the plex. +If the .Fl v flag is specified, .Ic rebuildparity first checks the existing parity blocks prints information about those found to -be incorrect before rebuilding. If the +be incorrect before rebuilding. +If the .Fl V flag is specified, .Ic rebuildparity @@ -1044,7 +1140,8 @@ prints a running progress report. .Op Ar drive | subdisk | plex | volume .Ar newname .Xc -Change the name of the specified object. If the +Change the name of the specified object. +If the .Fl r option is specified, subordinate objects will be named by the default rules: plex names will be formed by appending @@ -1068,7 +1165,8 @@ The .Ic resetconfig command completely obliterates the .Nm -configuration on a system. Use this command only when you want to completely +configuration on a system. +Use this command only when you want to completely delete the configuration. .Nm will ask for confirmation; you must type in the words @@ -1086,7 +1184,8 @@ NO FUTURE Vinum configuration obliterated .Ed .Pp -As the message suggests, this is a last-ditch command. Don't use it unless you +As the message suggests, this is a last-ditch command. +Don't use it unless you have an existing configuration which you never want to see again. .Pp .It Xo @@ -1095,13 +1194,15 @@ have an existing configuration which you never want to see again. .Op Ar volume | plex | subdisk .Xc .Nm -maintains a number of statistical counters for each object. See the header file +maintains a number of statistical counters for each object. +See the header file .In sys/dev/vinumvar.h for more information. .\" XXX put it in here when it's finalized Use the .Ic resetstats -command to reset these counters. In conjunction with the +command to reset these counters. +In conjunction with the .Fl r option, .Nm @@ -1116,20 +1217,24 @@ also resets the counters of subordinate objects. .Ic rm removes an object from the .Nm -configuration. Once an object has been removed, there is no way to recover it. +configuration. +Once an object has been removed, there is no way to recover it. Normally .Nm -performs a large amount of consistency checking before removing an object. The +performs a large amount of consistency checking before removing an object. +The .Fl f option tells .Nm -to omit this checking and remove the object anyway. Use this option with great +to omit this checking and remove the object anyway. +Use this option with great care: it can result in total loss of data on a volume. .Pp Normally, .Nm refuses to remove a volume or plex if it has subordinate plexes or subdisks -respectively. You can tell +respectively. +You can tell .Nm to remove the object anyway by using the .Fl f @@ -1137,20 +1242,25 @@ option, or you can cause .Nm to remove the subordinate objects as well by using the .Fl r -(recursive) option. If you remove a volume with the +(recursive) option. +If you remove a volume with the .Fl r option, it will remove both the plexes and the subdisks which belong to the plexes. .Pp .It Ic saveconfig -Save the current configuration to disk. Normally this is not necessary, since +Save the current configuration to disk. +Normally this is not necessary, since .Nm -automatically saves any change in configuration. If an error occurs on startup, -updates will be disabled. When you reenable them with the +automatically saves any change in configuration. +If an error occurs on startup, +updates will be disabled. +When you reenable them with the .Ic setdaemon command, .Nm -does not automatically save the configuration to disk. Use this command to save +does not automatically save the configuration to disk. +Use this command to save the configuration. .\".Pp .\".It Xo @@ -1175,19 +1285,24 @@ the configuration. .Ic setdaemon sets a variable bitmask for the .Nm -daemon. This command is temporary and will be replaced. Currently, the bit mask +daemon. +This command is temporary and will be replaced. +Currently, the bit mask may contain the bits 1 (log every action to syslog) and 4 (don't update -configuration). Option bit 4 can be useful for error recovery. +configuration). +Option bit 4 can be useful for error recovery. .Pp .It Xo .Ic setstate Ar state .Op Ar volume | plex | subdisk | drive .Xc .Ic setstate -sets the state of the specified objects to the specified state. This bypasses +sets the state of the specified objects to the specified state. +This bypasses the usual consistency mechanism of .Nm -and should be used only for recovery purposes. It is possible to crash the +and should be used only for recovery purposes. +It is possible to crash the system by incorrect use of this command. .Pp .It Xo @@ -1210,7 +1325,8 @@ scans the disks known to the system for .Nm drives and then reads in the configuration as described under the .Ic read -commands. The +commands. +The .Nm drive contains a header with all information about the data stored on the drive, including the names of the other drives which are required in order to represent @@ -1219,19 +1335,24 @@ plexes and volumes. If .Nm encounters any errors during this command, it will turn off automatic -configuration update to avoid corrupting the copies on disk. This will also +configuration update to avoid corrupting the copies on disk. +This will also happen if the configuration on disk indicates a configuration error (for -example, subdisks which do not have a valid space specification). You can turn +example, subdisks which do not have a valid space specification). +You can turn the updates on again with the .Ic setdaemon and .Ic saveconfig -command. Reset bit 4 of the daemon options mask to re-enable configuration +command. +Reset bit 4 of the daemon options mask to re-enable configuration saves. .Pp If object names are specified, .Nm -starts them. Normally this operation is only of use with subdisks. The action +starts them. +Normally this operation is only of use with subdisks. +The action depends on the current state of the object: .Bl -bullet .It @@ -1253,15 +1374,18 @@ state. .It If the object is a subdisk in the .Em empty -state, the change depends on the subdisk. If it is part of a plex which is part +state, the change depends on the subdisk. +If it is part of a plex which is part of a volume which contains other plexes, .Nm places the subdisk in the .Em reviving -state and attempts to copy the data from the volume. When the operation +state and attempts to copy the data from the volume. +When the operation completes, the subdisk is set into the .Em up -state. If it is part of a plex which is part of a volume which contains no +state. +If it is part of a plex which is part of a volume which contains no other plexes, or if it is not part of a plex, .Nm brings it into the @@ -1273,7 +1397,8 @@ If the object is a subdisk in the state, .Nm continues the revive -operation offline. When the operation completes, the subdisk is set into the +operation offline. +When the operation completes, the subdisk is set into the .Em up state. .El @@ -1291,19 +1416,23 @@ checks the state of the subordinate subdisks (and plexes in the case of a volume) and starts any subdisks which can be started. .Pp To start a plex in a multi-plex volume, the data must be copied from another -plex in the volume. Since this frequently takes a long time, it is normally -done in the background. If you want to wait for this operation to complete (for +plex in the volume. +Since this frequently takes a long time, it is normally +done in the background. +If you want to wait for this operation to complete (for example, if you are performing this operation in a script), use the .Fl w option. .Pp Copying data doesn't just take a long time, it can also place a significant load -on the system. You can specify the transfer size in bytes or sectors with the +on the system. +You can specify the transfer size in bytes or sectors with the .Fl S option, and an interval (in milliseconds) to wait between copying each block with the .Fl i -option. Both of these options lessen the load on the system. +option. +Both of these options lessen the load on the system. .Pp .It Xo .Ic stop @@ -1316,14 +1445,17 @@ removes the .Nm kld and stops .Xr vinum 4 . -This can only be done if no objects are active. In particular, the +This can only be done if no objects are active. +In particular, the .Fl f -option does not override this requirement. Normally, the +option does not override this requirement. +Normally, the .Ic stop command writes the current configuration back to the drives before terminating. This will not be possible if configuration updates are disabled, so .Nm -will not stop if configuration updates are disabled. You can override this by +will not stop if configuration updates are disabled. +You can override this by specifying the .Fl f option. @@ -1341,25 +1473,31 @@ is statically configured. .Pp If object names are specified, .Ic stop -disables access to the objects. If the objects have subordinate objects, the +disables access to the objects. +If the objects have subordinate objects, the subordinate objects must either already be inactive (stopped or in error), or the .Fl r and .Fl f -options must be specified. This command does not remove the objects from the -configuration. They can be accessed again after a +options must be specified. +This command does not remove the objects from the +configuration. +They can be accessed again after a .Ic start command. .Pp By default, .Nm -does not stop active objects. For example, you cannot stop a plex which is -attached to an active volume, and you cannot stop a volume which is open. The +does not stop active objects. +For example, you cannot stop a plex which is +attached to an active volume, and you cannot stop a volume which is open. +The .Fl f option tells .Nm -to omit this checking and remove the object anyway. Use this option with great +to omit this checking and remove the object anyway. +Use this option with great care and understanding: used incorrectly, it can result in serious data corruption. .Pp @@ -1374,26 +1512,32 @@ The .Ic stripe command provides a simplified alternative to the .Ic create -command for creating volumes with a single striped plex. The size of the +command for creating volumes with a single striped plex. +The size of the subdisks is the size of the largest contiguous space available on all the -specified drives. The stripe size is fixed at 279 kB. +specified drives. +The stripe size is fixed at 279 kB. .Pp Normally, the .Ic stripe -command creates an arbitrary name for the volume and its components. The name +command creates an arbitrary name for the volume and its components. +The name is composed of the text .Dq Li vinum and a small integer, for example .Dq Li vinum3 . You can override this with the .Fl n Ar name -option, which assigns the name specified to the volume. The plexes and subdisks +option, which assigns the name specified to the volume. +The plexes and subdisks are named after the volume in the default manner. .Pp -There is no choice of name for the drives. If the drives have already been +There is no choice of name for the drives. +If the drives have already been initialized as .Nm -drives, the name remains. Otherwise the drives are given names starting with +drives, the name remains. +Otherwise the drives are given names starting with the text .Dq Li vinumdrive and a small integer, for example @@ -1402,7 +1546,8 @@ As with the .Ic create command, the .Fl f -option can be used to specify that a previous name should be overwritten. The +option can be used to specify that a previous name should be overwritten. +The .Fl v is used to specify verbose output. .Pp @@ -1419,21 +1564,26 @@ configuration using the .Ic mirror and .Ic stripe -commands. These commands create convenient configurations for some more normal +commands. +These commands create convenient configurations for some more normal situations, but they are not as flexible as the .Ic create command. .Pp -See above for the description of the commands. Here are some examples, all -performed with the same collection of disks. Note that the first drive, +See above for the description of the commands. +Here are some examples, all +performed with the same collection of disks. +Note that the first drive, .Pa /dev/da1h , -is smaller than the others. This has an effect on the sizes chosen for each +is smaller than the others. +This has an effect on the sizes chosen for each kind of subdisk. .Pp The following examples all use the .Fl v option to show the commands passed to the system, and also to list the structure -of the volume. Without the +of the volume. +Without the .Fl v option, these commands produce no output. .Ss Volume with a single concatenated plex @@ -1464,7 +1614,8 @@ In this case, the complete space on all four disks was used, giving a volume .Ss Volume with a single striped plex A volume with a single striped plex may give better performance than a concatenated plex, but restrictions on striped plexes can mean that the volume -is smaller. It will also not be resilient to a drive failure: +is smaller. +It will also not be resilient to a drive failure: .Bd -literal vinum -> stripe -v /dev/da1h /dev/da2h /dev/da3h /dev/da4h drive vinumdrive0 device /dev/da1h @@ -1514,7 +1665,8 @@ S vinum0.p0.s3 State: up D: vinumdrive3 Size: 414 MB This example specifies the name of the volume, .Ar mirror . Since one drive is smaller than the others, the two plexes are of different -size, and the last 158 MB of the volume is non-resilient. To ensure complete +size, and the last 158 MB of the volume is non-resilient. +To ensure complete reliability in such a situation, use the .Ic create command to create a volume with 988 MB. @@ -1551,7 +1703,8 @@ The .Nm utility requires that all parameters to the .Ic create -commands must be in a configuration file. Entries in the configuration file +commands must be in a configuration file. +Entries in the configuration file define volumes, plexes and subdisks, and may be in free format, except that each entry must be on a single line. .Ss Scale factors @@ -1573,7 +1726,8 @@ is used for compatibility with It stands for blocks of 512 bytes. This abbreviation is confusing, since the word .Dq block -is used in different meanings, and its use is deprecated. Use the keyword 's' +is used in different meanings, and its use is deprecated. +Use the keyword 's' instead. .El .Pp @@ -1586,7 +1740,8 @@ or The configuration file can contain the following entries: .Bl -tag -width 4n .It Ic drive Ar name devicename Op Ar options -Define a drive. The options are: +Define a drive. +The options are: .Bl -tag -width 18n .It Cm device Ar devicename Specify the device on which the drive resides. @@ -1607,8 +1762,10 @@ drive, which is maintained to automatically replace a failed drive. The .Nm utility -does not allow this drive to be used for any other purpose. In particular, it -is not possible to create subdisks on it. This functionality has not been +does not allow this drive to be used for any other purpose. +In particular, it +is not possible to create subdisks on it. +This functionality has not been completely implemented. .El .It Ic volume Ar name Op Ar options @@ -1617,7 +1774,8 @@ Define a volume with name Options are: .Bl -tag -width 18n .It Cm plex Ar plexname -Add the specified plex to the volume. If +Add the specified plex to the volume. +If .Ar plexname is specified as .Cm * , @@ -1635,30 +1793,37 @@ or .Cm prefer Ar plexname . The .Nm -utility satisfies a read request from only one of the plexes. A +utility satisfies a read request from only one of the plexes. +A .Cm round read policy specifies that each read should be performed from a different plex in .Em round-robin -fashion. A +fashion. +A .Cm prefer read policy reads from the specified plex every time. .It Cm setupstate When creating a multi-plex volume, assume that the contents of all the plexes -are consistent. This is normally not the case, so by default +are consistent. +This is normally not the case, so by default .Nm sets all plexes except the first one to the .Em faulty -state. Use the +state. +Use the .Ic start -command to first bring them to a consistent state. In the case of striped and +command to first bring them to a consistent state. +In the case of striped and concatenated plexes, however, it does not normally cause problems to leave them inconsistent: when using a volume for a file system or a swap partition, the previous contents of the disks are not of interest, so they may be ignored. If you want to take this risk, use the .Cm setupstate -keyword. It will only apply to the plexes defined immediately after the volume -in the configuration file. If you add plexes to a volume at a later time, you +keyword. +It will only apply to the plexes defined immediately after the volume +in the configuration file. +If you add plexes to a volume at a later time, you must integrate them manually with the .Ic start command. @@ -1671,11 +1836,13 @@ command with RAID-5 plexes: otherwise extreme data corruption will result if one subdisk fails. .El .It Ic plex Op Ar options -Define a plex. Unlike a volume, you do not need to specify a name for a plex. +Define a plex. +Unlike a volume, you do not need to specify a name for a plex. The options may be: .Bl -tag -width 18n .It Cm name Ar plexname -Specify the name of the plex. Note that you must use the keyword +Specify the name of the plex. +Note that you must use the keyword .Cm name when naming a plex or subdisk. .It Cm org Ar organization Op Ar stripesize @@ -1693,31 +1860,42 @@ plexes, the parameter .Ar stripesize must be specified, while for .Cm concat -it must be omitted. For type +it must be omitted. +For type .Cm striped , -it specifies the width of each stripe. For type +it specifies the width of each stripe. +For type .Cm raid5 , -it specifies the size of a group. A group is a portion of a plex which -stores the parity bits all in the same subdisk. It must be a factor of the plex size (in +it specifies the size of a group. +A group is a portion of a plex which +stores the parity bits all in the same subdisk. +It must be a factor of the plex size (in other words, the result of dividing the plex size by the stripe size must be an integer), and it must be a multiple of a disk sector (512 bytes). .Pp For optimum performance, stripes should be at least 128 kB in size: anything smaller will result in a significant increase in I/O activity due to mapping of -individual requests over multiple disks. The performance improvement due to the +individual requests over multiple disks. +The performance improvement due to the increased number of concurrent transfers caused by this mapping will not make up -for the performance drop due to the increase in latency. A good guideline for -stripe size is between 256 kB and 512 kB. Avoid powers of 2, however: they tend -to cause all superblocks to be placed on the first subdisk. The simplified +for the performance drop due to the increase in latency. +A good guideline for +stripe size is between 256 kB and 512 kB. +Avoid powers of 2, however: they tend +to cause all superblocks to be placed on the first subdisk. +The simplified commands use a stripe size of 279 kB, which shows a reasonable distribution of superblocks. .Pp A striped plex must have at least two subdisks (otherwise it is a concatenated -plex), and each must be the same size. A RAID-5 plex must have at least three -subdisks, and each must be the same size. In practice, a RAID-5 plex should +plex), and each must be the same size. +A RAID-5 plex must have at least three +subdisks, and each must be the same size. +In practice, a RAID-5 plex should have at least 5 subdisks. .It Cm volume Ar volname -Add the plex to the specified volume. If no +Add the plex to the specified volume. +If no .Cm volume keyword is specified, the plex will be added to the last volume mentioned in the configuration file. @@ -1726,28 +1904,35 @@ Add the specified subdisk to the plex at offset .Ar offset . .El .It Ic subdisk Op Ar options -Define a subdisk. Options may be: +Define a subdisk. +Options may be: .Bl -hang -width 18n .It Cm name Ar name -Specify the name of a subdisk. It is not necessary to specify a name for a +Specify the name of a subdisk. +It is not necessary to specify a name for a subdisk\(emsee .Sx OBJECT NAMING -above. Note that you must specify the keyword +above. +Note that you must specify the keyword .Cm name if you wish to name a subdisk. .It Cm plexoffset Ar offset -Specify the starting offset of the subdisk in the plex. If not specified, +Specify the starting offset of the subdisk in the plex. +If not specified, .Nm allocates the space immediately after the previous subdisk, if any, or otherwise at the beginning of the plex. .It Cm driveoffset Ar offset -Specify the starting offset of the subdisk in the drive. If not specified, +Specify the starting offset of the subdisk in the drive. +If not specified, .Nm allocates the first contiguous .Ar length bytes of free space on the drive. .It Cm length Ar length -Specify the length of the subdisk. This keyword must be specified. There is no +Specify the length of the subdisk. +This keyword must be specified. +There is no default, but the value 0 may be specified to mean .Dq "use the largest available contiguous free area on the drive" . If the drive is empty, this means that the entire drive will be used for the @@ -1756,14 +1941,17 @@ subdisk. may be shortened to .Cm len . .It Cm plex Ar plex -Specify the plex to which the subdisk belongs. By default, the subdisk belongs +Specify the plex to which the subdisk belongs. +By default, the subdisk belongs to the last plex specified. .It Cm drive Ar drive -Specify the drive on which the subdisk resides. By default, the subdisk resides +Specify the drive on which the subdisk resides. +By default, the subdisk resides on the last drive specified. .It Cm retryerrors Specify that the subdisk should not be taken down if an unrecoverable error -occurs. Normally +occurs. +Normally .Nm responds to an unrecoverable error by making the entire subdisk inaccessible. .El @@ -1821,11 +2009,14 @@ volume vol5 .Nm drives are currently .Bx -disk partitions. They must be of type +disk partitions. +They must be of type .Em vinum -in order to avoid overwriting data used for other purposes. Use +in order to avoid overwriting data used for other purposes. +Use .Nm disklabel Fl e -to edit a partition type definition. The following display shows a typical +to edit a partition type definition. +The following display shows a typical partition layout as shown by .Xr disklabel 8 : .Bd -literal @@ -1843,7 +2034,8 @@ In this example, partition .Dq Li g may be used as a .Nm -partition. Partitions +partition. +Partitions .Dq Li a , .Dq Li e and @@ -1852,7 +2044,8 @@ may be used as .Em UFS file systems or .Em ccd -partitions. Partition +partitions. +Partition .Dq Li b is a swap partition, and partition .Dq Li c @@ -1874,11 +2067,13 @@ You can override the name of this file by setting the environment variable .Ev VINUM_HISTORY to the name of the file. .Pp -Each message in the log file is preceded by a date. The default format is +Each message in the log file is preceded by a date. +The default format is .Qq Li %e %b %Y %H:%M:%S . See .Xr strftime 3 -for further details of the format string. It can be overridden by the +for further details of the format string. +It can be overridden by the environment variable .Ev VINUM_DATEFORMAT . .Sh HOW TO SET UP VINUM @@ -1886,7 +2081,8 @@ This section gives practical advice about how to implement a .Nm system. .Ss Where to put the data -The first choice you need to make is where to put the data. You need dedicated +The first choice you need to make is where to put the data. +You need dedicated disk partitions for .Nm . They should be partitions, not devices, and they should not be partition @@ -1909,11 +2105,13 @@ above. .Ss Designing volumes The way you set up .Nm -volumes depends on your intentions. There are a number of possibilities: +volumes depends on your intentions. +There are a number of possibilities: .Bl -enum .It You may want to join up a number of small disks to make a reasonable sized file -system. For example, if you had five small drives and wanted to use all the +system. +For example, if you had five small drives and wanted to use all the space for a single volume, you might write a configuration file like: .Bd -literal -offset indent drive d1 device /dev/da2e @@ -1937,13 +2135,15 @@ space. .It You want to set up .Nm -to obtain additional resilience against disk failures. You have the choice of +to obtain additional resilience against disk failures. +You have the choice of RAID-1, also called .Dq mirroring , or RAID-5, also called .Dq parity . .Pp -To set up mirroring, create multiple plexes in a volume. For example, to create +To set up mirroring, create multiple plexes in a volume. +For example, to create a mirrored volume of 2 GB, you might create the following configuration file: .Bd -literal -offset indent drive d1 device /dev/da2e @@ -1983,10 +2183,13 @@ volume raid .Ed .Pp RAID-5 plexes require at least three subdisks, one of which is used for storing -parity information and is lost for data storage. The more disks you use, the -greater the proportion of the disk storage can be used for data storage. In +parity information and is lost for data storage. +The more disks you use, the +greater the proportion of the disk storage can be used for data storage. +In this example, the total storage usage is 2.5 GB, compared to 4 GB for a mirrored -configuration. If you were to use the minimum of only three disks, you would +configuration. +If you were to use the minimum of only three disks, you would require 3 GB to store the information, for example: .Bd -literal -offset indent drive d1 device /dev/da2e @@ -2006,8 +2209,10 @@ can access the complete address space of the volume even if a drive fails. .It You want to set up .Nm -to allow more concurrent access to a file system. In many cases, access to a -file system is limited by the speed of the disk. By spreading the volume across +to allow more concurrent access to a file system. +In many cases, access to a +file system is limited by the speed of the disk. +By spreading the volume across multiple disks, you can increase the throughput in multi-access environments. This technique shows little or no performance improvement in single-access environments. @@ -2015,7 +2220,8 @@ The .Nm utility uses a technique called .Dq striping , -or sometimes RAID-0, to increase this concurrency of access. The name RAID-0 is +or sometimes RAID-0, to increase this concurrency of access. +The name RAID-0 is misleading: striping does not provide any redundancy or additional reliability. In fact, it decreases the reliability, since the failure of a single disk will render the volume useless, and the more disks you have, the more likely it is @@ -2041,8 +2247,10 @@ A striped plex must have at least two subdisks, but the increase in performance is greater if you have a larger number of disks. .It You may want to have the best of both worlds and have both resilience and -performance. This is sometimes called RAID-10 (a combination of RAID-1 and -RAID-0), though again this name is misleading. With +performance. +This is sometimes called RAID-10 (a combination of RAID-1 and +RAID-0), though again this name is misleading. +With .Nm you can do this with the following configuration file: .Bd -literal -offset indent @@ -2064,9 +2272,12 @@ volume raid setupstate .Ed .Pp Here the plexes are striped, increasing performance, and there are two of them, -increasing reliability. Note that this example shows the subdisks of the second -plex in reverse order from the first plex. This is for performance reasons and -will be discussed below. In addition, the volume specification includes the +increasing reliability. +Note that this example shows the subdisks of the second +plex in reverse order from the first plex. +This is for performance reasons and +will be discussed below. +In addition, the volume specification includes the keyword .Cm setupstate , which ensures that all plexes are @@ -2076,7 +2287,8 @@ after creation. .Ss Creating the volumes Once you have created your configuration files, start .Nm -and create the volumes. In this example, the configuration is in the file +and create the volumes. +In this example, the configuration is in the file .Pa configfile : .Bd -literal -offset 2n # vinum create -v configfile @@ -2143,7 +2355,8 @@ The .Fl v option tells .Nm -to list the file as it configures. Subsequently it lists the current +to list the file as it configures. +Subsequently it lists the current configuration in the same format as the .Ic list Fl v command. @@ -2152,8 +2365,10 @@ Once you have created the .Nm volumes, .Nm -keeps track of them in its internal configuration files. You do not need to -create them again. In particular, if you run the +keeps track of them in its internal configuration files. +You do not need to +create them again. +In particular, if you run the .Ic create command again, you will create additional objects: .Bd -literal @@ -2185,11 +2400,14 @@ As this example (this time with the .Fl f option) shows, re-running the .Ic create -has created four new plexes, each with a new subdisk. If you want to add other -volumes, create new configuration files for them. They do not need to reference +has created four new plexes, each with a new subdisk. +If you want to add other +volumes, create new configuration files for them. +They do not need to reference the drives that .Nm -already knows about. For example, to create a volume +already knows about. +For example, to create a volume .Pa raid on the four drives .Pa /dev/da1e , /dev/da2e , /dev/da3e @@ -2242,7 +2460,8 @@ S raid.p0.s3 State: empty PO: 1299 kB Size: 2048 MB .Ed .Pp Note the size of the RAID-5 plex: it is only 6 GB, although together its -components use 8 GB of disk space. This is because the equivalent of one +components use 8 GB of disk space. +This is because the equivalent of one subdisk is used for storing parity data. .Ss Restarting Vinum On rebooting the system, start @@ -2255,22 +2474,27 @@ command: .Pp This will start all the .Nm -drives in the system. If for some reason you wish to start only some of them, +drives in the system. +If for some reason you wish to start only some of them, use the .Ic read command. .Ss Performance considerations A number of misconceptions exist about how to set up a RAID array for best -performance. In particular, most systems use far too small a stripe size. The +performance. +In particular, most systems use far too small a stripe size. +The following discussion applies to all RAID systems, not just to .Nm . .Pp The .Fx block I/O system issues requests of between .5kB and 128 kB; a -typical mix is somewhere round 8 kB. You can't stop any striping system from +typical mix is somewhere round 8 kB. +You can't stop any striping system from breaking a request into two physical requests, and if you make the stripe small -enough, it can be broken into several. This will result in a significant drop +enough, it can be broken into several. +This will result in a significant drop in performance: the decrease in transfer time per disk is offset by the order of magnitude greater increase in latency. .Pp @@ -2282,7 +2506,8 @@ and 512 kB; with correct RAID implementations there is no obvious reason not to increase the size to 2 or 4 MB on a large disk. .Pp When choosing a stripe size, consider that most current UFS file systems have -cylinder groups 32 MB in size. If you have a stripe size and number of disks +cylinder groups 32 MB in size. +If you have a stripe size and number of disks both of which are a power of two, it is probable that all superblocks and inodes will be placed on the same subdisk, which will impact performance significantly. Choose an odd number instead, for example 479 kB. @@ -2294,35 +2519,51 @@ Since just about everything is cached, the time relationship between the request and its completion is not so important: the important parameter is the total time that the request keeps the disks active, the time when the disks are not available to -perform other transfers. As a result, it doesn't really matter if the transfers -are happening at the same time or different times. In practical terms, the time +perform other transfers. +As a result, it doesn't really matter if the transfers +are happening at the same time or different times. +In practical terms, the time we're looking at is the sum of the total latency (positioning time and rotational latency, or the time it takes for the data to arrive under the disk -heads) and the total transfer time. For a given transfer to disks of the same +heads) and the total transfer time. +For a given transfer to disks of the same speed, the transfer time depends only on the total size of the transfer. .Pp Consider a typical news article or web page of 24 kB, which will probably be -read in a single I/O. Take disks with a transfer rate of 6 MB/s and an average -positioning time of 8 ms, and a file system with 4 kB blocks. Since it's 24 kB, +read in a single I/O. +Take disks with a transfer rate of 6 MB/s and an average +positioning time of 8 ms, and a file system with 4 kB blocks. +Since it's 24 kB, we don't have to worry about fragments, so the file will start on a 4 kB -boundary. The number of transfers required depends on where the block starts: +boundary. +The number of transfers required depends on where the block starts: it's (S + F - 1) / S, where S is the stripe size in file system blocks, and F is the file size in file system blocks. .Bl -enum .It -Stripe size of 4 kB. You'll have 6 transfers. Total subsystem load: 48 ms +Stripe size of 4 kB. +You'll have 6 transfers. +Total subsystem load: 48 ms latency, 2 ms transfer, 50 ms total. .It -Stripe size of 8 kB. On average, you'll have 3.5 transfers. Total subsystem +Stripe size of 8 kB. +On average, you'll have 3.5 transfers. +Total subsystem load: 28 ms latency, 2 ms transfer, 30 ms total. .It -Stripe size of 16 kB. On average, you'll have 2.25 transfers. Total subsystem +Stripe size of 16 kB. +On average, you'll have 2.25 transfers. +Total subsystem load: 18 ms latency, 2 ms transfer, 20 ms total. .It -Stripe size of 256 kB. On average, you'll have 1.08 transfers. Total subsystem +Stripe size of 256 kB. +On average, you'll have 1.08 transfers. +Total subsystem load: 8.6 ms latency, 2 ms transfer, 10.6 ms total. .It -Stripe size of 4 MB. On average, you'll have 1.0009 transfers. Total subsystem +Stripe size of 4 MB. +On average, you'll have 1.0009 transfers. +Total subsystem load: 8.01 ms latency, 2 ms transfer, 10.01 ms total. .El .Pp @@ -2349,7 +2590,8 @@ chance of individual requests being on different drives. .It Concatenating UFS file systems across multiple drives can also improve performance for multiple file access, since UFS divides a file system into -cylinder groups and attempts to keep files in a single cylinder group. In +cylinder groups and attempts to keep files in a single cylinder group. +In general, it is not as effective as striping. .It Mirroring can improve multi-access performance for reads, since by default @@ -2357,7 +2599,8 @@ Mirroring can improve multi-access performance for reads, since by default issues consecutive reads to consecutive plexes. .It Mirroring decreases performance for all writes, whether multi-access or single -access, since the data must be written to both plexes. This explains the +access, since the data must be written to both plexes. +This explains the subdisk layout in the example of a mirroring configuration above: if the corresponding subdisk in each plex is on a different physical disk, the write commands can be issued in parallel, whereas if they are on the same physical @@ -2372,7 +2615,8 @@ the write, .Nm must first read the data block and the corresponding parity block, perform some calculations and write back the parity block and the data block, four times as -many transfers as for writing a striped plex. On the other hand, this is offset +many transfers as for writing a striped plex. +On the other hand, this is offset by the cost of mirroring, so writes to a volume with a single RAID-5 plex are approximately half the speed of writes to a correctly configured volume with two striped plexes. @@ -2382,7 +2626,8 @@ When the configuration changes (for example, adding or removing objects, or the change of state of one of the objects), .Nm -writes up to 128 kB of updated configuration to each drive. The larger the +writes up to 128 kB of updated configuration to each drive. +The larger the number of drives, the longer this takes. .El .Ss Creating file systems on Vinum volumes @@ -2390,11 +2635,13 @@ You do not need to run .Xr disklabel 8 before creating a file system on a .Nm -volume. Just run +volume. +Just run .Xr newfs 8 . Use the .Fl v -option to state that the device is not divided into partitions. For example, to +option to state that the device is not divided into partitions. +For example, to create a file system on volume .Pa mirror , enter the following command: @@ -2406,9 +2653,11 @@ A number of other considerations apply to configuration: .Bl -bullet .It -There is no advantage in creating multiple drives on a single disk. Each drive +There is no advantage in creating multiple drives on a single disk. +Each drive uses 131.5 kB of data for label and configuration information, and performance -will suffer when the configuration changes. Use appropriately sized subdisks instead. +will suffer when the configuration changes. +Use appropriately sized subdisks instead. .It It is possible to increase the size of a concatenated .Nm @@ -2421,34 +2670,43 @@ Vinum objects have the concept of .Em state . See .Xr vinum 4 -for more details. They are only completely accessible if their state is +for more details. +They are only completely accessible if their state is .Em up . To change an object state to .Em up , use the .Ic start -command. To change an object state to +command. +To change an object state to .Em down , use the .Ic stop -command. Normally other states are created automatically by the relationship -between objects. For example, if you add a plex to a volume, the subdisks of +command. +Normally other states are created automatically by the relationship +between objects. +For example, if you add a plex to a volume, the subdisks of the plex will be set in the .Em empty state, indicating that, though the hardware is accessible, the data on the -subdisk is invalid. As a result of this state, the plex will be set in the +subdisk is invalid. +As a result of this state, the plex will be set in the .Em faulty state. .Ss The `reviving' state In many cases, when you start a subdisk the system must copy data to the -subdisk. Depending on the size of the subdisk, this can take a long time. +subdisk. +Depending on the size of the subdisk, this can take a long time. During this time, the subdisk is set in the .Em reviving -state. On successful completion of the copy operation, it is automatically set +state. +On successful completion of the copy operation, it is automatically set to the .Em up -state. It is possible for the process performing the revive to be stopped and -restarted. The system keeps track of how far the subdisk has been revived, and +state. +It is possible for the process performing the revive to be stopped and +restarted. +The system keeps track of how far the subdisk has been revived, and when the .Ic start command is reissued, the copying continues from this point. @@ -2456,11 +2714,13 @@ command is reissued, the copying continues from this point. In order to maintain the consistency of a volume while one or more of its plexes is being revived, .Nm -writes to subdisks which have been revived up to the point of the write. It may +writes to subdisks which have been revived up to the point of the write. +It may also read from the plex if the area being read has already been revived. .Sh GOTCHAS The following points are not bugs, and they have good reasons for existing, but -they have shown to cause confusion. Each is discussed in the appropriate +they have shown to cause confusion. +Each is discussed in the appropriate section above. .Bl -enum .It @@ -2496,8 +2756,10 @@ partition. .It When you create a volume with multiple plexes, .Nm -does not automatically initialize the plexes. This means that the contents are -not known, but they are certainly not consistent. As a result, by default +does not automatically initialize the plexes. +This means that the contents are +not known, but they are certainly not consistent. +As a result, by default .Nm sets the state of all newly-created plexes except the first to .Em faulty . @@ -2507,7 +2769,8 @@ them, which causes .Nm to copy the data from a plex which is in the .Em up -state. Depending on the size of the subdisks involved, this can take a long +state. +Depending on the size of the subdisks involved, this can take a long time. .Pp In practice, people aren't too interested in what was in the plex when it was @@ -2533,18 +2796,22 @@ to ignore any possible inconsistency and set the plexes to be .It Some of the commands currently supported by .Nm -are not really needed. For reasons which I don't understand, however, I find +are not really needed. +For reasons which I don't understand, however, I find that users frequently try the .Ic label and .Ic resetconfig commands, though especially .Ic resetconfig -outputs all sort of dire warnings. Don't use these commands unless you have a +outputs all sort of dire warnings. +Don't use these commands unless you have a good reason to do so. .It -Some state transitions are not very intuitive. In fact, it's not clear whether -this is a bug or a feature. If you find that you can't start an object in some +Some state transitions are not very intuitive. +In fact, it's not clear whether +this is a bug or a feature. +If you find that you can't start an object in some strange state, such as a .Em reborn subdisk, try first to get it into @@ -2553,7 +2820,9 @@ state, with the .Ic stop or .Ic stop Fl f -commands. If that works, you should then be able to start it. If you find +commands. +If that works, you should then be able to start it. +If you find that this is the only way to get out of a position where easier methods fail, please report the situation. .It @@ -2564,17 +2833,20 @@ option, you must also build with the .Fl D Ns Dv VINUMDEBUG option, since the size of some data objects used by both components depends on -this option. If you don't do so, commands will fail with a corresponding error +this option. +If you don't do so, commands will fail with a corresponding error message. .It The .Nm Ic read -command has a particularly emetic syntax. Once it was the only way to start +command has a particularly emetic syntax. +Once it was the only way to start .Nm , but now the preferred method is with .Nm Ic start . .Nm Ic read -should be used for maintenance purposes only. Note that its syntax has changed, +should be used for maintenance purposes only. +Note that its syntax has changed, and the arguments must be disk slices, such as .Pa /dev/da0 , not partitions such as |
