Index: head/sbin/bsdlabel/bsdlabel.8 =================================================================== --- head/sbin/bsdlabel/bsdlabel.8 (revision 162394) +++ head/sbin/bsdlabel/bsdlabel.8 (revision 162395) @@ -1,507 +1,507 @@ .\" Copyright (c) 1987, 1988, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Symmetric Computer Systems. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)disklabel.8 8.2 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" -.Dd September 17, 2005 +.Dd March 8, 2006 .Dt BSDLABEL 8 .Os .Sh NAME .Nm bsdlabel .Nd read and write disk pack label .Sh SYNOPSIS .Nm .Op Fl A .Ar disk | Fl f Ar file .Nm .Fl w .Op Fl \&An .Op Fl B Op Fl b Ar boot .Op Fl m Ar machine .Ar disk | Fl f Ar file .Op Ar type .Nm .Fl e .Op Fl \&An .Op Fl B Op Fl b Ar boot .Op Fl m Ar machine .Ar disk | Fl f Ar file .Nm .Fl R .Op Fl \&An .Op Fl B Op Fl b Ar boot .Op Fl m Ar machine .Op Fl f .Ar disk | Fl f Ar file .Ar protofile .Sh DESCRIPTION The .Nm utility installs, examines or modifies the .Bx label on a disk partition, or on a file containing a partition image. In addition, .Nm can install bootstrap code. .Ss Disk Device Name When specifying the device (i.e., when the .Fl f option is not used), the .Pa /dev/ path prefix may be omitted; the .Nm utility will automatically prepend it. .Ss General Options The .Fl A option enables processing of the historical parts of the .Bx label. If the option is not given, suitable values are set for these fields. .Pp The .Fl f option tells .Nm that the program will operate on a file instead of a disk partition. .Pp The .Fl n option stops the .Nm program right before the disk would have been modified, and displays the result instead of writing it. .Pp The .Fl m Ar machine argument forces .Nm to use a layout suitable for a different architecture. Current valid values are .Cm i386 , amd64 , ia64 , pc98 , and .Cm alpha . If this option is omitted, .Nm will use a layout suitable for the current machine. .Ss Reading the Disk Label To examine the label on a disk drive, use .Nm without options: .Pp .Nm .Op Fl A .Op Fl m Ar machine .Ar disk .Pp .Ar disk represents the disk in question, and may be in the form .Pa da0 or .Pa /dev/da0 . It will display the partition layout. .Ss Writing a Standard Label To write a standard label, use the form .Pp .Nm .Fl w .Op Fl \&An .Op Fl m Ar machine .Ar disk .Op Ar type .Pp If the drive type is specified, the entry of that name in the .Xr disktab 5 file is used; otherwise a default layout is used. .Ss Editing an Existing Disk Label To edit an existing disk label, use the form .Pp .Nm .Fl e .Op Fl \&An .Op Fl m Ar machine .Ar disk .Pp This command opens the disk label in the default editor, and when the editor exits, the label is validated and if OK written to disk. .Ss Restoring a Disk Label From a File To restore a disk label from a file, use the form .Pp .Nm .Fl R .Op Fl \&An .Op Fl m Ar machine .Ar disk protofile .Pp .Nm is capable of restoring a disk label that was previously saved in a file in .Tn ASCII format. The prototype file used to create the label should be in the same format as that produced when reading or editing a label. Comments are delimited by .Ql # and newline. .Ss Installing Bootstraps If the .Fl B argument is specified, bootstrap code will be read from the file .Pa /boot/boot and written to the disk. The .Fl b Ar boot argument allows a different file to be used. .Sh FILES .Bl -tag -width ".Pa /etc/disktab" -compact .It Pa /boot/boot Default boot image. .It Pa /etc/disktab Disk description file. .El .Sh SAVED FILE FORMAT The .Nm utility uses an .Tn ASCII version of the label when examining, editing, or restoring a disk label. The format is: .Bd -literal -offset 4n 8 partitions: # size offset fstype [fsize bsize bps/cpg] a: 81920 16 4.2BSD 1024 8192 16 b: 160000 81936 swap c: 1173930 0 unused 0 0 # "raw" part, don't edit .Ed .Pp If the .Fl A option is specified, the format is: .Bd -literal -offset 4n # /dev/da1c: type: SCSI disk: da0s1 label: flags: bytes/sector: 512 sectors/track: 51 tracks/cylinder: 19 sectors/cylinder: 969 cylinders: 1211 sectors/unit: 1173930 rpm: 3600 interleave: 1 trackskew: 0 cylinderskew: 0 headswitch: 0 # milliseconds track-to-track seek: 0 # milliseconds drivedata: 0 8 partitions: # size offset fstype [fsize bsize bps/cpg] a: 81920 16 4.2BSD 1024 8192 16 b: 160000 81936 swap c: 1173930 0 unused 0 0 # "raw" part, don't edit .Ed .Pp Lines starting with a .Ql # mark are comments. .Pp The partition table can have up to 8 entries. It contains the following information: .Bl -tag -width indent .It Ar # The partition identifier is a single letter in the range .Ql a to .Ql h . By convention, partition .Ql c is reserved to describe the entire disk. .It Ar size The size of the partition in sectors, .Cm K (kilobytes - 1024), .Cm M (megabytes - 1024*1024), .Cm G (gigabytes - 1024*1024*1024), .Cm % (percentage of free space .Em after removing any fixed-size partitions other than partition .Ql c ) , or .Cm * (all remaining free space .Em after fixed-size and percentage partitions). For partition .Ql c , a size of .Cm * indicates the entire disk. Lowercase versions of .Cm K , M , and .Cm G are allowed. Size and type should be specified without any spaces between them. .Pp Example: 2097152, 1G, 1024M and 1048576K are all the same size (assuming 512-byte sectors). .It Ar offset The offset of the start of the partition from the beginning of the drive in sectors, or .Cm * to have .Nm calculate the correct offset to use (the end of the previous partition plus one, ignoring partition .Ql c . For partition .Ql c , .Cm * will be interpreted as an offset of 0. The first partition should start at offset 16, because the first 16 sectors are reserved for metadata. .It Ar fstype Describes the purpose of the partition. The example shows all currently used partition types. For .Tn UFS file systems and .Xr ccd 4 partitions, use type .Cm 4.2BSD . For Vinum drives, use type .Cm vinum . Other common types are .Cm swap and .Cm unused . By convention, partition .Ql c represents the entire slice and should be of type .Cm unused , though .Nm does not enforce this convention. The .Nm utility also knows about a number of other partition types, none of which are in current use. (See the definitions starting with .Dv FS_UNUSED in .In sys/disklabel.h for more details.) .It Ar fsize For .Cm 4.2BSD and .Tn LFS file systems only, the fragment size. Defaults to 1024 for partitions smaller than 1GB, 4096 for partitions 1GB or larger. .It Ar bsize For .Cm 4.2BSD and .Tn LFS file systems only, the block size. Defaults to 8192 for partitions smaller than 1GB, 16384 for partitions 1GB or larger. .It Ar bps/cpg For .Cm 4.2BSD file systems, the number of cylinders in a cylinder group. For .Tn LFS file systems, the segment shift value. Defaults to 16 for partitions smaller than 1GB, 64 for partitions 1GB or larger. .El .Sh EXAMPLES .Dl "bsdlabel da0s1" .Pp Display the label for the first slice of the .Pa da0 disk, as obtained via .Pa /dev/da0s1 . .Pp .Dl "bsdlabel da0s1 > savedlabel" .Pp Save the in-core label for .Pa da0s1 into the file .Pa savedlabel . This file can be used with the .Fl R option to restore the label at a later date. .Pp .Dl "bsdlabel -w /dev/da0s1" .Pp Create a label for .Pa da0s1 . .Pp .Dl "bsdlabel -e da0s1" .Pp Read the label for .Pa da0s1 , edit it, and install the result. .Pp .Dl "bsdlabel -e -n da0s1" .Pp Read the on-disk label for .Pa da0s1 , edit it, and display what the new label would be (in sectors). It does .Em not install the new label either in-core or on-disk. .Pp .Dl "bsdlabel -w da0s1" .Pp Write a default label on .Pa da0s1 . Use another .Nm Fl e command to edit the partitioning and file system information. .Pp .Dl "bsdlabel -R da0s1 savedlabel" .Pp Restore the on-disk and in-core label for .Pa da0s1 from information in .Pa savedlabel . .Pp .Dl "bsdlabel -R -n da0s1 label_layout" .Pp Display what the label would be for .Pa da0s1 using the partition layout in .Pa label_layout . This is useful for determining how much space would be allotted for various partitions with a labeling scheme using .Cm % Ns -based or .Cm * partition sizes. .Pp .Dl "bsdlabel -B da0s1" .Pp Install a new bootstrap on .Pa da0s1 . The boot code comes from .Pa /boot/boot . .Pp .Dl "bsdlabel -w -B -b newboot /dev/da0s1" .Pp Install a new label and bootstrap. The bootstrap code comes from the file .Pa newboot in the current working directory. .Bd -literal -offset indent dd if=/dev/zero of=/dev/da0 bs=512 count=32 fdisk -BI da0 dd if=/dev/zero of=/dev/da0s1 bs=512 count=32 bsdlabel -w -B da0s1 bsdlabel -e da0s1 .Ed .Pp Completely wipe any prior information on the disk, creating a new bootable disk with a .Tn DOS partition table containing one slice, covering the whole disk. Initialize the label on this slice, then edit it. The .Xr dd 1 commands are optional, but may be necessary for some .Tn BIOS Ns es to properly recognize the disk. .Pp This is an example disk label that uses some of the new partition size types such as .Cm % , M , G , and .Cm * , which could be used as a source file for .Dq Li "bsdlabel -R ad0s1c new_label_file" : .Bd -literal -offset 4n # /dev/ad0s1c: 8 partitions: # size offset fstype [fsize bsize bps/cpg] a: 400M 16 4.2BSD 4096 16384 75 # (Cyl. 0 - 812*) b: 1G * swap c: * * unused e: 204800 * 4.2BSD f: 5g * 4.2BSD g: * * 4.2BSD .Ed .Sh DIAGNOSTICS The kernel device drivers will not allow the size of a disk partition to be decreased or the offset of a partition to be changed while it is open. .Sh COMPATIBILITY Due to the use of an .Vt u_int32_t to store the number of sectors, .Bx labels are restricted to a maximum of 2^32-1 sectors. This usually means 2TB of disk space. Larger disks should be partitioned using another method such as .Xr gpt 8 . .Pp The various .Bx Ns s all use slightly different versions of .Bx labels and are not generally compatible. .Sh SEE ALSO .Xr ccd 4 , .Xr geom 4 , .Xr md 4 , .\" Xr bsdlabel 5 , .Xr disktab 5 , .Xr boot0cfg 8 , .Xr fdisk 8 , .Xr gpt 8 Index: head/sbin/camcontrol/camcontrol.8 =================================================================== --- head/sbin/camcontrol/camcontrol.8 (revision 162394) +++ head/sbin/camcontrol/camcontrol.8 (revision 162395) @@ -1,923 +1,923 @@ .\" .\" Copyright (c) 1998, 1999, 2000, 2002, 2005, 2006 Kenneth D. Merry. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd September 14, 1998 +.Dd August 21, 2006 .Dt CAMCONTROL 8 .Os .Sh NAME .Nm camcontrol .Nd CAM control program .Sh SYNOPSIS .Nm .Aq Ar command .Op device id .Op generic args .Op command args .Nm .Ic devlist .Op Fl v .Nm .Ic periphlist .Op device id .Op Fl n Ar dev_name .Op Fl u Ar unit_number .Nm .Ic tur .Op device id .Op generic args .Nm .Ic inquiry .Op device id .Op generic args .Op Fl D .Op Fl S .Op Fl R .Nm .Ic reportluns .Op device id .Op generic args .Op Fl c .Op Fl l .Op Fl r Ar reporttype .Nm .Ic start .Op device id .Op generic args .Nm .Ic stop .Op device id .Op generic args .Nm .Ic load .Op device id .Op generic args .Nm .Ic eject .Op device id .Op generic args .Nm .Ic rescan .Aq all | bus Ns Op :target:lun .Nm .Ic reset .Aq all | bus Ns Op :target:lun .Nm .Ic defects .Op device id .Op generic args .Aq Fl f Ar format .Op Fl P .Op Fl G .Nm .Ic modepage .Op device id .Op generic args .Aq Fl m Ar page | Fl l .Op Fl P Ar pgctl .Op Fl b | Fl e .Op Fl d .Nm .Ic cmd .Op device id .Op generic args .Aq Fl c Ar cmd Op args .Op Fl i Ar len Ar fmt .Bk -words .Op Fl o Ar len Ar fmt Op args .Ek .Nm .Ic debug .Op Fl I .Op Fl P .Op Fl T .Op Fl S .Op Fl X .Op Fl c .Aq all|off|bus Ns Op :target Ns Op :lun .Nm .Ic tags .Op device id .Op generic args .Op Fl N Ar tags .Op Fl q .Op Fl v .Nm .Ic negotiate .Op device id .Op generic args .Op Fl c .Op Fl D Ar enable|disable .Op Fl O Ar offset .Op Fl q .Op Fl R Ar syncrate .Op Fl T Ar enable|disable .Op Fl U .Op Fl W Ar bus_width .Op Fl v .Nm .Ic format .Op device id .Op generic args .Op Fl q .Op Fl r .Op Fl w .Op Fl y .Nm .Ic help .Sh DESCRIPTION The .Nm utility is designed to provide a way for users to access and control the .Fx CAM subsystem. .Pp The .Nm utility 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: .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 .Em not allowed here. .It bus:target 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) .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 .Fl n and .Fl u arguments described below will override any device name or unit number specified beforehand. The .Fl n and .Fl u arguments will .Em not override a specified bus:target or bus:target:lun, however. .Pp Most of the .Nm 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 .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 .Pq Fl C 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". .It Fl t Ar timeout 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". .It Fl v Be verbose, print out sense information for failed SCSI commands. .El .Pp Primary command functions: .Bl -tag -width periphlist .It Ic devlist List all physical devices (logical units) attached to the CAM subsystem. This also includes a list of peripheral drivers attached to each device. With the .Fl v argument, SCSI bus number, adapter name and unit numbers are printed as well. .It Ic periphlist List all peripheral drivers attached to a given physical device (logical unit). .It Ic tur Send the SCSI test unit ready (0x00) command to the given device. 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, .Nm will print out the standard inquiry data, device serial number, and 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, .Nm will not print out "Serial Number" before the value returned by the drive. This is to aid in script writing. .It Fl R Print out transfer rate information. .El .It Ic reportluns Send the SCSI REPORT LUNS (0xA0) command to the given device. By default, .Nm will print out the list of logical units (LUNs) supported by the target device. There are a couple of options to modify the output: -.Bl -tag -width 01234567890123 +.Bl -tag -width 14n .It Fl c Just print out a count of LUNs, not the actual LUN numbers. .It Fl l Just print out the LUNs, and don't print out the count. .It Fl r Ar reporttype Specify the type of report to request from the target: .Bl -tag -width 012345678 .It default Return the default report. This is the .Nm default. Most targets will support this report if they support the REPORT LUNS command. .It wellknown Return only well known LUNs. .It all Return all available LUNs. .El .El .Pp .Nm will try to print out LUN numbers in a reasonable format. It can understand the peripheral, flat, LUN and extended LUN formats. .It Ic start Send the SCSI Start/Stop Unit (0x1B) command to the given device with the start bit set. .It Ic stop Send the SCSI Start/Stop Unit (0x1B) command to the given device with the start bit cleared. .It Ic load Send the SCSI Start/Stop Unit (0x1B) command to the given device with the start bit set and the load/eject bit set. .It Ic eject Send the SCSI Start/Stop Unit (0x1B) command to the given device with the start bit cleared and the load/eject bit set. .It Ic rescan 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 on a target is not supported. .It Ic reset Tell the kernel to reset all busses in the system (with the .Ar all argument) or the given bus (XPT_RESET_BUS) by issuing a SCSI bus reset for that bus, or to reset the given bus:target:lun (XPT_RESET_DEV), typically by issuing a BUS DEVICE RESET message after connecting to that device. Note that this can have a destructive impact on the system. .It Ic defects Send the SCSI READ DEFECT DATA (10) command (0x37) to the given device, and print out any combination of: the total number of defects, the primary defect list (PLIST), and the grown defect list (GLIST). .Bl -tag -width 11n .It Fl f Ar format The three format options are: .Em block , 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 do not support the requested format, return the data in an alternate format, along with sense information indicating that the requested data format is not supported. The .Nm utility attempts to detect this, and print out whatever format the drive returns. If the drive uses a non-standard sense code to report that it does not 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 been remapped since the disk left the factory. .It Fl P Print out the primary defect list. .El .Pp If neither .Fl P nor .Fl G is specified, .Nm 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 page formats are located in .Pa /usr/share/misc/scsi_modes . This can be overridden by specifying a different file in the .Ev SCSI_MODES environment variable. The .Ic modepage command takes several arguments: .Bl -tag -width 12n .It Fl d 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 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 .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 .Fl l is specified. .It Fl P Ar pgctl This allows the user to specify the page control field. Possible values are: .Bl -tag -width xxx -compact .It 0 Current values .It 1 Changeable values .It 2 Default values .It 3 Saved values .El .El .It Ic cmd Allows the user to send an arbitrary SCSI CDB to any device. 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 in .Xr cam_cdbparse 3 . NOTE: If the CDB specified causes data to be transfered to or from the SCSI device in question, you MUST specify either .Fl i 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. .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 .Sq - , .Ar len 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 .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 turning off the debugging printfs once they start, since the kernel will be busy printing messages and unable to service other requests quickly. The .Ic debug function takes a number of arguments: .Bl -tag -width 18n .It Fl I Enable CAM_DEBUG_INFO printfs. .It Fl P Enable CAM_DEBUG_PERIPH printfs. .It Fl T Enable CAM_DEBUG_TRACE printfs. .It Fl S 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 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 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 .Ic tags 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 .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 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 determined by using the .Fl v switch. The meaning of the .Fl v switch for this .Nm subcommand is described below. .It Fl q Be quiet, and do not 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 .Nm to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB: .Bl -tag -width 13n .It dev_openings 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 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 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 device. .It mintags This is the current "hard" minimum number of transactions that can be queued to a device at once. The .Ar dev_openings 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 .Ar dev_openings 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 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 supports, use the .Fl v flag. The meaning of the .Fl v flag for the .Ic negotiate command is described below. Also, some controller drivers do not support setting negotiation parameters, even if the underlying controller supports 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 .It Fl a 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. .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, do not print anything. This is generally useful when you want to set a parameter, but do not 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, .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 current negotiation settings. .It Fl v The verbose switch has special meaning for the .Ic negotiate 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 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 .Fl a switch above will automatically send a Test Unit Ready to the device so negotiation parameters will take effect. .It Ic format Issue the .Tn SCSI 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 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 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 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 does not 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 .Fl q and .Fl y arguments can be useful for scripts. .Pp .Bl -tag -width 6n .It Fl q Be quiet, do not print any status messages. This option will not disable the questions, however. To disable questions, use the .Fl y argument, below. .It Fl r Run in .Dq report only mode. This will report status on a format that is already running on the drive. .It Fl w Issue a non-immediate format command. By default, .Nm 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, .Nm gathers .Tn SCSI sense information from the device every second to determine how far along in the format process it is. If the .Fl w argument is specified, .Nm 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 Do not 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 will not be asked about the timeout if a timeout is specified on the command line. .El .It Ic help Print out verbose usage information. .El .Sh ENVIRONMENT The .Ev SCSI_MODES variable allows the user to specify an alternate mode page format file. .Pp The .Ev EDITOR variable determines which text editor .Nm starts when editing mode pages. .Sh FILES .Bl -tag -width /usr/share/misc/scsi_modes -compact .It Pa /usr/share/misc/scsi_modes is the SCSI mode format database. .It Pa /dev/xpt0 is the transport layer device. .It Pa /dev/pass* are the CAM application passthrough devices. .El .Sh EXAMPLES .Dl camcontrol eject -n cd -u 1 -v .Pp Eject the CD from cd1, and print SCSI sense information if the command fails. .Pp .Dl camcontrol tur da0 .Pp Send the SCSI test unit ready command to da0. The .Nm utility will report whether the disk is ready, but will not display sense information if the command fails since the .Fl v switch was not specified. .Pp .Bd -literal -offset indent 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 printing (with the .Fl v 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 utility will report whether the disk is ready. .Bd -literal -offset indent 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 information if the command fails. .Pp .Bd -literal -offset indent 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 cause data corruption. .Pp .Bd -literal -offset indent 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 write reallocation settings, among other things. .Pp .Dl camcontrol rescan all .Pp Rescan all SCSI busses in the system for devices that have been added, removed or changed. .Pp .Dl camcontrol rescan 0 .Pp Rescan SCSI bus 0 for devices that have been added, removed or changed. .Pp .Dl camcontrol rescan 0:1:0 .Pp Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or changed. .Pp .Dl camcontrol tags da5 -N 24 .Pp Set the number of concurrent transactions for da5 to 24. .Pp .Bd -literal -offset indent camcontrol negotiate -n da -u 4 -T disable .Ed .Pp Disable tagged queueing for da4. .Pp .Bd -literal -offset indent 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 Test Unit Ready command to make the settings take effect. .Sh SEE ALSO .Xr cam 3 , .Xr cam_cdbparse 3 , .Xr cam 4 , .Xr pass 4 , .Xr xpt 4 .Sh HISTORY The .Nm utility first appeared in .Fx 3.0 . .Pp The mode page editing code and arbitrary SCSI command code are based upon code in the old .Xr scsi 8 utility and .Xr scsi 3 library, written by Julian Elischer and Peter Dufault. The .Xr scsi 8 program first appeared in .Bx 386 0.1.2.4 , and first appeared in .Fx in .Fx 2.0.5 . .Sh AUTHORS .An Kenneth Merry Aq ken@FreeBSD.org .Sh BUGS The code that parses the generic command line arguments does not know that 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 .Ed .Pp The sense information from the test unit ready command would not get printed out, since the first .Xr getopt 3 call in .Nm 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 .Xr getopt 3 interface. The best way to circumvent this problem is to always make sure to specify generic .Nm arguments before any command-specific arguments. Index: head/sbin/dump/dump.8 =================================================================== --- head/sbin/dump/dump.8 (revision 162394) +++ head/sbin/dump/dump.8 (revision 162395) @@ -1,545 +1,549 @@ .\" Copyright (c) 1980, 1991, 1993 .\" Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)dump.8 8.3 (Berkeley) 5/1/95 .\" $FreeBSD$ .\" .Dd February 24, 2006 .Dt DUMP 8 .Os .Sh NAME .Nm dump , .Nm rdump .Nd file system backup .Sh SYNOPSIS .Nm .Op Fl 0123456789acLnSu .Op Fl B Ar records .Op Fl b Ar blocksize .Op Fl C Ar cachesize .Op Fl D Ar dumpdates .Op Fl d Ar density .Op Fl f Ar file | Fl P Ar pipecommand .Op Fl h Ar level .Op Fl s Ar feet .Op Fl T Ar date .Ar filesystem .Nm .Fl W | Fl w .Pp .Nm rdump is an alternate name for .Nm . .Pp .in \" XXX (The .Bx 4.3 option syntax is implemented for backward compatibility, but is not documented here.) .Sh DESCRIPTION The .Nm utility examines files on a file system and determines which files need to be backed up. These files are copied to the given disk, tape or other storage medium for safe keeping (see the .Fl f option below for doing remote backups). A dump that is larger than the output medium is broken into multiple volumes. On most media the size is determined by writing until an end-of-media indication is returned. This can be enforced by using the .Fl a option. .Pp On media that cannot reliably return an end-of-media indication (such as some cartridge tape drives) each volume is of a fixed size; the actual size is determined by the tape size and density and/or .Fl B options. By default, the same output file name is used for each volume after prompting the operator to change media. .Pp The file system to be dumped is specified by the argument .Ar filesystem as either its device-special file or its mount point (if that is in a standard entry in .Pa /etc/fstab ) . .Pp The following options are supported by .Nm : .Bl -tag -width Ds .It Fl 0-9 Dump levels. A level 0, full backup, guarantees the entire file system is copied (but see also the .Fl h option below). A level number above 0, incremental backup, tells dump to copy all files new or modified since the last dump of any lower level. The default level is 0. .It Fl a .Dq auto-size . Bypass all tape length considerations, and enforce writing until an end-of-media indication is returned. This fits best for most modern tape drives. Use of this option is particularly recommended when appending to an existing tape, or using a tape drive with hardware compression (where you can never be sure about the compression ratio). .It Fl B Ar records The number of kilobytes per output volume, except that if it is not an integer multiple of the output block size, the command uses the next smaller such multiple. This option overrides the calculation of tape size based on length and density. .It Fl b Ar blocksize The number of kilobytes per output block. The default block size is 10. .It Fl C Ar cachesize Specify the cache size in megabytes. This will greatly improve performance at the cost of .Nm possibly not noticing changes in the file system between passes. It is recommended that you always use this option when dumping a snapshot. Beware that .Nm forks, and the actual memory use may be larger than the specified cache size. The recommended cache size is between 8 and 32 (megabytes). .It Fl c Change the defaults for use with a cartridge tape drive, with a density of 8000 bpi, and a length of 1700 feet. .It Fl D Ar dumpdates Specify an alternate path to the .Pa dumpdates file. The default is .Pa /etc/dumpdates . .It Fl d Ar density Set tape density to .Ar density . The default is 1600BPI. .It Fl f Ar file Write the backup to .Ar file ; .Ar file may be a special device file like .Pa /dev/sa0 (a tape drive), .Pa /dev/fd1 (a floppy disk drive), an ordinary file, or .Sq Fl (the standard output). Multiple file names may be given as a single argument separated by commas. Each file will be used for one dump volume in the order listed; if the dump requires more volumes than the number of names given, the last file name will used for all remaining volumes after prompting for media changes. If the name of the file is of the form .Dq host:file , or .Dq user@host:file , .Nm writes to the named file on the remote host using .Xr rmt 8 . The default path name of the remote .Xr rmt 8 program is .\" rmt path, is the path on the remote host .Pa /etc/rmt ; this can be overridden by the environment variable .Ev RMT . .It Fl P Ar pipecommand Use .Xr popen 3 to execute the .Xr sh 1 script string defined by .Ar pipecommand for the output device of each volume. This child pipeline's .Dv stdin .Pq Pa /dev/fd/0 is redirected from the .Nm output stream, and the environment variable .Ev DUMP_VOLUME is set to the current volume number being written. After every volume, the writer side of the pipe is closed and .Ar pipecommand is executed again. Subject to the media size specified by .Fl B , each volume is written in this manner as if the output were a tape drive. .It Fl h Ar level Honor the user .Dq nodump flag .Pq Dv UF_NODUMP only for dumps at or above the given .Ar level . The default honor level is 1, so that incremental backups omit such files but full backups retain them. .It Fl L This option is to notify .Nm that it is dumping a live file system. To obtain a consistent dump image, .Nm takes a snapshot of the file system in the .Pa .snap directory in the root of the file system being dumped and then does a dump of the snapshot. The snapshot is unlinked as soon as the dump starts, and is thus removed when the dump is complete. This option is ignored for unmounted or read-only file systems. If the .Pa .snap directory does not exist in the root of the file system being dumped, a warning will be issued and the .Nm will revert to the standard behavior. This problem can be corrected by creating a .Pa .snap directory in the root of the file system to be dumped; its owner should be .Dq Li root , its group should be .Dq Li operator , and its mode should be .Dq Li 0770 . .It Fl n Whenever .Nm requires operator attention, notify all operators in the group .Dq operator by means similar to a .Xr wall 1 . .It Fl S Display an estimate of the backup size and the number of tapes required, and exit without actually performing the dump. .It Fl s Ar feet Attempt to calculate the amount of tape needed at a particular density. If this amount is exceeded, .Nm prompts for a new tape. It is recommended to be a bit conservative on this option. The default tape length is 2300 feet. .It Fl T Ar date Use the specified date as the starting time for the dump instead of the time determined from looking in the .Pa dumpdates file. The format of date is the same as that of .Xr ctime 3 . This option is useful for automated dump scripts that wish to dump over a specific period of time. The .Fl T option is mutually exclusive from the .Fl u option. .It Fl u Update the .Pa dumpdates file after a successful dump. The format of the .Pa dumpdates file is readable by people, consisting of one free format record per line: file system name, increment level and .Xr ctime 3 format dump date. There may be only one entry per file system at each level. The .Pa dumpdates file may be edited to change any of the fields, if necessary. The default path for the .Pa dumpdates file is .Pa /etc/dumpdates , but the .Fl D option may be used to change it. .It Fl W Tell the operator what file systems need to be dumped. This information is gleaned from the files .Pa dumpdates and .Pa /etc/fstab . The .Fl W option causes .Nm to print out, for each file system in the .Pa dumpdates file the most recent dump date and level, and highlights those file systems that should be dumped. If the .Fl W option is set, all other options are ignored, and .Nm exits immediately. .It Fl w Is like .Fl W , but prints only those file systems which need to be dumped. .El .Pp Directories and regular files which have their .Dq nodump flag .Pq Dv UF_NODUMP set will be omitted along with everything under such directories, subject to the .Fl h option. .Pp The .Nm utility requires operator intervention on these conditions: end of tape, end of dump, tape write error, tape open error or disk read error (if there are more than a threshold of 32). In addition to alerting all operators implied by the .Fl n key, .Nm interacts with the operator on .Em dump's control terminal at times when .Nm can no longer proceed, or if something is grossly wrong. All questions .Nm poses .Em must be answered by typing .Dq yes or .Dq no , appropriately. .Pp Since making a dump involves a lot of time and effort for full dumps, .Nm checkpoints itself at the start of each tape volume. If writing that volume fails for some reason, .Nm will, with operator permission, restart itself from the checkpoint after the old tape has been rewound and removed, and a new tape has been mounted. .Pp The .Nm utility tells the operator what is going on at periodic intervals (every 5 minutes, or promptly after receiving .Dv SIGINFO ) , including usually low estimates of the number of blocks to write, the number of tapes it will take, the time to completion, and the time to the tape change. The output is verbose, so that others know that the terminal controlling .Nm is busy, and will be for some time. .Pp In the event of a catastrophic disk event, the time required to restore all the necessary backup tapes or files to disk can be kept to a minimum by staggering the incremental dumps. An efficient method of staggering incremental dumps to minimize the number of tapes follows: .Bl -bullet -offset indent .It Always start with a level 0 backup, for example: .Bd -literal -offset indent /sbin/dump -0u -f /dev/nsa0 /usr/src .Ed .Pp This should be done at set intervals, say once a month or once every two months, and on a set of fresh tapes that is saved forever. .It After a level 0, dumps of active file systems (file systems with files that change, depending on your partition layout some file systems may contain only data that does not change) are taken on a daily basis, using a modified Tower of Hanoi algorithm, with this sequence of dump levels: .Bd -literal -offset indent 3 2 5 4 7 6 9 8 9 9 ... .Ed .Pp For the daily dumps, it should be possible to use a fixed number of tapes for each day, used on a weekly basis. Each week, a level 1 dump is taken, and the daily Hanoi sequence repeats beginning with 3. For weekly dumps, another fixed set of tapes per dumped file system is used, also on a cyclical basis. .El .Pp After several months or so, the daily and weekly tapes should get rotated out of the dump cycle and fresh tapes brought in. .Sh ENVIRONMENT .Bl -tag -width ".Ev TAPE" .It Ev TAPE The .Ar file or device to dump to if the .Fl f option is not used. .It Ev RMT Pathname of the remote .Xr rmt 8 program. .It Ev RSH Pathname of a remote shell program, if not .Xr rsh 1 . .El -.Sh EXAMPLES -Dumps the "/u" file system to dvds using growisofs. -Uses a 16MB cache and creates a snapshot of the dump and records the -dumpdates file. -.Bd -literal -/sbin/dump -0u -L -C16 -B4589840 -P 'growisofs -Z /dev/cd0=/dev/fd/0' /u -.Ed .Sh FILES .Bl -tag -width /etc/dumpdates -compact .It Pa /dev/sa0 default tape unit to dump to .It Pa /etc/dumpdates dump date records (this can be changed; see the .Fl D option) .It Pa /etc/fstab dump table: file systems and frequency .It Pa /etc/group to find group .Em operator .El .Sh EXIT STATUS Dump exits with zero status on success. Startup errors are indicated with an exit code of 1; abnormal termination is indicated with an exit code of 3. +.Sh EXAMPLES +Dumps the +.Pa /u +file system to DVDs using +.Nm growisofs . +Uses a 16MB cache, creates a snapshot of the dump, and records the +.Pa dumpdates +file. +.Bd -literal +/sbin/dump -0u -L -C16 -B4589840 -P 'growisofs -Z /dev/cd0=/dev/fd/0' /u +.Ed .Sh DIAGNOSTICS Many, and verbose. .Sh SEE ALSO .Xr chflags 1 , .Xr fstab 5 , .Xr restore 8 , .Xr rmt 8 .Sh HISTORY A .Nm utility appeared in .At v6 . .Sh BUGS Fewer than 32 read errors on the file system are ignored, though all errors will generate a warning message. This is a bit of a compromise. In practice, it is possible to generate read errors when doing dumps on mounted partitions if the file system is being modified while the .Nm is running. Since dumps are often done in an unattended fashion using .Xr cron 8 jobs asking for Operator intervention would result in the .Nm dying. However, there is nothing wrong with a dump tape written when this sort of read error occurs, and there is no reason to terminate the .Nm . .Pp Each reel requires a new process, so parent processes for reels already written just hang around until the entire tape is written. .Pp The .Nm utility with the .Fl W or .Fl w options does not report file systems that have never been recorded in the .Pa dumpdates file, even if listed in .Pa /etc/fstab . .Pp It would be nice if .Nm knew about the dump sequence, kept track of the tapes scribbled on, told the operator which tape to mount when, and provided more assistance for the operator running .Xr restore 8 . .Pp The .Nm utility cannot do remote backups without being run as root, due to its security history. This will be fixed in a later version of .Fx . Presently, it works if you set it setuid (like it used to be), but this might constitute a security risk. Index: head/sbin/fdisk_pc98/fdisk.8 =================================================================== --- head/sbin/fdisk_pc98/fdisk.8 (revision 162394) +++ head/sbin/fdisk_pc98/fdisk.8 (revision 162395) @@ -1,482 +1,484 @@ .\" $FreeBSD$ .\" .Dd February 26, 2006 .Dt FDISK 8 .Os .Sh NAME .Nm fdisk .Nd NEC PC-98x1 partition table maintenance program .Sh SYNOPSIS .Nm .Op Fl BIaistuv .Op Fl b Ar bootcode .Op Fl 1234 .Op Ar disk .Nm .Fl f Ar configfile .Op Fl itv .Op Ar disk .Sh PROLOGUE In order for the BIOS to boot the kernel, certain conventions must be adhered to. 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 0 boot code then searches the partition table to determine which partition is marked .Em active . This boot code then brings in the bootstrap from the .Em active partition and, if marked bootable, runs it. Under DOS, you can have one or more partitions with one .Em active . The DOS .Nm utility can be used to divide space on the disk into partitions and set one .Em active . .Sh DESCRIPTION The .Fx .Nm 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 .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 .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 if .Fl f is given. .It Fl I -Initialize the partition table. One +Initialize the partition table. +One .Fx slice covering the entire disk will be created. Some space at the start of the disk will reserved for the IPL program and the pc98 partition table itself. .It Fl f Ar configfile Set partition values using the file .Ar configfile . The .Ar configfile always modifies existing partitions, unless .Fl i is also given, in which case all existing partitions are deleted (marked as "unused") before the .Ar configfile is read. The .Ar configfile can be "-", in which case .Ar stdin is read. See .Sx CONFIGURATION FILE , below, for file syntax. .Pp .Em WARNING : 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! .It Fl i -Initialize sector 0 of the disk. This implies +Initialize sector 0 of the disk. +This implies .Fl u , unless .Fl f is given. .It Fl s Print summary information and exit. .It Fl t 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 .Fl v . .It Fl u Is used for updating (editing) sector 0 of the disk. Ignored if .Fl f is given. .It Fl v 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 .Fl f is given. .El .Pp The final disk name can be provided as a .Sq bare disk name only, e.g.\& .Ql da0 , or as a fully qualified device node under .Pa /dev . If omitted, the disks .Ql wd0 , .Ql da0 , and .Ql od0 are being searched in that order, until one is being found responding. .Pp When called with no arguments, it prints the sector 0 partition table. An example follows: .Bd -literal ******* Working on device /dev/rda0 ******* parameters extracted from in-core disklabel are: cylinders=33075 heads=8 sectors/track=32 (256 blks/cyl) parameters to be used for BIOS calculations are: cylinders=33075 heads=8 sectors/track=32 (256 blks/cyl) Media sector size is 512 Warning: BIOS sector numbering starts with sector 1 Information from DOS bootblock is: The data for partition 1 is: sysmid 148,(FreeBSD/NetBSD/386BSD) start 256, size 2490112 (1215 Meg), sid 196 beg: cyl 1/ sector 0/ head 0; end: cyl 9727/ sector 0/ head 0 system Name FreeBSD(98) The data for partition 2 is: sysmid 148,(FreeBSD/NetBSD/386BSD) start 2490368, size 5505024 (2688 Meg), sid 196 beg: cyl 9728/ sector 0/ head 0; end: cyl 31231/ sector 0/ head 0 system Name FreeBSD(98) The data for partition 3 is: The data for partition 4 is: The data for partition 5 is: The data for partition 6 is: The data for partition 7 is: The data for partition 8 is: The data for partition 9 is: The data for partition 10 is: The data for partition 11 is: The data for partition 12 is: The data for partition 13 is: The data for partition 14 is: The data for partition 15 is: The data for partition 16 is: .Ed .Pp The disk is divided into three partitions that happen to fill the disk. The second partition overlaps the end of the first. (Used for debugging purposes) .Bl -tag -width "cyl, sector and head" .It Em "sysmid" is used to label the partition. .Fx reserves the magic number 148 decimal (94 in hex). .It Em start No and Em size fields provide the start address and size of a partition in sectors. .\" !PC98 .It Em "flag 80" .\" specifies that this is the active partition. .It Em cyl , sector No and Em head fields are used to specify the beginning address and end address for the partition. .It Em "system Name" is the name of the partition. .It Em Note : these numbers are calculated using BIOS's understanding of the disk geometry and saved in the bootblock. .El .Pp The flags .Fl i or .Fl u are used to indicate that the partition data is to be updated, unless the .Fl f option is used. If the .Fl f option is not used, the .Nm utility will enter a conversational mode. This mode is designed not to change any data unless you explicitly tell it to. The .Nm utility selects defaults for its questions to guarantee the above behavior. .Pp It displays each partition and ask if you want to edit it. If you say yes, it will step through each field showing the old value and asking for a new one. When you are done with a partition, .Nm will display it and ask if it is correct. The .Nm utility will then proceed to the next entry. .Pp Getting the .Em cyl , sector , and .Em head fields correct is tricky. So by default, they will be calculated for you; you can specify them if you choose. .Pp After all the partitions are processed, you are given the option to change the .Em active partition. Finally, when the all the data for the first sector has been accumulated, you are asked if you really want to rewrite sector 0. Only if you answer yes, will the data be written to disk. .Pp The difference between the .Fl u flag and .Fl i flag is that the .Fl u flag just edits the fields as they appear on the disk. While the .Fl i flag is used to "initialize" sector 0; 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 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, but the program initially gives you an opportunity to change them. This allows the user to create a bootblock that can work with drives that use geometry translation under the BIOS. .Pp If you hand craft your disk layout, please make sure that the .Fx partition starts on a cylinder boundary. A number of decisions made later may assume this. (This might not be necessary later.) .Pp 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 not fully explained in this manual page. .Sh CONFIGURATION FILE When the .Fl f 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 a specification, and whitespace (except for newlines) are ignored: .Bl -tag -width Ds .It Xo .Ic # .Ar comment ... .Xc Lines beginning with a "#" are comments and are ignored. .It Xo .Ic g .Ar spec1 .Ar spec2 .Ar spec3 .Xc 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 .It Cm c Ar num .Sm on Set the number of cylinders to .Ar num . .Sm off .It Cm h Ar num .Sm on Set the number of heads to .Ar num . .Sm off .It Cm s Ar num .Sm on Set the number of sectors/track to .Ar num . .El .Pp These specs can occur in any order, as the leading letter determines which value is which; however, all three must be specified. .Pp This line must occur before any lines that specify partition information. .Pp It is an error if the following is not true: .Bd -literal -offset indent 1 <= number of cylinders 1 <= number of heads <= 256 1 <= number of sectors/track < 64 .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 .Fx partitions (the "/" file system) must lie completely within the first 1024 cylinders; if this is not true, booting may fail. Non-bootable partitions do not have this restriction. .Pp Example (all of these are equivalent), for a disk with 1019 cylinders, 39 heads, and 63 sectors: .Bd -literal -offset indent g c1019 h39 s63 g h39 c1019 s63 g s63 h39 c1019 .Ed .It Xo .Ic p .Ar partition .Ar type .Ar start .Ar length .Xc Set the partition given by .Ar partition (1-4) to type .Ar type , starting at sector .Ar start for .Ar length sectors. .Pp Only those partitions explicitly mentioned by these lines are modified; any partition not referenced by a "p" line will not be modified. 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 set, multiple "p" lines must be specified; one for each partition. .Pp These partition lines must occur after any geometry specification lines, if one is present. .Pp The .Ar type is 165 for .Fx 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 and .Ar length . .Pp Note: the start offset will be rounded upwards to a head boundary if necessary, and the end offset will be rounded downwards to a cylinder boundary if necessary. .Pp Example: to clear partition 4 and mark it as unused: .Bd -literal -offset indent p 4 0 0 0 .Ed .Pp Example: to set partition 1 to a .Fx partition, starting at sector 1 for 2503871 sectors (note: these numbers will be rounded upwards and downwards to correspond to head and cylinder boundaries): .Bd -literal -offset indent p 1 165 1 2503871 .Ed .It Xo .Ic a .Ar partition .Xc Make .Ar partition 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: .Bd -literal -offset indent a 1 .Ed .El .Sh FILES .Bl -tag -width /boot/mbr -compact .It Pa /boot/mbr The default boot code .El .Sh SEE ALSO .Xr disklabel 8 .Sh BUGS The default boot code will not necessarily handle all partition types correctly, in particular those introduced since MS-DOS 6.x. .Pp The entire program should be made more user-friendly. .Pp Throughout this man page, the term .Sq partition is used where it should actually be .Sq slice , in order to conform with the terms used elsewhere. .Pp You cannot use this command to completely dedicate a disk to .Fx . The .Xr disklabel 8 command must be used for this. Index: head/sbin/fsdb/fsdb.8 =================================================================== --- head/sbin/fsdb/fsdb.8 (revision 162394) +++ head/sbin/fsdb/fsdb.8 (revision 162395) @@ -1,269 +1,269 @@ .\" $NetBSD: fsdb.8,v 1.2 1995/10/08 23:18:08 thorpej Exp $ .\" .\" Copyright (c) 1995 John T. Kohl .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR `AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 24, 2006 .Dt FSDB 8 .Os .Sh NAME .Nm fsdb .Nd FFS debugging/editing tool .Sh SYNOPSIS .Nm .Op Fl d .Op Fl f .Op Fl r .Ar fsname .Sh DESCRIPTION The .Nm 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 to enter a command with .Ic "fsdb (inum X)>" where .Va X 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 library, so you can use command line editing to reduce typing if desired. When you exit the command loop, the file system superblock is marked dirty and any buffered blocks are written to the file system. .Pp The following options are available: .Bl -tag -width indent .It Fl d Enable additional debugging output (which comes primarily from .Xr fsck 8 Ns -derived code). .It Fl f Left for historical reasons and has no meaning. .It Fl r Open the file system read/only, and disables all commands that would write to it. .El .Sh COMMANDS Besides the built-in .Xr editline 3 commands, .Nm supports these commands: .Pp .Bl -tag -width indent -compact .It Cm help Print out the list of accepted commands. .Pp .It Cm inode Ar i-number Select inode .Ar i-number as the new current inode. .Pp .It Cm back Revert to the previously current inode. .Pp .It Cm clri Ar i-number Clear .Ar i-number . .Pp .It Cm lookup Ar name .It Cm cd Ar name Find .Ar name 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 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. .Pp .It Cm active .It Cm print Print out the active inode. .Pp .It Cm blocks Print out the block list of the active inode. Note that the printout can become long for large files, since all indirect block pointers will also be printed. .Pp -.It Cm findblk Ar disk block number ... +.It Cm findblk Ar disk_block_number ... Find the inode(s) owning the specified disk block(s) number(s). Note that these are not absolute disk blocks numbers, but offsets from the start of the partition. .Pp .It Cm uplink Increment the active inode's link count. .Pp .It Cm downlink Decrement the active inode's link count. .Pp .It Cm linkcount Ar number 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 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 if the current inode is a directory. .Pp .It Cm ln Ar ino Ar name Create a link to inode .Ar ino under the name .Ar name 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 Change the i-number in directory entry .Ar dirslot to .Ar inum . .Pp .It Cm chname Ar dirslot Ar name Change the name in directory entry .Ar dirslot to .Ar name . 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 Change the type of the current inode to .Ar type . .Ar Type may be one of: .Em file , .Em dir , .Em socket , or .Em fifo . .Pp .It Cm chmod Ar mode Change the mode bits of the current inode to .Ar mode . You cannot change the file type with this subcommand; use .Ic chtype to do that. .Pp .It Cm chflags Ar flags Change the file flags of the current inode to .Ar flags . .Pp .It Cm chown Ar uid Change the owner of the current inode to .Ar uid . .Pp .It Cm chgrp Ar gid Change the group of the current inode to .Ar gid . .Pp .It Cm chgen Ar gen Change the generation number of the current inode to .Ar gen . .Pp .It Cm btime Ar time .It Cm mtime Ar time .It Cm ctime Ar time .It Cm atime Ar time Change the creation (birth), modification, change, or access time (respectively) on the current inode to .Ar time . .Ar Time should be in the format .Em YYYYMMDDHHMMSS[.nsec] where .Em nsec is an optional nanosecond specification. If no nanoseconds are specified, the .Va birthnsec , .Va mtimensec , .Va ctimensec , or .Va atimensec field will be set to zero. Note that .Cm btime is available on UFS2 file systems only. .Pp .It Cm quit , q , exit , Em Exit the program. .El .Sh SEE ALSO .Xr editline 3 , .Xr fs 5 , .Xr clri 8 , .Xr fsck 8 .Sh HISTORY The .Nm utility uses the source code for .Xr fsck 8 to implement most of the file system manipulation code. The remainder of .Nm first appeared in .Nx , written by .An John T. Kohl . .Pp .An Peter Wemm ported it to .Fx . .Sh BUGS Manipulation of ``short'' symlinks has no effect. In particular, one should not try changing a symlink's type. .Pp You must specify modes as numbers rather than symbolic names. .Pp There are a bunch of other things that you might want to do which .Nm does not implement. .Sh WARNING Use this tool with extreme caution--you can damage an FFS file system beyond what .Xr fsck 8 can repair. Index: head/sbin/gbde/gbde.8 =================================================================== --- head/sbin/gbde/gbde.8 (revision 162394) +++ head/sbin/gbde/gbde.8 (revision 162395) @@ -1,256 +1,256 @@ .\" .\" Copyright (c) 2002 Poul-Henning Kamp .\" Copyright (c) 2002 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by Poul-Henning Kamp .\" and NAI Labs, the Security Research Division of Network Associates, Inc. .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the .\" DARPA CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd February 12, 2005 +.Dd February 8, 2006 .Dt GBDE 8 .Os .Sh NAME .Nm gbde .Nd operation and management utility for Geom Based Disk Encryption .Sh SYNOPSIS .Nm .Cm attach .Ar destination .Op Fl k Ar keyfile .Op Fl l Ar lockfile .Op Fl p Ar pass-phrase .Nm .Cm detach .Ar destination .Nm .Cm init .Ar destination .Op Fl i .Op Fl f Ar filename .Op Fl K Ar new-keyfile .Op Fl L Ar new-lockfile .Op Fl P Ar new-pass-phrase .Nm .Cm setkey .Ar destination .Op Fl n Ar key .Op Fl k Ar keyfile .Op Fl l Ar lockfile .Op Fl p Ar pass-phrase .Op Fl K Ar new-keyfile .Op Fl L Ar new-lockfile .Op Fl P Ar new-pass-phrase .Nm .Cm nuke .Ar destination .Op Fl n Ar key .Op Fl k Ar keyfile .Op Fl l Ar lockfile .Op Fl p Ar pass-phrase .Nm .Cm destroy .Ar destination .Op Fl k Ar keyfile .Op Fl l Ar lockfile .Op Fl p Ar pass-phrase .Sh DESCRIPTION .Bf -symbolic NOTICE: Please be aware that this code has not yet received much review and analysis by qualified cryptographers and therefore should be considered a slightly suspect experimental facility. .Pp We cannot at this point guarantee that the on-disk format will not change in response to reviews or bug-fixes, so potential users are advised to be prepared that .Xr dump 8 Ns / Ns .Xr restore 8 based migrations may be called for in the future. .Ef .Pp The .Nm utility is the only official operation and management interface for the .Xr gbde 4 .Tn GEOM based disk encryption kernel facility. The interaction between the .Nm utility and the kernel part is not a published interface. .Pp The operational aspect consists of two subcommands: one to open and attach a device to the in-kernel cryptographic .Nm module .Pq Cm attach , and one to close and detach a device .Pq Cm detach . .Pp The management part allows initialization of the master key and lock sectors on a device .Pq Cm init , initialization and replacement of pass-phrases .Pq Cm setkey , and key invalidation .Pq Cm nuke and blackening .Pq Cm destroy functions. .Pp The .Fl l Ar lockfile argument is used to supply the lock selector data. If no .Fl l option is specified, the first sector is used for this purpose. .Pp The .Fl L Ar new-lockfile argument specifies the lock selector file for the key initialized with the .Cm init subcommand or modified with the .Cm setkey subcommand. .Pp The .Fl n Ar key argument can be used to specify to which of the four keys the operation applies. A value of 1 to 4 selects the specified key, a value of 0 (the default) means .Dq "this key" (i.e., the key used to gain access to the device) and a value of \-1 means .Dq "all keys" . .Pp The .Fl f Ar filename specifies an optional parameter file for use under initialization. .Pp Alternatively, the .Fl i option toggles an interactive mode where a template file with descriptions of the parameters can be interactively edited. .Pp The .Fl p Ar pass-phrase argument specifies the pass-phrase used for opening the device. If not specified, the controlling terminal will be used to prompt the user for the pass-phrase. Be aware that using this option may expose the pass-phrase to other users who happen to run .Xr ps 1 or similar while the command is running. .Pp The .Fl P Ar new-pass-phrase argument can be used to specify the new pass-phrase to the .Cm init and .Cm setkey subcommands. If not specified, the user is prompted for the new pass-phrase on the controlling terminal. Be aware that using this option may expose the pass-phrase to other users who happen to run .Xr ps 1 or similar while the command is running. .Pp The .Fl k Ar keyfile argument specifies a key file to be used in combination with the pass-phrase (whether the pass-phrase is specified on the command line or entered from the terminal) for opening the device. The device will only be opened if the contents of the key file and the pass-phrase are both correct. .Pp The .Fl K Ar new-keyfile argument can be used to specify a new key file to the .Cm init and .Cm setkey subcommands. If not specified, no key file will be used (even if one was previously used). .Sh EXAMPLES To initialize a device, using default parameters: .Pp .Dl "gbde init /dev/ad0s1f -L /etc/ad0s1f.lock" .Pp To attach an encrypted device: .Pp .Dl "gbde attach ad0s1f -l /etc/ad0s1f.lock" .Pp The encrypted device has the suffix .Pa .bde so a typical command to create and mount a file system would be: .Pp .Dl "newfs /dev/ad0s1f.bde" .Dl "mount /dev/ad0s1f.bde /secret" .Pp To detach an encrypted device: .Pp .Dl "gbde detach ad0s1f" .Pp Please notice that detaching an encrypted device corresponds to physically removing it, do not forget to unmount the file system first. .Pp To initialize the second key using a detached lockfile and a trivial pass-phrase: .Pp .Dl "gbde setkey ad0s1f -n 2 -P foo -L key2.lockfile" .Pp To destroy all copies of the masterkey: .Pp .Dl "gbde destroy ad0s1f -n -1" .Sh SEE ALSO .Xr gbde 4 , .Xr geom 4 .Sh HISTORY This software was developed for the .Fx Project by .An "Poul-Henning Kamp" and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. .Sh AUTHORS .An "Poul-Henning Kamp" Aq phk@FreeBSD.org .Sh BUGS The cryptographic algorithms and the overall design have not been attacked mercilessly for over 10 years by a gang of cryptoanalysts. Index: head/sbin/geom/class/mirror/gmirror.8 =================================================================== --- head/sbin/geom/class/mirror/gmirror.8 (revision 162394) +++ head/sbin/geom/class/mirror/gmirror.8 (revision 162395) @@ -1,347 +1,349 @@ .\" Copyright (c) 2004-2005 Pawel Jakub Dawidek .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 8, 2006 .Dt GMIRROR 8 .Os .Sh NAME .Nm gmirror .Nd "control utility for mirrored devices" .Sh SYNOPSIS .Nm .Cm label .Op Fl hnv .Op Fl b Ar balance .Op Fl s Ar slice .Ar name .Ar prov ... .Nm .Cm clear .Op Fl v .Ar prov ... .Nm .Cm configure .Op Fl adhnv .Op Fl b Ar balance .Op Fl s Ar slice .Ar name .Nm .Cm rebuild .Op Fl v .Ar name .Ar prov ... .Nm .Cm insert .Op Fl hiv .Op Fl p Ar priority .Ar name .Ar prov ... .Nm .Cm remove .Op Fl v .Ar name .Ar prov ... .Nm .Cm activate .Op Fl v .Ar name .Ar prov ... .Nm .Cm deactivate .Op Fl v .Ar name .Ar prov ... .Nm .Cm forget .Op Fl v .Ar name ... .Nm .Cm stop .Op Fl fv .Ar name ... .Nm .Cm clear .Op Fl v .Ar prov ... .Nm .Cm dump .Ar prov ... .Nm .Cm list .Nm .Cm status .Nm .Cm load .Nm .Cm unload .Sh DESCRIPTION The .Nm utility is used for mirror (RAID1) configurations. After a mirror's creation, all components are detected and configured automatically. All operations like failure detection, stale component detection, rebuild of stale components, etc.\& are also done automatically. The .Nm utility uses on-disk metadata (stored in the provider's last sector) to store all needed information. Since the last sector is used for this purpose, it is possible to place a root file system on a mirror. .Pp The first argument to .Nm indicates an action to be performed: .Bl -tag -width ".Cm deactivate" .It Cm label Create a mirror. The order of components is important, because a component's priority is based on its position (starting from 0). -The component with the biggest priority is used by the prefer balance algorithm +The component with the biggest priority is used by the +.Cm prefer +balance algorithm and is also used as a master component when resynchronization is needed, e.g.\& after a power failure when the device was open for writing. .Pp Additional options include: .Bl -tag -width ".Fl b Ar balance" .It Fl b Ar balance Specifies balance algorithm to use, one of: .Bl -tag -width ".Cm round-robin" .It Cm load Read from the component with the lowest load. .It Cm prefer Read from the component with the biggest priority. .It Cm round-robin Use round-robin algorithm when choosing component to read. .It Cm split Split read requests, which are bigger than or equal to slice size on N pieces, where N is the number of active components. This is the default balance algorithm. .El .It Fl h Hardcode providers' names in metadata. .It Fl n Turn off autosynchronization of stale components. .It Fl s Ar slice When using the .Cm split balance algorithm and an I/O READ request is bigger than or equal to this value, the I/O request will be split into N pieces, where N is the number of active components. Defaults to 4096 bytes. .El .It Cm clear Clear metadata on the given providers. .It Cm configure Configure the given device. .Pp Additional options include: .Bl -tag -width ".Fl b Ar balance" .It Fl a Turn on autosynchronization of stale components. .It Fl b Ar balance Specifies balance algorithm to use. .It Fl d Do not hardcode providers' names in metadata. .It Fl h Hardcode providers' names in metadata. .It Fl n Turn off autosynchronization of stale components. .It Fl s Ar slice Specifies slice size for .Cm split balance algorithm. .El .It Cm rebuild Rebuild the given mirror components forcibly. If autosynchronization was not turned off for the given device, this command should be unnecessary. .It Cm insert Add the given component(s) to the existing mirror. .Pp Additional options include: .Bl -tag -width ".Fl p Ar priority" .It Fl h Hardcode providers' names in metadata. .It Fl i Mark component(s) as inactive immediately after insertion. .It Fl p Ar priority Specifies priority of the given component(s). .El .It Cm remove Remove the given component(s) from the mirror and clear metadata on it. .It Cm activate Activate the given component(s), which were marked as inactive before. .It Cm deactivate Mark the given component(s) as inactive, so it will not be automatically connected to the mirror. .It Cm forget Forget about components which are not connected. This command is useful when a disk has failed and cannot be reconnected, preventing the .Cm remove command from being used to remove it. .It Cm stop Stop the given mirror. .Pp Additional options include: .Bl -tag -width ".Fl f" .It Fl f Stop the given mirror even if it is opened. .El .It Cm dump Dump metadata stored on the given providers. .It Cm list See .Xr geom 8 . .It Cm status See .Xr geom 8 . .It Cm load See .Xr geom 8 . .It Cm unload See .Xr geom 8 . .El .Pp Additional options include: .Bl -tag -width ".Fl v" .It Fl v Be more verbose. .El .Sh EXIT STATUS Exit status is 0 on success, and 1 if the command fails. .Sh EXAMPLES Use 3 disks to setup a mirror. Choose split balance algorithm, split only requests which are bigger than or equal to 2kB. Create file system, mount it, then unmount it and stop device: .Bd -literal -offset indent gmirror label -v -b split -s 2048 data da0 da1 da2 newfs /dev/mirror/data mount /dev/mirror/data /mnt \&... umount /mnt gmirror stop data gmirror unload .Ed .Pp Create a mirror on disk with valid data (note that the last sector of the disk will be overwritten). Add another disk to this mirror, so it will be synchronized with existing disk: .Bd -literal -offset indent gmirror label -v -b round-robin data da0 gmirror insert data da1 .Ed .Pp Create a mirror, but do not use automatic synchronization feature. Add another disk and rebuild it: .Bd -literal -offset indent gmirror label -v -n -b load data da0 da1 gmirror insert data da2 gmirror rebuild data da2 .Ed .Pp One disk failed. Replace it with a brand new one: .Bd -literal -offset indent gmirror forget data gmirror insert data da1 .Ed .Pp Create a mirror, deactivate one component, do the backup and connect it again. It will not be resynchronized, if there is no need to do so (there were no writes in the meantime): .Bd -literal -offset indent gmirror label data da0 da1 gmirror deactivate data da1 dd if=/dev/da1 of=/backup/data.img bs=1m gmirror activate data da1 .Ed .Sh NOTES Doing kernel dumps to .Nm providers. .Pp This is possible, but some conditions have to be met. First of all, a kernel dump will go only to one component and .Nm always chooses the component with the highest priority. -Reading a dump from the mirror on boot will only work if the prefer +Reading a dump from the mirror on boot will only work if the +.Cm prefer balance algorithm is used (that way .Nm will read only from the component with the highest priority). If you use a different balance algorithm, you should add: .Bd -literal -offset indent gmirror configure -b prefer data .Ed .Pp to the .Pa /etc/rc.early script and: .Bd -literal -offset indent gmirror configure -b round-robin data .Ed .Pp to the .Pa /etc/rc.local script. The decision which component to choose for dumping is made when .Xr dumpon 8 is called. If on the next boot a component with a higher priority will be available, the prefer algorithm will choose to read from it and .Xr savecore 8 will find nothing. If on the next boot a component with the highest priority will be synchronized, the prefer balance algorithm will read from the next one, thus will find nothing there. -.Ed .Sh SEE ALSO .Xr geom 4 , .Xr dumpon 8 , .Xr geom 8 , .Xr mount 8 , .Xr newfs 8 , .Xr savecore 8 , .Xr umount 8 , .Xr vinum 8 .Sh HISTORY The .Nm utility appeared in .Fx 5.3 . .Sh AUTHORS .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .Sh BUGS There should be a way to change a component's priority inside a running mirror. .Pp There should be a section with an implementation description. .Pp Documentation for sysctls .Va kern.geom.mirror.* is missing. Index: head/sbin/geom/class/nop/gnop.8 =================================================================== --- head/sbin/geom/class/nop/gnop.8 (revision 162394) +++ head/sbin/geom/class/nop/gnop.8 (revision 162395) @@ -1,175 +1,176 @@ .\" Copyright (c) 2004-2006 Pawel Jakub Dawidek .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 8, 2006 .Dt GNOP 8 .Os .Sh NAME .Nm gnop .Nd "control utility for NOP GEOM class" .Sh SYNOPSIS .Nm .Cm create .Op Fl v .Op Fl e Ar error .Op Fl o Ar offset .Op Fl r Ar rfailprob .Op Fl s Ar size .Op Fl S Ar secsize .Op Fl w Ar wfailprob .Ar dev ... .Nm .Cm configure .Op Fl v .Op Fl e Ar error .Op Fl r Ar rfailprob .Op Fl w Ar wfailprob .Ar prov ... .Nm .Cm destroy .Op Fl fv .Ar prov ... .Nm .Cm reset .Op Fl v .Ar prov ... .Nm .Cm list .Nm .Cm status .Nm .Cm load .Nm .Cm unload .Sh DESCRIPTION The .Nm utility is used for setting up transparent providers on existing ones. Its main purpose is testing other GEOM classes, as it allows forced provider removal and I/O error simulation with a given probability. It also gathers the following statistics: number of read requests, number of write requests, number of read bytes and number of wrote bytes. In addition, it can be used as a good starting point for implementing new GEOM class. .Pp The first argument to .Nm indicates an action to be performed: .Bl -tag -width ".Cm configure" .It Cm create Set up a transparent provider on the given devices. If the operation succeeds, the new provider should appear with name .Pa /dev/ Ns Ao Ar dev Ac Ns Pa .nop . The kernel module .Pa geom_nop.ko will be loaded if it is not loaded already. .It Cm configure Configure existing transparent provider. At the moment it is only used for changing failure probability. .It Cm destroy Turn off the given transparent providers. .It Cm reset Reset statistics for the given transparent providers. .It Cm list See .Xr geom 8 . .It Cm status See .Xr geom 8 . .It Cm load See .Xr geom 8 . .It Cm unload See .Xr geom 8 . .El .Pp Additional options: -.Bl -tag -width ".Fl f Ar rfailprob" +.Bl -tag -width ".Fl r Ar rfailprob" .It Fl e Ar error Specifies the error number to return on failure. .It Fl f Force the removal of the specified provider. .It Fl o Ar offset Where to begin on the original provider. .It Fl r Ar rfailprob Specifies read failure probability in percent. .It Fl s Ar size Size of the transparent provider. .It Fl S Ar secsize Sector size of the transparent provider. .It Fl w Ar wfailprob Specifies write failure probability in percent. .It Fl v Be more verbose. .El .Sh SYSCTL VARIABLES The following .Xr sysctl 8 variables can be used to control the behavior of the .Nm NOP GEOM class. The default value is shown next to each variable. .Bl -tag -width indent .It Va kern.geom.nop.debug : No 0 Debug level of the .Nm NOP GEOM class. This can be set to a number between 0 and 2 inclusive. If set to 0 minimal debug information is printed, and if set to 2 the maximum amount of debug information is printed. .El .Sh EXIT STATUS Exit status is 0 on success, and 1 if the command fails. .Sh EXAMPLES The following example shows how to create a transparent provider for disk .Pa /dev/da0 with 50% failure probability, and how to destroy it. .Bd -literal -offset indent gnop create -v -f 50 da0 gnop destroy -v da0.nop .Ed .Pp -The traffic statistics for the given transparent providers we can get with +The traffic statistics for the given transparent providers can be obtained +with the .Cm list command. -Example below shows how can we obtain number of bytes written with +Example below shows the number of bytes written with .Xr newfs 8 : .Bd -literal -offset indent gnop create da0 newfs /dev/da0.nop gnop list .Ed .Sh SEE ALSO .Xr geom 4 , .Xr geom 8 .Sh HISTORY The .Nm utility appeared in .Fx 5.3 . .Sh AUTHORS .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org Index: head/sbin/ggate/ggatec/ggatec.8 =================================================================== --- head/sbin/ggate/ggatec/ggatec.8 (revision 162394) +++ head/sbin/ggate/ggatec/ggatec.8 (revision 162395) @@ -1,181 +1,181 @@ .\" Copyright (c) 2004 Pawel Jakub Dawidek .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 26, 2004 .Dt GGATEC 8 .Os .Sh NAME .Nm ggatec .Nd "GEOM Gate network client and control utility" .Sh SYNOPSIS .Nm .Cm create .Op Fl n .Op Fl v .Op Fl o Cm ro | wo | rw .Op Fl p Ar port .Op Fl q Ar queue_size .Op Fl R Ar rcvbuf .Op Fl S Ar sndbuf .Op Fl s Ar sectorsize .Op Fl t Ar timeout .Op Fl u Ar unit .Ar host .Ar path .Nm .Cm rescue .Op Fl n .Op Fl v .Op Fl o Cm ro | wo | rw .Op Fl p Ar port .Op Fl R Ar rcvbuf .Op Fl S Ar sndbuf .Fl u Ar unit .Ar host .Ar path .Nm .Cm destroy .Op Fl f .Fl u Ar unit .Nm .Cm list .Op Fl v .Op Fl u Ar unit .Sh DESCRIPTION The .Nm utility is a network client for GEOM Gate class. It is responsible for creation of .Nm ggate devices and forwarding I/O requests between .Nm geom_gate.ko kernel module and .Xr ggated 8 network daemon. Available commands: .Bl -tag -width ".Cm destroy" .It Cm create Connect to given .Xr ggated 8 daemon and create a .Nm ggate provider related to the given remote file or device. .It Cm rescue If .Nm process died/has been killed, you can save situation with this command, which creates new connection to the .Xr ggated 8 daemon and will handle pending and future requests. .It Cm destroy Destroy the given .Nm ggate provider. .It Cm list List .Nm ggate providers. .El .Pp Available options: .Bl -tag -width ".Fl s Cm ro | wo | rw" .It Fl f Forcibly destroy .Nm ggate provider (cancels all pending requests). .It Fl n Do not use .Dv TCP_NODELAY option on TCP sockets. .It Fl o Cm ro | wo | rw Specify permission to use when opening the file or device: read-only .Pq Cm ro , write-only .Pq Cm wo , or read-write .Pq Cm rw . Default is .Cm rw . .It Fl p Ar port Port to connect to on the remote host. Default is 3080. .It Fl q Ar queue_size Number of pending I/O requests that can be queued before they will start to be canceled. Default is 1024. .It Fl R Ar rcvbuf Size of receive buffer to use. Default is 131072 (128kB). .It Fl S Ar sndbuf Size of send buffer to use. Default is 131072 (128kB). .It Fl s Ar sectorsize Sector size for .Nm ggate provider. If not specified, it is taken from device, or set to 512 bytes for files. .It Fl t Ar timeout Number of seconds to wait before an I/O request will be canceled. 0 means no timeout. Default is 0. .It Fl u Ar unit Unit number to use. .It Fl v Do not fork, run in foreground and print debug informations on standard output. .It Ar host Remote host to connect to. .It Ar path Path to a regular file or device. .El .Sh EXIT STATUS Exit status is 0 on success, or 1 if the command fails. To get details about the failure, .Nm should be called with the .Fl v option. .Sh EXAMPLES Make use of CD-ROM device from remote host. .Bd -literal -offset indent server# cat /etc/gg.exports client RO /dev/acd0 server# ggated -.Pp + client# ggatec create -o ro server /dev/acd0 ggate0 client# mount_cd9660 /dev/ggate0 /cdrom .Ed .Sh SEE ALSO .Xr geom 4 , .Xr ggated 8 , .Xr ggatel 8 , .Xr mount_cd9660 8 .Sh AUTHORS The .Nm utility as well as this manual page was written by .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . Index: head/sbin/ifconfig/ifconfig.8 =================================================================== --- head/sbin/ifconfig/ifconfig.8 (revision 162394) +++ head/sbin/ifconfig/ifconfig.8 (revision 162395) @@ -1,1528 +1,1529 @@ .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" From: @(#)ifconfig.8 8.3 (Berkeley) 1/5/94 .\" $FreeBSD$ .\" -.Dd July 25, 2006 +.Dd September 6, 2006 .Dt IFCONFIG 8 .Os .Sh NAME .Nm ifconfig .Nd configure network interface parameters .Sh SYNOPSIS .Nm .Op Fl L .Op Fl k .Op Fl m .Ar interface .Op Cm create .Op Ar address_family .Oo .Ar address .Op Ar dest_address .Oc .Op Ar parameters .Nm .Ar interface .Cm destroy .Nm .Fl a .Op Fl L .Op Fl d .Op Fl m .Op Fl u .Op Fl v .Op Ar address_family .Nm .Fl l .Op Fl d .Op Fl u .Op Ar address_family .Nm .Op Fl L .Op Fl d .Op Fl k .Op Fl m .Op Fl u .Op Fl v .Op Fl C .Nm .Op Fl g Ar groupname .Sh DESCRIPTION The .Nm utility is used to assign an address to a network interface and/or configure network interface parameters. The .Nm utility must be used at boot time to define the network address of each interface present on a machine; it may also be used at a later time to redefine an interface's address or other operating parameters. .Pp The following options are available: .Bl -tag -width indent .It Ar address For the .Tn DARPA Ns -Internet family, the address is either a host name present in the host name data base, .Xr hosts 5 , or a .Tn DARPA Internet address expressed in the Internet standard .Dq dot notation . .Pp It is also possible to use the CIDR notation (also known as the slash notation) to include the netmask. That is, one can specify an address like .Li 192.168.0.1/16 . .Pp For .Dq inet6 family, it is also possible to specify the prefix length using the slash notation, like .Li ::1/128 . See the .Cm prefixlen parameter below for more information. .\" For the Xerox Network Systems(tm) family, .\" addresses are .\" .Ar net:a.b.c.d.e.f , .\" where .\" .Ar net .\" is the assigned network number (in decimal), .\" and each of the six bytes of the host number, .\" .Ar a .\" through .\" .Ar f , .\" are specified in hexadecimal. .\" The host number may be omitted on IEEE 802 protocol .\" (Ethernet, FDDI, and Token Ring) interfaces, .\" which use the hardware physical address, .\" and on interfaces other than the first. .\" For the .\" .Tn ISO .\" family, addresses are specified as a long hexadecimal string, .\" as in the Xerox family. .\" However, two consecutive dots imply a zero .\" byte, and the dots are optional, if the user wishes to (carefully) .\" count out long strings of digits in network byte order. .Pp The link-level .Pq Dq link 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 mechanism used is not ethernet-specific. If the interface is already up when this option is used, it will be briefly brought down and then brought back up again in order to ensure that the receive filter in the underlying ethernet hardware is properly reprogrammed. .It Ar address_family Specify the address family which affects interpretation of the remaining parameters. Since an interface can receive transmissions in differing protocols with different naming schemes, specifying the address family is recommended. The address or protocol families currently supported are .Dq inet , .Dq inet6 , .Dq atalk , .Dq ipx , .\" .Dq iso , and .Dq link . .\" and .\" .Dq ns . The default is .Dq inet . .Dq ether and .Dq lladdr are synonyms for .Dq link . .It Ar dest_address Specify the address of the correspondent on the other end of a point to point link. .It Ar interface This parameter is a string of the form .Dq name unit , for example, .Dq Li ed0 . .It Ar groupname List the interfaces in the given group. .El .Pp The following parameters may be set with .Nm : .Bl -tag -width indent .It Cm add Another name for the .Cm alias parameter. Introduced for compatibility with .Bsx . .It Cm alias Establish an additional network address for this interface. This is sometimes useful when changing network numbers, and one wishes to accept packets addressed to the old interface. If the address is on the same subnet as the first network address for this interface, a non-conflicting netmask must be given. Usually .Li 0xffffffff is most appropriate. .It Fl alias Remove the network address specified. This would be used if you incorrectly specified an alias, or it was no longer needed. If you have incorrectly set an NS address having the side effect of specifying the host portion, removing all NS addresses will allow you to respecify the host portion. .It Cm anycast (Inet6 only.) Specify that the address configured is an anycast address. Based on the current specification, only routers may configure anycast addresses. Anycast address will not be used as source address of any of outgoing IPv6 packets. .It Cm arp Enable the use of the Address Resolution Protocol .Pq Xr arp 4 in mapping between network level addresses and link level addresses (default). This is currently implemented for mapping between .Tn DARPA Internet addresses and .Tn IEEE 802 48-bit MAC addresses (Ethernet, FDDI, and Token Ring addresses). .It Fl arp Disable the use of the Address Resolution Protocol .Pq Xr arp 4 . .It Cm staticarp If the Address Resolution Protocol is enabled, the host will only reply to requests for its addresses, and will never send any requests. .It Fl staticarp If the Address Resolution Protocol is enabled, the host will perform normally, sending out requests and listening for replies. .It Cm broadcast (Inet only.) Specify the address to use to represent broadcasts to the network. The default broadcast address is the address with a host part of all 1's. .It Cm debug Enable driver dependent debugging code; usually, this turns on extra console error logging. .It Fl debug Disable driver dependent debugging code. .It Cm promisc Put interface into permanently promiscuous mode. .It Fl promisc Disable permanently promiscuous mode. .It Cm delete Another name for the .Fl alias parameter. .It Cm down Mark an interface .Dq down . When an interface is marked .Dq down , the system will not attempt to transmit messages through that interface. If possible, the interface will be reset to disable reception as well. This action does not automatically disable routes using the interface. .It Cm group Ar group-name Assign the interface to a .Dq group . Any interface can be in multiple groups. .Pp Cloned interfaces are members of their interface family group by default. For example, a PPP interface such as .Em ppp0 is a member of the PPP interface family group, .Em ppp . .\" The interface(s) the default route(s) point to are members of the .\" .Em egress .\" interface group. .It Cm -group Ar group-name Remove the interface from the given .Dq group . .It Cm eui64 (Inet6 only.) Fill interface index (lowermost 64bit of an IPv6 address) automatically. .It Cm ipdst This is used to specify an Internet host who is willing to receive IP packets encapsulating IPX packets bound for a remote network. An apparent point to point link is constructed, and the address specified will be taken as the IPX address and network of the destination. .It Cm maclabel Ar label If Mandatory Access Control support is enabled in the kernel, set the MAC label to .Ar label . .\" (see .\" .Xr maclabel 7 ) . .It Cm media Ar type If the driver supports the media selection system, set the media type of the interface to .Ar type . Some interfaces support the mutually exclusive use of one of several different physical media connectors. For example, a 10Mbit/s Ethernet interface might support the use of either .Tn AUI or twisted pair connectors. Setting the media type to .Cm 10base5/AUI would change the currently active connector to the AUI port. Setting it to .Cm 10baseT/UTP would activate twisted pair. Refer to the interfaces' driver specific documentation or man page for a complete list of the available types. .It Cm mediaopt Ar opts If the driver supports the media selection system, set the specified media options on the interface. The .Ar opts argument is a comma delimited list of options to apply to the interface. Refer to the interfaces' driver specific man page for a complete list of available options. .It Fl mediaopt Ar opts If the driver supports the media selection system, disable the specified media options on the interface. .It Cm mode Ar mode If the driver supports the media selection system, set the specified operating mode on the interface to .Ar mode . For IEEE 802.11 wireless interfaces that support multiple operating modes this directive is used to select between 802.11a .Pq Cm 11a , 802.11b .Pq Cm 11b , and 802.11g .Pq Cm 11g operating modes. .It Cm name Ar name Set the interface name to .Ar name . .It Cm rxcsum , txcsum If the driver supports user-configurable checksum offloading, enable receive (or transmit) checksum offloading on the interface. Some drivers may not be able to enable these flags independently of each other, so setting one may also set the other. The driver will offload as much checksum work as it can reliably support, the exact level of offloading varies between drivers. .It Fl rxcsum , txcsum If the driver supports user-configurable checksum offloading, disable receive (or transmit) checksum offloading on the interface. These settings may not always be independent of each other. .It Cm tso If the driver supports .Xr tcp 4 segmentation offloading, enable TSO on the interface. Some drivers may not be able to support TSO for .Xr ip 4 and .Xr ip6 4 packets, so they may enable only one of them. .It Fl tso If the driver supports .Xr tcp 4 segmentation offloading, disable TSO on the interface. It will always disable TSO for .Xr ip 4 and .Xr ip6 4 . .It Cm vlanmtu , vlanhwtag If the driver offers user-configurable VLAN support, enable reception of extended frames or tag processing in hardware, respectively. Note that this must be issued on a physical interface associated with .Xr vlan 4 , not on a .Xr vlan 4 interface itself. .It Fl vlanmtu , vlanhwtag If the driver offers user-configurable VLAN support, disable reception of extended frames or tag processing in hardware, respectively. .It Cm polling Turn on .Xr polling 4 feature and disable interrupts on the interface, if driver supports this mode. .It Fl polling Turn off .Xr polling 4 feature and enable interrupt mode on the interface. .It Cm create Create the specified network pseudo-device. If the interface is given without a unit number, try to create a new device with an arbitrary unit number. If creation of an arbitrary device is successful, the new device name is printed to standard output unless the interface is renamed or destroyed in the same .Nm invocation. .It Cm destroy Destroy the specified network pseudo-device. .It Cm plumb Another name for the .Cm create parameter. Included for .Tn Solaris compatibility. .It Cm unplumb Another name for the .Cm destroy parameter. Included for .Tn Solaris compatibility. .It Cm metric Ar n Set the routing metric of the interface to .Ar n , default 0. The routing metric is used by the routing protocol .Pq Xr routed 8 . Higher metrics have the effect of making a route less favorable; metrics are counted as addition hops to the destination network or host. .It Cm mtu Ar n Set the maximum transmission unit of the interface to .Ar n , default is interface specific. The MTU is used to limit the size of packets that are transmitted on an interface. Not all interfaces support setting the MTU, and some interfaces have range restrictions. .It Cm netmask Ar mask .\" (Inet and ISO.) (Inet only.) Specify how much of the address to reserve for subdividing networks into sub-networks. The mask includes the network part of the local address and the subnet part, which is taken from the host field of the address. The mask can be specified as a single hexadecimal number with a leading .Ql 0x , with a dot-notation Internet address, or with a pseudo-network name listed in the network table .Xr networks 5 . The mask contains 1's for the bit positions in the 32-bit address which are to be used for the network and subnet parts, and 0's for the host part. The mask should contain at least the standard network portion, and the subnet field should be contiguous with the network portion. .Pp The netmask can also be specified in CIDR notation after the address. See the .Ar address option above for more information. .It Cm prefixlen Ar len (Inet6 only.) Specify that .Ar len bits are reserved for subdividing networks into sub-networks. The .Ar len must be integer, and for syntactical reason it must be between 0 to 128. It is almost always 64 under the current IPv6 assignment rule. If the parameter is omitted, 64 is used. .Pp The prefix can also be specified using the slash notation after the address. See the .Ar address option above for more information. .\" see .\" Xr eon 5 . .\" .It Cm nsellength Ar n .\" .Pf ( Tn ISO .\" only) .\" This specifies a trailing number of bytes for a received .\" .Tn NSAP .\" used for local identification, the remaining leading part of which is .\" taken to be the .\" .Tn NET .\" (Network Entity Title). .\" The default value is 1, which is conformant to US .\" .Tn GOSIP . .\" When an ISO address is set in an ifconfig command, .\" it is really the .\" .Tn NSAP .\" which is being specified. .\" For example, in .\" .Tn US GOSIP , .\" 20 hex digits should be .\" specified in the .\" .Tn ISO NSAP .\" to be assigned to the interface. .\" There is some evidence that a number different from 1 may be useful .\" for .\" .Tn AFI .\" 37 type addresses. .It Cm range Ar netrange Under appletalk, set the interface to respond to a .Ar netrange of the form .Ar startnet Ns - Ns Ar endnet . Appletalk uses this scheme instead of netmasks though .Fx implements it internally as a set of netmasks. .It Cm remove Another name for the .Fl alias parameter. Introduced for compatibility with .Bsx . .It Cm phase The argument following this specifies the version (phase) of the Appletalk network attached to the interface. Values of 1 or 2 are permitted. .Sm off .It Cm link Op Cm 0 No - Cm 2 .Sm on Enable special processing of the link level of the interface. These three options are interface specific in actual effect, however, they are in general used to select special modes of operation. An example of this is to enable SLIP compression, or to select the connector type for some Ethernet cards. Refer to the man page for the specific driver for more information. .Sm off .It Fl link Op Cm 0 No - Cm 2 .Sm on Disable special processing at the link level with the specified interface. .It Cm monitor Put the interface in monitor mode. No packets are transmitted, and received packets are discarded after .Xr bpf 4 processing. .It Fl monitor Take the interface out of monitor mode. .It Cm up Mark an interface .Dq up . This may be used to enable an interface after an .Dq Nm Cm down . It happens automatically when setting the first address on an interface. If the interface was reset when previously marked down, the hardware will be re-initialized. .El .Pp The following parameters are specific to IEEE 802.11 wireless interfaces: .Bl -tag -width indent .It Cm apbridge When operating as an access point, pass packets between wireless clients directly (default). To instead let them pass up through the system and be forwarded using some other mechanism, use .Fl apbridge . Disabling the internal bridging is useful when traffic is to be processed with packet filtering. .It Cm authmode Ar mode Set the desired authentication mode in infrastructure mode. Not all adaptors support all modes. The set of valid modes is .Cm none , open , shared (shared key), .Cm 8021x (IEEE 802.1x), and .Cm wpa (IEEE WPA/WPA2/802.11i). The .Cm 8021x and .Cm wpa modes are only useful when using an authentication service (a supplicant for client operation or an authenticator when operating as an access point). Modes are case insensitive. .It Cm bintval Ar interval Set the interval at which beacon frames are sent when operating in ad-hoc or ap mode. The .Ar interval parameter is specified in TU's (1/1024 msecs). By default beacon frames are transmitted every 100 TU's. .It Cm bmissthreshold Ar count Set the number of consecutive missed beacons at which the station -will attempt to roam (i.e. search for a new access point). +will attempt to roam (i.e., search for a new access point). The .Ar count -parameter is must be in the range 1 to 255; though the -upper bound may be reduced according to device capabilities.. +parameter must be in the range 1 to 255; though the +upper bound may be reduced according to device capabilities. The default threshold is 7 consecutive missed beacons; but this may be overridden by the device driver. Another name for the .Cm bmissthreshold parameter is .Cm bmiss . .It Cm bssid Ar address Specify the MAC address of the access point to use when operating as a station in a BSS network. This overrides any automatic selection done by the system. To disable a previously selected access point, supply .Cm any , none , or .Cm - for the address. This option is useful when more than one access points have the same SSID. Another name for the .Cm bssid parameter is .Cm ap . .It Cm burst Enable packet bursting. Packet bursting is a transmission technique whereby the wireless medium is acquired once to send multiple frames and the interframe spacing is reduced. This technique can significantly increase throughput by reducing transmission overhead. Packet bursting is supported by the 802.11e QoS specification and some devices that do not support QoS may still be capable. By default packet bursting is enabled if a device is capable of doing it. To disable packet bursting, use .Fl burst . .It Cm chanlist Ar channels Set the desired channels to use when scanning for access points, neighbors in an IBSS network, or looking for unoccupied channels when operating as an access point. The set of channels is specified as a comma-separated list with each element in the list representing either a single channel number or a range of the form .Dq Li a-b . Channel numbers must be in the range 1 to 255 and be permissible according to the operating characteristics of the device. .It Cm channel Ar number Set a single desired channel. Channels range from 1 to 255, but the exact selection available depends on the region your adaptor was manufactured for. Setting the channel to .Li 0 , .Cm any , or .Cm - will give you the default for your adaptor. Some adaptors ignore this setting unless you are in ad-hoc mode. Alternatively the frequency, in megahertz, may be specified instead of the channel number. .It Cm deftxkey Ar index Set the default key to use for transmission. Typically this is only set when using WEP encryption. The .Cm weptxkey is an alias for this request; it is provided for backwards compatibility. .It Cm dtimperiod Ar period Set the DTIM period for transmitting buffered multicast data frames when operating in ap mode. The .Ar period specifies the number of beacon intervals between DTIM and must be in the range 1 to 15. By default DTIM is 1 (i.e., DTIM occurs at each beacon). .It Cm fragthreshold Ar length Set the threshold for which transmitted frames are broken into fragments. The .Ar length argument is the frame size in bytes and must be in the range 256 to 2346. Setting .Ar length to .Li 2346 , .Cm any , or .Cm - disables transmit fragmentation. Not all adaptors honor the fragmentation threshold. .It Cm hidessid When operating as an access point, do not broadcast the SSID in beacon frames or respond to probe request frames unless they are directed to the ap (i.e., they include the ap's SSID). By default, the SSID is included in beacon frames and undirected probe request frames are answered. To re-enable the broadcast of the SSID etc., use .Fl hidessid . .It Cm list active Display the list of channels available for use taking into account any restrictions set with the .Cm chanlist directive. See the description of .Cm list chan for more information. .It Cm list caps Display the adaptor's capabilities, including the operating modes supported. .It Cm list chan Display the list of channels available for use. Channels are shown with their IEEE channel number, equivalent frequency, and usage modes. Channels identified as .Ql 11g are also usable in .Ql 11b mode. Channels identified as .Ql 11a Turbo may be used only for Atheros' Static Turbo mode -.Pq specified with Cm mediaopt turbo . +(specified with +. Cm mediaopt turbo ) . Channels marked with a .Ql * have a regulatory constraint that they be passively scanned. This means a station is not permitted to transmit on the channel until it identifies the channel is being used for 802.11 communication; typically by hearing a beacon frame from an access point operating on the channel. .Cm list freq is another way of requesting this information. .It Cm list mac Display the current MAC Access Control List state. Each address is prefixed with a character that indicates the current policy applied to it: .Ql + indicates the address is allowed access, .Ql - indicates the address is denied access, .Ql * indicates the address is present but the current policy open (so the ACL is not consulted). .It Cm list scan Display the access points and/or ad-hoc neighbors located in the vicinity. This information may be updated automatically by the adaptor and/or with a .Cm scan request. .Cm list ap is another way of requesting this information. .It Cm list sta When operating as an access point display the stations that are currently associated. When operating in ad-hoc mode display stations identified as neighbors in the IBSS. Capabilities advertised by the stations are described under the .Cm scan request. Depending on the capabilities of the stations the following flags can be included in the output: .Bl -tag -width 3n .It Li A Authorized. Indicates that the station is permitted to send/receive data frames. .It Li E Extended Rate Phy (ERP). Indicates that the station is operating in an 802.11g network using extended transmit rates. .It Li P Power Save. Indicates that the station is operating in power save mode. .It Li Q Quality of Service (QoS). Indicates that the station is using QoS encapsulation for data frame. QoS encapsulation is enabled only when WME mode is enabled. .El .It Cm list wme Display the current parameters to use when operating in WME mode. When WME mode is enabled for an adaptor this information will be displayed with the regular status; this command is mostly useful for examining parameters when WME mode is disabled. See the description of the .Cm wme directive for information on the various parameters. .It Cm mcastrate Ar rate Set the rate for transmitting multicast/broadcast frames. -Rates are specified as megabits/second in decimal; e.g. 5.5 for 5.5 Mb/s. +Rates are specified as megabits/second in decimal; e.g.\& 5.5 for 5.5 Mb/s. This rate should be valid for the current operating conditions; if an invalid rate is specified drivers are free to chose an appropriate rate. .It Cm powersave Enable powersave operation. When operating as a client, the station will conserve power by periodically turning off the radio and listening for messages from the access point telling it there are packets waiting. The station must then retrieve the packets. When operating as an access point, the station must honor power save operation of associated clients. Not all devices support power save operation, either as a client or as an access point. Use .Fl powersave to disable powersave operation. .It Cm powersavesleep Ar sleep Set the desired max powersave sleep time in milliseconds. .It Cm protmode Ar technique For interfaces operating in 802.11g, use the specified .Ar technique for protecting OFDM frames in a mixed 11b/11g network. The set of valid techniques is .Cm off , cts (CTS to self), and .Cm rtscts (RTS/CTS). Technique names are case insensitive. .It Cm pureg When operating as an access point in 802.11g mode allow only 11g-capable stations to associate (11b-only stations are not permitted to associate). To allow both 11g and 11b-only stations to associate, use .Fl pureg . .It Cm roaming Ar mode When operating as a station, control how the system will behave when communication with the current access point is broken. The .Ar mode argument may be one of .Cm device (leave it to the hardware device to decide), .Cm auto (handle either in the device or the operating system\[em]as appropriate), .Cm manual (do nothing until explicitly instructed). By default, the device is left to handle this if it is capable; otherwise, the operating system will automatically attempt to reestablish communication. Manual mode is mostly useful when an application wants to control the selection of an access point. .It Cm rtsthreshold Ar length Set the threshold for which transmitted frames are preceded by transmission of an RTS control frame. The .Ar length argument is the frame size in bytes and must be in the range 1 to 2346. Setting .Ar length to .Li 2346 , .Cm any , or .Cm - disables transmission of RTS frames. Not all adaptors support setting the RTS threshold. .It Cm ssid Ar ssid Set the desired Service Set Identifier (aka network name). The SSID is a string up to 32 characters in length and may be specified as either a normal string or in hexadecimal when preceded by .Ql 0x . Additionally, the SSID may be cleared by setting it to .Ql - . .It Cm scan Initiate a scan of neighboring stations, wait for it to complete, and display all stations found. Only the super-user can initiate a scan. Depending on the capabilities of the APs, the following flags can be included in the output: .Bl -tag -width 3n .It Li A Channel Agility. Indicates that the station support channel hopping as described by the IEEE 802.11b specification. .It Li B Packet Binary Convolution Code (PBCC). A modulation alternative to the standard OFDM method. .It Dv C Pollreq .It Dv c Pollable .It Dv D Direct Sequence Spread Spectrum (DSSSOFDM). Indicates the the station supports DSSS modulation. .It Li E Extended Service Set (ESS). Indicates that the station is part of an infrastructure network (in contrast to an IBSS/ad-hoc network). .It Li I IBSS/ad-hoc network. Indicates that the station is part of an ad-hoc network (in contrast to an ESS network). .It Li P Privacy. Data confidentiality is required for all data frames exchanged within the BSS. This means that this BSS requires the station to use cryptographic means such as WEP, TKIP or AES-CCMP to encrypt/decrypt data frames being exchanged with others. .It Dv R Robust Security Network (RSN). Indicates that the station supports the IEEE 802.11i authentication and key management protocol. .It Li S Short Preamble. Indicates that the network is using short preambles (defined in 802.11b High Rate/DSSS PHY, short preamble utilizes a 56 bit sync field in contrast to a 128 bit field used in long preamble mode). .It Li s Short slot time. Indicates that the network is using a short slot time. .El .Pp The .Cm list scan request can be used to show recent scan results without initiating a new scan. .It Cm stationname Ar name Set the name of this station. It appears that the station name is not really part of the IEEE 802.11 protocol though all interfaces seem to support it. As such it only seems to be meaningful to identical or virtually identical equipment. Setting the station name is identical in syntax to setting the SSID. .It Cm txpower Ar power Set the power used to transmit frames. The .Ar power argument is a unitless value in the range 0 to 100 that is interpreted by drivers to derive a device-specific value. Out of range values are truncated. Typically only a few discreet power settings are available and the driver will use the setting closest to the specified value. Not all adaptors support changing the transmit power. .It Cm wepmode Ar mode Set the desired WEP mode. Not all adaptors support all modes. The set of valid modes is .Cm off , on , and .Cm mixed . The .Cm mixed mode explicitly tells the adaptor to allow association with access points which allow both encrypted and unencrypted traffic. On these adaptors, .Cm on means that the access point must only allow encrypted connections. On other adaptors, .Cm on is generally another name for .Cm mixed . Modes are case insensitive. .It Cm weptxkey Ar index Set the WEP key to be used for transmission. This is the same as setting the default transmission key with .Cm deftxkey . .It Cm wepkey Ar key Ns | Ns Ar index : Ns Ar key Set the selected WEP key. If an .Ar index is not given, key 1 is set. A WEP key will be either 5 or 13 characters (40 or 104 bits) depending of the local network and the capabilities of the adaptor. It may be specified either as a plain string or as a string of hexadecimal digits preceded by .Ql 0x . For maximum portability, hex keys are recommended; the mapping of text keys to WEP encryption is usually driver-specific. In particular, the .Tn Windows drivers do this mapping differently to .Fx . A key may be cleared by setting it to .Ql - . If WEP is supported then there are at least four keys. Some adaptors support more than four keys. If that is the case, then the first four keys (1-4) will be the standard temporary keys and any others will be adaptor specific keys such as permanent keys stored in NVRAM. .It Cm wme Enable Wireless Multimedia Extensions (WME) support, if available, for the specified interface. WME is a subset of the IEEE 802.11e standard to support the efficient communication of realtime and multimedia data. To disable WME support, use .Fl wme . .Pp The following parameters are meaningful only when WME support is in use. Parameters are specified per-AC (Access Category) and split into those that are used by a station when acting as an access point and those for client stations in the BSS. The latter are received from the access point and may not be changed (at the station). The following Access Categories are recognized: .Pp .Bl -tag -width ".Cm AC_BK" -compact .It Cm AC_BE (or .Cm BE ) best effort delivery, .It Cm AC_BK (or .Cm BK ) background traffic, .It Cm AC_VI (or .Cm VI ) video traffic, .It Cm AC_VO (or .Cm VO ) voice traffic. .El .Pp AC parameters are case-insensitive. Traffic classification is done in the operating system using the vlan priority associated with data frames or the ToS (Type of Service) indication in IP-encapsulated frames. If neither information is present, traffic is assigned to the Best Effort (BE) category. .Bl -tag -width indent .It Cm ack Ar ac Set the ACK policy for QoS transmissions by the local station; this controls whether or not data frames transmitted by a station require an ACK response from the receiving station. To disable waiting for an ACK use .Fl ack . This parameter is applied only to the local station. .It Cm acm Ar ac Enable the Admission Control Mandatory (ACM) mechanism for transmissions by the local station. To disable the ACM use .Fl acm . On stations in a BSS this parameter is read-only and indicates the setting received from the access point. NB: ACM is not supported right now. .It Cm aifs Ar ac Ar count Set the Arbitration Inter Frame Spacing (AIFS) channel access parameter to use for transmissions by the local station. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm cwmin Ar ac Ar count Set the CWmin channel access parameter to use for transmissions by the local station. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm cwmax Ar ac Ar count Set the CWmax channel access parameter to use for transmissions by the local station. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm txoplimit Ar ac Ar limit Set the Transmission Opportunity Limit channel access parameter to use for transmissions by the local station. This parameter defines an interval of time when a WME station has the right to initiate transmissions onto the wireless medium. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm bss:aifs Ar ac Ar count Set the AIFS channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .It Cm bss:cwmin Ar ac Ar count Set the CWmin channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .It Cm bss:cwmax Ar ac Ar count Set the CWmax channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .It Cm bss:txoplimit Ar ac Ar limit Set the TxOpLimit channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .El .El .Pp The following parameters support an optional access control list feature available with some adaptors when operating in ap mode; see .Xr wlan_acl 4 . This facility allows an access point to accept/deny association requests based on the MAC address of the station. Note that this feature does not significantly enhance security as MAC address spoofing is easy to do. .Bl -tag -width indent .It Cm mac:add Ar address Add the specified MAC address to the database. Depending on the policy setting association requests from the specified station will be allowed or denied. .It Cm mac:allow Set the ACL policy to permit association only by stations registered in the database. .It Cm mac:del Ar address Delete the specified MAC address from the database. .It Cm mac:deny Set the ACL policy to deny association only by stations registered in the database. .It Cm mac:kick Ar address Force the specified station to be deauthenticated. This typically is done to block a station after updating the address database. .It Cm mac:open Set the ACL policy to allow all stations to associate. .It Cm mac:flush Delete all entries in the database. .El .Pp The following parameters are for compatibility with other systems: .Bl -tag -width indent .It Cm nwid Ar ssid Another name for the .Cm ssid parameter. Included for .Nx compatibility. .It Cm station Ar name Another name for the .Cm stationname parameter. Included for .Bsx compatibility. .It Cm wep Another way of saying .Cm wepmode on . Included for .Bsx compatibility. .It Fl wep Another way of saying .Cm wepmode off . Included for .Bsx compatibility. .It Cm nwkey key Another way of saying: .Dq Li "wepmode on weptxkey 1 wepkey 1:key wepkey 2:- wepkey 3:- wepkey 4:-" . Included for .Nx compatibility. .It Cm nwkey Xo .Sm off .Ar n : k1 , k2 , k3 , k4 .Sm on .Xc Another way of saying .Dq Li "wepmode on weptxkey n wepkey 1:k1 wepkey 2:k2 wepkey 3:k3 wepkey 4:k4" . Included for .Nx compatibility. .It Fl nwkey Another way of saying .Cm wepmode off . Included for .Nx compatibility. .El .Pp The following parameters are specific to bridge interfaces: .Bl -tag -width indent .It Cm addm Ar interface Add the interface named by .Ar interface as a member of the bridge. The interface is put into promiscuous mode so that it can receive every packet sent on the network. .It Cm deletem Ar interface Remove the interface named by .Ar interface from the bridge. Promiscuous mode is disabled on the interface when it is removed from the bridge. .It Cm maxaddr Ar size Set the size of the bridge address cache to .Ar size . The default is 100 entries. .It Cm timeout Ar seconds Set the timeout of address cache entries to .Ar seconds seconds. If .Ar seconds is zero, then address cache entries will not be expired. The default is 240 seconds. .It Cm addr Display the addresses that have been learned by the bridge. .It Cm static Ar interface-name Ar address Add a static entry into the address cache pointing to .Ar interface-name . Static entries are never aged out of the cache or re-placed, even if the address is seen on a different interface. .It Cm deladdr Ar address Delete .Ar address from the address cache. .It Cm flush Delete all dynamically-learned addresses from the address cache. .It Cm flushall Delete all addresses, including static addresses, from the address cache. .It Cm discover Ar interface Mark an interface as a .Dq discovering interface. When the bridge has no address cache entry (either dynamic or static) for the destination address of a packet, the bridge will forward the packet to all member interfaces marked as .Dq discovering . This is the default for all interfaces added to a bridge. .It Cm -discover Ar interface Clear the .Dq discovering attribute on a member interface. For packets without the .Dq discovering attribute, the only packets forwarded on the interface are broadcast or multicast packets and packets for which the destination address is known to be on the interface's segment. .It Cm learn Ar interface Mark an interface as a .Dq learning interface. When a packet arrives on such an interface, the source address of the packet is entered into the address cache as being a destination address on the interface's segment. This is the default for all interfaces added to a bridge. .It Cm -learn Ar interface Clear the .Dq learning attribute on a member interface. .It Cm span Ar interface Add the interface named by .Ar interface as a span port on the bridge. Span ports transmit a copy of every frame received by the bridge. This is most useful for snooping a bridged network passively on another host connected to one of the span ports of the bridge. .It Cm -span Ar interface Delete the interface named by .Ar interface from the list of span ports of the bridge. .It Cm stp Ar interface Enable Spanning Tree protocol on .Ar interface . The .Xr if_bridge 4 driver has support for the IEEE 802.1D Spanning Tree protocol (STP). Spanning Tree is used to detect and remove loops in a network topology. .It Cm -stp Ar interface Disable Spanning Tree protocol on .Ar interface . This is the default for all interfaces added to a bridge. .It Cm maxage Ar seconds Set the time that a Spanning Tree protocol configuration is valid. The default is 20 seconds. The minimum is 1 second and the maximum is 255 seconds. .It Cm fwddelay Ar seconds Set the time that must pass before an interface begins forwarding packets when Spanning Tree is enabled. The default is 15 seconds. The minimum is 1 second and the maximum is 255 seconds. .It Cm hellotime Ar seconds Set the time between broadcasting of Spanning Tree protocol configuration messages. The default is 2 seconds. The minimum is 1 second and the maximum is 255 seconds. .It Cm priority Ar value Set the bridge priority for Spanning Tree. The default is 32768. The minimum is 0 and the maximum is 65536. .It Cm ifpriority Ar interface Ar value Set the Spanning Tree priority of .Ar interface to .Ar value . The default is 128. The minimum is 0 and the maximum is 255. .It Cm ifpathcost Ar interface Ar value Set the Spanning Tree path cost of .Ar interface to .Ar value . The default is 55. The minimum is 0 and the maximum is 65535. .El .Pp The following parameters are specific to IP tunnel interfaces, .Xr gif 4 : .Bl -tag -width indent .It Cm tunnel Ar src_addr dest_addr Configure the physical source and destination address for IP tunnel interfaces. The arguments .Ar src_addr and .Ar dest_addr are interpreted as the outer source/destination for the encapsulating IPv4/IPv6 header. .It Fl tunnel Unconfigure the physical source and destination address for IP tunnel interfaces previously configured with .Cm tunnel . .It Cm deletetunnel Another name for the .Fl tunnel parameter. .El .Pp The following parameters are specific to .Xr pfsync 4 interfaces: .Bl -tag -width indent .It Cm maxupd Ar n Set the maximum number of updates for a single state which can be collapsed into one. -This is an 8-bit number; the default value is 128. +This is an 8-bit number; the default value is 128. .El .Pp The following parameters are specific to .Xr vlan 4 interfaces: .Bl -tag -width indent .It Cm vlan Ar vlan_tag Set the VLAN tag value to .Ar vlan_tag . This value is a 16-bit number which is used to create an 802.1Q VLAN header for packets sent from the .Xr vlan 4 interface. Note that .Cm vlan and .Cm vlandev must both be set at the same time. .It Cm vlandev Ar iface Associate the physical interface .Ar iface with a .Xr vlan 4 interface. Packets transmitted through the .Xr vlan 4 interface will be diverted to the specified physical interface .Ar iface with 802.1Q VLAN encapsulation. Packets with 802.1Q encapsulation received by the parent interface with the correct VLAN tag will be diverted to the associated .Xr vlan 4 pseudo-interface. The .Xr vlan 4 interface is assigned a copy of the parent interface's flags and the parent's ethernet address. The .Cm vlandev and .Cm vlan must both be set at the same time. If the .Xr vlan 4 interface already has a physical interface associated with it, this command will fail. To change the association to another physical interface, the existing association must be cleared first. .Pp Note: if the hardware tagging capability is set on the parent interface, the .Xr vlan 4 pseudo interface's behavior changes: the .Xr vlan 4 interface recognizes that the parent interface supports insertion and extraction of VLAN tags on its own (usually in firmware) and that it should pass packets to and from the parent unaltered. .It Fl vlandev Op Ar iface If the driver is a .Xr vlan 4 pseudo device, disassociate the parent interface from it. This breaks the link between the .Xr vlan 4 interface and its parent, clears its VLAN tag, flags and its link address and shuts the interface down. The .Ar iface argument is useless and hence deprecated. .El .Pp The following parameters are specific to .Xr carp 4 interfaces: .Bl -tag -width indent .It Cm advbase Ar seconds Specifies the base of the advertisement interval in seconds. The acceptable values are 1 to 255. The default value is 1. .\" The default value is .\" .Dv CARP_DFLTINTV . .It Cm advskew Ar interval Specifies the skew to add to the base advertisement interval to make one host advertise slower than another host. It is specified in 1/256 of seconds. The acceptable values are 1 to 254. The default value is 0. .It Cm pass Ar phrase Set the authentication key to .Ar phrase . .It Cm vhid Ar n Set the virtual host ID. This is a required setting. Acceptable values are 1 to 255. .El .Pp The .Nm utility displays the current configuration for a network interface when no optional parameters are supplied. If a protocol family is specified, .Nm will report only the details specific to that protocol family. .Pp If the .Fl m flag is passed before an interface name, .Nm will display the capability list and all of the supported media for the specified interface. If .Fl L flag is supplied, address lifetime is displayed for IPv6 addresses, as time offset string. .Pp Optionally, the .Fl a flag may be used instead of an interface name. This flag instructs .Nm to display information about all interfaces in the system. The .Fl d flag limits this to interfaces that are down, and .Fl u limits this to interfaces that are up. When no arguments are given, .Fl a is implied. .Pp The .Fl l flag may be used to list all available interfaces on the system, with no other additional information. Use of this flag is mutually exclusive with all other flags and commands, except for .Fl d (only list interfaces that are down) and .Fl u (only list interfaces that are up). .Pp The .Fl v flag may be used to get more verbose status for an interface. .Pp The .Fl C flag may be used to list all of the interface cloners available on the system, with no additional information. Use of this flag is mutually exclusive with all other flags and commands. .Pp The .Fl k flag causes keying information for the interface, if available, to be printed. For example, the values of 802.11 WEP keys will be printed, if accessible to the current user. This information is not printed by default, as it may be considered sensitive. .Pp Only the super-user may modify the configuration of a network interface. .Sh NOTES The media selection system is relatively new and only some drivers support it (or have need for it). .Sh DIAGNOSTICS Messages indicating the specified interface does not exist, the requested address is unknown, or the user is not privileged and tried to alter an interface's configuration. .Sh SEE ALSO .Xr netstat 1 , .Xr carp 4 , .Xr netintro 4 , .Xr pfsync 4 , .Xr polling 4 , .Xr vlan 4 , .\" .Xr eon 5 , .Xr rc 8 , .Xr routed 8 , .Xr sysctl 8 .Sh HISTORY The .Nm utility appeared in .Bx 4.2 . .Sh BUGS Basic IPv6 node operation requires a link-local address on each interface configured for IPv6. Normally, such an address is automatically configured by the kernel on each interface added to the system; this behaviour may be disabled by setting the sysctl MIB variable .Va net.inet6.ip6.auto_linklocal to 0. .Pp If you delete such an address using .Nm , the kernel may act very oddly. Do this at your own risk. Index: head/sbin/ipfw/ipfw.8 =================================================================== --- head/sbin/ipfw/ipfw.8 (revision 162394) +++ head/sbin/ipfw/ipfw.8 (revision 162395) @@ -1,2515 +1,2517 @@ .\" .\" $FreeBSD$ .\" .Dd July 25, 2006 .Dt IPFW 8 .Os .Sh NAME .Nm ipfw .Nd IP firewall and traffic shaper control program .Sh SYNOPSIS .Nm .Op Fl cq .Cm add .Ar rule .Nm .Op Fl acdefnNStT .Brq Cm list | show .Op Ar rule | first-last ... .Nm .Op Fl f | q .Cm flush .Nm .Op Fl q .Brq Cm delete | zero | resetlog .Op Cm set .Op Ar number ... .Nm .Cm enable .Brq Cm firewall | altq | one_pass | debug | verbose | dyn_keepalive .Nm .Cm disable .Brq Cm firewall | altq | one_pass | debug | verbose | dyn_keepalive .Pp .Nm .Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ... .Nm .Cm set move .Op Cm rule .Ar number Cm to Ar number .Nm .Cm set swap Ar number number .Nm .Cm set show .Pp .Nm .Cm table Ar number Cm add Ar addr Ns Oo / Ns Ar masklen Oc Op Ar value .Nm .Cm table Ar number Cm delete Ar addr Ns Op / Ns Ar masklen .Nm .Cm table Ar number Cm flush .Nm .Cm table Ar number Cm list .Pp .Nm .Brq Cm pipe | queue .Ar number .Cm config .Ar config-options .Nm .Op Fl s Op Ar field .Brq Cm pipe | queue .Brq Cm delete | list | show .Op Ar number ... .Pp .Nm .Op Fl cfnNqS .Oo .Fl p Ar preproc .Oo .Ar preproc-flags .Oc .Oc .Ar pathname .Sh DESCRIPTION The .Nm utility is the user interface for controlling the .Xr ipfw 4 firewall and the .Xr dummynet 4 traffic shaper in .Fx . .Pp An .Nm configuration, or .Em ruleset , is made of a list of .Em rules numbered from 1 to 65535. Packets are passed to .Nm from a number of different places in the protocol stack (depending on the source and destination of the packet, it is possible that .Nm is invoked multiple times on the same packet). The packet passed to the firewall is compared against each of the rules in the firewall .Em ruleset . When a match is found, the action corresponding to the matching rule is performed. .Pp Depending on the action and certain system settings, packets can be reinjected into the firewall at some rule after the matching one for further processing. .Pp An .Nm ruleset always includes a .Em default rule (numbered 65535) which cannot be modified or deleted, and matches all packets. The action associated with the .Em default rule can be either .Cm deny or .Cm allow depending on how the kernel is configured. .Pp If the ruleset includes one or more rules with the .Cm keep-state or .Cm limit option, then .Nm assumes a .Em stateful 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 at the first occurrence of a .Cm check-state , .Cm keep-state or .Cm limit rule, and are typically used to open the firewall on-demand to legitimate traffic only. See the .Sx STATEFUL FIREWALL and .Sx EXAMPLES Sections below for more information on the stateful behaviour of .Nm . .Pp All rules (including dynamic ones) have a few associated counters: a packet count, a byte count, a log count and a timestamp indicating the time of the last match. Counters can be displayed or reset with .Nm commands. .Pp Rules can be added with the .Cm add command; deleted individually or in groups with the .Cm delete command, and globally (except those in set 31) with the .Cm flush command; displayed, optionally with the content of the counters, using the .Cm show and .Cm list commands. Finally, counters can be reset with the .Cm zero and .Cm resetlog commands. .Pp Also, each rule belongs to one of 32 different .Em sets , and there are .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 install temporary configurations, or to test them. See Section .Sx SETS OF RULES for more information on .Em sets . .Pp The following options are available: .Bl -tag -width indent .It Fl a While listing, show counter values. The .Cm show command just implies this option. .It Fl b Only show the action and the comment, not the body of a rule. 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 when this does not carry any additional information. .It Fl d While listing, show dynamic rules in addition to static ones. .It Fl e While listing, if the .Fl d option was specified, also show expired dynamic rules. .It Fl f Do not ask for confirmation for commands that can cause problems if misused, .No i.e. Cm flush . If there is no tty associated with the process, this is implied. .It Fl n Only check syntax of the command strings, without actually passing them to the kernel. .It Fl N Try to resolve addresses and service names in output. .It Fl q While .Cm add Ns ing , .Cm zero Ns ing , .Cm resetlog Ns ging or .Cm flush Ns ing , be quiet about actions (implies .Fl f ) . This is useful for adjusting rules by executing multiple .Nm commands in a script (e.g., .Ql sh\ /etc/rc.firewall ) , or by processing a file of many .Nm -rules across a remote login session. It also stops a table add or delete +rules across a remote login session. +It also stops a table add or delete from failing if the entry already exists or is not present. If a .Cm flush is performed in normal (verbose) mode (with the default kernel configuration), it prints a message. Because all rules are flushed, the message might not be delivered to the login session, causing the remote login session to be closed and the remainder of the ruleset to not be processed. Access to the console would then be required to recover. .It Fl S While listing rules, show the .Em set each rule belongs to. If this flag is not specified, disabled rules will not be listed. .It Fl s Op Ar field While listing pipes, sort according to one of the four counters (total or current packets or bytes). .It Fl t While listing, show last match timestamp (converted with ctime()). .It Fl T While listing, show last match timestamp (as seconds from the epoch). This form can be more convenient for postprocessing by scripts. .El .Pp To ease configuration, rules can be put into a file which is processed using .Nm as shown in the last synopsis line. An absolute .Ar pathname must be used. The file will be read line by line and applied as arguments to the .Nm utility. .Pp Optionally, a preprocessor can be specified using .Fl p Ar preproc where .Ar pathname is to be piped through. Useful preprocessors include .Xr cpp 1 and .Xr m4 1 . If .Ar preproc does not start with a slash .Pq Ql / as its first character, the usual .Ev PATH 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). Once .Fl p has been specified, any additional arguments as passed on to the preprocessor for interpretation. This allows for flexible configuration files (like conditionalizing them on the local hostname) and the use of macros to centralize frequently required arguments like IP addresses. .Pp The .Nm .Cm pipe and .Cm queue commands are used to configure the traffic shaper, as shown in the .Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION 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 .Nm .Cm disable .Cm firewall to temporarily disable the firewall to regain access to the network, allowing you to fix the problem. .Sh PACKET FLOW A packet is checked against the active ruleset in multiple places in the protocol stack, under control of several sysctl variables. These places and variables are shown below, and it is important to have this picture in mind in order to design a correct ruleset. .Bd -literal -offset indent ^ to upper layers V | | +----------->-----------+ ^ V [ip(6)_input] [ip(6)_output] net.inet(6).ip(6).fw.enable=1 | | ^ V [ether_demux] [ether_output_frame] net.link.ether.ipfw=1 | | +-->--[bdg_forward]-->--+ net.link.bridge.ipfw=1 ^ V | to devices | .Ed .Pp As can be noted from the above picture, the number of times the same packet goes through the firewall can vary between 0 and 4 depending on packet source and destination, and system configuration. .Pp Note that as packets flow through the stack, headers can be stripped or added to it, and so they may or may not be available for inspection. E.g., incoming packets will include the MAC header when .Nm is invoked from .Cm ether_demux() , but the same packets will have the MAC header stripped off when .Nm is invoked from .Cm ip_input() or .Cm ip6_input() . .Pp 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 .Cm ip_input or .Cm ip6_input ), the match pattern will not match, but a .Cm not operator in front of such patterns .Em will cause the pattern to .Em always match on those packets. It is thus the responsibility of the programmer, if necessary, to write a suitable ruleset to differentiate among the possible places. .Cm skipto rules can be useful here, as an example: .Bd -literal -offset indent # packets from ether_demux or bdg_forward ipfw add 10 skipto 1000 all from any to any layer2 in # packets from ip_input ipfw add 10 skipto 2000 all from any to any not layer2 in # packets from ip_output ipfw add 10 skipto 3000 all from any to any not layer2 out # packets from ether_output_frame ipfw add 10 skipto 4000 all from any to any layer2 out .Ed .Pp (yes, at the moment there is no way to differentiate between 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 or may not be case-sensitive depending on their nature (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 command (including flags) into a single argument. 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 ipfw "-q add deny src-ip 10.0.0.0/24, 127.0.0.1/8" .Ed .Sh RULE FORMAT The format of .Nm rules is the following: .Bd -ragged -offset indent .Bk -words .Op Ar rule_number .Op Cm set Ar set_number .Op Cm prob Ar match_probability .Ar action .Op Cm log Op Cm logamount Ar number .Op Cm altq Ar queue .Oo .Bro Cm tag | untag .Brc Ar number .Oc .Ar body .Ek .Ed .Pp where the body of the rule specifies which information is used for filtering packets, among the following: .Pp .Bl -tag -width "Source and dest. addresses and ports" -offset XXX -compact .It Layer-2 header fields When available .It IPv4 and IPv6 Protocol TCP, UDP, ICMP, etc. .It Source and dest. addresses and ports .It Direction See Section .Sx PACKET FLOW .It Transmit and receive interface By name or address .It Misc. IP header fields Version, type of service, datagram length, identification, fragment flag (non-zero IP offset), Time To Live .It IP options .It IPv6 Extension headers Fragmentation, Hop-by-Hop options, source routing, IPSec options. .It IPv6 Flow-ID .It Misc. TCP header fields TCP flags (SYN, FIN, ACK, RST, etc.), sequence number, acknowledgment number, window .It TCP options .It ICMP types for ICMP packets .It ICMP6 types for ICMP6 packets .It User/group ID When the packet can be associated with a local socket. .It Divert status Whether a packet came from a divert socket (e.g., .Xr natd 8 ) . .El .Pp 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 .It Ar rule_number Each rule is associated with a .Ar rule_number in the range 1..65535, with the latter reserved for the .Em default rule. Rules are checked sequentially by rule number. Multiple rules can have the same number, in which case they are checked (and listed) according to the order in which they have been added. If a rule is entered without specifying a number, the kernel will assign one in such a way that the rule becomes the last one before the .Em default rule. 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 maximum allowed rule number), the number of the last non-default value is used instead. .It Cm set Ar set_number Each rule is associated with a .Ar set_number in the range 0..31. Sets can be individually disabled and enabled, so this parameter is of fundamental importance for atomic ruleset manipulation. It can be also used to simplify deletion of groups of rules. If a rule is entered without specifying a set number, set 0 will be used. .br Set 31 is special in that it cannot be disabled, and rules in set 31 are not deleted by the .Nm ipfw flush command (but you can delete them with the .Nm ipfw delete set 31 command). Set 31 is also used for the .Em default rule. .It Cm prob Ar match_probability A match is only declared with the specified probability (floating point number between 0 and 1). This can be useful for a number of applications such as random packet drop or (in conjunction with .Xr dummynet 4 ) to simulate the effect of multiple paths leading to out-of-order packet delivery. .Pp Note: this condition is checked before any other condition, including ones such as keep-state or check-state which might have side effects. .It Cm log Op Cm logamount Ar number When a packet matches a rule with the .Cm log keyword, a message will be logged to .Xr syslogd 8 with a .Dv LOG_SECURITY facility. The logging only occurs if the sysctl variable .Em net.inet.ip.fw.verbose is set to 1 (which is the default when the kernel is compiled with .Dv IPFIREWALL_VERBOSE ) and the number of packets logged so far for that particular rule does not exceed the .Cm logamount parameter. If no .Cm logamount is specified, the limit is taken from the sysctl variable .Em net.inet.ip.fw.verbose_limit . In both cases, a value of 0 removes the logging limit. .Pp Once the limit is reached, logging can be re-enabled by clearing the logging counter or the packet counter for that entry, see the .Cm resetlog command. .Pp Note: logging is done after all other packet matching conditions have been successfully verified, and before performing the final action (accept, deny, etc.) on the packet. .It Cm tag Ar number When a packet matches a rule with the .Cm tag keyword, the numeric tag for the given .Ar number in the range 1..65534 will be attached to the packet. The tag acts as an internal marker (it is not sent out over the wire) that can be used to identify these packets later on. This can be used, for example, to provide trust between interfaces and to start doing policy-based filtering. A packet can have mutiple tags at the same time. Tags are "sticky", meaning once a tag is applied to a packet by a matching rule it exists until explicit removal. Tags are kept with the packet everywhere within the kernel, but are lost when packet leaves the kernel, for example, on transmitting packet out to the network or sending packet to a .Xr divert 4 socket. .Pp To check for previously applied tags, use the .Cm tagged -rule option. To delete previously applied tag, use the +rule option. +To delete previously applied tag, use the .Cm untag keyword. .Pp Note: since tags are kept with the packet everywhere in kernelspace, they can be set and unset anywhere in kernel network subsystem (using .Xr mbuf_tags 9 facility), not only by means of .Xr ipfw 4 .Cm tag and .Cm untag keywords. For example, there can be a specialized .Xr netgraph 4 node doing traffic analyzing and tagging for later inspecting in firewall. .It Cm untag Ar number When a packet matches a rule with the .Cm untag keyword, the tag with the number .Ar number is searched among the tags attached to this packet and, if found, removed from it. Other tags bound to packet, if present, are left untouched. .It Cm altq Ar queue When a packet matches a rule with the .Cm altq keyword, the ALTQ identifier for the given .Ar queue (see .Xr altq 4 ) will be attached. Note that this ALTQ tag is only meaningful for packets going "out" of IPFW, and not being rejected or going to divert sockets. Note that if there is insufficient memory at the time the packet is processed, it will not be tagged, so it is wise to make your ALTQ "default" queue policy account for this. If multiple .Cm altq rules match a single packet, only the first one adds the ALTQ classification tag. In doing so, traffic may be shaped by using .Cm count Cm altq Ar queue rules for classification early in the ruleset, then later applying the filtering decision. For example, .Cm check-state and .Cm keep-state rules may come later and provide the actual filtering decisions in addition to the fallback ALTQ tag. .Pp You must run .Xr pfctl 8 to set up the queues before IPFW will be able to look them up by name, and if the ALTQ disciplines are rearranged, the rules in containing the queue identifiers in the kernel will likely have gone stale and need to be reloaded. Stale queue identifiers will probably result in misclassification. .Pp All system ALTQ processing can be turned on or off via .Nm .Cm enable Ar altq and .Nm .Cm disable Ar altq . The usage of .Em net.inet.ip.fw.one_pass is irrelevant to ALTQ traffic shaping, as the actual rule action is followed always after adding an ALTQ tag. .El .Ss RULE ACTIONS A rule can be associated with one of the following actions, which will be executed when the packet matches the body of the rule. .Bl -tag -width indent .It Cm allow | accept | pass | permit Allow packets that match rule. The search terminates. .It Cm check-state Checks the packet against the dynamic ruleset. If a match is found, execute the action associated with the rule which generated this dynamic rule, otherwise move to the next rule. .br .Cm Check-state rules do not have a body. If no .Cm check-state rule is found, the dynamic ruleset is checked at the first .Cm keep-state or .Cm limit rule. .It Cm count Update counters for all packets that match rule. The search continues with the next rule. .It Cm deny | drop Discard packets that match this rule. The search terminates. .It Cm divert Ar port Divert packets that match this rule to the .Xr divert 4 socket bound to port .Ar port . The search terminates. .It Cm fwd | forward Ar ipaddr | tablearg Ns Op , Ns Ar port Change the next-hop on matching packets to .Ar ipaddr , which can be an IP address or a host name. The next hop can also be supplied by the last table looked up for the packet by using the .Cm tablearg keyword instead of an explicit address. The search terminates if this rule matches. .Pp If .Ar ipaddr is a local address, then matching packets will be forwarded to .Ar port (or the port number in the packet if one is not specified in the rule) on the local machine. .br If .Ar ipaddr is not a local address, then the port number (if specified) is ignored, and the packet will be forwarded to the remote address, using the route as found in the local routing table for that IP. .br A .Ar fwd rule will not match layer-2 packets (those received on ether_input, ether_output, or bridged). .br The .Cm fwd action does not change the contents of the packet at all. In particular, the destination address remains unmodified, so packets forwarded to another system will usually be rejected by that system unless there is a matching rule on that system to capture them. For packets forwarded locally, the local address of the socket will be set to the original destination address of the packet. This makes the .Xr netstat 1 entry look rather weird but is intended for use with transparent proxy servers. .Pp To enable .Cm fwd a custom kernel needs to be compiled with the option .Cd "options IPFIREWALL_FORWARD" . .It Cm pipe Ar pipe_nr Pass packet to a .Xr dummynet 4 .Dq pipe (for bandwidth limitation, delay, etc.). See the .Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION Section for further information. The search terminates; however, on exit from the pipe and if the .Xr sysctl 8 variable .Em net.inet.ip.fw.one_pass is not set, the packet is passed again to the firewall code starting from the next rule. .It Cm queue Ar queue_nr Pass packet to a .Xr dummynet 4 .Dq queue (for bandwidth limitation using WF2Q+). .It Cm reject (Deprecated). Synonym for .Cm unreach host . .It Cm reset Discard packets that match this rule, and if the packet is a TCP packet, try to send a TCP reset (RST) notice. The search terminates. .It Cm reset6 Discard packets that match this rule, and if the packet is a TCP packet, try to send a TCP reset (RST) notice. The search terminates. .It Cm skipto Ar number Skip all subsequent rules numbered less than .Ar number . The search continues with the first rule numbered .Ar number or higher. .It Cm tee Ar port Send a copy of packets matching this rule to the .Xr divert 4 socket bound to port .Ar port . The search continues with the next rule. .It Cm unreach Ar code Discard packets that match this rule, and try to send an ICMP unreachable notice with code .Ar code , where .Ar code is a number from 0 to 255, or one of these aliases: .Cm net , host , protocol , port , .Cm needfrag , srcfail , net-unknown , host-unknown , .Cm isolated , net-prohib , host-prohib , tosnet , .Cm toshost , filter-prohib , host-precedence or .Cm precedence-cutoff . The search terminates. .It Cm unreach6 Ar code Discard packets that match this rule, and try to send an ICMPv6 unreachable notice with code .Ar code , where .Ar code is a number from 0, 1, 3 or 4, or one of these aliases: .Cm no-route, admin-prohib, address or .Cm port . The search terminates. .It Cm netgraph Ar cookie Divert packet into netgraph with given .Ar cookie . The search terminates. If packet is later returned from netgraph it is either accepted or continues with the next rule, depending on .Em net.inet.ip.fw.one_pass sysctl variable. .It Cm ngtee Ar cookie A copy of packet is diverted into netgraph, original packet is either accepted or continues with the next rule, depending on .Em net.inet.ip.fw.one_pass sysctl variable. See .Xr ng_ipfw 4 for more information on .Cm netgraph and .Cm ngtee actions. .El .Ss RULE BODY The body of a rule contains zero or more patterns (such as specific source and destination addresses or ports, 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 rule to match. Individual patterns can be prefixed by the .Cm not operator to reverse the result of the match, as in .Pp .Dl "ipfw add 100 allow ip from not 1.2.3.4 to any" .Pp Additionally, sets of alternative match patterns .Pq Em or-blocks can be constructed by putting the patterns in lists enclosed between parentheses ( ) or braces { }, and using the .Cm or operator as follows: .Pp .Dl "ipfw add 100 allow ip from { x or not y or z } to any" .Pp Only one level of parentheses is allowed. Beware that most shells have special meanings for parentheses or braces, so it is advisable to put a backslash \\ in front of them to prevent such interpretations. .Pp The body of a rule must in general include a source and destination address specifier. The keyword .Ar any can be used in various places to specify that the content of a required field is irrelevant. .Pp The rule body has the following format: .Bd -ragged -offset indent .Op Ar proto Cm from Ar src Cm to Ar dst .Op Ar options .Ed .Pp The first part (proto from src to dst) is for backward compatibility with earlier versions of .Fx . In modern .Fx any match pattern (including MAC headers, IP protocols, addresses and ports) can be specified in the .Ar options section. .Pp Rule fields have the following meaning: .Bl -tag -width indent .It Ar proto : protocol | Cm { Ar protocol Cm or ... } .It Ar protocol : Oo Cm not Oc Ar protocol-name | protocol-number An IP protocol specified by number or name (for a complete list see .Pa /etc/protocols ) , or one of the following keywords: .Bl -tag -width indent .It Cm ip4 | ipv4 Matches IPv4 packets. .It Cm ip6 | ipv6 Matches IPv6 packets. .It Cm ip | all Matches any packet. .El .Pp The .Cm ipv6 in .Cm proto option will be treated as inner protocol. And, the .Cm ipv4 is not available in .Cm proto option. .Pp The .Cm { Ar protocol Cm or ... } format (an .Em or-block ) is provided for convenience only but its use is deprecated. .It Ar src No and Ar dst : Bro Cm addr | Cm { Ar addr Cm or ... } Brc Op Oo Cm not Oc Ar ports An address (or a list, see below) optionally followed by .Ar ports specifiers. .Pp The second format .Em ( or-block with multiple addresses) is provided for convenience only and its use is discouraged. .It Ar addr : Oo Cm not Oc Bro .Cm any | me | me6 | .Cm table Ns Pq Ar number Ns Op , Ns Ar value .Ar | addr-list | addr-set .Brc .It Cm any matches any IP address. .It Cm me matches any IP address configured on an interface in the system. .It Cm me6 matches any IPv6 address configured on an interface in the system. The address list is evaluated at the time the packet is analysed. .It Cm table Ns Pq Ar number Ns Op , Ns Ar value Matches any IPv4 address for which an entry exists in the lookup table .Ar number . If an optional 32-bit unsigned .Ar value is also specified, an entry will match only if it has this value. See the .Sx LOOKUP TABLES section below for more information on lookup tables. .It Ar addr-list : ip-addr Ns Op Ns , Ns Ar addr-list .It Ar ip-addr : A host or subnet address specified in one of the following ways: .Bl -tag -width indent .It Ar numeric-ip | hostname Matches a single IPv4 address, specified as dotted-quad or a hostname. Hostnames are resolved at the time the rule is added to the firewall list. .It Ar addr Ns / Ns Ar masklen Matches all addresses with base .Ar addr (specified as an IP address or a hostname) and mask width of .Cm masklen bits. As an example, 1.2.3.4/25 will match all IP numbers from 1.2.3.0 to 1.2.3.127 . .It Ar addr Ns : Ns Ar mask Matches all addresses with base .Ar addr (specified as an IP address or a hostname) and the mask of .Ar mask , 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 .Ar addr Ns / Ns Ar masklen format for contiguous masks, which is more compact and less error-prone. .El .It Ar addr-set : addr Ns Oo Ns / Ns Ar masklen Oc Ns Cm { Ns Ar list Ns Cm } .It Ar list : Bro Ar num | num-num Brc Ns Op Ns , Ns Ar list Matches all addresses with base address .Ar addr (specified as an IP address or a hostname) and whose last byte is in the list between braces { } . Note that there must be no spaces between braces and numbers (spaces after commas are allowed). Elements of the list can be specified as single entries 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, 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 bitmask, it takes constant time and dramatically reduces the complexity of rulesets. .br As an example, an address specified as 1.2.3.4/24{128,35-55,89} will match the following IP addresses: .br 1.2.3.128, 1.2.3.35 to 1.2.3.55, 1.2.3.89 . .It Ar addr6-list : ip6-addr Ns Op Ns , Ns Ar addr6-list .It Ar ip6-addr : A host or subnet specified one of the following ways: .Pp .Bl -tag -width indent .It Ar numeric-ip | hostname Matches a single IPv6 address as allowed by .Xr inet_pton 3 or a hostname. Hostnames are resolved at the time the rule is added to the firewall list. .It Ar addr Ns / Ns Ar masklen Matches all IPv6 addresses with base .Ar addr (specified as allowed by .Xr inet_pton or a hostname) and mask width of .Cm masklen bits. .El .Pp No support for sets of IPv6 addresses is provided because IPv6 addresses are typically random past the initial prefix. .It Ar ports : Bro Ar port | port Ns \&- Ns Ar port Ns Brc Ns Op , Ns Ar ports For protocols which support port numbers (such as TCP and UDP), optional .Cm ports may be specified as one or more ports or port ranges, separated by commas but no spaces, and an optional .Cm not operator. The .Ql \&- notation specifies a range of ports (including boundaries). .Pp Service names (from .Pa /etc/services ) may be used instead of numeric port values. The length of the port list is limited to 30 ports or ranges, though one can specify larger ranges by using an .Em or-block in the .Cm options section of the rule. .Pp A backslash .Pq Ql \e can be used to escape the dash .Pq Ql - character in a service name (from a shell, the backslash must be typed twice to avoid the shell itself interpreting it as an escape 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 fragment) will never match a rule which has one or more port specifications. See the .Cm frag 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 .Em options can be present in a rule, optionally prefixed by the .Cm not operand, and possibly grouped into .Em or-blocks . .Pp The following match patterns can be used (listed in alphabetical order): .Bl -tag -width indent .It Cm // this is a comment. Inserts the specified text as a comment in the rule. Everything following // is considered as a comment and stored in the rule. You can have comment-only rules, which are listed as having a .Cm count action followed by the comment. .It Cm bridged Alias for .Cm layer2 . .It Cm diverted Matches only packets generated by a divert socket. .It Cm diverted-loopback Matches only packets coming from a divert socket back into the IP stack input for delivery. .It Cm diverted-output Matches only packets going from a divert socket back outward to the IP stack output for delivery. .It Cm dst-ip Ar ip-address Matches IPv4 packets whose destination IP is one of the address(es) specified as argument. .It Bro Cm dst-ip6 | dst-ipv6 Brc Ar ip6-address Matches IPv6 packets whose destination IP is one of the address(es) specified as argument. .It Cm dst-port Ar ports Matches IP packets whose destination port is one of the port(s) specified as argument. .It Cm established Matches TCP packets that have the RST or ACK bits set. .It Cm ext6hdr Ar header Matches IPv6 packets containing the extended header given by .Ar header . Supported headers are: .Pp Fragment, .Pq Cm frag , Hop-to-hop options .Pq Cm hopopt , Source routing .Pq Cm route , Destination options .Pq Cm dstopt , IPSec authentication headers .Pq Cm ah , and IPSec encapsulated security payload headers .Pq Cm esp . .It Cm flow-id Ar labels Matches IPv6 packets containing any of the flow labels given in .Ar labels . .Ar labels is a comma seperate list of numeric flow labels. .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 these headers cannot match. .It Cm gid Ar group Matches all TCP or UDP packets sent by or received for a .Ar group . A .Ar group may be specified by name or number. This option should be used only if debug.mpsafenet=0 to avoid possible deadlocks due to layering violations in its implementation. .It Cm jail Ar prisonID Matches all TCP or UDP packets sent by or received for the jail whos prison ID is .Ar prisonID . This option should be used only if debug.mpsafenet=0 to avoid possible deadlocks due to layering violations in its implementation. .It Cm icmptypes Ar types Matches ICMP packets whose ICMP type is in the list .Ar types . The list may be specified as any combination of individual types (numeric) separated by commas. .Em Ranges are not allowed. The supported ICMP types are: .Pp echo reply .Pq Cm 0 , destination unreachable .Pq Cm 3 , source quench .Pq Cm 4 , redirect .Pq Cm 5 , echo request .Pq Cm 8 , router advertisement .Pq Cm 9 , router solicitation .Pq Cm 10 , time-to-live exceeded .Pq Cm 11 , IP header bad .Pq Cm 12 , timestamp request .Pq Cm 13 , timestamp reply .Pq Cm 14 , information request .Pq Cm 15 , information reply .Pq Cm 16 , address mask request .Pq Cm 17 and address mask reply .Pq Cm 18 . .It Cm icmp6types Ar types Matches ICMP6 packets whose ICMP6 type is in the list of .Ar types . The list may be specified as any combination of individual types (numeric) separated by commas. .Em Ranges are not allowed. .It Cm in | out Matches incoming or outgoing packets, respectively. .Cm in and .Cm out are mutually exclusive (in fact, .Cm out is implemented as .Cm not in Ns No ). .It Cm ipid Ar id-list Matches IPv4 packets whose .Cm ip_id field has value included in .Ar id-list , which is either a single value or a list of values or ranges specified in the same way as .Ar ports . .It Cm iplen Ar len-list 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 specified in the same way as .Ar ports . .It Cm ipoptions Ar spec Matches packets whose IPv4 header contains the comma separated list of options specified in .Ar spec . The supported IP options are: .Pp .Cm ssrr (strict source route), .Cm lsrr (loose source route), .Cm rr (record packet route) and .Cm ts (timestamp). The absence of a particular option may be denoted with a .Ql \&! . .It Cm ipprecedence Ar precedence Matches IPv4 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 has IPSEC support and IPSEC_FILTERGIF option, and can correctly decapsulate it). .Pp Note that specifying .Cm ipsec is different from specifying .Cm proto Ar ipsec as the latter will only look at the specific IP protocol field, irrespective of IPSEC kernel support and the validity of the IPSEC data. .Pp Further note that this flag is silently ignored in kernels without IPSEC support. It does not affect rule processing when given and the rules are handled as if with no .Cm ipsec flag. .It Cm iptos Ar spec Matches IPv4 packets whose .Cm tos field contains the comma separated list of service types specified in .Ar spec . The supported IP types of service are: .Pp .Cm lowdelay .Pq Dv IPTOS_LOWDELAY , .Cm throughput .Pq Dv IPTOS_THROUGHPUT , .Cm reliability .Pq Dv IPTOS_RELIABILITY , .Cm mincost .Pq Dv IPTOS_MINCOST , .Cm congestion .Pq Dv IPTOS_CE . The absence of a particular type may be denoted with a .Ql \&! . .It Cm ipttl Ar ttl-list Matches IPv4 packets whose time to live is included in .Ar ttl-list , which is either a single value or a list of values or ranges specified in the same way as .Ar ports . .It Cm ipversion Ar ver Matches IP packets whose IP version field is .Ar ver . .It Cm keep-state Upon a match, the firewall will create a dynamic rule, whose default behaviour is to match bidirectional traffic between source and destination IP/port using the same protocol. The rule has a limited lifetime (controlled by a set of .Xr sysctl 8 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 .Nm from ether_demux() and ether_output_frame(). .It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N The firewall will only allow .Ar N connections with the same set of parameters as specified in the rule. One or more of source and destination addresses and ports can be specified. Currently, only IPv4 flows are supported. .It Cm { MAC | mac } Ar dst-mac src-mac Match packets with a given .Ar dst-mac and .Ar src-mac addresses, specified as the .Cm any keyword (matching any MAC address), or six groups of hex digits separated by colons, and optionally followed by a mask indicating the significant bits. The mask may be specified using either of the following methods: .Bl -enum -width indent .It A slash .Pq / followed by the number of significant bits. For example, an address with 33 significant bits could be specified as: .Pp .Dl "MAC 10:20:30:40:50:60/33 any" .Pp .It An ampersand .Pq & followed by a bitmask specified as six groups of hex digits separated by colons. For example, an address in which the last 16 bits are significant could be specified as: .Pp .Dl "MAC 10:20:30:40:50:60&00:00:00:00:ff:ff any" .Pp Note that the ampersand character has a special meaning in many shells and should generally be escaped. .Pp .El Note that the order of MAC addresses (destination first, source second) is the same as on the wire, but the opposite of the one used for IP addresses. .It Cm mac-type Ar mac-type Matches packets whose Ethernet Type field 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). 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), and they are always printed as hexadecimal (unless the .Cm -N option is used, in which case symbolic resolution will be attempted). .It Cm proto Ar protocol Matches packets with the corresponding IP protocol. .It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar ipno | Ar any Matches packets received, transmitted or going through, respectively, the interface specified by exact name .Ns No ( Ar ifX Ns No ), by device name .Ns No ( Ar if Ns Ar * Ns No ), by IP address, or through some interface. .Pp The .Cm via keyword causes the interface to always be checked. If .Cm recv or .Cm xmit is used instead of .Cm via , then only the receive or transmit interface (respectively) is checked. By specifying both, it is possible to match packets based on both receive and transmit interface, e.g.: .Pp .Dl "ipfw add deny ip from any to any out recv ed0 xmit ed1" .Pp The .Cm recv interface can be tested on either incoming or outgoing packets, while the .Cm xmit interface can only be tested on outgoing packets. So .Cm out is required (and .Cm in is invalid) whenever .Cm xmit is used. .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 the local host have no transmit interface. .It Cm setup Matches TCP packets that have the SYN bit set but no ACK bit. This is the short form of .Dq Li tcpflags\ syn,!ack . .It Cm src-ip Ar ip-address Matches IPv4 packets whose source IP is one of the address(es) specified as an argument. .It Cm src-ip6 Ar ip6-address Matches IPv6 packets whose source IP is one of the address(es) specified as an argument. .It Cm src-port Ar ports Matches IP packets whose source port is one of the port(s) specified as argument. .It Cm tagged Ar tag-list Matches packets whose tags are included in .Ar tag-list , which is either a single value or a list of values or ranges specified in the same way as .Ar ports . Tags can be applied to the packet using .Cm tag rule action parameter (see it's description for details on tags). .It Cm tcpack Ar ack TCP packets only. Match if the TCP header acknowledgment number field is set to .Ar ack . .It Cm tcpdatalen Ar tcpdatalen-list Matches TCP packets whose length of TCP data is .Ar tcpdatalen-list , which is either a single value or a list of values or ranges specified in the same way as .Ar ports . .It Cm tcpflags Ar spec TCP packets only. Match if the TCP header contains the comma separated list of flags specified in .Ar spec . The supported TCP flags are: .Pp .Cm fin , .Cm syn , .Cm rst , .Cm psh , .Cm ack and .Cm urg . The absence of a particular flag may be denoted with a .Ql \&! . A rule which contains a .Cm tcpflags specification can never match a fragmented packet which has a non-zero offset. See the .Cm frag option for details on matching fragmented packets. .It Cm tcpseq Ar seq TCP packets only. Match if the TCP header sequence number field is set to .Ar seq . .It Cm tcpwin Ar win TCP packets only. Match if the TCP header window field is set to .Ar win . .It Cm tcpoptions Ar spec TCP packets only. Match if the TCP header contains the comma separated list of options specified in .Ar spec . The supported TCP options are: .Pp .Cm mss (maximum segment size), .Cm window (tcp window advertisement), .Cm sack (selective ack), .Cm ts (rfc1323 timestamp) and .Cm cc (rfc1644 t/tcp connection count). The absence of a particular option may be denoted with a .Ql \&! . .It Cm uid Ar user Match all TCP or UDP packets sent by or received for a .Ar user . A .Ar user may be matched by name or identification number. This option should be used only if debug.mpsafenet=0 to avoid possible deadlocks due to layering violations in its implementation. .It Cm verrevpath For incoming packets, a routing table lookup is done on the packet's source address. If the interface on which the packet entered the system matches the outgoing interface for the route, the packet matches. If the interfaces do not match up, the packet does not match. All outgoing packets or packets with no incoming interface match. .Pp The name and functionality of the option is intentionally similar to the Cisco IOS command: .Pp .Dl ip verify unicast reverse-path .Pp This option can be used to make anti-spoofing rules to reject all packets with source addresses not from this interface. See also the option .Cm antispoof . .It Cm versrcreach For incoming packets, a routing table lookup is done on the packet's source address. If a route to the source address exists, but not the default route or a blackhole/reject route, the packet matches. Otherwise, the packet does not match. All outgoing packets match. .Pp The name and functionality of the option is intentionally similar to the Cisco IOS command: .Pp .Dl ip verify unicast source reachable-via any .Pp This option can be used to make anti-spoofing rules to reject all packets whose source address is unreachable. .It Cm antispoof For incoming packets, the packet's source address is checked if it belongs to a directly connected network. If the network is directly connected, then the interface the packet came on in is compared to the interface the network is connected to. When incoming interface and directly connected interface are not the same, the packet does not match. Otherwise, the packet does match. All outgoing packets match. .Pp This option can be used to make anti-spoofing rules to reject all packets that pretend to be from a directly connected network but do not come in through that interface. This option is similar to but more restricted than .Cm verrevpath because it engages only on packets with source addresses of directly connected networks instead of all source addresses. .El .Sh LOOKUP TABLES Lookup tables are useful to handle large sparse address sets, typically from a hundred to several thousands of entries. There may be up to 128 different lookup tables, numbered 0 to 127. .Pp Each entry is represented by an .Ar addr Ns Op / Ns Ar masklen and will match all addresses with base .Ar addr (specified as an IP address or a hostname) and mask width of .Ar masklen bits. If .Ar masklen is not specified, it defaults to 32. When looking up an IP address in a table, the most specific entry will match. Associated with each entry is a 32-bit unsigned .Ar value , which can optionally be checked by a rule matching code. When adding an entry, if .Ar value is not specified, it defaults to 0. .Pp An entry can be added to a table .Pq Cm add , removed from a table .Pq Cm delete , a table can be examined .Pq Cm list or flushed .Pq Cm flush . .Pp Internally, each table is stored in a Radix tree, the same way as the routing table (see .Xr route 4 ) . .Pp Lookup tables currently support IPv4 addresses only. .Pp The .Cm tablearg feature provides the ability to use a value, looked up in the table, as the argument for a rule action, action parameter or rule option. This can significantly reduce number of rules in some configurations. The .Cm tablearg argument can be used with the following actions: .Cm pipe , queue, divert, tee, netgraph, ngtee, fwd action parameters: .Cm tag, untag, rule options: .Cm limit, tagged. .Pp When used with .Cm fwd it is possible to supply table entries with values that are in the form of IP addresses or hostnames. See the .Sx EXAMPLES Section for example usage of tables and the tablearg keyword. .Sh SETS OF RULES Each rule belongs to one of 32 different .Em sets , numbered 0 to 31. Set 31 is reserved for the default rule. .Pp By default, rules are put in set 0, unless you use the .Cm set N attribute when entering a new rule. Sets can be individually and atomically enabled or disabled, so this mechanism permits an easy way to store multiple configurations of the firewall and quickly (and atomically) switch between them. The command to enable/disable sets is .Bd -ragged -offset indent .Nm .Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ... .Ed .Pp where multiple .Cm enable or .Cm disable sections can be specified. Command execution is atomic on all the sets specified in the command. By default, all sets are enabled. .Pp 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 dynamic rules you have to explicitly delete the parent rule which generated them. .Ed .Pp The set number of rules can be changed with the command .Bd -ragged -offset indent .Nm .Cm set move .Brq Cm rule Ar rule-number | old-set .Cm to Ar new-set .Ed .Pp Also, you can atomically swap two rulesets with the command .Bd -ragged -offset indent .Nm .Cm set swap Ar first-set second-set .Ed .Pp See the .Sx EXAMPLES 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 operation comes through the .Cm check-state , keep-state and .Cm limit options of .Nm rules . .Pp Dynamic rules are created when a packet matches a .Cm keep-state or .Cm limit rule, causing the creation of a .Em dynamic rule which will match all and only packets with a given .Em protocol between a .Em src-ip/src-port dst-ip/dst-port pair of addresses .Em ( src and .Em dst are used here only to denote the initial match addresses, but they are completely equivalent afterwards). Dynamic rules will be checked at the first .Cm check-state, keep-state or .Cm limit occurrence, and the action performed upon a match will be the same as in the parent rule. .Pp Note that no additional attributes other than protocol and IP addresses and ports are checked on dynamic rules. .Pp The typical use of dynamic rules is to keep a closed firewall configuration, but let the first TCP SYN packet from the inside network install a dynamic rule for the flow so that packets belonging to that session will be allowed through the firewall: .Pp .Dl "ipfw add check-state" .Dl "ipfw add allow tcp from my-subnet to any setup keep-state" .Dl "ipfw add deny tcp from any to any" .Pp A similar approach can be used for UDP, where an UDP packet coming from the inside will install a dynamic rule to let the response through the firewall: .Pp .Dl "ipfw add check-state" .Dl "ipfw add allow udp from my-subnet to any keep-state" .Dl "ipfw add deny udp from any to any" .Pp Dynamic rules expire after some time, which depends on the status of the flow and the setting of some .Cm sysctl variables. See Section .Sx SYSCTL VARIABLES for more details. For TCP sessions, dynamic rules can be instructed to periodically send keepalive packets to refresh the state of the rule when it is about to expire. .Pp See Section .Sx EXAMPLES for more examples on how to use dynamic rules. .Sh TRAFFIC SHAPER (DUMMYNET) CONFIGURATION .Nm is also the user interface for the .Xr dummynet 4 traffic shaper. .Pp .Nm dummynet operates by first using the firewall to classify packets and divide them into .Em flows , using any match pattern that can be used in .Nm rules. Depending on local policies, a flow can contain packets for a single TCP connection, or from/to a given host, or entire subnet, or a protocol type, etc. .Pp Packets belonging to the same flow are then passed to either of two different objects, which implement the traffic regulation: .Bl -hang -offset XXXX .It Em pipe A pipe emulates a link with given bandwidth, propagation delay, queue size and packet loss rate. Packets are queued in front of the pipe as they come out from the classifier, and then transferred to the pipe according to the pipe's parameters. .Pp .It Em queue A queue is an abstraction used to implement the WF2Q+ (Worst-case Fair Weighted Fair Queueing) policy, which is an efficient variant of the WFQ policy. .br The queue associates a .Em weight and a reference pipe to each flow, and then all backlogged (i.e., with packets queued) flows linked to the same pipe share the pipe's bandwidth proportionally to their weights. Note that weights are not priorities; a flow with a lower weight is still guaranteed to get its fraction of the bandwidth even if a flow with a higher weight is permanently backlogged. .Pp .El In practice, .Em pipes can be used to set hard limits to the bandwidth that a flow can use, whereas .Em queues can be used to determine how different flow share the available bandwidth. .Pp The .Em pipe and .Em queue configuration commands are the following: .Bd -ragged -offset indent .Cm pipe Ar number Cm config Ar pipe-configuration .Pp .Cm queue Ar number Cm config Ar queue-configuration .Ed .Pp The following parameters can be configured for a pipe: .Pp .Bl -tag -width indent -compact .It Cm bw Ar bandwidth | device Bandwidth, measured in .Sm off .Op Cm K | M .Brq Cm bit/s | Byte/s . .Sm on .Pp A value of 0 (default) means unlimited bandwidth. The unit must immediately follow the number, as in .Pp .Dl "ipfw pipe 1 config bw 300Kbit/s" .Pp If a device name is specified instead of a numeric value, as in .Pp .Dl "ipfw pipe 1 config bw tun0" .Pp then the transmit clock is supplied by the specified device. At the moment only the .Xr tun 4 device supports this functionality, for use in conjunction with .Xr ppp 8 . .Pp .It Cm delay Ar ms-delay Propagation delay, measured in milliseconds. The value is rounded to the next multiple of the clock tick (typically 10ms, but it is a good practice to run kernels with .Dq "options HZ=1000" to reduce the granularity to 1ms or less). Default value is 0, meaning no delay. .El .Pp The following parameters can be configured for a queue: .Pp .Bl -tag -width indent -compact .It Cm pipe Ar pipe_nr Connects a queue to the specified pipe. Multiple queues (with the same or different weights) can be connected to the same pipe, which specifies the aggregate rate for the set of queues. .Pp .It Cm weight Ar weight Specifies the weight to be used for flows matching this queue. The weight must be in the range 1..100, and defaults to 1. .El .Pp Finally, the following parameters can be configured for both pipes and queues: .Pp .Bl -tag -width XXXX -compact .Pp .It Cm buckets Ar hash-table-size Specifies the size of the hash table used for storing the various queues. Default value is 64 controlled by the .Xr sysctl 8 variable .Em net.inet.ip.dummynet.hash_size , allowed range is 16 to 65536. .Pp .It Cm mask Ar mask-specifier Packets sent to a given pipe or queue by an .Nm rule can be further classified into multiple flows, each of which is then sent to a different .Em dynamic pipe or queue. A flow identifier is constructed by masking the IP addresses, ports and protocol types as specified with the .Cm mask options in the configuration of the pipe or queue. For each different flow identifier, a new pipe or queue is created with the same parameters as the original object, and matching packets are sent to it. .Pp Thus, when .Em dynamic pipes are used, each flow will get the same bandwidth as defined by the pipe, whereas when .Em dynamic queues are used, each flow will share the parent's pipe bandwidth evenly with other flows generated by the same queue (note that other queues with different weights might be connected to the same pipe). .br Available mask specifiers are a combination of one or more of the following: .Pp .Cm dst-ip Ar mask , .Cm dst-ip6 Ar mask , .Cm src-ip Ar mask , .Cm src-ip6 Ar mask , .Cm dst-port Ar mask , .Cm src-port Ar mask , .Cm flow-id Ar mask , .Cm proto Ar mask or .Cm all , .Pp where the latter means all bits in all fields are significant. .Pp .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 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. .Pp .It Cm plr Ar packet-loss-rate Packet loss rate. Argument .Ar packet-loss-rate is a floating-point number between 0 and 1, with 0 meaning no loss, 1 meaning 100% loss. The loss rate is internally represented on 31 bits. .Pp .It Cm queue Brq Ar slots | size Ns Cm Kbytes Queue size, in .Ar slots or .Cm KBytes . Default value is 50 slots, which is the typical queue size for Ethernet devices. Note that for slow speed links you should keep the queue size short or your traffic might be affected by a significant 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 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 Make use of the RED (Random Early Detection) queue management algorithm. .Ar w_q and .Ar max_p are floating point numbers between 0 and 1 (0 not included), while .Ar min_th and .Ar max_th are integer numbers specifying thresholds for queue management (thresholds are computed in bytes if the queue has been defined in bytes, in slots otherwise). The .Xr dummynet 4 also supports the gentle RED variant (gred). Three .Xr sysctl 8 variables can be used to control the RED behaviour: .Bl -tag -width indent .It Em net.inet.ip.dummynet.red_lookup_depth specifies the accuracy in computing the average queue when the link is idle (defaults to 256, must be greater than zero) .It Em net.inet.ip.dummynet.red_avg_pkt_size specifies the expected average packet size (defaults to 512, must be greater than zero) .It Em net.inet.ip.dummynet.red_max_pkt_size specifies the expected maximum packet size, only used when queue thresholds are in bytes (defaults to 1500, must be greater than zero). .El .El .Pp When used with IPv6 data, dummynet currently has several limitations. First, debug.mpsafenet=0 must be set. Second, the information necessicary to route link-local packets to an interface is not avalable after processing by dummynet so those packets are dropped in the output path. Care should be taken to insure that link-local packets are not passed to dummynet. .Sh CHECKLIST Here are some important points to consider when designing your rules: .Bl -bullet .It Remember that you filter both packets going .Cm in and .Cm out . Most connections need packets going in both directions. .It Remember to test very carefully. It is a good idea to be near the console when doing this. If you cannot be near the console, use an auto-recovery script such as the one in .Pa /usr/share/examples/ipfw/change_rules.sh . .It Do not forget the loopback interface. .El .Sh FINE POINTS .Bl -bullet .It There are circumstances where fragmented datagrams are unconditionally dropped. TCP packets are dropped if they do not contain at least 20 bytes of TCP header, UDP packets are dropped if they do not contain a full 8 byte UDP header, and ICMP packets are dropped if they do not contain 4 bytes of ICMP header, enough to specify the ICMP type, code, and checksum. These packets are simply logged as .Dq pullup failed since there may not be enough good data in the packet to produce a meaningful log entry. .It Another type of packet is unconditionally dropped, a TCP packet with a fragment offset of one. This is a valid packet, but it only has one use, to try to circumvent firewalls. When logging is enabled, these packets are reported as being dropped by rule -1. .It If you are logged in over a network, loading the .Xr kld 4 version of .Nm is probably not as straightforward as you would think. I recommend the following command line: .Bd -literal -offset indent kldload ipfw && \e ipfw add 32000 allow ip from any to any .Ed .Pp Along the same lines, doing an .Bd -literal -offset indent ipfw flush .Ed .Pp in similar surroundings is also a bad idea. .It The .Nm filter list may not be modified if the system security level is set to 3 or higher (see .Xr init 8 for information on system security levels). .El .Sh PACKET DIVERSION A .Xr divert 4 socket bound to the specified port will receive all packets diverted to that port. If no socket is bound to the destination port, or if the divert module is not loaded, or if the kernel was not compiled with divert socket support, the packets are dropped. .Sh SYSCTL VARIABLES A set of .Xr sysctl 8 variables controls the behaviour of the firewall and associated modules .Pq Nm dummynet , bridge . These are shown below together with their default value (but always check with the .Xr sysctl 8 command what value is actually in use) and meaning: .Bl -tag -width indent .It Em net.inet.ip.dummynet.expire : No 1 Lazily delete dynamic pipes/queue once they have no pending traffic. You can disable this by setting the variable to 0, in which case the pipes/queues will only be deleted when the threshold is reached. .It Em net.inet.ip.dummynet.hash_size : No 64 Default size of the hash table used for dynamic pipes/queues. This value is used when no .Cm buckets option is specified when configuring a pipe/queue. .It Em net.inet.ip.dummynet.max_chain_len : No 16 Target value for the maximum number of pipes/queues in a hash bucket. The product .Cm max_chain_len*hash_size is used to determine the threshold over which empty pipes/queues will be expired even when .Cm net.inet.ip.dummynet.expire=0 . .It Em net.inet.ip.dummynet.red_lookup_depth : No 256 .It Em net.inet.ip.dummynet.red_avg_pkt_size : No 512 .It Em net.inet.ip.dummynet.red_max_pkt_size : No 1500 Parameters used in the computations of the drop probability for the RED algorithm. .It Em net.inet.ip.fw.autoinc_step : No 100 Delta between rule numbers when auto-generating them. The value must be in the range 1..1000. .It Em net.inet.ip.fw.curr_dyn_buckets : Em net.inet.ip.fw.dyn_buckets The current number of buckets in the hash table for dynamic rules (readonly). .It Em net.inet.ip.fw.debug : No 1 Controls debugging messages produced by .Nm . .It Em net.inet.ip.fw.dyn_buckets : No 256 The number of buckets in the hash table for dynamic rules. Must be a power of 2, up to 65536. It only takes effect when all dynamic rules have expired, so you are advised to use a .Cm flush command to make sure that the hash table is resized. .It Em net.inet.ip.fw.dyn_count : No 3 Current number of dynamic rules (read-only). .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 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 Maximum number of dynamic rules. When you hit this limit, no more dynamic rules can be installed until old ones expire. .It Em net.inet.ip.fw.dyn_ack_lifetime : No 300 .It Em net.inet.ip.fw.dyn_syn_lifetime : No 20 .It Em net.inet.ip.fw.dyn_fin_lifetime : No 1 .It Em net.inet.ip.fw.dyn_rst_lifetime : No 1 .It Em net.inet.ip.fw.dyn_udp_lifetime : No 5 .It Em net.inet.ip.fw.dyn_short_lifetime : No 30 These variables control the lifetime, in seconds, of dynamic rules. Upon the initial SYN exchange the lifetime is kept short, then increased after both SYN have been seen, then decreased again during the final FIN exchange or when a RST is received. Both .Em dyn_fin_lifetime and .Em dyn_rst_lifetime must be strictly lower than 5 seconds, the period of 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 firewall even if compiled in. .It Em net.inet6.ip6.fw.enable : No 1 provides the same functionality as above for the IPv6 case. .It Em net.inet.ip.fw.one_pass : No 1 When set, the packet exiting from the .Xr dummynet 4 pipe or from .Xr ng_ipfw 4 node is not passed though the firewall again. Otherwise, after an action, the packet is reinjected into the firewall at the next rule. .It Em net.inet.ip.fw.verbose : No 1 Enables verbose messages. .It Em net.inet.ip.fw.verbose_limit : No 0 Limits the number of messages produced by a verbose firewall. .It Em net.inet6.ip6.fw.deny_unknown_exthdrs : No 1 If enabled packets with unknown IPv6 Extension Headers will be denied. .It Em net.link.ether.ipfw : No 0 Controls whether layer-2 packets are passed to .Nm . Default is no. .It Em net.link.bridge.ipfw : No 0 Controls whether bridged packets are passed to .Nm . Default is no. .El .Pp .Sh EXAMPLES There are far too many possible uses of .Nm so this Section will only give a small set of examples. .Pp .Ss BASIC PACKET FILTERING This command adds an entry which denies all tcp packets from .Em cracker.evil.org to the telnet port of .Em wolf.tambov.su from being forwarded by the host: .Pp .Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet" .Pp This one disallows any connection from the entire cracker's network to my host: .Pp .Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org" .Pp A first and efficient way to limit access (not using dynamic rules) is the use of the following rules: .Pp .Dl "ipfw add allow tcp from any to any established" .Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup" .Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup" .Dl "..." .Dl "ipfw add deny tcp from any to any" .Pp The first rule will be a quick match for normal TCP packets, but it will not match the initial SYN packet, which will be matched by the .Cm setup rules only for selected source/destination pairs. All other SYN packets will be rejected by the final .Cm deny rule. .Pp If you administer one or more subnets, you can take advantage of the address sets and or-blocks and write extremely compact rulesets which selectively enable services to blocks of clients, as below: .Pp .Dl "goodguys=\*q{ 10.1.2.0/24{20,35,66,18} or 10.2.3.0/28{6,3,11} }\*q" .Dl "badguys=\*q10.1.2.0/24{8,38,60}\*q" .Dl "" .Dl "ipfw add allow ip from ${goodguys} to any" .Dl "ipfw add deny ip from ${badguys} to any" .Dl "... normal policies ..." .Pp The .Cm verrevpath option could be used to do automated anti-spoofing by adding the following to the top of a ruleset: .Pp .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 address belonging to a host on a protected internal network would be dropped if it tried to enter the system from an external interface. .Pp The .Cm antispoof option could be used to do similar but more restricted anti-spoofing by adding the following to the top of a ruleset: .Pp .Dl "ipfw add deny ip from any to any not antispoof in" .Pp This rule drops all incoming packets that appear to be coming from another directly connected system but on the wrong interface. For example, a packet with a source address of .Li 192.168.0.0/24 , configured on .Li fxp0 , but coming in on .Li fxp1 would be dropped. .Ss DYNAMIC RULES In order to protect a site from flood attacks involving fake TCP packets, it is safer to use dynamic rules: .Pp .Dl "ipfw add check-state" .Dl "ipfw add deny tcp from any to any established" .Dl "ipfw add allow tcp from my-net to any setup keep-state" .Pp This will let the firewall install dynamic rules only for those connection which start with a regular SYN packet coming from the inside of our network. Dynamic rules are checked when encountering the first .Cm check-state or .Cm keep-state rule. A .Cm check-state rule should usually be placed near the beginning of the ruleset to minimize the amount of work scanning the ruleset. Your mileage may vary. .Pp To limit the number of connections a user can open you can use the following type of rules: .Pp .Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10" .Dl "ipfw add allow tcp from any to me setup limit src-addr 4" .Pp The former (assuming it runs on a gateway) will allow each host on a /24 network to open at most 10 TCP connections. The latter can be placed on a server to make sure that a single client does not use more than 4 simultaneous connections. .Pp .Em BEWARE : stateful rules can be subject to denial-of-service attacks by a SYN-flood which opens a huge number of dynamic rules. The effects of such attacks can be partially limited by acting on a set of .Xr sysctl 8 variables which control the operation of the firewall. .Pp Here is a good usage of the .Cm list command to see accounting records and timestamp information: .Pp .Dl ipfw -at list .Pp or in short form without timestamps: .Pp .Dl ipfw -a list .Pp which is equivalent to: .Pp .Dl ipfw show .Pp Next rule diverts all incoming packets from 192.168.2.0/24 to divert port 5000: .Pp .Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in .Pp .Ss TRAFFIC SHAPING The following rules show some of the applications of .Nm and .Xr dummynet 4 for simulations and the like. .Pp This rule drops random incoming packets with a probability of 5%: .Pp .Dl "ipfw add prob 0.05 deny ip from any to any in" .Pp A similar effect can be achieved making use of dummynet pipes: .Pp .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 machine acting as a router, if we want to limit traffic from local clients on 192.168.2.0/24 we do: .Pp .Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" .Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes" .Pp note that we use the .Cm out modifier so that the rule is not used twice. Remember in fact that .Nm rules are checked both on incoming and outgoing packets. .Pp Should we want to simulate a bidirectional link with bandwidth limitations, the correct way is the following: .Pp .Dl "ipfw add pipe 1 ip from any to any out" .Dl "ipfw add pipe 2 ip from any to any in" .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 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, Ethernet, IRDA). It is not necessary that both pipes have the same configuration, so we can also simulate asymmetric links. .Pp Should we want to verify network performance with the RED queue management algorithm: .Pp .Dl "ipfw add pipe 1 ip from any to any" .Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1" .Pp Another typical application of the traffic shaper is to introduce some delay in the communication. This can significantly affect applications which do a lot of Remote Procedure Calls, and where the round-trip-time of the connection often becomes a limiting factor much more than bandwidth: .Pp .Dl "ipfw add pipe 1 ip from any to any out" .Dl "ipfw add pipe 2 ip from any to any in" .Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s" .Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s" .Pp Per-flow queueing can be useful for a variety of purposes. A very simple one is counting traffic: .Pp .Dl "ipfw add pipe 1 tcp from any to any" .Dl "ipfw add pipe 1 udp from any to any" .Dl "ipfw add pipe 1 ip from any to any" .Dl "ipfw pipe 1 config mask all" .Pp The above set of rules will create queues (and collect statistics) for all traffic. Because the pipes have no limitations, the only effect is collecting statistics. Note that we need 3 rules, not just the last one, because when .Nm tries to match IP packets it will not consider ports, so we would not see connections on separate ports as different ones. .Pp A more sophisticated example is limiting the outbound traffic on a net with per-host limits, rather than per-network limits: .Pp .Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" .Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in" .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 LOOKUP TABLES In the following example, we need to create several traffic bandwidth classes and we need different hosts/networks to fall into different classes. We create one pipe for each class and configure them accordingly. Then we create a single table and fill it with IP subnets and addresses. For each subnet/host we set the argument equal to the number of the pipe that it should use. Then we classify traffic using a single rule: .Pp .Dl "ipfw pipe 1 config bw 1000Kbyte/s" .Dl "ipfw pipe 4 config bw 4000Kbyte/s" .Dl "..." .Dl "ipfw table 1 add 192.168.2.0/24 1" .Dl "ipfw table 1 add 192.168.0.0/27 4" .Dl "ipfw table 1 add 192.168.0.2 1" .Dl "..." .Dl "ipfw pipe tablearg ip from table(1) to any" .Pp Using the .Cm fwd action, the table entries may include hostnames and IP addresses. .Pp .Dl "ipfw table 1 add 192.168.2.0/24 10.23.2.1" .Dl "ipfw table 1 add 192.168.0.0/27 router1.dmz" .Dl "..." .Dl "ipfw add 100 fwd tablearg ip from any to table(1)" .Ss SETS OF RULES 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" .Dl "ipfw set enable 18" .Pp To delete a set of rules atomically the command is simply: .Pp .Dl "ipfw delete set 18" .Pp To test a ruleset and disable it and regain control if something goes wrong: .Pp .Dl "ipfw set disable 18" .Dl "ipfw add NN set 18 ... # repeat as needed" .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 you cannot access your box, the ruleset will be disabled after the sleep terminates thus restoring the previous situation. .Sh SEE ALSO .Xr cpp 1 , .Xr m4 1 , .Xr altq 4 , .Xr divert 4 , .Xr dummynet 4 , .Xr if_bridge 4 , .Xr ip 4 , .Xr ipfirewall 4 , .Xr ng_ipfw 4 , .Xr protocols 5 , .Xr services 5 , .Xr init 8 , .Xr kldload 8 , .Xr reboot 8 , .Xr sysctl 8 , .Xr syslogd 8 .Sh HISTORY The .Nm utility first appeared in .Fx 2.0 . .Xr dummynet 4 was introduced in .Fx 2.2.8 . Stateful extensions were introduced in .Fx 4.0 . .Nm ipfw2 was introduced in Summer 2002. .Sh AUTHORS .An Ugen J. S. Antsilevich , .An Poul-Henning Kamp , .An Alex Nash , .An Archie Cobbs , .An Luigi Rizzo . .Pp .An -nosplit API based upon code written by .An Daniel Boulet for BSDI. .Pp Work on .Xr dummynet 4 traffic shaper supported by Akamba Corp. .Sh BUGS Use of dummynet with IPv6 requires that debug.mpsafenet be set to 0. .Pp The syntax has grown over the years and sometimes it might be confusing. Unfortunately, backward compatibility prevents cleaning up mistakes made in the definition of the syntax. .Pp .Em !!! WARNING !!! .Pp Misconfiguring the firewall can put your computer in an unusable state, possibly shutting down network services and requiring console access to regain control of it. .Pp Incoming packet fragments diverted by .Cm divert are reassembled before delivery to the socket. The action used on those packet is the one from the rule which matches the first fragment of the packet. .Pp Packets diverted to userland, and then reinserted by a userland process may lose various packet attributes. The packet source interface name will be preserved if it is shorter than 8 bytes and the userland process saves and reuses the sockaddr_in (as does .Xr natd 8 ) ; otherwise, it may be lost. If a packet is reinserted in this manner, later rules may be incorrectly applied, making the order of .Cm divert rules in the rule sequence very important. .Pp Dummynet drops all packets with IPv6 link-local addresses. .Pp Rules using .Cm uid or .Cm gid may not behave as expected. In particular, incoming SYN packets may have no uid or gid associated with them since they do not yet belong to a TCP connection, and the uid/gid associated with a packet may not be as expected if the associated process calls .Xr setuid 2 or similar system calls. .Pp Rules which use uid, gid or jail based matching should be used only if debug.mpsafenet=0 to avoid possible deadlocks due to layering violations in its implementation. Index: head/sbin/mdmfs/mdmfs.8 =================================================================== --- head/sbin/mdmfs/mdmfs.8 (revision 162394) +++ head/sbin/mdmfs/mdmfs.8 (revision 162395) @@ -1,381 +1,381 @@ .\" .\" Copyright (c) 2001 Dima Dorfman. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd January 2, 2006 +.Dd February 16, 2006 .Dt MDMFS 8 .Os .Sh NAME .Nm mdmfs , .Nm mount_mfs .Nd configure and mount an in-memory file system using the .Xr md 4 driver .Sh SYNOPSIS .Nm .Op Fl DLlMNPSUX .Op Fl a Ar maxcontig .Op Fl b Ar block-size .Op Fl c Ar cylinders .Op Fl d Ar rotdelay .Op Fl E Ar path-mdconfig .Op Fl e Ar maxbpg .Op Fl F Ar file .Op Fl f Ar frag-size .Op Fl i Ar bytes .Op Fl m Ar percent-free .Op Fl n Ar rotational-positions .Op Fl O Ar optimization .Op Fl o Ar mount-options .Op Fl p Ar permissions .Op Fl s Ar size .Op Fl v Ar version .Op Fl w Ar user : Ns Ar group .Ar md-device .Ar mount-point .Nm .Fl C .Op Fl lNU .Op Fl a Ar maxcontig .Op Fl b Ar block-size .Op Fl c Ar cylinders .Op Fl d Ar rotdelay .Op Fl E Ar path-mdconfig .Op Fl e Ar maxbpg .Op Fl F Ar file .Op Fl f Ar frag-size .Op Fl i Ar bytes .Op Fl m Ar percent-free .Op Fl n Ar rotational-positions .Op Fl O Ar optimization .Op Fl o Ar mount-options .Op Fl s Ar size .Op Fl v Ar version .Ar md-device .Ar mount-point .Sh DESCRIPTION The .Nm utility is designed to be a work-alike and look-alike of the deprecated .Xr mount_mfs 8 . The end result is essentially the same, but is accomplished in a completely different way. The .Nm utility configures an .Xr md 4 disk using .Xr mdconfig 8 , puts a UFS file system on it using .Xr newfs 8 , and mounts it using .Xr mount 8 . All the command line options are passed to the appropriate program at the appropriate stage in order to achieve the desired effect. .Pp By default, .Nm creates a swap-based .Pq Dv MD_SWAP disk with soft-updates enabled and mounts it on .Ar mount-point . It uses the .Xr md 4 device specified by .Ar md-device . If .Ar md-device is .Ql md (no unit number), it will use .Xr md 4 Ns 's auto-unit feature to automatically select an unused device. Unless otherwise specified with one of the options below, it uses the default arguments to all the helper programs. .Pp The following options are available. Where possible, the option letter matches the one used by .Xr mount_mfs 8 for the same thing. .Bl -tag -width indent .It Fl a Ar maxcontig Specify the maximum number of contiguous blocks that will be laid out before forcing a rotational delay (see the .Fl d option). .It Fl b Ar block-size The block size of the file system, in bytes. .It Fl C Enable full compatibility mode with .Xr mount_mfs 8 . See the .Sx COMPATIBILITY section for more information. .It Fl c Ar cylinders The number of cylinders per cylinder group in the file system. .It Fl D If not using auto-unit, do not run .Xr mdconfig 8 to try to detach the unit before attaching it. .It Fl d Ar rotdelay Specify the minimum time in milliseconds required to initiate another disk transfer on the same cylinder. Modern disks with read/write-behind achieve higher performance without this feature, so it is best to leave it at 0 milliseconds. .It Fl E Ar path-mdconfig Use .Ar path-mdconfig as a location of the .Xr mdconfig 8 utility. .It Fl e Ar maxbpg Indicate the maximum number of blocks any single file can allocate out of a cylinder group before it is forced to begin allocating blocks from another cylinder group. .It Fl F Ar file Create a vnode-backed .Pq Dv MD_VNODE memory disk backed by .Ar file . .It Fl f Ar frag-size The fragment size of the file system in bytes. .It Fl i Ar bytes Number of bytes per inode. .It Fl l Enable multilabel MAC on the new file system. .It Fl L Show the output of the helper programs. By default, it is sent to .Pa /dev/null . .It Fl M Create a .Xr malloc 9 backed disk .Pq Dv MD_MALLOC instead of a swap-backed disk. .It Fl m Ar percent-free The percentage of space reserved for the superuser. .It Fl N Do not actually run the helper programs. This is most useful in conjunction with .Fl X . .It Fl n Ar rotational-positions The default number of rotational positions to distinguish. .It Fl O Ar optimization Select the optimization preference; valid choices are .Cm space and .Cm time , which will optimize for minimum space fragmentation and minimum time spent allocating blocks, respectively. .It Fl o Ar mount-options Specify the mount options with which to mount the file system. See .Xr mount 8 for more information. .It Fl P -Preserve the existing filesystem; +Preserve the existing file system; do not run .Xr newfs 8 . This only makes sense if .Fl F is specified to create a vnode-backed disk. .It Fl p Ar permissions Set the file (directory) permissions of the mount point .Ar mount-point to .Ar permissions . The .Ar permissions argument can be in any of the mode formats recognized by .Xr chmod 1 . If symbolic permissions are specified, the operation characters .Dq + and .Dq - are interpreted relative to the initial permissions of .Dq a=rwx . .It Fl S Do not enable soft-updates on the file system. .It Fl s Ar size Specify the size of the disk to create. This only makes sense if .Fl F is .Em not specified. That is, this will work for the default swap-backed .Pq Dv MD_SWAP disks, and the optional .Pq Fl M .Xr malloc 9 backed disks .Pq Dv MD_MALLOC . .It Fl U Enable soft-updates on the file system. This is the default, even in compatibility mode, and is accepted only for compatibility. It is only really useful to negate the .Fl S flag, should such a need occur. .It Fl v Ar version Specify the UFS version number for use on the file system; it may be either .Dv 1 or .Dv 2 . The default is derived from the default of the .Xr newfs 8 command. .It Fl w Ar user : Ns Ar group Set the owner and group to .Ar user and .Ar group , respectively. The arguments have the same semantics as with .Xr chown 8 , but specifying just a .Ar user or just a .Ar group is not supported. .It Fl X Print what command will be run before running it, and other assorted debugging information. .El .Pp The .Fl F and .Fl s options are passed to .Xr mdconfig 8 as .Fl f and .Fl s , respectively. The .Fl a , b , c , d , e , f , i , m and .Fl n options are passed to .Xr newfs 8 with the same letter; the .Fl O option is passed to .Xr newfs 8 as .Fl o . The .Fl o option is passed to .Xr mount 8 with the same letter. See the programs that the options are passed to for more information on their semantics. .Sh EXAMPLES Create and mount a 32 megabyte swap-backed file system on .Pa /tmp : .Pp .Dl "mdmfs -s 32m md /tmp" .Pp The same file system created as an entry in .Pa /etc/fstab : .Pp .Dl "md /tmp mfs rw,-s32m 2 0" .Pp Create and mount a 16 megabyte malloc-backed file system on .Pa /tmp using the .Pa /dev/md1 device; furthermore, do not use soft-updates on it and mount it .Cm async : .Pp .Dl "mdmfs -M -S -o async -s 16m md1 /tmp" .Sh COMPATIBILITY The .Nm utility, while designed to be fully compatible with .Xr mount_mfs 8 , can be useful by itself. Since .Xr mount_mfs 8 had some silly defaults, a .Dq full compatibility mode is provided for the case where bug-to-bug compatibility is desired. .Pp Full compatibility is enabled with the .Fl C flag, or by starting .Nm with the name .Li mount_mfs or .Li mfs (as returned by .Xr getprogname 3 ) . In this mode, only the options which would be accepted by .Xr mount_mfs 8 are valid. Furthermore, the following behavior, as done by .Xr mount_mfs 8 , is duplicated: .Bl -bullet -offset indent .It The file mode of .Ar mount-point is set to .Li 01777 as if .Fl p Ar 1777 was given on the command line. .El .Sh SEE ALSO .Xr md 4 , .Xr fstab 5 , .Xr mdconfig 8 , .Xr mount 8 , .Xr newfs 8 .Sh AUTHORS .An Dima Dorfman Index: head/sbin/mount/mount.8 =================================================================== --- head/sbin/mount/mount.8 (revision 162394) +++ head/sbin/mount/mount.8 (revision 162395) @@ -1,534 +1,534 @@ .\" Copyright (c) 1980, 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)mount.8 8.8 (Berkeley) 6/16/94 .\" $FreeBSD$ .\" .Dd July 12, 2006 .Dt MOUNT 8 .Os .Sh NAME .Nm mount .Nd mount file systems .Sh SYNOPSIS .Nm .Op Fl adflpruvw .Op Fl F Ar fstab .Op Fl o Ar options -.Op Fl t Ar ufs | external_type +.Op Fl t Cm ufs | Ar external_type .Nm .Op Fl dfpruvw .Ar special | node .Nm .Op Fl dfpruvw .Op Fl o Ar options -.Op Fl t Ar ufs | external_type +.Op Fl t Cm ufs | Ar external_type .Ar special node .Sh DESCRIPTION The .Nm utility calls the .Xr nmount 2 system call to prepare and graft a -.Ar "special device" -or the remote node (rhost:path) on to the file system tree at the point +.Ar special +device or the remote node (rhost:path) on to the file system tree at the point .Ar node . If either .Ar special or .Ar node are not provided, the appropriate information is taken from the .Xr fstab 5 file. .Pp The system maintains a list of currently mounted file systems. If no arguments are given to .Nm , this list is printed. .Pp The options are as follows: .Bl -tag -width indent .It Fl a All the file systems described in .Xr fstab 5 are mounted. Exceptions are those marked as -.Dq noauto , +.Dq Li noauto , those marked as -.Dq late +.Dq Li late (unless the .Fl l option was specified), those excluded by the .Fl t flag (see below), or if they are already mounted (except the root file system which is always remounted to preserve traditional single user mode behavior). .It Fl d Causes everything to be done except for the actual system call. This option is useful in conjunction with the .Fl v flag to determine what the .Nm command is trying to do. .It Fl F Ar fstab Specify the .Pa fstab file to use. .It Fl f Forces the revocation of write access when trying to downgrade a file system mount status from read-write to read-only. Also forces the R/W mount of an unclean file system (dangerous; use with caution). .It Fl l When used in conjunction with the .Fl a option, also mount those file systems which are marked as -.Dq late . +.Dq Li late . .It Fl o Options are specified with a .Fl o flag followed by a comma separated string of options. In case of conflicting options being specified, the rightmost option takes effect. The following options are available: .Bl -tag -width indent .It Cm acls Enable Access Control Lists, or ACLS, which can be customized via the .Xr setfacl 1 and .Xr getfacl 1 commands. .It Cm async All .Tn I/O to the file system should be done asynchronously. This is a .Em dangerous flag to set, since it does not guarantee that the file system structure on the disk will remain consistent. For this reason, the .Cm async flag should be used sparingly, and only when some data recovery mechanism is present. .It Cm current When used with the .Fl u flag, this is the same as specifying the options currently in effect for the mounted file system. .It Cm force The same as .Fl f ; forces the revocation of write access when trying to downgrade a file system mount status from read-write to read-only. Also forces the R/W mount of an unclean file system (dangerous; use with caution). .It Cm fstab When used with the .Fl u flag, this is the same as specifying all the options listed in the .Xr fstab 5 file for the file system. .It Cm late This file system should be skipped when .Nm is run with the .Fl a flag but without the .Fl l flag. .It Cm multilabel Enable multi-label Mandatory Access Control, or MAC, on the specified file system. If the file system supports multilabel operation, individual labels will be maintained for each object in the file system, rather than using a single label for all objects. An alternative to the .Fl l flag in .Xr tunefs 8 . See .Xr mac 4 for more information, which cause the multilabel mount flag to be set automatically at mount-time. .It Cm noasync Metadata I/O should be done synchronously, while data I/O should be done asynchronously. This is the default. .It Cm noatime Do not update the file access time when reading from a file. This option is useful on file systems where there are large numbers of files and performance is more critical than updating the file access time (which is rarely ever important). This option is currently only supported on local file systems. .It Cm noauto This file system should be skipped when .Nm is run with the .Fl a flag. .It Cm noclusterr Disable read clustering. .It Cm noclusterw Disable write clustering. .It Cm noexec Do not allow execution of any binaries on the mounted file system. This option is useful for a server that has file systems containing binaries for architectures other than its own. Note: This option was not designed as a security feature and no guarantee is made that it will prevent malicious code execution; for example, it is still possible to execute scripts which reside on a .Cm noexec mounted partition. .It Cm nosuid Do not allow set-user-identifier or set-group-identifier bits to take effect. Note: this option is worthless if a public available suid or sgid wrapper like .Xr suidperl 1 is installed on your system. It is set automatically when the user does not have super-user privileges. .It Cm nosymfollow Do not follow symlinks on the mounted file system. .It Cm ro The same as .Fl r ; mount the file system read-only (even the super-user may not write it). .It Cm sync All .Tn I/O to the file system should be done synchronously. .It Cm snapshot This option allows a snapshot of the specified file system to be taken. The .Fl u flag is required with this option. Note that snapshot files must be created in the file system that is being snapshotted. You may create up to 20 snapshots per file system. Active snapshots are recorded in the superblock, so they persist across unmount and remount operations and across system reboots. When you are done with a snapshot, it can be removed with the .Xr rm 1 command. Snapshots may be removed in any order, however you may not get back all the space contained in the snapshot as another snapshot may claim some of the blocks that it is releasing. Note that the schg flag is set on snapshots to ensure that not even the root user can write to them. The unlink command makes an exception for snapshot files in that it allows them to be removed even though they have the schg flag set, so it is not necessary to clear the schg flag before removing a snapshot file. .Pp Once you have taken a snapshot, there are three interesting things that you can do with it: .Pp .Bl -enum -compact .It Run .Xr fsck 8 on the snapshot file. Assuming that the file system was clean when it was mounted, you should always get a clean (and unchanging) result from running fsck on the snapshot. This is essentially what the background fsck process does. .Pp .It Run .Xr dump 8 on the snapshot. You will get a dump that is consistent with the file system as of the timestamp of the snapshot. .Pp .It Mount the snapshot as a frozen image of the file system. To mount the snapshot .Pa /var/snapshot/snap1 : .Bd -literal mdconfig -a -t vnode -f /var/snapshot/snap1 -u 4 mount -r /dev/md4 /mnt .Ed .Pp You can now cruise around your frozen .Pa /var file system at .Pa /mnt . Everything will be in the same state that it was at the time the snapshot was taken. The one exception is that any earlier snapshots will appear as zero length files. When you are done with the mounted snapshot: .Bd -literal umount /mnt mdconfig -d -u 4 .Ed .Pp Further details can be found in the file at .Pa /usr/src/sys/ufs/ffs/README.snapshot . .El .It Cm suiddir A directory on the mounted file system will respond to the SUID bit being set, by setting the owner of any new files to be the same as the owner of the directory. New directories will inherit the bit from their parents. Execute bits are removed from the file, and it will not be given to root. .Pp This feature is designed for use on fileservers serving PC users via ftp, SAMBA, or netatalk. It provides security holes for shell users and as such should not be used on shell machines, especially on home directories. This option requires the SUIDDIR option in the kernel to work. Only UFS file systems support this option. See .Xr chmod 2 for more information. .It Cm update The same as .Fl u ; indicate that the status of an already mounted file system should be changed. .It Cm union Causes the namespace at the mount point to appear as the union of the mounted file system root and the existing directory. Lookups will be done in the mounted file system first. If those operations fail due to a non-existent file the underlying directory is then accessed. All creates are done in the mounted file system. .El .Pp Any additional options specific to a file system type that is not one of the internally known types (see the .Fl t option) may be passed as a comma separated list; these options are distinguished by a leading .Dq \&- (dash). Options that take a value are specified using the syntax -option=value. For example, the .Nm command: .Bd -literal -offset indent mount -t unionfs -o -b /sys $HOME/sys .Ed .Pp causes .Nm to execute the equivalent of: .Bd -literal -offset indent /sbin/mount_unionfs -b /sys $HOME/sys .Ed .Pp Additional options specific to file system types which are not internally known (see the description of the .Fl t option below) may be described in the manual pages for the associated .Pa /sbin/mount_ Ns Sy XXX utilities. .It Fl p Print mount information in .Xr fstab 5 format. Implies also the .Fl v option. .It Fl r The file system is to be mounted read-only. Mount the file system read-only (even the super-user may not write it). The same as the .Cm ro argument to the .Fl o option. -.It Fl t Ar ufs | external_type +.It Fl t Cm ufs | Ar external_type The argument following the .Fl t is used to indicate the file system type. The type -.Ar ufs +.Cm ufs is the default. The .Fl t option can be used to indicate that the actions should only be taken on file systems of the specified type. More than one type may be specified in a comma separated list. The list of file system types can be prefixed with -.Dq no +.Dq Li no to specify the file system types for which action should .Em not be taken. For example, the .Nm command: .Bd -literal -offset indent mount -a -t nonfs,nullfs .Ed .Pp mounts all file systems except those of type .Tn NFS and .Tn NULLFS . .Pp The default behavior of .Nm is to pass the .Fl t option directly to the .Xr nmount 2 system call in the .Li fstype option. .Pp However, for the following file system types: -.Ar cd9660 , -.Ar mfs , -.Ar msdosfs , -.Ar nfs , -.Ar nfs4 , -.Ar ntfs , -.Ar nwfs , -.Ar nullfs , -.Ar portalfs , -.Ar smbfs , -.Ar udf , -.Ar umapfs , +.Cm cd9660 , +.Cm mfs , +.Cm msdosfs , +.Cm nfs , +.Cm nfs4 , +.Cm ntfs , +.Cm nwfs , +.Cm nullfs , +.Cm portalfs , +.Cm smbfs , +.Cm udf , +.Cm umapfs , and -.Ar unionfs , +.Cm unionfs , .Nm will not call .Xr nmount 2 directly and will instead attempt to execute a program in .Pa /sbin/mount_ Ns Sy XXX where .Sy XXX is replaced by the file system type name. For example, nfs file systems are mounted by the program .Pa /sbin/mount_nfs . .Pp Most file systems will be dynamically loaded by the kernel if not already present, and if the kernel module is available. .It Fl u The .Fl u flag indicates that the status of an already mounted file system should be changed. Any of the options discussed above (the .Fl o option) may be changed; also a file system can be changed from read-only to read-write or vice versa. An attempt to change from read-write to read-only will fail if any files on the file system are currently open for writing unless the .Fl f flag is also specified. The set of options is determined by applying the options specified in the argument to .Fl o and finally applying the .Fl r or .Fl w option. .It Fl v Verbose mode. .It Fl w The file system object is to be read and write. .El .Sh ENVIRONMENT .Bl -tag -width ".Ev PATH_FSTAB" .It Ev PATH_FSTAB If the environment variable .Ev PATH_FSTAB is set, all operations are performed against the specified file. .Ev PATH_FSTAB will not be honored if the process environment or memory address space is considered .Dq tainted . (See .Xr issetugid 2 for more information.) .El .Sh FILES .Bl -tag -width /etc/fstab -compact .It Pa /etc/fstab file system table .El .Sh DIAGNOSTICS Various, most of them are self-explanatory. .Pp .Dl XXXXX file system is not available .Pp The kernel does not support the respective file system type. Note that support for a particular file system might be provided either on a static (kernel compile-time), or dynamic basis (loaded as a kernel module by .Xr kldload 8 ) . .Sh SEE ALSO .Xr getfacl 1 , .Xr setfacl 1 , .Xr nmount 2 , .Xr acl 3 , .Xr mac 4 , -.Xr fstab 5 , -.Xr kldload 8 , .Xr ext2fs 5 , +.Xr fstab 5 , .Xr procfs 5 , +.Xr kldload 8 , .Xr mount_cd9660 8 , .Xr mount_msdosfs 8 , .Xr mount_nfs 8 , .Xr mount_ntfs 8 , .Xr mount_nullfs 8 , .Xr mount_nwfs 8 , .Xr mount_portalfs 8 , .Xr mount_smbfs 8 , .Xr mount_std 8 , .Xr mount_udf 8 , .Xr mount_umapfs 8 , .Xr mount_unionfs 8 , .Xr umount 8 .Sh CAVEATS After a successful .Nm , the permissions on the original mount point determine if .Pa ..\& is accessible from the mounted file system. The minimum permissions for the mount point for traversal across the mount point in both directions to be possible for all users is 0111 (execute for all). .Sh HISTORY A .Nm utility appeared in .At v1 . .Sh BUGS It is possible for a corrupted file system to cause a crash. Index: head/sbin/setkey/setkey.8 =================================================================== --- head/sbin/setkey/setkey.8 (revision 162394) +++ head/sbin/setkey/setkey.8 (revision 162395) @@ -1,723 +1,731 @@ .\" $KAME: setkey.8,v 1.89 2003/09/07 22:17:41 itojun Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the project nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd January 8, 2006 +.Dd May 13, 2006 .Dt SETKEY 8 .Os .\" .Sh NAME .Nm setkey .Nd "manually manipulate the IPsec SA/SP database" .\" .Sh SYNOPSIS .Nm .Op Fl v .Fl c .Nm .Op Fl v .Fl f Ar filename .Nm .Op Fl aPlv .Fl D .Nm .Op Fl Pv .Fl F .Nm .Op Fl h .Fl x .\" .Sh DESCRIPTION The .Nm utility adds, updates, dumps, or flushes Security Association Database (SAD) entries as well as Security Policy Database (SPD) entries in the kernel. .Pp The .Nm utility takes a series of operations from the standard input (if invoked with .Fl c ) or the file named .Ar filename (if invoked with .Fl f Ar filename ) . .Bl -tag -width indent .It Fl D Dump the SAD entries. If with .Fl P , the SPD entries are dumped. .It Fl F Flush the SAD entries. If with .Fl P , the SPD entries are flushed. .It Fl a The .Nm utility usually does not display dead SAD entries with .Fl D . If with .Fl a , the dead SAD entries will be displayed as well. A dead SAD entry means that it has been expired but remains in the system because it is referenced by some SPD entries. .It Fl h Add hexadecimal dump on .Fl x mode. .It Fl l Loop forever with short output on .Fl D . .It Fl v Be verbose. The program will dump messages exchanged on .Dv PF_KEY socket, including messages sent from other processes to the kernel. .It Fl x Loop forever and dump all the messages transmitted to .Dv PF_KEY socket. .Fl xx makes each timestamps unformatted. .El .Ss Configuration syntax With .Fl c or .Fl f on the command line, .Nm accepts the following configuration syntax. Lines starting with hash signs .Pq Ql # are treated as comment lines. .Bl -tag -width indent .It Xo .Li add .Op Fl 46n .Ar src Ar dst Ar protocol Ar spi .Op Ar extensions .Ar algorithm ... .Li ; .Xc Add an SAD entry. .Li add can fail with multiple reasons, including when the key length does not match the specified algorithm. .\" .It Xo .Li get .Op Fl 46n .Ar src Ar dst Ar protocol Ar spi .Li ; .Xc Show an SAD entry. .\" .It Xo .Li delete .Op Fl 46n .Ar src Ar dst Ar protocol Ar spi .Li ; .Xc Remove an SAD entry. .\" .It Xo .Li deleteall .Op Fl 46n .Ar src Ar dst Ar protocol .Li ; .Xc Remove all SAD entries that match the specification. .\" .It Xo .Li flush .Op Ar protocol .Li ; .Xc Clear all SAD entries matched by the options. .Fl F on the command line achieves the same functionality. .\" .It Xo .Li dump .Op Ar protocol .Li ; .Xc Dumps all SAD entries matched by the options. .Fl D on the command line achieves the same functionality. .\" .It Xo .Li spdadd .Op Fl 46n .Ar src_range Ar dst_range Ar upperspec Ar policy .Li ; .Xc Add an SPD entry. .\" .It Xo .Li spddelete .Op Fl 46n .Ar src_range Ar dst_range Ar upperspec Fl P Ar direction .Li ; .Xc Delete an SPD entry. .\" .It Xo .Li spdflush .Li ; .Xc Clear all SPD entries. .Fl FP on the command line achieves the same functionality. .\" .It Xo .Li spddump .Li ; .Xc Dumps all SPD entries. .Fl DP on the command line achieves the same functionality. .El .\" .Pp Meta-arguments are as follows: .Pp .Bl -tag -compact -width indent .It Ar src .It Ar dst Source/destination of the secure communication is specified as IPv4/v6 address. The .Nm utility can resolve a FQDN into numeric addresses. If the FQDN resolves into multiple addresses, .Nm will install multiple SAD/SPD entries into the kernel by trying all possible combinations. .Fl 4 , .Fl 6 and .Fl n restricts the address resolution of FQDN in certain ways. .Fl 4 and .Fl 6 restrict results into IPv4/v6 addresses only, respectively. .Fl n avoids FQDN resolution and requires addresses to be numeric addresses. .\" .Pp .It Ar protocol .Ar protocol is one of following: .Bl -tag -width Fl -compact .It Li esp ESP based on rfc2406 .It Li esp-old ESP based on rfc1827 .It Li ah AH based on rfc2402 .It Li ah-old AH based on rfc1826 .It Li ipcomp IPComp .It Li tcp TCP-MD5 based on rfc2385 .El .\" .Pp .It Ar spi Security Parameter Index (SPI) for the SAD and the SPD. .Ar spi must be a decimal number, or a hexadecimal number with .Ql 0x prefix. SPI values between 0 and 255 are reserved for future use by IANA and they cannot be used. TCP-MD5 associations must use 0x1000 and therefore only have per-host granularity at this time. .\" .Pp .It Ar extensions take some of the following: .Bl -tag -width Fl -compact .\" .It Fl m Ar mode Specify a security protocol mode for use. .Ar mode is one of following: .Li transport , tunnel or .Li any . The default value is .Li any . .\" .It Fl r Ar size Specify window size of bytes for replay prevention. .Ar size must be decimal number in 32-bit word. If .Ar size is zero or not specified, replay check does not take place. .\" .It Fl u Ar id Specify the identifier of the policy entry in SPD. See .Ar policy . .\" .It Fl f Ar pad_option defines the content of the ESP padding. .Ar pad_option is one of following: .Bl -tag -width random-pad -compact .It Li zero-pad All of the padding are zero. .It Li random-pad A series of randomized values are set. .It Li seq-pad A series of sequential increasing numbers started from 1 are set. .El .\" .It Fl f Li nocyclic-seq Do not allow cyclic sequence number. .\" .It Fl lh Ar time .It Fl ls Ar time Specify hard/soft life time duration of the SA. .El .\" .Pp .It Ar algorithm .Bl -tag -width Fl -compact .It Fl E Ar ealgo Ar key Specify an encryption algorithm .Ar ealgo for ESP. .It Xo .Fl E Ar ealgo Ar key .Fl A Ar aalgo Ar key .Xc Specify a encryption algorithm .Ar ealgo , as well as a payload authentication algorithm .Ar aalgo , for ESP. .It Fl A Ar aalgo Ar key Specify an authentication algorithm for AH. .It Fl C Ar calgo Op Fl R Specify a compression algorithm for IPComp. If .Fl R is specified, the .Ar spi field value will be used as the IPComp CPI (compression parameter index) on wire as is. If .Fl R is not specified, the kernel will use well-known CPI on wire, and .Ar spi field will be used only as an index for kernel internal usage. .El .Pp .Ar key must be double-quoted character string, or a series of hexadecimal digits preceded by .Ql 0x . .Pp Possible values for .Ar ealgo , .Ar aalgo and .Ar calgo are specified in separate section. .\" .Pp .It Ar src_range .It Ar dst_range These are selections of the secure communication specified as IPv4/v6 address or IPv4/v6 address range, and it may accompany TCP/UDP port specification. This takes the following form: .Bd -unfilled .Ar address .Ar address/prefixlen .Ar address[port] .Ar address/prefixlen[port] .Ed .Pp .Ar prefixlen and .Ar port must be a decimal number. The square brackets around .Ar port are necessary and are not manpage metacharacters. For FQDN resolution, the rules applicable to .Ar src and .Ar dst apply here as well. .\" .Pp .It Ar upperspec The upper layer protocol to be used. You can use one of the words in .Pa /etc/protocols as .Ar upperspec , as well as .Li icmp6 , .Li ip4 , or .Li any . -.Li Any +The word +.Li any stands for .Dq any protocol . -The protocol number may also be used to specify the +The protocol number may also be used to specify the .Ar upperspec . A type and code related to ICMPv6 may also be specified as an .Ar upperspec . The type is specified first, followed by a comma and then the relevant code. The specification must be placed after .Li icmp6 . -The kernel considers a zero to be a wildcard but -cannot distinguish between a wildcard and an ICMPv6 +The kernel considers a zero to be a wildcard but +cannot distinguish between a wildcard and an ICMPv6 type which is zero. The following example shows a policy where IPSec is not required for inbound Neighbor Solicitations: .Pp .Dl "spdadd ::/0 ::/0 icmp6 135,0 -P in none;" .Pp NOTE: .Ar upperspec does not work in the forwarding case at this moment, as it requires extra reassembly at forwarding node, which is not implemented at this moment. Although there are many protocols in .Pa /etc/protocols , protocols other than TCP, UDP and ICMP may not be suitable to use with IPsec. .\" .Pp .It Ar policy .Ar policy is expressed in one of the following three formats: .Bd -ragged -offset indent .It Fl P Ar direction Li discard .It Fl P Ar direction Li none .It Xo Fl P Ar direction Li ipsec .Ar protocol/mode/src-dst/level Op ... .Xc .Ed .Pp The direction of a policy must be specified as one of: .Li out , .Li in , -.Li discard +.Li discard , .Li none , -or +or .Li ipsec . -.Li Discard +The +.Li discard +direction means that packets matching the supplied indices will be discarded -while +while .Li none means that IPsec operations will not take place on the packet and .Li ipsec means that IPsec operation will take place onto the packet. -The +The .Ar protocol/mode/src-dst/level statement gives the rule for how to process the packet. -.Ar Protocol is specified as +The +.Ar protocol +is specified as .Li ah , .Li esp or .Li ipcomp The .Ar mode is either .Li transport or .Li tunnel . If .Ar mode is .Li tunnel , you must specify the end-point addresses of the SA as .Ar src and .Ar dst -with a dash, +with a dash, .Sq - , between the addresses. If .Ar mode is .Li transport , both .Ar src and .Ar dst can be omitted. The .Ar level is one of the following: .Li default , use , require or .Li unique . If the SA is not available in every level, the kernel will request the SA from the key exchange daemon. A value of .Li default -tells the kernel to use the system wide default protocol -e.g. the one from the +tells the kernel to use the system wide default protocol +e.g.\& the one from the .Li esp_trans_deflev sysctl variable, when the kernel processes the packet. -.Li Use +A value of +.Li use means that the kernel will use an SA if it is available, otherwise the kernel will pass the packet as it would normally. -.Li Require +A value of +.Li require means that an SA is required whenever the kernel sends a packet matched that matches the policy. -The +The .Li unique level is the same as .Li require but, in addition, it allows the policy to bind with the unique out-bound SA. For example, if you specify the policy level .Li unique , .Xr racoon 8 will configure the SA for the policy. If you configure the SA by manual keying for that policy, you can put the decimal number as the policy identifier after .Li unique separated by colon .Ql :\& as in the following example: .Li unique:number . In order to bind this policy to the SA, .Li number -must be between 1 and 32767, +must be between 1 and 32767, which corresponds to .Ar extensions Fl u of manual SA configuration. .Pp -When you want to use an SA bundle, you can define multiple rules. For +When you want to use an SA bundle, you can define multiple rules. +For example, if an IP header was followed by an AH header followed by an ESP header followed by an upper layer protocol header, the rule would be: .Dl esp/transport//require ah/transport//require ; The rule order is very important. .Pp Note that .Dq Li discard and .Dq Li none are not in the syntax described in .Xr ipsec_set_policy 3 . There are small, but important, differences in the syntax. See .Xr ipsec_set_policy 3 for details. .Pp .El .Pp .\" .Sh ALGORITHMS The following list shows the supported algorithms. The .Sy protocol and .Sy algorithm are almost completely orthogonal. The following list of authentication algorithms can be used as .Ar aalgo in the .Fl A Ar aalgo of the .Ar protocol parameter: .Pp .Bd -literal -offset indent algorithm keylen (bits) comment hmac-md5 128 ah: rfc2403 128 ah-old: rfc2085 hmac-sha1 160 ah: rfc2404 160 ah-old: 128bit ICV (no document) keyed-md5 128 ah: 96bit ICV (no document) 128 ah-old: rfc1828 keyed-sha1 160 ah: 96bit ICV (no document) 160 ah-old: 128bit ICV (no document) null 0 to 2048 for debugging hmac-sha2-256 256 ah: 96bit ICV (draft-ietf-ipsec-ciph-sha-256-00) 256 ah-old: 128bit ICV (no document) hmac-sha2-384 384 ah: 96bit ICV (no document) 384 ah-old: 128bit ICV (no document) hmac-sha2-512 512 ah: 96bit ICV (no document) 512 ah-old: 128bit ICV (no document) hmac-ripemd160 160 ah: 96bit ICV (RFC2857) ah-old: 128bit ICV (no document) aes-xcbc-mac 128 ah: 96bit ICV (RFC3566) 128 ah-old: 128bit ICV (no document) tcp-md5 8 to 640 tcp: rfc2385 .Ed .Pp The following is the list of encryption algorithms that can be used as the .Ar ealgo in the .Fl E Ar ealgo of the .Ar protocol parameter: .Pp .Bd -literal -offset indent algorithm keylen (bits) comment des-cbc 64 esp-old: rfc1829, esp: rfc2405 3des-cbc 192 rfc2451 null 0 to 2048 rfc2410 blowfish-cbc 40 to 448 rfc2451 cast128-cbc 40 to 128 rfc2451 des-deriv 64 ipsec-ciph-des-derived-01 3des-deriv 192 no document rijndael-cbc 128/192/256 rfc3602 aes-ctr 160/224/288 draft-ietf-ipsec-ciph-aes-ctr-03 .Ed .Pp Note that the first 128/192/256 bits of a key for .Li aes-ctr will be used as AES key, and remaining 32 bits will be used as nonce. .Pp The following are the list of compression algorithms that can be used as the .Ar calgo in the .Fl C Ar calgo of the .Ar protocol parameter: .Pp .Bd -literal -offset indent algorithm comment deflate rfc2394 .Ed .\" .Sh EXIT STATUS .Ex -std .\" .Sh EXAMPLES Add an ESP SA between two IPv6 addresses using the des-cbc encryption algorithm. .Bd -literal -offset add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 -E des-cbc 0x3ffe05014819ffff ; .Ed .\" Add an authentication SA between two FQDN specified hosts: .Bd -literal -offset add -6 myhost.example.com yourhost.example.com ah 123456 -A hmac-sha1 "AH SA configuration!" ; .Ed Use both ESP and AH between two numerically specified hosts: .Bd -literal -offset add 10.0.11.41 10.0.11.33 esp 0x10001 -E des-cbc 0x3ffe05014819ffff -A hmac-md5 "authentication!!" ; .Ed Get the SA information assocaited with first example above: .Bd -literal -offset get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ; .Ed Flush all entries from the database: .Bd -literal -offset flush ; .Ed Dump the ESP entries from the database: .Bd -literal -offset dump esp ; .Ed Add a security policy between two networks that uses ESP in tunnel mode: .Bd -literal -offset spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ; .Ed Use TCP MD5 between two numerically specified hosts: .Bd -literal -offset add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ; .Ed .\" .Sh SEE ALSO .Xr ipsec_set_policy 3 , .Xr racoon 8 , .Xr sysctl 8 .Rs .%T "Changed manual key configuration for IPsec" .%O "http://www.kame.net/newsletter/19991007/" .%D "October 1999" .Re .\" .Sh HISTORY The .Nm utility first appeared in WIDE Hydrangea IPv6 protocol stack kit. The utility was completely re-designed in June 1998. .\" .Sh BUGS The .Nm utility should report and handle syntax errors better. .Pp For IPsec gateway configuration, .Ar src_range and .Ar dst_range with TCP/UDP port number do not work, as the gateway does not reassemble packets (cannot inspect upper-layer headers).