Index: head/sbin/geom/class/part/gpart.8 =================================================================== --- head/sbin/geom/class/part/gpart.8 (revision 222598) +++ head/sbin/geom/class/part/gpart.8 (revision 222599) @@ -1,944 +1,945 @@ .\" Copyright (c) 2007, 2008 Marcel Moolenaar .\" 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 May 30, 2011 .Dt GPART 8 .Os .Sh NAME .Nm gpart .Nd "control utility for the disk partitioning GEOM class" .Sh SYNOPSIS To add support for the disk partitioning GEOM class, place one or more of the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "options GEOM_PART_APM" .Cd "options GEOM_PART_BSD" .Cd "options GEOM_PART_EBR" .Cd "options GEOM_PART_EBR_COMPAT" .Cd "options GEOM_PART_GPT" .Cd "options GEOM_PART_MBR" .Cd "options GEOM_PART_PC98" .Cd "options GEOM_PART_VTOC8" .Ed .Pp The .Dv GEOM_PART_APM option adds support for the Apple Partition Map (APM) found on Apple Macintosh computers. The .Dv GEOM_PART_BSD option adds support for the traditional .Bx disklabel. The .Dv GEOM_PART_EBR option adds support for the Extended Boot Record (EBR), which is used to define a logical partition. The .Dv GEOM_PART_EBR_COMPAT option enables backward compatibility for partition names in the EBR scheme. Also it makes impossible any types of actions with such partitions. The .Dv GEOM_PART_GPT option adds support for the GUID Partition Table (GPT) found on Intel Itanium computers and Intel-based Macintosh computers. The .Dv GEOM_PART_MBR option adds support for the Master Boot Record (MBR) found on PCs and used on many removable media. The .Dv GEOM_PART_PC98 option adds support for the MBR variant as used on NEC PC-98 computers. The .Dv GEOM_PART_VTOC8 option adds support for Sun's SMI VTOC8 label as found on computers based on .Tn SPARC64 and .Tn UltraSPARC. .Pp Usage of the .Ns Nm utility: .Pp .\" ==== ADD ==== .Nm .Cm add .Fl t Ar type .Op Fl a Ar alignment .Op Fl b Ar start .Op Fl s Ar size .Op Fl i Ar index .Op Fl l Ar label .Op Fl f Ar flags .Ar geom .\" ==== BACKUP ==== .Nm .Cm backup .Ar geom .\" ==== BOOTCODE ==== .Nm .Cm bootcode .Op Fl b Ar bootcode .Op Fl p Ar partcode Fl i Ar index .Op Fl f Ar flags .Ar geom .\" ==== COMMIT ==== .Nm .Cm commit .Ar geom .\" ==== CREATE ==== .Nm .Cm create .Fl s Ar scheme .Op Fl n Ar entries .Op Fl f Ar flags .Ar provider .\" ==== DELETE ==== .Nm .Cm delete .Fl i Ar index .Op Fl f Ar flags .Ar geom .\" ==== DESTROY ==== .Nm .Cm destroy .Op Fl F .Op Fl f Ar flags .Ar geom .\" ==== MODIFY ==== .Nm .Cm modify .Fl i Ar index .Op Fl l Ar label .Op Fl t Ar type .Op Fl f Ar flags .Ar geom .\" ==== RECOVER ==== .Nm .Cm recover .Op Fl f Ar flags .Ar geom .\" ==== RESIZE ==== .Nm .Cm resize .Fl i Ar index .Op Fl a Ar alignment .Op Fl s Ar size .Op Fl f Ar flags .Ar geom .\" ==== RESTORE ==== .Nm .Cm restore .Op Fl lF .Op Fl f Ar flags .Ar provider .Op Ar ... .\" ==== SET ==== .Nm .Cm set .Fl a Ar attrib .Fl i Ar index .Op Fl f Ar flags .Ar geom .\" ==== SHOW ==== .Nm .Cm show .Op Fl l | Fl r .Op Fl p .Op Ar geom ... .\" ==== UNDO ==== .Nm .Cm undo .Ar geom .\" ==== UNSET ==== .Nm .Cm unset .Fl a Ar attrib .Fl i Ar index .Op Fl f Ar flags .Ar geom .\" .Sh DESCRIPTION The .Nm utility is used to partition GEOM providers, normally disks. The first argument of which is the action to be taken: .Bl -tag -width ".Cm bootcode" .\" ==== ADD ==== .It Cm add Add a new partition to the partitioning scheme given by .Ar geom . The partition begins on the logical block address given by the .Fl b Ar start option. Its size is given by the .Fl s Ar size option. SI unit suffixes are allowed. One or both .Fl b and .Fl s options can be omitted. If so they are automatically calculated. The type of the partition is given by the .Fl t Ar type option. Partition types are discussed below in the section entitled .Sx "PARTITION TYPES" . .Pp Additional options include: .Bl -tag -width 12n .It Fl a Ar alignment If specified, then .Nm utility tries to align .Ar start offset and partition .Ar size to be multiple of .Ar alignment value. .It Fl i Ar index The index in the partition table at which the new partition is to be placed. The index determines the name of the device special file used to represent the partition. .It Fl l Ar label The label attached to the partition. This option is only valid when used on partitioning schemes that support partition labels. .It Fl f Ar flags Additional operational flags. See the section entitled .Sx "OPERATIONAL FLAGS" below for a discussion about its use. .El .\" ==== BACKUP ==== .It Cm backup Dump a partition table to standard output in special format used by .Cm restore action. .\" ==== BOOTCODE ==== .It Cm bootcode Embed bootstrap code into the partitioning scheme's metadata on the .Ar geom (using .Fl b Ar bootcode ) or write bootstrap code into a partition (using .Fl p Ar partcode and .Fl i Ar index ) . Not all partitioning schemes have embedded bootstrap code, so the .Fl b Ar bootcode option is scheme-specific in nature. For the GPT scheme, embedded bootstrap code is supported. The bootstrap code is embedded in the protective MBR rather than the GPT. The .Fl b Ar bootcode option specifies a file that contains the bootstrap code. The contents and size of the file are determined by the partitioning scheme. For the MBR scheme, it is a 512 byte file of which the first 446 bytes are installed as bootstrap code. The .Fl p Ar partcode option specifies a file that contains the bootstrap code intended to be written to a partition. For the VTOC8 scheme, it is a 8192 byte file of which the last 7680 bytes are installed as bootstrap code. The partition is specified by the .Fl i Ar index option. For the VTOC8 scheme, if the .Fl i Ar index option is omitted, the bootstrap code is written to all sufficiently large partitions. The size of the file must be smaller than the size of the partition. .Pp Additional options include: .Bl -tag -width 10n .It Fl f Ar flags Additional operational flags. See the section entitled .Sx "OPERATIONAL FLAGS" below for a discussion about its use. .El .\" ==== COMMIT ==== .It Cm commit Commit any pending changes for geom .Ar geom . All actions are being committed by default and will not result in pending changes. Actions can be modified with the .Fl f Ar flags option so that they are not being committed by default. As such, they become pending. Pending changes are reflected by the geom and the .Nm utility, but they are not actually written to disk. The .Cm commit action will write any and all pending changes to disk. .\" ==== CREATE ==== .It Cm create Create a new partitioning scheme on a provider given by .Ar provider . The .Fl s Ar scheme option determines the scheme to use. The kernel needs to have support for a particular scheme before that scheme can be used to partition a disk. .Pp Additional options include: .Bl -tag -width 10n .It Fl n Ar entries The number of entries in the partition table. Every partitioning scheme has a minimum and a maximum number of entries and this option allows tables to be created with the number of entries that lies anywhere between the minimum and the maximum. Some schemes have a maximum equal to the minimum and some schemes have a maximum large enough to be considered unlimited. By default, partition tables are created with the minimum number of entries. .It Fl f Ar flags Additional operational flags. See the section entitled .Sx "OPERATIONAL FLAGS" below for a discussion about its use. .El .\" ==== DELETE ==== .It Cm delete Delete a partition from geom .Ar geom and further identified by the .Fl i Ar index option. The partition cannot be actively used by the kernel. .Pp Additional options include: .Bl -tag -width 10n .It Fl f Ar flags Additional operational flags. See the section entitled .Sx "OPERATIONAL FLAGS" below for a discussion about its use. .El .\" ==== DESTROY ==== .It Cm destroy Destroy the partitioning scheme as implemented by geom .Ar geom . .Pp Additional options include: .Bl -tag -width 10n .It Fl F Forced destroying of the partition table even if it is not empty. .It Fl f Ar flags Additional operational flags. See the section entitled .Sx "OPERATIONAL FLAGS" below for a discussion about its use. .El .\" ==== MODIFY ==== .It Cm modify Modify a partition from geom .Ar geom and further identified by the .Fl i Ar index option. Only the the type and/or label of the partition can be modified. To change the type of a partition, specify the new type with the .Fl t Ar type option. To change the label of a partition, specify the new label with the .Fl l Ar label option. Not all partitioning schemes support labels and it is invalid to try to change a partition label in such cases. .Pp Additional options include: .Bl -tag -width 10n .It Fl f Ar flags Additional operational flags. See the section entitled .Sx "OPERATIONAL FLAGS" below for a discussion about its use. .El .\" ==== RECOVER ==== .It Cm recover Recover corrupt partition's scheme metadata on the geom .Ar geom . See the section entitled .Sx "RECOVERING" below for the additional information. .Pp Additional options include: .Bl -tag -width 10n .It Fl f Ar flags Additional operational flags. See the section entitled .Sx "OPERATIONAL FLAGS" below for a discussion about its use. .El .\" ==== RESIZE ==== .It Cm resize Resize a partition from geom .Ar geom and further identified by the .Fl i Ar index option. New partition size is expressed in logical block numbers and can be given by the .Fl s Ar size option. If .Fl s option is omitted then new size is automatically calculated to maximum available from given geom .Ar geom . .Pp Additional options include: .Bl -tag -width 12n .It Fl a Ar alignment If specified, then .Nm utility tries to align partition .Ar size to be multiple of .Ar alignment value. .It Fl f Ar flags Additional operational flags. See the section entitled .Sx "OPERATIONAL FLAGS" below for a discussion about its use. .El .\" ==== RESTORE ==== .It Cm restore Restore the partition table from backup previously created by .Cm backup action and given from standard input. Only partition table may be restored. This action does not affect content of partitions. This mean that you should copy your data from backup after restoring partition table and write bootcode again if it is needed. .Pp Additional options include: .Bl -tag -width 10n .It Fl F Destroy partition table on the given .Ar provider before doing restore. .It Fl l Restore partition labels for partitioning schemes that support them. .It Fl f Ar flags Additional operational flags. See the section entitled .Sx "OPERATIONAL FLAGS" below for a discussion about its use. .El .\" ==== SET ==== .It Cm set Set the named attribute on the partition entry. See the section entitled .Sx "ATTRIBUTES" below for a list of available attributes. .Pp Additional options include: .Bl -tag -width 10n .It Fl f Ar flags Additional operational flags. See the section entitled .Sx "OPERATIONAL FLAGS" below for a discussion about its use. .El .\" ==== SHOW ==== .It Cm show Show the current partition information of the specified geoms or all geoms if none are specified. Additional options include: .Bl -tag -width 10n .It Fl l For partition schemes that support partition labels print them instead of partition type. .It Fl p Show provider names instead of partition indexes. .It Fl r Show raw partition type instead of symbolic name. .El .\" ==== UNDO ==== .It Cm undo Revert any pending changes for geom .Ar geom . This action is the opposite of the .Cm commit action and can be used to undo any changes that have not been committed. .\" ==== UNSET ==== .It Cm unset Clear the named attribute on the partition entry. See the section entitled .Sx "ATTRIBUTES" below for a list of available attributes. .Pp Additional options include: .Bl -tag -width 10n .It Fl f Ar flags Additional operational flags. See the section entitled .Sx "OPERATIONAL FLAGS" below for a discussion about its use. .El .El .\" .Sh PARTITION TYPES The .Nm utility uses symbolic names for common partition types to avoid that the user needs to know what the partitioning scheme in question is and what the actual number or identification needs to be used for a particular type. The .Nm utility also allows the user to specify scheme-specific partition types for partition types that do not have symbol names. The symbolic names currently understood are: .Bl -tag -width ".Cm freebsd-vinum" .It Cm bios-boot The system partition dedicated to second stage of the boot loader program. Usually it used by GRUB 2 loader when the partition table is GPT. The scheme-specific type is .Qq Li "!21686148-6449-6E6F-744E-656564454649" . .It Cm efi The system partition for computers that use the Extensible Firmware Interface (EFI). In such cases, the GPT partitioning scheme is being used and the actual partition type for the system partition can also be specified as .Qq Li "!c12a7328-f81f-11d2-ba4b-00a0c93ec93ab" . .It Cm freebsd A .Fx partition that uses the .Bx disklabel to sub-divide the partition into file systems. This is a legacy partition type and should not be used for the APM or GPT schemes. The scheme-specific types are .Qq Li "!165" for MBR, .Qq Li "!FreeBSD" for APM, and .Qq Li "!516e7cb4-6ecf-11d6-8ff8-00022d09712b" for GPT. .It Cm freebsd-boot A .Fx partition dedicated to bootstrap code. The scheme-specific type is .Qq Li "!83bd6b9d-7f41-11dc-be0b-001560b84f0f" for GPT. .It Cm freebsd-swap A .Fx partition dedicated to swap space. The scheme-specific types are .Qq Li "!FreeBSD-swap" for APM, .Qq Li "!516e7cb5-6ecf-11d6-8ff8-00022d09712b" for GPT, and tag 0x0901 for VTOC8. .It Cm freebsd-ufs A .Fx partition that contains a UFS or UFS2 file system. The scheme-specific types are .Qq Li "!FreeBSD-UFS" for APM, .Qq Li "!516e7cb6-6ecf-11d6-8ff8-00022d09712b" for GPT, and tag 0x0902 for VTOC8. .It Cm freebsd-vinum A .Fx partition that contains a Vinum volume. The scheme-specific types are .Qq Li "!FreeBSD-Vinum" for APM, .Qq Li "!516e7cb8-6ecf-11d6-8ff8-00022d09712b" for GPT, and tag 0x0903 for VTOC8. .It Cm freebsd-zfs A .Fx partition that contains a ZFS volume. The scheme-specific types are .Qq Li "!FreeBSD-ZFS" for APM, .Qq Li "!516e7cba-6ecf-11d6-8ff8-00022d09712b" for GPT, and 0x0904 for VTOC8. .It Cm mbr A partition that is sub-partitioned by a master boot record (MBR). This type is known as .Qq Li "!024dee41-33e7-11d3-9d69-0008c781f39f" by GPT. .El .Sh ATTRIBUTES The scheme-specific attributes for EBR: .Bl -tag -width ".Ar active" .It Ar active .El .Pp The scheme-specific attributes for GPT: .Bl -tag -width ".Ar bootfailed" .It Ar bootme When set, the .Nm gptboot stage 1 boot loader will try to boot the system from this partition. Multiple partitions might be marked with the .Ar bootme attribute. In such scenario the .Nm gptboot will try all .Ar bootme partitions one by one, until the next boot stage is successfully entered. .It Ar bootonce Setting this attribute automatically sets the .Ar bootme attribute. When set, the .Nm gptboot stage 1 boot loader will try to boot the system from this partition only once. Partitions with both .Ar bootonce and .Ar bootme attributes are tried before partitions with only the .Ar bootme attribute. Before .Ar bootonce partition is tried, the .Nm gptboot removes the .Ar bootme attribute and tries to execute the next boot stage. If it fails, the .Ar bootonce attribute that is now alone is replaced with the .Ar bootfailed attribute. If the execution of the next boot stage succeeds, but the system is not fully booted, the .Nm gptboot will look for .Ar bootonce attributes alone (without the .Ar bootme attribute) on the next system boot and will replace those with the .Ar bootfailed attribute. If the system is fully booted, the .Pa /etc/rc.d/gptboot start-up script will look for partition with the .Ar bootonce attribute alone, will remove the attribute and log that the system was successfully booted from this partition. There should be at most one .Ar bootonce partition when system is successfully booted. Multiple partitions might be marked with the .Ar bootonce and .Ar bootme attribute pairs. .It Ar bootfailed This attribute should not be manually managed. It is managed by the .Nm gptboot stage 1 boot loader and the .Pa /etc/rc.d/gptboot start-up script. This attribute is used to mark partitions that had the .Ar bootonce attribute set, but we failed to boot from them. Once we successfully boot, the .Pa /etc/rc.d/gptboot script will log all the partitions we failed to boot from and will remove the .Ar bootfailed attributes. .El .Pp The scheme-specific attributes for MBR: .Bl -tag -width ".Ar active" .It Ar active .El .Pp The scheme-specific attributes for PC98: .Bl -tag -width ".Ar bootable" .It Ar active .It Ar bootable .El .Sh OPERATIONAL FLAGS Actions other than the .Cm commit and .Cm undo actions take an optional .Fl f Ar flags option. This option is used to specify action-specific operational flags. By default, the .Nm utility defines the .Ql C flag so that the action is immediately committed. The user can specify .Dq Fl f Cm x to have the action result in a pending change that can later, with other pending changes, be committed as a single compound change with the .Cm commit action or reverted with the .Cm undo action. .Sh RECOVERING The GEOM class PART supports recovering of partition tables only for GPT. The GUID partition table has a primary and secondary (backup) copy of metadata for redundance. They are stored in the begining and in the end of device respectively. Therefore it is acceptable to have some corruptions in the metadata that are not fatal to work with GPT. When kernel detects corrupt metadata it marks this table as corrupt and reports about corruption. Any changes in corrupt table are prohibited except .Cm destroy and .Cm recover . .Pp In case when only first sector is corrupt kernel can not detect GPT even if partition table is not corrupt. You can write protective MBR with .Xr dd 1 command to restore ability of GPT detection. The copy of protective MBR is usually located in the .Pa /boot/pmbr file. .Pp In case when some of metadata is corrupt you will get to know about this from kernel's messages like these: .Bd -literal -offset indent GEOM: provider: the primary GPT table is corrupt or invalid. GEOM: provider: using the secondary instead -- recovery strongly advised. .Ed .Pp or .Bd -literal -offset indent GEOM: provider: the secondary GPT table is corrupt or invalid. GEOM: provider: using the primary only -- recovery suggested. .Ed .Pp Also .Cm gpart commands like .Cm show , .Cm status and .Cm list will report about corrupt table. .Pp In case when the size of device has changed (e.g. volume expansion) the secondary GPT header will become located not in the last sector. This is not a metadata corruption, but it is dangerous because any corruption of the primary GPT will lead to lost of partition table. Kernel reports about this problem with message: .Bd -literal -offset indent GEOM: provider: the secondary GPT header is not in the last LBA. .Ed .Pp A corrupt table can be recovered with .Cm gpart recover command. This command does reconstruction of corrupt metadata using known valid metadata. Also it can relocate secondary GPT to the end of device. .Pp .Pa NOTE : The GEOM class PART can detect the same partition table on different GEOM providers and some of them will be marked as corrupt. Be careful when choosing a provider for recovering. If you choose incorrectly you can destroy the metadata of another GEOM class, e.g. GEOM MIRROR or GEOM LABEL. .Sh SYSCTL VARIABLES The following .Xr sysctl 8 variables can be used to control the behavior of the .Nm PART GEOM class. The default value is shown next to each variable. .Bl -tag -width indent .It Va kern.geom.part.check_integrity : No 1 This variable controls the behaviour of metadata integrity checks. When integrity checks are enabled .Nm PART GEOM class verifies all generic partition parameters that it gets from the disk metadata. If some inconsistency is detected, partition table will be rejected with a diagnostic message: .Pa GEOM_PART: Integrity check failed (provider, scheme) . +.El .Sh EXIT STATUS Exit status is 0 on success, and 1 if the command fails. .Sh EXAMPLES Create GPT scheme on .Pa ad0 . .Bd -literal -offset indent /sbin/gpart create -s GPT ad0 .Ed .Pp Embed GPT bootstrap code into protective MBR. .Bd -literal -offset indent /sbin/gpart bootcode -b /boot/pmbr ad0 .Ed .Pp Create a dedicated .Cm freebsd-boot partition that can boot .Fx from a .Cm freebsd-ufs partition, and install bootstrap code into it. This partition must be larger than .Pa /boot/gptboot , or the GPT boot you are planning to write, but smaller than 545 KB. A size of 15 blocks (7680 bytes) would be sufficient for booting from UFS but let's use 128 blocks (64 KB) here in this example, in order to reserve some space for potential future need (e.g.\& from a ZFS partition). .Bd -literal -offset indent /sbin/gpart add -b 34 -s 128 -t freebsd-boot ad0 /sbin/gpart bootcode -p /boot/gptboot -i 1 ad0 .Ed .Pp Create a 512MB-sized .Cm freebsd-ufs partition that would contain UFS where the system boots from. .Bd -literal -offset indent /sbin/gpart add -b 162 -s 1048576 -t freebsd-ufs ad0 .Ed .Pp Create MBR scheme on .Pa ada0 , then create 30GB-sized FreeBSD slice, mark it active and install boot0 boot manager: .Bd -literal -offset indent /sbin/gpart create -s MBR ada0 /sbin/gpart add -t freebsd -s 30G ada0 /sbin/gpart set -a active -i 1 ada0 /sbin/gpart bootcode -b /boot/boot0 ada0 .Ed .Pp Now create BSD scheme (BSD label) with ability to have up to 20 partitions: .Bd -literal -offset indent /sbin/gpart create -s BSD -n 20 ada0s1 .Ed .Pp Create 1GB-sized UFS partition and 4GB-sized swap partition: .Bd -literal -offset indent /sbin/gpart add -t freebsd-ufs -s 1G ada0s1 /sbin/gpart add -t freebsd-swap -s 4G ada0s1 .Ed .Pp Install bootstrap code for the BSD label: .Bd -literal -offset indent /sbin/gpart bootcode -b /boot/boot ada0s1 .Ed .Pp Create VTOC8 scheme on .Pa da0 . .Bd -literal -offset indent /sbin/gpart create -s VTOC8 da0 .Ed .Pp Create a 512MB-sized .Cm freebsd-ufs partition that would contain UFS where the system boots from. .Bd -literal -offset indent /sbin/gpart add -s 512M -t freebsd-ufs da0 .Ed .Pp Create a 15GB-sized .Cm freebsd-ufs partition that would contain UFS and aligned on 4KB boundaries: .Bd -literal -offset indent /sbin/gpart add -s 15G -t freebsd-ufs -a 4k da0 .Ed .Pp After having created all required partitions, embed bootstrap code into them. .Bd -literal -offset indent /sbin/gpart bootcode -p /boot/boot1 da0 .Ed .Pp Create backup of partition table from .Pa da0 .Bd -literal -offset indent /sbin/gpart backup da0 > da0.backup .Ed .Pp Restore partition table from backup to .Pa da0 .Bd -literal -offset indent /sbin/gpart restore -l da0 < /mnt/da0.backup .Ed .Pp Clone partition table from .Pa ada0 to .Pa ada1 and .Pa ada2 .Bd -literal -offset indent /sbin/gpart backup ada0 | /sbin/gpart restore -F ada1 ada2 .Ed .Sh SEE ALSO .Xr dd 1 , .Xr geom 4 , .Xr geom 8 .Sh HISTORY The .Nm utility appeared in .Fx 7.0 . .Sh AUTHORS .An Marcel Moolenaar Aq marcel@FreeBSD.org Index: head/sbin/setkey/setkey.8 =================================================================== --- head/sbin/setkey/setkey.8 (revision 222598) +++ head/sbin/setkey/setkey.8 (revision 222599) @@ -1,728 +1,729 @@ .\" $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 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 . The word .Li any stands for .Dq any protocol . 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 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 +.Pp +.Bl -tag -compact .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 +.El .Pp The direction of a policy must be specified as one of: .Li out , .Li in , .Li discard , .Li none , or .Li ipsec . The .Li discard direction means that packets matching the supplied indices will be discarded 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 .Ar protocol/mode/src-dst/level statement gives the rule for how to process the packet. 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, .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 .Li esp_trans_deflev sysctl variable, when the kernel processes the packet. 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. A value of .Li require means that an SA is required whenever the kernel sends a packet matched that matches the policy. 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, 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 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. .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: .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: .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 camllia-cbc 128/192/256 rfc4312 .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: .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 associated 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" .%U 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). Index: head/sys/boot/forth/check-password.4th.8 =================================================================== --- head/sys/boot/forth/check-password.4th.8 (revision 222598) +++ head/sys/boot/forth/check-password.4th.8 (revision 222599) @@ -1,123 +1,123 @@ .\" Copyright (c) 2011 Devin Teske .\" 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 May 18, 2011 .Dt CHECK-PASSWORD.4TH 8 .Os .Sh NAME .Nm check-password.4th .Nd FreeBSD password-checking boot module. .Sh DESCRIPTION The file that goes by the name of .Nm is a set of commands designed to prevent booting without the proper password. The commands of .Nm by themselves are not enough for most uses. Please refer to the examples below for the most common situations, and to .Xr loader 8 for additional commands. .Pp Before using any of the commands provided in .Nm , it must be included through the command: .Pp .Dl include check-password.4th .Pp This line is present in .Pa /boot/loader.4th file, so it is not needed (and should not be re-issued) in a normal setup. .Pp The commands provided by it are: .Pp .Bl -tag -width disable-module_module -compact -offset indent .It Ic check-password Once called, the user cannot continue until the correct password is entered. If the user enters the correct password the function returns. .Pp The password that is required is configured by setting the .Ic password variable in .Xr loader.conf 5 . .Pp Subsequent calls after a successful password has been entered will not cause reprompting -.Nd the function will silently return. +\(em the function will silently return. .El .Pp The environment variables that effect its behavior are: .Bl -tag -width bootfile -offset indent .It Va password Sets the password (up to 16 characters long) that is required by .Ic check-password to be entered before the system is allowed to boot. If unset (default) or NULL, .Ic check-password will silently abort. .El .Sh FILES .Bl -tag -width /boot/loader.4th -compact .It Pa /boot/loader The .Xr loader 8 . .It Pa /boot/check-password.4th .Nm itself. .It Pa /boot/loader.rc .Xr loader 8 bootstrapping script. .El .Sh EXAMPLES Standard i386 .Pa /boot/loader.rc : .Pp .Bd -literal -offset indent -compact include /boot/loader.4th check-password .Ed .Pp Set a password in .Xr loader.conf 5 : .Pp .Bd -literal -offset indent -compact password="abc123" .Ed .Sh SEE ALSO .Xr loader.conf 5 , .Xr loader 8 , .Xr loader.4th 8 .Sh HISTORY The .Nm set of commands first appeared in .Fx 9.0 . .Sh AUTHORS The .Nm set of commands was written by .An -nosplit .An Devin Teske Aq devinteske@hotmail.com . Index: head/usr.bin/rctl/rctl.8 =================================================================== --- head/usr.bin/rctl/rctl.8 (revision 222598) +++ head/usr.bin/rctl/rctl.8 (revision 222599) @@ -1,199 +1,199 @@ .\"- .\" Copyright (c) 2009 Edward Tomasz Napierala .\" 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 THE VOICES IN HIS HEAD 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 May 26, 2011 .Dt RCTL 8 .Os .Sh NAME .Nm rctl .Nd display and update resource limits database .Sh SYNOPSIS .Nm .Op Fl h .Op Fl n .Op Ar filter .Nm .Fl a .Op Ar rule .Nm .Op Fl h .Op Fl n .Fl l .Op Ar filter .Nm .Fl r .Op Ar filter .Nm .Op Fl h .Fl u .Op Ar filter .Sh DESCRIPTION When called without options, the .Nm command writes currently defined RCTL rules to standard output. .Pp If a .Ar filter argument is specified, only rules matching the filter are displayed. The options are as follows: .Bl -tag -width indent .It Fl a Ar rule Add .Ar rule to the RCTL database. .It Fl l Ar filter Display rules applicable to the process defined by .Ar filter . .It Fl r Ar filter Remove rules matching .Ar filter from the RCTL database. .It Fl u Ar filter Display resource usage for a subject (process, user, login class or jail) matching the .Ar filter . .It Fl h "Human-readable" output. Use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte and Petabyte. .It Fl n Display user IDs numerically rather than converting them to a user name. -.Pp +.El .Sh RULE SYNTAX Syntax for a rule is subject:subject-id:resource:action=amount/per. .Pp Subject defines the kind of entity the rule applies to. It can be either process, user, login class, or jail. .Pp Subject ID identifies the subject. It can be user name, numerical user ID, login class name, or jail name. .Pp Resource identifies the resource the rule controls. .Pp Action defines what will happen when a process exceeds the allowed amount. .Pp Amount defines how much of the resource a process can use before the defined action triggers. .Pp The per field defines what entity the amount gets accounted for. For example, rule "loginclass:users:vmem:deny=100M/process" means that each process of any user belonging to login class "users" may allocate up to 100MB of virtual memory. Rule "loginclass:users:vmem:deny=100M/user" would mean that for each user belonging to the login class "users", the sum of virtual memory allocated by all the processes of that user will not exceed 100MB. Rule "loginclass:users:vmem:deny=100M/loginclass" would mean that the sum of virtual memory allocated by all processes of all users belonging to that login class will not exceed 100MB. .Pp Valid rule has all those fields specified, except for the per, which defaults to the value of subject. .Pp A filter is a rule for which one of more fields other than per is left empty. For example, a filter that matches every rule could be written as ":::=/", or, in short, ":". A filter that matches all the login classes would be "loginclass:". A filter that matches all defined rules for nproc resource would be "::nproc". .Pp .Sh RESOURCES .Bl -column -offset 3n "msgqqueued" .It cpu CPU time, in milliseconds .It data data size, in bytes .It stack stack size, in bytes .It core core dump size, in bytes .It rss resident set size, in bytes .It memlock locked memory, in bytes .It nproc number of processes .It nofile file descriptor table size .It vmem address space limit, in bytes .It npts number of PTYs .It swap swap usage, in bytes .It nthr number of threads .It msgqqueued number of queued SysV messages .It msgqsize SysV message queue size, in bytes .It nmsgq number of SysV message queues .It nsem number of SysV semaphores .It nsemop number of SysV semaphores modified in a single semop(2) call .It nshm number of SysV shared memory segments .It shmsize SysV shared memory size, in bytes .It wallclock wallclock time, in milliseconds .It pctcpu %cpu time .El .Pp .Sh ACTIONS .Bl -column -offset 3n "msgqqueued" .It deny deny the allocation; not supported for cpu and wallclock .It log log a warning to the console .It devctl send notification to .Xr devd 8 .It sig* e.g. sigterm; send a signal to the offending process .El .Pp See .Xr signal 3 for a list of supported signals. .Pp Not all actions are supported for all resources. Attempt to add rule with action not supported by a given resouce will result in error. .Pp Note that limiting RSS may kill the machine due to thrashing. .Pp .Sh EXIT STATUS .Ex -std .Sh EXAMPLES .Dl rctl -a user:joe:vmem:deny=1g .Pp Prevent user "joe" from allocating more than 1GB of virtual memory. .Pp .Dl rctl -r : .Pp Remove all RCTL rules. .Pp .Dl rctl -hu jail:www .Pp Display resource usage information for jail named "www". .Pp .Dl rctl -l process:512 .Pp Display all the rules applicable to process with PID 512. .Sh SEE ALSO .Xr rctl.conf 5 , .Xr jailstat 8 , .Xr userstat 8 .Sh HISTORY The .Nm command appeared in .Fx 9.0. .Sh AUTHORS .An -nosplit The .Nm command was written by .An Edward Tomasz Napierala Aq trasz@FreeBSD.org .