sginfo

title: sginfo(8)

text:
# sginfo(8)

## NAME
sginfo - access mode page information for a SCSI (or ATAPI) device

## SYNOPSIS
sginfo [OPTIONS] [DEVICE] [REPLACEMENT_PARAMETERS]

## DESCRIPTION
sginfo is a port of the Linux scsiinfo program by Eric Youngdale. It uses SCSI generic (sg) devices; however in some cases the high level device name (i.e. sd, sr, st, osst, or hd) can also be used. The primary role of this program is to access mode page information. If permitted, mode page information can be altered. In addition information from the INQUIRY and READ DEFECTS commands are also available.

This utility is in legacy mode, only obvious bugs will be fixed. Options like -l (to list devices) are broken in recent versions of Linux (e.g. 2.6 series and later); the lsscsi(8) utility can be used instead. Also mode pages are not being updated as https://www.t10.org adds and modifies mode page fields. Those interested in SCSI mode pages may find the sdparm utility more up to date and easier use, especially for changing parameters.

Four sets of values are maintained by a SCSI device for each mode page: current (active), default (manufacturer's supplied values), saved (values that are retained if the SCSI device is powered down), and changeable (mask indicating those values that can be changed). By default when a mode page is displayed the current values are shown. This can be overridden by "-M" (defaults), "-S" (saved) or "-m" (modifiable (i.e. changeable)).

Many mode pages are decoded: for disks (see SBC-2), for CD/DVDs (see MMC-2/3/4/5), for tapes (see SSC-2) and for enclosures (see SES-2). Some mode pages common to all SCSI peripheral device types are defined in SPC-4 (primary commands). A decoded mode page has its field names in the first column and the corresponding value in the second column. A "hex" mode page (and subpage) has its byte position in the first column (in hex and starting at 0x2) and the corresponding hex value in the second column. Decoded pages can be viewed with the '-t' option or with a specific option (e.g. 'c' for the caching mode page). Naturally decoded pages must be supplied by the DEVICE and recognised by this program. If supported by the device, decoded pages may be modified. All mode pages (and subpages) that the device supports can be viewed in hex (and potentially modified) via the "-u" option

If no options are given that will cause mode page(s) or INQUIRY data to be printed out, then a brief INQUIRY response is output. This includes the vendor, product and revision level of the device.

## OPTIONS
-6

Perform 6 byte MODE SENSE and MODE SELECT commands; by default the 10 byte variants are used.

-a

Display some INQUIRY data and the unit serial number followed by all mode pages reported by the device. It is similar to the '-t 0x3f' option. If the mode page is known then it is output in decoded form otherwise it is output in hexadecimal.

-A

Display some INQUIRY data and the unit serial number followed by all mode pages and all mode subpages reported by the device. It is similar to the '-t 0x3f,0xff' option. If a mode (sub)page is known then it is output in decoded form otherwise it is output in hexadecimal.

-c

Access information in the Caching mode page.

-C

Access information in the Control mode Page.

-d

Display defect lists (default format: index).

-D

Access information in the Disconnect-Reconnect mode page.

-e

Access information in the Error Recovery mode page.

-E

Access information in the Control Extension mode page.

-f

Access information in the Format Device mode page.

-Farg

Format of the defect lists:

-Flogical - logical block addresses (32 bit)

-Flba64 - logical block addresses (64 bit)

-Fphysical - physical blocks

-Findex - defect bytes from index

-Fhead - sort by head

Used in conjunction with "-d" or "-G". If a format is not given "index" is assumed.

-g

Access information in the Rigid Disk Drive Geometry mode page.

-G

Display grown defect list (default format: index).

-i

Display the response to a standard INQUIRY command.

-I

Access the Informational Exceptions mode page.

-l

Deprecated. Only use in old versions of Linux (e.g. 2.4 and earlier). Please use lsscsi(8) in the Linux 2.6 series and later. List known SCSI devices on the system.

-n

Access information in the Notch and Partition mode page.

-N

Negate (i.e. stop) mode page changes being placed in the "saved" page (by default changes go to the current and the saved page). Only active when used together with '-R'.

-P

Access information in the Power Condition mode page.

-r

Display all raw (or primary) SCSI device names visible in the /dev directory. Examples are /dev/sda, /dev/st1 and /dev/scd2. Does not list sg device names so devices such as a SCSI enclosure which only have an sg device name are not listed.

-s

Display information in the unit serial number page which is a INQUIRY command variant.

-t PN[,SPN]

Display information from mode page number PN (and optionally sub page number SPN) in decoded format (if known, otherwise in hex form). PN is a mode page number in a decimal number from 0 to 63 inclusive. SPN is the mode subpage number and is assumed to be 0 if not given. SPN is a decimal number from 1 to 255 inclusive. A page number of 63 returns all pages supported by the device in ascending order except for page 0 which, if present, is last. Page 0 is vendor specific and not necessarily in mode page format. Alternatively hex values can be given for both PN and SPN (both prefixed by '0x').

-T

Trace commands to obtain more verbose output (for debugging). When used once SCSI commands are shown (in hex) and any errors from these SCSI commands are spelt out (i.e. with a decoded and raw sense buffer). When used twice, the additional data sent with mode select and the response from mode sense are shown (in hex).

-u PN[,SPN]

Display information from mode page number PN (and optionally SPN) in hex form. PN is a mode page number in a decimal number from 0 to 63 inclusive. SPN is the mode subpage number and is assumed to be 0 if not given. SPN is a decimal number from 1 to 255 inclusive. A page number of 63 returns all pages supported by the device in ascending order except for page 0 which, if present, is last. Page 0 is vendor specific and not necessarily in mode page format. Alternatively hex values can be given for both PN and SPN (both prefixed by '0x'). For example 63 and 0x3f are equivalent.

-v

Display version string then exit. [N.B. This option increases verbosity for most other utilities in this package as outlined in 'man 8 sg3_utils'. This odd usage is for backward compatibility with the scsiinfo utility.]

-V

Access information in the Verify Error Recovery mode page. [N.B. This option prints the version string then exits in most other utilities in this package as outlined in 'man 8 sg3_utils'. This odd usage is for backward compatibility with the scsiinfo utility.]

-z

do a single fetch for mode pages (over-estimating the expected length of the returned response). The default action is to do a double fetch, the first fetch is to find the response length that could be returned. Devices that closely adhere to SCSI standards should not require this option, some real world devices do require it.

## ADVANCED OPTIONS
Only one of the following three options can be specified. None of these three implies the current values are returned.

-m

Display modifiable fields instead of current values

-M

Display manufacturer's defaults instead of current values

-S

Display saved defaults instead of current values

The following are advanced options, not generally suited for most users:

-X

Display output values in a list. Make them suitable for editing and being given back to the '-R' (replace command).

-R

Replace parameters - best used with -X (expert use only)

## CHANGING MODE PAGE PARAMETERS
Firstly you should know what you are doing before changing existing parameters. Taking the control page as an example, first list it out normally (e.g. "sginfo -C /dev/sda") and decide which parameter is to be changed (note its position relative to the other lines output). Then execute the same sginfo command with the "-X" option added; this will output the parameter values in a single row in the same relative positions as the previous command. Now execute "sginfo -CXR /dev/sda ..." with the "..." replaced by the single row of values output by the previous command, with the relevant parameter changed. Here is a simplified example:

$ sginfo -C /dev/sda

Control mode page (0xa)

-----------------------

TST 0

D_SENSE 0

GLTSD 1

RLEC 0

[Actually the Control page has more parameters that shown above.] Next output those parameters in single line form:

$ sginfo -CX /dev/sda

0 0 1 0

Let us assume that the GLTSD bit is to be cleared. The command that will clear it is:

$ sginfo -CXR /dev/sda 0 0 0 0

The same number of parameters output by the "-CX" command needs to be placed at the end of the "-CXR" command line (after the device name). Now check that the change took effect:

$ sginfo -C /dev/sda

Control mode page (0xa)

-----------------------

TST 0

D_SENSE 0

GLTSD 0

RLEC 0

When a mode page is "replaced" the default action is to change both the current page and the saved page. [For some reason versions of sginfo and scsiinfo prior to 2.0 did not change the "saved" page.] To change only the current mode page but not the corresponding saved page use the "-N" option.

## GENERATING SCRIPT FILES AND HEX PAGES
The "-aX" or "-AX" option generates output suitable for a script file. Mode pages are output in list format (after the INQUIRY and serial number) one page per line. To facilitate running the output as (part of) a script file to assert chosen mode page values, each line is prefixed by "sginfo -t PN[,SPN] -XR ". When such a script file is run, it will have the effect of re-asserting the mode page values to what they were when the "-aX" generated the output.

All mode pages (and subpages) supported by the device can be accessed via the -t and -u options. To see all mode pages supported by the device use "-u 63". [To see all mode pages and all subpages use "-u 63,255".] To list the control mode page in hex (mode page index in the first column and the corresponding byte value in the second column) use "-u 0xa". Mode pages (subpage code == 0) start at index position 2 while subpages start at index position 4. If the "-Xu ..." option is used then a list a hex values each value prefixed by "@" is output. Mode (sub)page values can then be modified with the "-RXu ..." option.

## RESTRICTIONS
The SCSI MODE SENSE command yields block descriptors as well as a mode page(s). This utility ignores block descriptors and does not display them. The "disable block descriptor" switch (DBD) in the MODE SENSE command is not set since some devices yield errors when it is set. When mode page values are being changed (the "-R" option), the same block descriptor obtained by reading the mode page (i.e. via a MODE SENSE command) is sent back when the mode page is written (i.e. via a MODE SELECT command).

## REFERENCES
SCSI (draft) standards can be found at https://www.t10.org . The relevant documents are SPC-4 (mode pages common to all device types), SBC-2 (direct access devices [e.g. disks]), MMC-4 (CDs and DVDs) and SSC-2 (tapes).

## AUTHORS
Written by Eric Youngdale, Michael Weller, Douglas Gilbert, Kurt Garloff, Thomas Steudten

## HISTORY
scsiinfo version 1.0 was released by Eric Youngdale on 1st November 1993. The most recent version of scsiinfo is version 1.7 with the last patches by Michael Weller. sginfo is derived from scsiinfo and uses the sg interface to get around the 4 KB buffer limit in scsiinfo that cramped the display of defect lists especially. sginfo was written by Douglas Gilbert with patches from Kurt Garloff. This manpage corresponds with version 2.25 of sginfo.

This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
lsscsi(lsscsi), scsiinfo(internet); sg_modes, sg_inq, sg_vpd (sg3_utils), sdparm(sdparm)


title: sgm_dd(8)

text:
# sgm_dd(8)

## NAME
sgm_dd - copy data to and from files and devices, especially SCSI devices

## SYNOPSIS
sgm_dd [bs=BS] [count=COUNT] [ibs=BS] [if=IFILE] [iflag=FLAGS] [obs=BS] [of=OFILE] [oflag=FLAGS] [seek=SEEK] [skip=SKIP] [--help] [--version]

[bpt=BPT] [cdbsz=6|10|12|16] [dio=0|1] [sync=0|1] [time=0|1] [verbose=VERB] [--dry-run] [--progress] [--verbose]

## DESCRIPTION
Copy data to and from any files. Specialized for "files" that are Linux SCSI generic (sg) devices and raw devices. Uses memory mapped transfers on sg devices. Similar syntax and semantics to dd(1) but does not perform any conversions.

Will only perform memory mapped transfers when IFILE or OFILE are SCSI generic (sg) devices.

If both IFILE and OFILE are sg devices then memory mapped transfers are performed on IFILE. If no other flags are specified then indirect IO is performed on OFILE. If 'oflag=dio' is given then direct IO is attempted on OFILE. If direct IO is not available, then this utility falls back to indirect IO and reports this at the end of the copy.

The first group in the synopsis above are "standard" Unix dd(1) operands. The second group are extra options added by this utility. Both groups are defined below.

## OPTIONS
bpt=BPT

each IO transaction will be made using BPT blocks (or less if near the end of the copy). Default is 128 for block sizes less that 2048 bytes, otherwise the default is 32. So for bs=512 the reads and writes will each convey 64 KiB of data by default (less if near the end of the transfer or memory restrictions). When cd/dvd drives are accessed, the block size is typically 2048 bytes and bpt defaults to 32 which again implies 64 KiB transfers.

bs=BS

where BS must be the block size of the physical device. Note that this differs from dd(1) which permits BS to be an integral multiple. Default is 512 which is usually correct for disks but incorrect for cdroms (which normally have 2048 byte blocks). For this utility the maximum size of each individual IO operation is BS * BPT bytes.

cdbsz=6 | 10 | 12 | 16

size of SCSI READ and/or WRITE commands issued on sg device names. Default is 10 byte SCSI command blocks (unless calculations indicate that a 4 byte block number may be exceeded, in which case it defaults to 16 byte SCSI commands).

count=COUNT

copy COUNT blocks from IFILE to OFILE. Default is the minimum (of IFILE and OFILE) number of blocks that sg devices report from SCSI READ CAPACITY commands or that block devices (or their partitions) report. Normal files are not probed for their size. If skip=SKIP or seek=SEEK are given and the count is derived (i.e. not explicitly given) then the derived count is scaled back so that the copy will not overrun the device. If the file name is a block device partition and COUNT is not given then the size of the partition rather than the size of the whole device is used. If COUNT is not given and cannot be derived then an error message is issued and no copy takes place.

dio=0 | 1

permits direct IO to be selected on the write-side (i.e. on OFILE). Only allowed when the read-side (i.e. IFILE) is a sg device. When 1 there may be a "zero copy" copy (i.e. mmap-ed transfer on the read into the user space and direct IO from there on the write, potentially two DMAs and no data copying from the CPU). Default is 0. The same action as 'dio=1' is also available with 'oflag=dio'.

ibs=BS

if given must be the same as BS given to 'bs=' option.

if=IFILE

read from IFILE instead of stdin. If IFILE is '-' then stdin is read. Starts reading at the beginning of IFILE unless SKIP is given.

iflag=FLAGS

where FLAGS is a comma separated list of one or more flags outlined below. These flags are associated with IFILE and are ignored when IFILE is stdin.

obs=BS

if given must be the same as BS given to 'bs=' option.

of=OFILE

write to OFILE instead of stdout. If OFILE is '-' then writes to stdout. If OFILE is /dev/null then no actual writes are performed. If OFILE is '.' (period) then it is treated the same way as /dev/null (this is a shorthand notation). If OFILE exists then it is _not_ truncated; it is overwritten from the start of OFILE unless 'oflag=append' or SEEK is given.

oflag=FLAGS

where FLAGS is a comma separated list of one or more flags outlined below. These flags are associated with OFILE and are ignored when OFILE is /dev/null, '.' (period), or stdout.

seek=SEEK

start writing SEEK bs-sized blocks from the start of OFILE. Default is block 0 (i.e. start of file).

skip=SKIP

start reading SKIP bs-sized blocks from the start of IFILE. Default is block 0 (i.e. start of file).

sync=0 | 1

when 1, does SYNCHRONIZE CACHE command on OFILE at the end of the transfer. Only active when OFILE is a sg device file name.

time=0 | 1

when 1, times transfer and does throughput calculation, outputting the results (to stderr) at completion. When 0 (default) doesn't perform timing.

verbose=VERB

as VERB increases so does the amount of debug output sent to stderr. Default value is zero which yields the minimum amount of debug output. A value of 1 reports extra information that is not repetitive. A value 2 reports cdbs and responses for SCSI commands that are not repetitive (i.e. other that READ and WRITE). Error processing is not considered repetitive. Values of 3 and 4 yield output for all SCSI commands (and Unix read() and write() calls) so there can be a lot of output.

-d, --dry-run

does all the command line parsing and preparation but bypasses the actual copy or read. That preparation may include opening IFILE or OFILE to determine their lengths. This option may be useful for testing the syntax of complex command line invocations in advance of executing them.

-h, --help

outputs usage message and exits.

-p, --progress

this option causes a progress report to be output every two minutes until the copy is complete. After the copy is complete a line with "completed" is printed to distinguish the final report from the prior progress reports. When used twice the progress report is every minute, when used three times the progress report is every 30 seconds.

If this option is given then the 'time=1' option is set implicitly.

-v, --verbose

when used once, this is equivalent to verbose=1. When used twice (e.g. "-vv") this is equivalent to verbose=2, etc.

-V, --version

outputs version number information and exits.

## FLAGS
Here is a list of flags and their meanings:

append

causes the O_APPEND flag to be added to the open of OFILE. For normal files this will lead to data appended to the end of any existing data. Cannot be used together with the seek=SEEK option as they conflict. The default action of this utility is to overwrite any existing data from the beginning of the file or, if SEEK is given, starting at block SEEK. Note that attempting to 'append' to a device file (e.g. a disk) will usually be ignored or may cause an error to be reported.

dio

is only active with oflag (i.e. 'oflag=dio'). Its action is described in the 'dio=1' option description above.

direct

causes the O_DIRECT flag to be added to the open of IFILE and/or OFILE. This flag requires some memory alignment on IO. Hence user memory buffers are aligned to the page size. Has no effect on sg, normal or raw files.

dpo

set the DPO bit (disable page out) in SCSI READ and WRITE commands. Not supported for 6 byte cdb variants of READ and WRITE. Indicates that data is unlikely to be required to stay in device (e.g. disk) cache. May speed media copy and/or cause a media copy to have less impact on other device users.

dsync

causes the O_SYNC flag to be added to the open of IFILE and/or OFILE. The "d" is prepended to lower confusion with the 'sync=0|1' option which has another action (i.e. a synchronisation to media at the end of the transfer).

excl

causes the O_EXCL flag to be added to the open of IFILE and/or OFILE.

fua

causes the FUA (force unit access) bit to be set in SCSI READ and/or WRITE commands. This only has effect with sg devices. The 6 byte variants of the SCSI READ and WRITE commands do not support the FUA bit. Only active for sg device file names.

null

has no affect, just a placeholder.

## RETIRED OPTIONS
Here are some retired options that are still present:

fua=0 | 1 | 2 | 3

force unit access bit. When 3, fua is set on both IFILE and OFILE; when 2, fua is set on IFILE; when 1, fua is set on OFILE; when 0 (default), fua is cleared on both. See the 'fua' flag.

## NOTES
A raw device must be bound to a block device prior to using sgm_dd. See raw(8) for more information about binding raw devices. To be safe, the sg device mapping to SCSI block devices should be checked with the lsscsi utility before use.

Raw device partition information can often be found with fdisk(8) [the "-ul" argument is useful in this respect].

Various numeric arguments (e.g. SKIP) may include multiplicative suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section in the sg3_utils(8) man page.

The count, skip and seek parameters can take 64 bit values (i.e. very big numbers). Other values are limited to what can fit in a signed 32 bit number.

Data usually gets to the user space in a 2 stage process: first the SCSI adapter DMAs into kernel buffers and then the sg driver copies this data into user memory (write operations reverse this sequence). With memory mapped transfers a kernel buffer reserved by sg is memory mapped (see the mmap(2) system call) into the user space. When this is done the second (redundant) copy from kernel buffers to user space is not needed. Hence the transfer is faster and requires less "grunt" from the CPU.

All informative, warning and error output is sent to stderr so that dd's output file can be stdout and remain unpolluted. If no options are given, then the usage message is output and nothing else happens.

For sg devices this utility issues SCSI READ and WRITE (SBC) commands which are appropriate for disks and reading from CD/DVD/BD drives. Those commands are not formatted correctly for tape devices so sgm_dd should not be used on tape devices.

This utility stops the copy if any error is encountered. For more advanced "copy on error" logic see the sg_dd utility (and its 'coe' flag).

## EXAMPLES
See the examples given in the man page for sg_dd(8).

## SIGNALS
The signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIGPIPE output the number of remaining blocks to be transferred and the records in + out counts; then they have their default action. SIGUSR1 causes the same information to be output yet the copy continues. All output caused by signals is sent to stderr.

## EXIT STATUS
The exit status of sgm_dd is 0 when it is successful. Otherwise see the sg3_utils(8) man page. Since this utility works at a higher level than individual commands, and there are 'coe' and 'retries' flags, individual SCSI command failures do not necessary cause the process to exit.

## AUTHORS
Written by Douglas Gilbert and Peter Allworth.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2000-2023 Douglas Gilbert

This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
The simplest variant of this utility is called sg_dd. A POSIX threads version of this utility called sgp_dd is in the sg3_utils package. The lmbench package contains lmdd which is also interesting. dd(1), ddpt(ddpt), raw(8)


title: sgp_dd(8)

text:
# sgp_dd(8)

## NAME
sgp_dd - copy data to and from files and devices, especially SCSI devices

## SYNOPSIS
sgp_dd [bs=BS] [count=COUNT] [ibs=BS] [if=IFILE] [iflag=FLAGS] [obs=BS] [of=OFILE] [oflag=FLAGS] [seek=SEEK] [skip=SKIP] [--help] [--version]

[bpt=BPT] [coe=0|1] [cdbsz=6|10|12|16] [deb=VERB] [dio=0|1] [sync=0|1] [thr=THR] [time=0|1] [verbose=VERB] [--chkaddr] [--dry-run] [--progress] [--verbose]

## DESCRIPTION
Copy data to and from any files. Specialised for "files" that are Linux SCSI generic (sg) and raw devices. Similar syntax and semantics to dd(1) but does not perform any conversions. Uses POSIX threads (often called "pthreads") to increase the amount of parallelism. This improves speed in some cases.

The first group in the synopsis above are "standard" Unix dd(1) operands. The second group are extra options added by this utility. Both groups are defined below.

## OPTIONS
bpt=BPT

each IO transaction will be made using BPT blocks (or less if near the end of the copy). Default is 128 for block sizes less that 2048 bytes, otherwise the default is 32. So for bs=512 the reads and writes will each convey 64 KiB of data by default (less if near the end of the transfer or memory restrictions). When cd/dvd drives are accessed, the block size is typically 2048 bytes and bpt defaults to 32 which again implies 64 KiB transfers.

bs=BS

where BS must be the block size of the physical device. Note that this differs from dd(1) which permits 'bs' to be an integral multiple of the actual device block size. Default is 512 which is usually correct for disks but incorrect for cdroms (which normally have 2048 byte blocks).

cdbsz=6 | 10 | 12 | 16

size of SCSI READ and/or WRITE commands issued on sg device names. Default is 10 byte SCSI command blocks (unless calculations indicate that a 4 byte block number may be exceeded, in which case it defaults to 16 byte SCSI commands).

coe=0 | 1

set to 1 for continue on error. Only applies to errors on sg devices. Thus errors on other files will stop sgp_dd. Default is 0 which implies stop on any error. See the 'coe' flag for more information.

count=COUNT

copy COUNT blocks from IFILE to OFILE. Default is the minimum (of IFILE and OFILE) number of blocks that sg devices report from SCSI READ CAPACITY commands or that block devices (or their partitions) report. Normal files are not probed for their size. If skip=SKIP or seek=SEEK are given and the count is deduced (i.e. not explicitly given) then that count is scaled back so that the copy will not overrun the device. If the file name is a block device partition and COUNT is not given then the size of the partition rather than the size of the whole device is used. If COUNT is not given and cannot be deduced then an error message is issued and no copy takes place.

deb=VERB

outputs debug information. If VERB is 0 (default) then there is minimal debug information and as VERB increases so does the amount of debug (max debug output when VERB is 9).

dio=0 | 1

default is 0 which selects indirect IO. Value of 1 attempts direct IO which, if not available, falls back to indirect IO and notes this at completion. If direct IO is selected and /sys/module/sg/parameters/allow_dio has the value of 0 then a warning is issued (and indirect IO is performed) For finer grain control use 'iflag=dio' or 'oflag=dio'.

ibs=BS

if given must be the same as BS given to 'bs=' option.

if=IFILE

read from IFILE instead of stdin. If IFILE is '-' then stdin is read. Starts reading at the beginning of IFILE unless SKIP is given.

iflag=FLAGS

where FLAGS is a comma separated list of one or more flags outlined below. These flags are associated with IFILE and are ignored when IFILE is stdin.

obs=BS

if given must be the same as BS given to 'bs=' option.

of=OFILE

write to OFILE instead of stdout. If OFILE is '-' then writes to stdout. If OFILE is /dev/null then no actual writes are performed. If OFILE is '.' (period) then it is treated the same way as /dev/null (this is a shorthand notation). If OFILE exists then it is _not_ truncated; it is overwritten from the start of OFILE unless 'oflag=append' or SEEK is given.

oflag=FLAGS

where FLAGS is a comma separated list of one or more flags outlined below. These flags are associated with OFILE and are ignored when OFILE is /dev/null, '.' (period), or stdout.

seek=SEEK

start writing SEEK bs-sized blocks from the start of OFILE. Default is block 0 (i.e. start of file).

skip=SKIP

start reading SKIP bs-sized blocks from the start of IFILE. Default is block 0 (i.e. start of file).

sync=0 | 1

when 1, does SYNCHRONIZE CACHE command on OFILE at the end of the transfer. Only active when OFILE is a sg device file name.

thr=THR

where THR is the number or worker threads (default 4) that attempt to copy in parallel. Minimum is 1 and maximum is 1024.

time=0 | 1

when 1, the transfer is timed and throughput calculation is performed, outputting the results (to stderr) at completion. When 0 (default) no timing is performed.

verbose=VERB

increase verbosity. Same as deb=VERB. Added for compatibility with sg_dd and sgm_dd.

-c, --chkaddr

this option checks that every block read contains the (32 bit) block address of that block. If that check fails, the copy exits with a miscompare error. This check complements the 'sg_dd iflag=00,ff' generation of blocks that contain their own (32 bit, big endian) block address. When --chkaddr is used once, only the first block address in each block is checked. When used twice, each block address (that fits in a block) is checked.

-d, --dry-run

does all the command line parsing and preparation but bypasses the actual copy or read. That preparation may include opening IFILE or OFILE to determine their lengths. This option may be useful for testing the syntax of complex command line invocations in advance of executing them.

-h, --help

outputs usage message and exits.

-p, --progress

this option causes a progress report to be output every two minutes until the copy is complete. After the copy is complete a line with "completed" is printed to distinguish the final report from the prior progress reports. When used twice the progress report is every minute, when used three times the progress report is every 30 seconds.

If this option is given then the 'time=1' option is set implicitly.

-v, --verbose

when used once, this is equivalent to verbose=1. When used twice (e.g. "-vv") this is equivalent to verbose=2, etc.

-V, --version

outputs version number information and exits.

## FLAGS
Here is a list of flags and their meanings:

append

causes the O_APPEND flag to be added to the open of OFILE. For normal files this will lead to data appended to the end of any existing data. Cannot be used together with the seek=SEEK option as they conflict. The default action of this utility is to overwrite any existing data from the beginning of the file or, if SEEK is given, starting at block SEEK. Note that attempting to 'append' to a device file (e.g. a disk) will usually be ignored or may cause an error to be reported.

coe

continue on error. When given with 'iflag=', an error that is detected in a single SCSI command (typically 'bpt' blocks) is noted (by an error message sent to stderr), then zeros are substituted into the buffer for the corresponding write operation and the copy continues. Note that the sg_dd utility is more sophisticated in such error situations when 'iflag=coe'. When given with 'oflag=', any error reported by a SCSI WRITE command is reported to stderr and the copy continues (as if nothing went wrong).

dio

request the sg device node associated with this flag does direct IO. If direct IO is not available, falls back to indirect IO and notes this at completion. If direct IO is selected and /sys/module/sg/parameters/allow_dio has the value of 0 then a warning is issued (and indirect IO is performed).

direct

causes the O_DIRECT flag to be added to the open of IFILE and/or OFILE. This flag requires some memory alignment on IO. Hence user memory buffers are aligned to the page size. Has no effect on sg, normal or raw files.

dpo

set the DPO bit (disable page out) in SCSI READ and WRITE commands. Not supported for 6 byte cdb variants of READ and WRITE. Indicates that data is unlikely to be required to stay in device (e.g. disk) cache. May speed media copy and/or cause a media copy to have less impact on other device users.

dsync

causes the O_SYNC flag to be added to the open of IFILE and/or OFILE. The 'd' is prepended to lower confusion with the 'sync=0|1' option which has another action (i.e. a synchronisation to media at the end of the transfer).

excl

causes the O_EXCL flag to be added to the open of IFILE and/or OFILE.

fua

causes the FUA (force unit access) bit to be set in SCSI READ and/or WRITE commands. This only has effect with sg devices. The 6 byte variants of the SCSI READ and WRITE commands do not support the FUA bit. Only active for sg device file names.

mmap

can only be used in the iflag=FLAGS or the oflag=FLAGS argument list but not both. The nominated side of the copy will use memory mapped IO based on the mmap(2) system call. The sg driver will remap its DMA destination or source buffer into the user space when the mmap(2) system call is used on a sg device.

null

has no affect, just a placeholder.

## RETIRED OPTIONS
Here are some retired options that are still present:

coe=0 | 1

continue on error is 0 (off) by default. When it is 1, it is equivalent to 'iflag=coe oflag=coe' described in the FLAGS section above. Similar to 'conv=noerror,sync' in dd(1) utility. Default is 0 which implies stop on error. More advanced coe=1 processing on reads is performed by the sg_dd utility.

fua=0 | 1 | 2 | 3

force unit access bit. When 3, fua is set on both IFILE and OFILE; when 2, fua is set on IFILE;, when 1, fua is set on OFILE; when 0 (default), fua is cleared on both. See the 'fua' flag.

## NOTES
A raw device must be bound to a block device prior to using sgp_dd. See raw(8) for more information about binding raw devices. To be safe, the sg device mapping to SCSI block devices should be checked with 'sg_map' before use.

Raw device partition information can often be found with fdisk(8) [the "-ul" argument is useful in this respect].

Various numeric arguments (e.g. SKIP) may include multiplicative suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section in the sg3_utils(8) man page.

The COUNT, SKIP and SEEK arguments can take 64 bit values (i.e. very big numbers). Other values are limited to what can fit in a signed 32 bit number.

Data usually gets to the user space in a 2 stage process: first the SCSI adapter DMAs into kernel buffers and then the sg driver copies this data into user memory (write operations reverse this sequence). This is called "indirect IO" and there is a 'dio' option to select "direct IO" which will DMA directly into user memory. Due to some issues "direct IO" is disabled in the sg driver and needs a configuration change to activate it.

All informative, warning and error output is sent to stderr so that dd's output file can be stdout and remain unpolluted. If no options are given, then the usage message is output and nothing else happens.

Why use sgp_dd? Because in some cases it is twice as fast as dd (mainly with sg devices, raw devices give some improvement). Another reason is that big copies fill the block device caches which has a negative impact on other machine activity.

## SIGNALS
The signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIGPIPE output the number of remaining blocks to be transferred and the records in + out counts; then they have their default action. SIGUSR1 causes the same information to be output yet the copy continues. All output caused by signals is sent to stderr.

## EXAMPLES
Looks quite similar in usage to dd:

sgp_dd if=/dev/sg0 of=t bs=512 count=1MB

This will copy 1 million 512 byte blocks from the device associated with /dev/sg0 (which should have 512 byte blocks) to a file called t. Assuming /dev/sda and /dev/sg0 are the same device then the above is equivalent to:

dd if=/dev/sda of=t bs=512 count=1000000

although dd's speed may improve if bs was larger and count was correspondingly scaled. Using a raw device to do something similar on a ATA disk:

raw /dev/raw/raw1 /dev/hda

sgp_dd if=/dev/raw/raw1 of=t bs=512 count=1MB

To copy a SCSI disk partition to an ATA disk partition:

raw /dev/raw/raw2 /dev/hda3

sgp_dd if=/dev/sg0 skip=10123456 of=/dev/raw/raw2 bs=512

This assumes a valid partition is found on the SCSI disk at the given skip block address (past the 5 GB point of that disk) and that the partition goes to the end of the SCSI disk. An explicit count is probably a safer option.

To do a fast copy from one SCSI disk to another one with similar geometry (stepping over errors on the source disk):

sgp_dd if=/dev/sg0 of=/dev/sg1 bs=512 coe=1

## EXIT STATUS
The exit status of sgp_dd is 0 when it is successful. Otherwise see the sg3_utils(8) man page. Since this utility works at a higher level than individual commands, and there are 'coe' and 'retries' flags, individual SCSI command failures do not necessary cause the process to exit.

## AUTHORS
Written by Douglas Gilbert and Peter Allworth.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2000-2023 Douglas Gilbert

This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
A simpler, non-threaded version of this utility but with more advanced "continue on error" logic is called sg_dd and is also found in the sg3_utils package. The lmbench package contains lmdd which is also interesting. raw(8), dd(1)


install-catalog

package: sgml-common

title: install-catalog(8)

text:
# install-catalog(8)

## NAME
install-catalog - Manage a SGML or XML centralized catalog

## SYNOPSIS
install-catalog [ option ] action ... [ [ -d] [ --delegate] ] [ [ -a centralized ordinary] [ --add centralized ordinary]

[ -r centralized ordinary] [ --remove centralized ordinary]

[ -h] [ --help]

[ -v] [ --version] ]

## DESCRIPTION
This shell script allows to handle a centralized catalog referencing other "ordinary" SGML or XML Open Catalogs.

An Open Catalog contains a set of directives defined by OASIS, mostly used for defining equivalences between FPIs (Formal Public Identifiers) and real file names (see TR9401:1997 on http://www.oasis-open.org <URL:http://www.oasis-open.org>). The Open Catalogs usually reside in /usr/share/sgml.

A centralized catalog is a special Open Catalog that includes only comments and CATALOG directives pointing to other catalogs (or DELEGATE directives if supported). The centralized catalog can be the key to all other SGML resources. It usually resides in /etc/sgml.

The centralized catalog can be edited manually or through the install-catalog script to add or remove references to other ordinary catalogs. This script is mainly destined to software package post-installation scripts.

An example of a typical call to install-catalog is:

```
      install-catalog --add \

        /usr/share/sgml/docbook/dsssl-stylesheets-1.54/catalog \

        /etc/sgml/sgml-docbook-4.0.cat

```

This call will install in /etc/sgml/sgml-docbook-4.0.cat a reference to /usr/share/sgml/docbook/dsssl-stylesheets-1.54/catalog.

## OPTIONS
Here is the list of options that can influence the way install-catalog works:

[ [ -d] [ --delegate] ]

Use DELEGATE instead of CATALOG directives to specify a pointer

## ACTIONS
Here is the list of actions that can be requested to install-catalog:

[ [ -a centralized ordinary] [ --add centralized ordinary] ]

Declare a new SGML package.

[ [ -r centralized ordinary] [ --remove centralized ordinary] ]

Remove a previously installed SGML package.

[ [ -h] [ --help] ]

Print a short help message and exit

[ [ -v] [ --version] ]

Print the version identifier and exit

## FILES
/etc/sgml/*

The SGML centralized catalogs

## AUTHORS
Eric Bischoff <ebisch@cybercable.tm.fr>

Developper of install-catalog.

## SEE ALSO
jw(1)

conversion from DocBook to other file formats

nsgmls(1)

a base component of Jade DSSSL engine

http://sourceware.cygnus.com/docbook-tools/ <URL:http://sourceware.cygnus.com/docbook-tools/>

the home page of the DocBook tools, a compendium of all tools necessary to process DocBook files, including the SGML-common stuff.


grpck

package: shadow-check

title: grpck(8)

summary: verify integrity of group files

text:
# grpck(8)

## NAME
grpck - verify integrity of group files

## SYNOPSIS
grpck [options] [group [ shadow ]]

## DESCRIPTION
The grpck command verifies the integrity of the groups information. It checks that all entries in /etc/group and /etc/gshadow have the proper format and contain valid data. The user is prompted to delete entries that are improperly formatted or which have other uncorrectable errors.

Checks are made to verify that each entry has:

•the correct number of fields

•a unique and valid group name

•a valid group identifier (/etc/group only)

•a valid list of members and administrators

•a corresponding entry in the /etc/gshadow file (respectively /etc/group for the gshadow checks)

The checks for correct number of fields and unique group name are fatal. If an entry has the wrong number of fields, the user will be prompted to delete the entire line. If the user does not answer affirmatively, all further checks are bypassed. An entry with a duplicated group name is prompted for deletion, but the remaining checks will still be made. All other errors are warnings and the user is encouraged to run the groupmod command to correct the error.

The commands which operate on the /etc/group and /etc/gshadow files are not able to alter corrupted or duplicated entries. grpck should be used in those circumstances to remove the offending entries.

## OPTIONS
The -r and -s options cannot be combined.

The options which apply to the grpck command are:

-h, --help

Display help message and exit.

-r, --read-only

Execute the grpck command in read-only mode. This causes all questions regarding changes to be answered no without user intervention.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

-s, --sort

Sort entries in /etc/group and /etc/gshadow by GID.

By default, grpck operates on /etc/group and /etc/gshadow. The user may select alternate files with the group and shadow parameters.

## CONFIGURATION
The following configuration variables in /etc/login.defs change the behavior of this tool:

MAX_MEMBERS_PER_GROUP (number)

Maximum members per group entry. When the maximum is reached, a new group entry (line) is started in /etc/group (with the same name, same password, and same GID). The default value is 0, meaning that there are no limits in the number of members in a group.

This feature (split group) permits to limit the length of lines in the group file. This is useful to make sure that lines for NIS groups are not larger than 1024 characters.

If you need to enforce such limit, you can use 25.

Note: split groups may not be supported by all tools (even in the Shadow toolsuite). You should not use this variable unless you really need it.

## FILES
/etc/group

Group account information.

/etc/gshadow

Secure group account information.

/etc/passwd

User account information.

## EXIT VALUES
The grpck command exits with the following values:

0

success

1

invalid command syntax

2

one or more bad group entries

3

can't open group files

4

can't lock group files

5

can't update group files

## SEE ALSO
group(5), groupmod(8), gshadow(5), passwd(5), pwck(8), shadow(5).


pwck

title: pwck(8)

summary: verify integrity of password files

text:
# pwck(8)

## NAME
pwck - verify integrity of password files

## SYNOPSIS
pwck [options] [passwd [ shadow ]]

## DESCRIPTION
The pwck command verifies the integrity of the users and authentication information. It checks that all entries in /etc/passwd and /etc/shadow (or the files in /etc/tcb, when USE_TCB is enabled) have the proper format and contain valid data. The user is prompted to delete entries that are improperly formatted or which have other uncorrectable errors.

Checks are made to verify that each entry has:

•the correct number of fields

•a unique and valid user name

•a valid user and group identifier

•a valid primary group

•a valid home directory

•a valid login shell

shadow checks are enabled when a second file parameter is specified or when /etc/shadow exists on the system.

These checks are the following:

•every passwd entry has a matching shadow entry, and every shadow entry has a matching passwd entry

•passwords are specified in the shadowed file

•shadow entries have the correct number of fields

•shadow entries are unique in shadow

•the last password changes are not in the future

The checks for correct number of fields and unique user name are fatal. If the entry has the wrong number of fields, the user will be prompted to delete the entire line. If the user does not answer affirmatively, all further checks are bypassed. An entry with a duplicated user name is prompted for deletion, but the remaining checks will still be made. All other errors are warning and the user is encouraged to run the usermod command to correct the error.

The commands which operate on the /etc/passwd file are not able to alter corrupted or duplicated entries. pwck should be used in those circumstances to remove the offending entry.

## OPTIONS
The -r and -s options cannot be combined.

The options which apply to the pwck command are:

-h, --help

Display help message and exit.

-q, --quiet

Report errors only. The warnings which do not require any action from the user won't be displayed.

-r, --read-only

Execute the pwck command in read-only mode.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

-s, --sort

Sort entries in /etc/passwd and /etc/shadow by UID. This option has no effect when USE_TCB is enabled.

By default, pwck operates on the files /etc/passwd and /etc/shadow(or the files in /etc/tcb). The user may select alternate files with the passwd and shadow parameters.

Note that when USE_TCB is enabled, you cannot specify an alternative shadow file. In future releases, this parameter could be replaced by an alternate TCB directory.

## CONFIGURATION
The following configuration variables in /etc/login.defs change the behavior of this tool:

PASS_MAX_DAYS (number)

The maximum number of days a password may be used. If the password is older than this, a password change will be forced. If not specified, -1 will be assumed (which disables the restriction).

PASS_MIN_DAYS (number)

The minimum number of days allowed between password changes. Any password changes attempted sooner than this will be rejected. If not specified, -1 will be assumed (which disables the restriction).

PASS_WARN_AGE (number)

The number of days warning given before a password expires. A zero means warning is given only upon the day of expiration, a negative value means no warning is given. If not specified, no warning will be provided.

TCB_AUTH_GROUP (boolean)

If yes, newly created tcb shadow files will be group owned by the auth group.

TCB_SYMLINKS (boolean)

If yes, the location of the user tcb directory to be created will not be automatically set to /etc/tcb/user, but will be computed depending on the UID of the user, according to the following algorithm:

```
if ( UID is less than 1000) {

  use /etc/tcb/user
} else if ( UID is less than 1000000) {

  kilos = UID / 1000

  use /etc/tcb/:kilos/user

  make symlink /etc/tcb/user to the above directory
} else {

  megas = UID / 1000000

  kilos = ( UID / megas * 1000000 ) / 1000

  use /etc/tcb/:megas/:kilos/user

  make symlink /etc/tcb/user to the above directory
}

```

USE_TCB (boolean)

If yes, the tcb(5) password shadowing scheme will be used.

## FILES
/etc/group

Group account information.

/etc/passwd

User account information.

/etc/shadow

Secure user account information.

## EXIT VALUES
The pwck command exits with the following values:

0

success

1

invalid command syntax

2

one or more bad password entries

3

can't open password files

4

can't lock password files

5

can't update password files

6

can't sort password files

## SEE ALSO
group(5), grpck(8), passwd(5), shadow(5), usermod(8).


pwconv

package: shadow-convert

title: pwconv(8)

text:
# pwconv(8)

## NAME
pwconv, pwunconv, grpconv, grpunconv - convert to and from shadow passwords and groups

## SYNOPSIS
pwconv [options]

pwunconv [options]

grpconv [options]

grpunconv [options]

## DESCRIPTION
The pwconv command creates shadow from passwd and an optionally existing shadow.

pwconv does not work with USE_TCB enabled. To convert to tcb passwords, you should first use pwconv to convert to shadowed passwords by disabling USE_TCB in login.defs and then convert to tcb password using tcb_convert (and re-enable USE_TCB in login.defs.)

The pwunconv command creates passwd from passwd and shadow and then removes shadow.

pwunconv does not work with USE_TCB enabled. You should first switch back from tcb to shadowed passwords using tcb_unconvert, and then disable USE_TCB in login.defs before using pwunconv.

The grpconv command creates gshadow from group and an optionally existing gshadow.

The grpunconv command creates group from group and gshadow and then removes gshadow.

These four programs all operate on the normal and shadow password and group files: /etc/passwd, /etc/group, /etc/shadow, and /etc/gshadow.

Each program acquires the necessary locks before conversion. pwconv and grpconv are similar. First, entries in the shadowed file which don't exist in the main file are removed. Then, shadowed entries which don't have `x' as the password in the main file are updated. Any missing shadowed entries are added. Finally, passwords in the main file are replaced with `x'. These programs can be used for initial conversion as well to update the shadowed file if the main file is edited by hand.

pwconv will use the values of PASS_MIN_DAYS, PASS_MAX_DAYS, and PASS_WARN_AGE from /etc/login.defs when adding new entries to /etc/shadow.

Likewise pwunconv and grpunconv are similar. Passwords in the main file are updated from the shadowed file. Entries which exist in the main file but not in the shadowed file are left alone. Finally, the shadowed file is removed. Some password aging information is lost by pwunconv. It will convert what it can.

## OPTIONS
The options which apply to the pwconv, pwunconv, grpconv, and grpunconv commands are:

-h, --help

Display help message and exit.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

## BUGS
Errors in the password or group files (such as invalid or duplicate entries) may cause these programs to loop forever or fail in other strange ways. Please run pwck and grpck to correct any such errors before converting to or from shadow passwords or groups.

## CONFIGURATION
The following configuration variable in /etc/login.defs changes the behavior of grpconv and grpunconv:

MAX_MEMBERS_PER_GROUP (number)

Maximum members per group entry. When the maximum is reached, a new group entry (line) is started in /etc/group (with the same name, same password, and same GID). The default value is 0, meaning that there are no limits in the number of members in a group.

This feature (split group) permits to limit the length of lines in the group file. This is useful to make sure that lines for NIS groups are not larger than 1024 characters.

If you need to enforce such limit, you can use 25.

Note: split groups may not be supported by all tools (even in the Shadow toolsuite). You should not use this variable unless you really need it.

The following configuration variables in /etc/login.defs change the behavior of pwconv:

PASS_MAX_DAYS (number)

The maximum number of days a password may be used. If the password is older than this, a password change will be forced. If not specified, -1 will be assumed (which disables the restriction).

PASS_MIN_DAYS (number)

The minimum number of days allowed between password changes. Any password changes attempted sooner than this will be rejected. If not specified, -1 will be assumed (which disables the restriction).

PASS_WARN_AGE (number)

The number of days warning given before a password expires. A zero means warning is given only upon the day of expiration, a negative value means no warning is given. If not specified, no warning will be provided.

USE_TCB (boolean)

If yes, the tcb(5) password shadowing scheme will be used.

## FILES
/etc/login.defs

Shadow password suite configuration.

## SEE ALSO
grpck(8), login.defs(5), pwck(8), tcb_convert(8), tcb_unconvert(8).


vipw

package: shadow-edit

title: vipw(8)

summary: edit the password, group, shadow\-password or shadow\-group file

text:
# vipw(8)

## NAME
vipw, vigr - edit the password, group, shadow-password or shadow-group file

## SYNOPSIS
vipw [options]

vigr [options]

## DESCRIPTION
The vipw and vigr commands edits the files /etc/passwd and /etc/group, respectively. With the -s flag, they will edit the shadow versions of those files, /etc/shadow and /etc/gshadow, respectively. The programs will set the appropriate locks to prevent file corruption. When looking for an editor, the programs will first try the environment variable $VISUAL, then the environment variable $EDITOR, and finally the default editor, vi(1).

## OPTIONS
The options which apply to the vipw and vigr commands are:

-g, --group

Edit group database.

-h, --help

Display help message and exit.

-p, --passwd

Edit passwd database.

-q, --quiet

Quiet mode.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

-s, --shadow

Edit shadow or gshadow database.

-u, --user

Indicates which user's tcb shadow file to edit (implies -s).

## CONFIGURATION
The following configuration variables in /etc/login.defs change the behavior of this tool:

USE_TCB (boolean)

If yes, the tcb(5) password shadowing scheme will be used.

## ENVIRONMENT
VISUAL

Editor to be used.

EDITOR

Editor to be used if VISUAL is not set.

## FILES
/etc/group

Group account information.

/etc/gshadow

Secure group account information.

/etc/passwd

User account information.

/etc/shadow

Secure user account information.

## SEE ALSO
vi(1), group(5), gshadow(5) login.defs(5), passwd(5), tcb(5), shadow(5).


groupmems

package: shadow-groups

title: groupmems(8)

summary: administer members of a user\*(Aqs primary group

text:
# groupmems(8)

## NAME
groupmems - administer members of a user's primary group

## SYNOPSIS
groupmems -a user_name | -d user_name | [-g group_name] | -l | -p

## DESCRIPTION
The groupmems command allows a user to administer his/her own group membership list without the requirement of superuser privileges. The groupmems utility is for systems that configure its users to be in their own name sake primary group (i.e., guest / guest).

Only the superuser, as administrator, can use groupmems to alter the memberships of other groups.

## OPTIONS
The options which apply to the groupmems command are:

-a, --add user_name

Add a user to the group membership list. If the /etc/gshadow file exist, and the group has no entry in the /etc/gshadow file, a new entry will be created.

-d, --delete user_name

Delete a user from the group membership list. If the /etc/gshadow file exist, the user will be removed from the list of members and administrators of the group.

If the /etc/gshadow file exist, and the group has no entry in the /etc/gshadow file, a new entry will be created.

-g, --group group_name

The superuser can specify which group membership list to modify.

-h, --help

Display help message and exit.

-l, --list

List the group membership list.

-p, --purge

Purge all users from the group membership list. If the /etc/gshadow file exist, and the group has no entry in the /etc/gshadow file, a new entry will be created.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

## SETUP
The groupmems executable should be in mode 2770 as user root and in group groups. The system administrator can add users to group groups to allow or disallow them using the groupmems utility to manage their own group membership list.

```
	$ groupadd -r groups
	$ chmod 2770 groupmems
	$ chown root.groups groupmems
	$ groupmems -g groups -a gk4

```

## CONFIGURATION
The following configuration variables in /etc/login.defs change the behavior of this tool:

MAX_MEMBERS_PER_GROUP (number)

Maximum members per group entry. When the maximum is reached, a new group entry (line) is started in /etc/group (with the same name, same password, and same GID). The default value is 0, meaning that there are no limits in the number of members in a group.

This feature (split group) permits to limit the length of lines in the group file. This is useful to make sure that lines for NIS groups are not larger than 1024 characters.

If you need to enforce such limit, you can use 25.

Note: split groups may not be supported by all tools (even in the Shadow toolsuite). You should not use this variable unless you really need it.

## FILES
/etc/group

Group account information.

/etc/gshadow

secure group account information

## SEE ALSO
chfn(1), chsh(1), passwd(1), groupadd(8), groupdel(8), useradd(8), userdel(8), usermod(8).


faillog

package: shadow-log

title: faillog(8)

text:
# faillog(8)

## NAME
faillog - display faillog records or set login failure limits

## SYNOPSIS
faillog [options]

## DESCRIPTION
faillog displays the contents of the failure log database (/var/log/faillog). It can also set the failure counters and limits. When faillog is run without arguments, it only displays the faillog records of the users who had a login failure.

## OPTIONS
The options which apply to the faillog command are:

-a, --all

Display (or act on) faillog records for all users having an entry in the faillog database. The range of users can be restricted with the -u option.

In display mode, this is still restricted to existing users but forces the display of the faillog entries even if they are empty.

With the -l, -m, -r, -t options, the users' records are changed, even if the user does not exist on the system. This is useful to reset records of users that have been deleted or to set a policy in advance for a range of users.

-h, --help

Display help message and exit.

-l, --lock-secs SEC

Lock account for SEC seconds after failed login. Write access to /var/log/faillog is required for this option.

-m, --maximum MAX

Set the maximum number of login failures after the account is disabled to MAX. Selecting a MAX value of 0 has the effect of not placing a limit on the number of failed logins.

The maximum failure count should always be 0 for root to prevent a denial of services attack against the system.

Write access to /var/log/faillog is required for this option.

-r, --reset

Reset the counters of login failures. Write access to /var/log/faillog is required for this option.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

-t, --time DAYS

Display faillog records more recent than DAYS.

-u, --user LOGIN|RANGE

Display faillog record or maintains failure counters and limits (if used with -l, -m or -r options) only for the specified user(s). The users can be specified by a login name, a numerical user ID, or a RANGE of users. This RANGE of users can be specified with a min and max values (UID_MIN-UID_MAX), a max value (-UID_MAX), or a min value (UID_MIN-).

When none of the -l, -m, or -r options are used, faillog displays the faillog record of the specified user(s).

## CAVEATS
faillog only prints out users with no successful login since the last failure. To print out a user who has had a successful login since their last failure, you must explicitly request the user with the -u flag, or print out all users with the -a flag.

## FILES
/var/log/faillog

Failure logging file.

## SEE ALSO
login(1), faillog(5).


lastlog

title: lastlog(8)

text:
# lastlog(8)

## NAME
lastlog - reports the most recent login of all users or of a given user

## SYNOPSIS
lastlog [options]

## DESCRIPTION
lastlog formats and prints the contents of the last login log /var/log/lastlog file. The login-name, port, and last login time will be printed. The default (no flags) causes lastlog entries to be printed, sorted by their order in /etc/passwd.

## OPTIONS
The options which apply to the lastlog command are:

-b, --before DAYS

Print only lastlog records older than DAYS.

-C, --clear

Clear lastlog record of a user. This option can be used only together with -u (--user)).

-h, --help

Display help message and exit.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

-S, --set

Set lastlog record of a user to the current time. This option can be used only together with -u (--user)).

-t, --time DAYS

Print the lastlog records more recent than DAYS.

-u, --user LOGIN|RANGE

Print the lastlog record of the specified user(s). The users can be specified by a login name, a numerical user ID, or a RANGE of users. This RANGE of users can be specified with a min and max values (UID_MIN-UID_MAX), a max value (-UID_MAX), or a min value (UID_MIN-).

If the user has never logged in the message ** Never logged in** will be displayed instead of the port and time.

Only the entries for the current users of the system will be displayed. Other entries may exist for users that were deleted previously.

## NOTE
The lastlog file is a database which contains info on the last login of each user. You should not rotate it. It is a sparse file, so its size on the disk is usually much smaller than the one shown by "ls -l" (which can indicate a really big file if you have in passwd users with a high UID). You can display its real size with "ls -s".

## FILES
/var/log/lastlog

Database times of previous user logins.

## CAVEATS
Large gaps in UID numbers will cause the lastlog program to run longer with no output to the screen (i.e. if in lastlog database there is no entries for users with UID between 170 and 800 lastlog will appear to hang as it processes entries with UIDs 171-799).


chpasswd

package: shadow-utils

title: chpasswd(8)

summary: update passwords in batch mode

text:
# chpasswd(8)

## NAME
chpasswd - update passwords in batch mode

## SYNOPSIS
chpasswd [options]

## DESCRIPTION
The chpasswd command reads a list of user name and password pairs from standard input and uses this information to update a group of existing users. Each line is of the format:

user_name:password

By default the passwords must be supplied in clear-text, and are encrypted by chpasswd. Also the password age will be updated, if present.

By default, passwords are encrypted by PAM, but (even if not recommended) you can select a different encryption method with the -e, -m, or -c options.

Except when PAM is used to encrypt the passwords, chpasswd first updates all the passwords in memory, and then commits all the changes to disk if no errors occurred for any user.

When PAM is used to encrypt the passwords (and update the passwords in the system database) then if a password cannot be updated chpasswd continues updating the passwords of the next users, and will return an error code on exit.

This command is intended to be used in a large system environment where many accounts are created at a single time.

## OPTIONS
The options which apply to the chpasswd command are:

-c, --crypt-method METHOD

Use the specified method to encrypt the passwords. The available methods are DES, MD5, and NONE.

By default, PAM is used to encrypt the passwords.

-e, --encrypted

Supplied passwords are in encrypted form.

-h, --help

Display help message and exit.

-m, --md5

Use MD5 encryption instead of DES when the supplied passwords are not encrypted.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

## CAVEATS
Remember to set permissions or umask to prevent readability of unencrypted files by other users.

## CONFIGURATION
The following configuration variables in /etc/login.defs change the behavior of this tool:

## FILES
/etc/passwd

User account information.

/etc/shadow

Secure user account information.

/etc/login.defs

Shadow password suite configuration.

/etc/pam.d/chpasswd

PAM configuration for chpasswd.

## SEE ALSO
passwd(1), newusers(8), login.defs(5), useradd(8).


groupadd

title: groupadd(8)

summary: create a new group

text:
# groupadd(8)

## NAME
groupadd - create a new group

## SYNOPSIS
groupadd [options] group

## DESCRIPTION
The groupadd command creates a new group account using the values specified on the command line plus the default values from the system. The new group will be entered into the system files as needed.

## OPTIONS
The options which apply to the groupadd command are:

-f, --force

This option causes the command to simply exit with success status if the specified group already exists. When used with -g, and the specified GID already exists, another (unique) GID is chosen (i.e. -g is turned off).

-g, --gid GID

The numerical value of the group's ID. This value must be unique, unless the -o option is used. The value must be non-negative. The default is to use the smallest ID value greater than or equal to GID_MIN and greater than every other group. See also the -r option and the GID_MAX description.

-h, --help

Display help message and exit.

-K, --key KEY=VALUE

Overrides /etc/login.defs defaults (GID_MIN, GID_MAX and others). Multiple -K options can be specified. Example: -K GID_MIN=100 -K GID_MAX=499

Note: -K GID_MIN=10,GID_MAX=499 doesn't work yet.

-o, --non-unique

This option permits to add a group with a non-unique GID.

-p, --password PASSWORD

The encrypted password, as returned by crypt(3). The default is to disable the password. Note: This option is not recommended because the password (or encrypted password) will be visible by users listing the processes.

You should make sure the password respects the system's password policy.

-r, --system

Create a system group. The numeric identifiers of new system groups are chosen in the SYS_GID_MIN-SYS_GID_MAX range, defined in login.defs, instead of GID_MIN-GID_MAX.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

## CONFIGURATION
The following configuration variables in /etc/login.defs change the behavior of this tool:

GID_MAX (number), GID_MIN (number)

Range of group IDs used for the creation of regular groups by useradd, groupadd, or newusers. The default value for GID_MIN (resp. GID_MAX) is 1000 (resp. 60000).

MAX_MEMBERS_PER_GROUP (number)

Maximum members per group entry. When the maximum is reached, a new group entry (line) is started in /etc/group (with the same name, same password, and same GID). The default value is 0, meaning that there are no limits in the number of members in a group.

This feature (split group) permits to limit the length of lines in the group file. This is useful to make sure that lines for NIS groups are not larger than 1024 characters.

If you need to enforce such limit, you can use 25.

Note: split groups may not be supported by all tools (even in the Shadow toolsuite). You should not use this variable unless you really need it.

SYS_GID_MAX (number), SYS_GID_MIN (number)

Range of group IDs used for the creation of system groups by useradd, groupadd, or newusers. The default value for SYS_GID_MIN (resp. SYS_GID_MAX) is 101 (resp. GID_MIN-1).

## FILES
/etc/group

Group account information.

/etc/gshadow

Secure group account information.

/etc/login.defs

Shadow password suite configuration.

## CAVEATS
Groupnames must start with a lower case letter or an underscore, followed by lower case letters, digits, underscores, or dashes. They can end with a dollar sign. In regular expression terms: [a-z_][a-z0-9_-]*[$]?

Groupnames may only be up to 32 characters long.

You may not add a NIS or LDAP group. This must be performed on the corresponding server.

If the groupname already exists in an external group database such as NIS or LDAP, groupadd will deny the group creation request.

## EXIT VALUES
The groupadd command exits with the following values:

0

success

2

invalid command syntax

3

invalid argument to option

4

GID not unique (when -o not used)

9

group name not unique

10

can't update group file

## SEE ALSO
chfn(1), chsh(1), passwd(1), gpasswd(8), groupdel(8), groupmod(8), login.defs(5), useradd(8), userdel(8), usermod(8).


groupdel

title: groupdel(8)

summary: delete a group

text:
# groupdel(8)

## NAME
groupdel - delete a group

## SYNOPSIS
groupdel [options] GROUP

## DESCRIPTION
The groupdel command modifies the system account files, deleting all entries that refer to GROUP. The named group must exist.

## OPTIONS
The options which apply to the groupdel command are:

-h, --help

Display help message and exit.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

## CAVEATS
You may not remove the primary group of any existing user. You must remove the user before you remove the group.

You should manually check all file systems to ensure that no files remain owned by this group.

## CONFIGURATION
The following configuration variables in /etc/login.defs change the behavior of this tool:

MAX_MEMBERS_PER_GROUP (number)

Maximum members per group entry. When the maximum is reached, a new group entry (line) is started in /etc/group (with the same name, same password, and same GID). The default value is 0, meaning that there are no limits in the number of members in a group.

This feature (split group) permits to limit the length of lines in the group file. This is useful to make sure that lines for NIS groups are not larger than 1024 characters.

If you need to enforce such limit, you can use 25.

Note: split groups may not be supported by all tools (even in the Shadow toolsuite). You should not use this variable unless you really need it.

## FILES
/etc/group

Group account information.

/etc/gshadow

Secure group account information.

## EXIT VALUES
The groupdel command exits with the following values:

0

success

2

invalid command syntax

6

specified group doesn't exist

8

can't remove user's primary group

10

can't update group file

## SEE ALSO
chfn(1), chsh(1), passwd(1), gpasswd(8), groupadd(8), groupmod(8), useradd(8), userdel(8), usermod(8).


groupmod

title: groupmod(8)

summary: modify a group definition on the system

text:
# groupmod(8)

## NAME
groupmod - modify a group definition on the system

## SYNOPSIS
groupmod [options] GROUP

## DESCRIPTION
The groupmod command modifies the definition of the specified GROUP by modifying the appropriate entry in the group database.

## OPTIONS
The options which apply to the groupmod command are:

-g, --gid GID

The group ID of the given GROUP will be changed to GID. The value of GID must be a non-negative decimal integer. This value must be unique, unless the -o option is used.

Users who use the group as primary group will be updated to keep the group as their primary group.

Any files that have the old group ID and must continue to belong to GROUP, must have their group ID changed manually.

No checks will be performed with regard to the GID_MIN, GID_MAX, SYS_GID_MIN, or SYS_GID_MAX from /etc/login.defs.

-h, --help

Display help message and exit.

-n, --new-name NEW_GROUP

The name of the group will be changed from GROUP to NEW_GROUP name.

-o, --non-unique

When used with the -g option, allow to change the group GID to a non-unique value.

-p, --password PASSWORD

The encrypted password, as returned by crypt(3). Note: This option is not recommended because the password (or encrypted password) will be visible by users listing the processes.

You should make sure the password respects the system's password policy.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

## CONFIGURATION
The following configuration variables in /etc/login.defs change the behavior of this tool:

MAX_MEMBERS_PER_GROUP (number)

Maximum members per group entry. When the maximum is reached, a new group entry (line) is started in /etc/group (with the same name, same password, and same GID). The default value is 0, meaning that there are no limits in the number of members in a group.

This feature (split group) permits to limit the length of lines in the group file. This is useful to make sure that lines for NIS groups are not larger than 1024 characters.

If you need to enforce such limit, you can use 25.

Note: split groups may not be supported by all tools (even in the Shadow toolsuite). You should not use this variable unless you really need it.

## FILES
/etc/group

Group account information.

/etc/gshadow

Secure group account information.

/etc/login.defs

Shadow password suite configuration.

/etc/passwd

User account information.

## EXIT VALUES
The groupmod command exits with the following values:

0

success

2

invalid command syntax

3

invalid argument to option

4

specified group doesn't exist

6

specified group doesn't exist

9

group name already in use

10

can't update group file

## SEE ALSO
chfn(1), chsh(1), passwd(1), gpasswd(8), groupadd(8), groupdel(8), login.defs(5), useradd(8), userdel(8), usermod(8).


newusers

title: newusers(8)

summary: update and create new users in batch

text:
# newusers(8)

## NAME
newusers - update and create new users in batch

## SYNOPSIS
newusers [options] [file]

## DESCRIPTION
The newusers command reads a file (or the standard input by default) and uses this information to update a set of existing users or to create new users. Each line is in the same format as the standard password file (see passwd(5)) with the exceptions explained below:

pw_name:pw_passwd:pw_uid:pw_gid:pw_gecos:pw_dir:pw_shell

pw_name

This is the name of the user. It can be the name of a new user or the name of an existing user (or a user created before by newusers). In case of an existing user, the user's information will be changed, otherwise a new user will be created.

pw_passwd

This field will be encrypted and used as the new value of the encrypted password.

pw_uid

This field is used to define the UID of the user. If the field is empty, a new (unused) UID will be defined automatically by newusers.

If this field contains a number, this number will be used as the UID.

If this field contains the name of an existing user (or the name of a user created before by newusers), the UID of the specified user will be used.

If the UID of an existing user is changed, the files ownership of the user's file should be fixed manually.

pw_gid

This field is used to define the primary group ID for the user. If this field contains the name of an existing group (or a group created before by newusers), the GID of this group will be used as the primary group ID for the user.

If this field is a number, this number will be used as the primary group ID of the user. If no groups exist with this GID, a new group will be created with this GID, and the name of the user.

If this field is empty, a new group will be created with the name of the user and a GID will be automatically defined by newusers to be used as the primary group ID for the user and as the GID for the new group.

If this field contains the name of a group which does not exist (and was not created before by newusers), a new group will be created with the specified name and a GID will be automatically defined by newusers to be used as the primary group ID for the user and GID for the new group.

pw_gecos

This field is copied in the GECOS field of the user.

pw_dir

This field is used to define the home directory of the user. If this field does not specify an existing directory, the specified directory is created, with ownership set to the user being created or updated and its primary group.

If the home directory of an existing user is changed, newusers does not move or copy the content of the old directory to the new location. This should be done manually.

pw_shell

This field defines the shell of the user. No checks are performed on this field.

newusers first tries to create or change all the specified users, and then write these changes to the user or group databases. If an error occurs (except in the final writes to the databases), no changes are committed to the databases.

During this first pass, users are created with a locked password (and passwords are not changed for the users which are not created). A second pass is used to update the passwords using PAM. Failures to update a password are reported, but will not stop the other password updates.

This command is intended to be used in a large system environment where many accounts are updated at a single time.

## OPTIONS
The options which apply to the newusers command are:

-h, --help

Display help message and exit.

-r, --system

Create a system account. System users will be created with no aging information in /etc/shadow, and their numeric identifiers are chosen in the SYS_UID_MIN-SYS_UID_MAX range, defined in login.defs, instead of UID_MIN-UID_MAX (and their GID counterparts for the creation of groups).

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

## CAVEATS
The input file must be protected since it contains unencrypted passwords.

## CONFIGURATION
The following configuration variables in /etc/login.defs change the behavior of this tool:

GID_MAX (number), GID_MIN (number)

Range of group IDs used for the creation of regular groups by useradd, groupadd, or newusers. The default value for GID_MIN (resp. GID_MAX) is 1000 (resp. 60000).

MAX_MEMBERS_PER_GROUP (number)

Maximum members per group entry. When the maximum is reached, a new group entry (line) is started in /etc/group (with the same name, same password, and same GID). The default value is 0, meaning that there are no limits in the number of members in a group.

This feature (split group) permits to limit the length of lines in the group file. This is useful to make sure that lines for NIS groups are not larger than 1024 characters.

If you need to enforce such limit, you can use 25.

Note: split groups may not be supported by all tools (even in the Shadow toolsuite). You should not use this variable unless you really need it.

PASS_MAX_DAYS (number)

The maximum number of days a password may be used. If the password is older than this, a password change will be forced. If not specified, -1 will be assumed (which disables the restriction).

PASS_MIN_DAYS (number)

The minimum number of days allowed between password changes. Any password changes attempted sooner than this will be rejected. If not specified, -1 will be assumed (which disables the restriction).

PASS_WARN_AGE (number)

The number of days warning given before a password expires. A zero means warning is given only upon the day of expiration, a negative value means no warning is given. If not specified, no warning will be provided.

SUB_GID_MIN (number), SUB_GID_MAX (number), SUB_GID_COUNT (number)

If /etc/subuid exists, the commands useradd and newusers (unless the user already have subordinate group IDs) allocate SUB_GID_COUNT unused group IDs from the range SUB_GID_MIN to SUB_GID_MAX for each new user. The default values for SUB_GID_MIN, SUB_GID_MAX, SUB_GID_COUNT are respectively 100000, 600100000 and 10000.

SUB_UID_MIN (number), SUB_UID_MAX (number), SUB_UID_COUNT (number)

If /etc/subuid exists, the commands useradd and newusers (unless the user already have subordinate user IDs) allocate SUB_UID_COUNT unused user IDs from the range SUB_UID_MIN to SUB_UID_MAX for each new user. The default values for SUB_UID_MIN, SUB_UID_MAX, SUB_UID_COUNT are respectively 100000, 600100000 and 10000.

SYS_GID_MAX (number), SYS_GID_MIN (number)

Range of group IDs used for the creation of system groups by useradd, groupadd, or newusers. The default value for SYS_GID_MIN (resp. SYS_GID_MAX) is 101 (resp. GID_MIN-1).

SYS_UID_MAX (number), SYS_UID_MIN (number)

Range of user IDs used for the creation of system users by useradd or newusers. The default value for SYS_UID_MIN (resp. SYS_UID_MAX) is 101 (resp. UID_MIN-1).

UID_MAX (number), UID_MIN (number)

Range of user IDs used for the creation of regular users by useradd or newusers. The default value for UID_MIN (resp. UID_MAX) is 1000 (resp. 60000).

UMASK (number)

The file mode creation mask is initialized to this value. If not specified, the mask will be initialized to 022. useradd and newusers use this mask to set the mode of the home directory they create

It is also used by pam_umask as the default umask value.

## FILES
/etc/passwd

User account information.

/etc/shadow

Secure user account information.

/etc/group

Group account information.

/etc/gshadow

Secure group account information.

/etc/login.defs

Shadow password suite configuration.

/etc/pam.d/newusers

PAM configuration for newusers.

/etc/subgid

Per user subordinate group IDs.

/etc/subuid

Per user subordinate user IDs.

## SEE ALSO
login.defs(5), passwd(1), subgid(5), subuid(5), useradd(8).


useradd

title: useradd(8)

text:
# useradd(8)

## NAME
useradd - create a new user or update default new user information

## SYNOPSIS
useradd [options] LOGIN

useradd -D

useradd -D [options]

## DESCRIPTION
When invoked without the -D option, the useradd command creates a new user account using the values specified on the command line plus the default values from the system. Depending on command line options, the useradd command will update system files and may also create the new user's home directory and copy initial files.

By default, a group will also be created for the new user (see -g, -N, -U, and USERGROUPS_ENAB).

## OPTIONS
The options which apply to the useradd command are:

-b, --base-dir BASE_DIR

The default base directory for the system if -d HOME_DIR is not specified. BASE_DIR is concatenated with the account name to define the home directory. If the -m option is not used, BASE_DIR must exist. If this option is not specified, useradd will use the base directory specified by the HOME variable in /etc/default/useradd, or /home by default.

-c, --comment COMMENT

Any text string. It is generally a short description of the login, and is currently used as the field for the user's full name.

-d, --home-dir HOME_DIR

The new user will be created using HOME_DIR as the value for the user's login directory. The default is to append the LOGIN name to BASE_DIR and use that as the login directory name. The directory HOME_DIR does not have to exist but will not be created if it is missing.

-D, --defaults

See below, the subsection "Changing the default values".

-e, --expiredate EXPIRE_DATE

The date on which the user account will be disabled. The date is specified in the format YYYY-MM-DD. If not specified, useradd will use the default expiry date specified by the EXPIRE variable in /etc/default/useradd, or an empty string (no expiry) by default.

-f, --inactive INACTIVE

The number of days after a password expires until the account is permanently disabled. A value of 0 disables the account as soon as the password has expired, and a value of -1 disables the feature. If not specified, useradd will use the default inactivity period specified by the INACTIVE variable in /etc/default/useradd, or -1 by default.

-g, --gid GROUP

The group name or number of the user's initial login group. The group name must exist. A group number must refer to an already existing group. If not specified, the behavior of useradd will depend on the USERGROUPS_ENAB variable in /etc/login.defs. If this variable is set to yes (or -U/--user-group is specified on the command line), a group will be created for the user, with the same name as her loginname. If the variable is set to no (or -N/--no-user-group is specified on the command line), useradd will set the primary group of the new user to the value specified by the GROUP variable in /etc/default/useradd, or 100 by default.

-G, --groups GROUP1[,GROUP2,...[,GROUPN]]]

A list of supplementary groups which the user is also a member of. Each group is separated from the next by a comma, with no intervening whitespace. The groups are subject to the same restrictions as the group given with the -g option. The default is for the user to belong only to the initial group.

-h, --help

Display help message and exit.

-k, --skel SKEL_DIR

The skeleton directory, which contains files and directories to be copied in the user's home directory, when the home directory is created by useradd. This option is only valid if the -m (or --create-home) option is specified.

If this option is not set, the skeleton directory is defined by the SKEL variable in /etc/default/useradd or, by default, /etc/skel.

If possible, the ACLs and extended attributes are copied.

-K, --key KEY=VALUE

Overrides /etc/login.defs defaults (UID_MIN, UID_MAX, UMASK, PASS_MAX_DAYS and others). Example: -K PASS_MAX_DAYS=-1 can be used when creating system account to turn off password aging, even though system account has no password at all. Multiple -K options can be specified, e.g.: -K UID_MIN=100 -K UID_MAX=499

-l, --no-log-init

Do not add the user to the lastlog and faillog databases. By default, the user's entries in the lastlog and faillog databases are reset to avoid reusing the entry from a previously deleted user.

-m, --create-home

Create the user's home directory if it does not exist. The files and directories contained in the skeleton directory (which can be defined with the -k option) will be copied to the home directory. By default, if this option is not specified and CREATE_HOME is not enabled, no home directories are created.

-M, --no-create-home

Do no create the user's home directory, even if the system wide setting from /etc/login.defs (CREATE_HOME) is set to yes.

-N, --no-user-group

Do not create a group with the same name as the user, but add the user to the group specified by the -g option or by the GROUP variable in /etc/default/useradd. The default behavior (if the -g, -N, and -U options are not specified) is defined by the USERGROUPS_ENAB variable in /etc/login.defs.

-o, --non-unique

Allow the creation of a user account with a duplicate (non-unique) UID. This option is only valid in combination with the -u option.

-p, --password PASSWORD

The encrypted password, as returned by crypt(3). The default is to disable the password. Note: This option is not recommended because the password (or encrypted password) will be visible by users listing the processes.

You should make sure the password respects the system's password policy.

-r, --system

Create a system account. System users will be created with no aging information in /etc/shadow, and their numeric identifiers are chosen in the SYS_UID_MIN-SYS_UID_MAX range, defined in /etc/login.defs, instead of UID_MIN-UID_MAX (and their GID counterparts for the creation of groups).

Note that useradd will not create a home directory for such a user, regardless of the default setting in /etc/login.defs (CREATE_HOME). You have to specify the -m options if you want a home directory for a system account to be created.

-R, --root CHROOT_DIR

Apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory.

-s, --shell SHELL

The name of the user's login shell. The default is to leave this field blank, which causes the system to select the default login shell specified by the SHELL variable in /etc/default/useradd, or an empty string by default.

-u, --uid UID

The numerical value of the user's ID. This value must be unique, unless the -o option is used. The value must be non-negative. The default is to use the smallest ID value greater than or equal to UID_MIN and greater than every other user. See also the -r option and the UID_MAX description.

-U, --user-group

Create a group with the same name as the user, and add the user to this group. The default behavior (if the -g, -N, and -U options are not specified) is defined by the USERGROUPS_ENAB variable in /etc/login.defs.

-Z, --selinux-user SEUSER

The SELinux user for the user's login. The default is to leave this field blank, which causes the system to select the default SELinux user.

### Changing the default values
When invoked with only the -D option, useradd will display the current default values. When invoked with -D plus other options, useradd will update the default values for the specified options. Valid default-changing options are:

-b, --base-dir BASE_DIR

The path prefix for a new user's home directory. The user's name will be affixed to the end of BASE_DIR to form the new user's home directory name, if the -d option is not used when creating a new account. This option sets the HOME variable in /etc/default/useradd.

-e, --expiredate EXPIRE_DATE

The date on which the user account is disabled. This option sets the EXPIRE variable in /etc/default/useradd.

-f, --inactive INACTIVE

The number of days after a password has expired before the account will be disabled. This option sets the INACTIVE variable in /etc/default/useradd.

-g, --gid GROUP

The group name or ID for a new user's initial group (when the -N/--no-user-group is used or when the USERGROUPS_ENAB variable is set to no in /etc/login.defs). The named group must exist, and a numerical group ID must have an existing entry. This option sets the GROUP variable in /etc/default/useradd.

-s, --shell SHELL

The name of a new user's login shell. This option sets the SHELL variable in /etc/default/useradd.

## NOTES
The system administrator is responsible for placing the default user files in the /etc/skel/ directory (or any other skeleton directory specified in /etc/default/useradd or on the command line).

## CAVEATS
You may not add a user to a NIS or LDAP group. This must be performed on the corresponding server.

Similarly, if the username already exists in an external user database such as NIS or LDAP, useradd will deny the user account creation request.

Usernames must start with a lower case letter or an underscore, followed by lower case letters, digits, underscores, or dashes. They can end with a dollar sign. In regular expression terms: [a-z_][a-z0-9_-]*[$]?

Usernames may only be up to 32 characters long.

## CONFIGURATION
The following configuration variables in /etc/login.defs change the behavior of this tool:

CREATE_HOME (boolean)

Indicate if a home directory should be created by default for new users. This setting does not apply to system users, and can be overridden on the command line.

GID_MAX (number), GID_MIN (number)

Range of group IDs used for the creation of regular groups by useradd, groupadd, or newusers. The default value for GID_MIN (resp. GID_MAX) is 1000 (resp. 60000).

MAIL_DIR (string)

The mail spool directory. This is needed to manipulate the mailbox when its corresponding user account is modified or deleted. If not specified, a compile-time default is used.

MAIL_FILE (string)

Defines the location of the users mail spool files relatively to their home directory.

The MAIL_DIR and MAIL_FILE variables are used by useradd, usermod, and userdel to create, move, or delete the user's mail spool.

MAX_MEMBERS_PER_GROUP (number)

Maximum members per group entry. When the maximum is reached, a new group entry (line) is started in /etc/group (with the same name, same password, and same GID). The default value is 0, meaning that there are no limits in the number of members in a group.

This feature (split group) permits to limit the length of lines in the group file. This is useful to make sure that lines for NIS groups are not larger than 1024 characters.

If you need to enforce such limit, you can use 25.

Note: split groups may not be supported by all tools (even in the Shadow toolsuite). You should not use this variable unless you really need it.

PASS_MAX_DAYS (number)

The maximum number of days a password may be used. If the password is older than this, a password change will be forced. If not specified, -1 will be assumed (which disables the restriction).

PASS_MIN_DAYS (number)

The minimum number of days allowed between password changes. Any password changes attempted sooner than this will be rejected. If not specified, -1 will be assumed (which disables the restriction).

PASS_WARN_AGE (number)

The number of days warning given before a password expires. A zero means warning is given only upon the day of expiration, a negative value means no warning is given. If not specified, no warning will be provided.

SUB_GID_MIN (number), SUB_GID_MAX (number), SUB_GID_COUNT (number)

If /etc/subuid exists, the commands useradd and newusers (unless the user already have subordinate group IDs) allocate SUB_GID_COUNT unused group IDs from the range SUB_GID_MIN to SUB_GID_MAX for each new user. The default values for SUB_GID_MIN, SUB_GID_MAX, SUB_GID_COUNT are respectively 100000, 600100000 and 10000.

SUB_UID_MIN (number), SUB_UID_MAX (number), SUB_UID_COUNT (number)

If /etc/subuid exists, the commands useradd and newusers (unless the user already have subordinate user IDs) allocate SUB_UID_COUNT unused user IDs from the range SUB_UID_MIN to SUB_UID_MAX for each new user. The default values for SUB_UID_MIN, SUB_UID_MAX, SUB_UID_COUNT are respectively 100000, 600100000 and 10000.

SYS_GID_MAX (number), SYS_GID_MIN (number)

Range of group IDs used for the creation of system groups by useradd, groupadd, or newusers. The default value for SYS_GID_MIN (resp. SYS_GID_MAX) is 101 (resp. GID_MIN-1).

SYS_UID_MAX (number), SYS_UID_MIN (number)

Range of user IDs used for the creation of system users by useradd or newusers. The default value for SYS_UID_MIN (resp. SYS_UID_MAX) is 101 (resp. UID_MIN-1).

TCB_AUTH_GROUP (boolean)

If yes, newly created tcb shadow files will be group owned by the auth group.

TCB_SYMLINKS (boolean)

If yes, the location of the user tcb directory to be created will not be automatically set to /etc/tcb/user, but will be computed depending on the UID of the user, according to the following algorithm:

```
if ( UID is less than 1000) {

  use /etc/tcb/user
} else if ( UID is less than 1000000) {

  kilos = UID / 1000

  use /etc/tcb/:kilos/user

  make symlink /etc/tcb/user to the above directory
} else {

  megas = UID / 1000000

  kilos = ( UID / megas * 1000000 ) / 1000

  use /etc/tcb/:megas/:kilos/user

  make symlink /etc/tcb/user to the above directory
}

```

UID_MAX (number), UID_MIN (number)

Range of user IDs used for the creation of regular users by useradd or newusers. The default value for UID_MIN (resp. UID_MAX) is 1000 (resp. 60000).

UMASK (number)

The file mode creation mask is initialized to this value. If not specified, the mask will be initialized to 022. useradd and newusers use this mask to set the mode of the home directory they create

It is also used by pam_umask as the default umask value.

USE_TCB (boolean)

If yes, the tcb(5) password shadowing scheme will be used.

USERGROUPS_ENAB (boolean)

If set to yes, userdel will remove the user's group if it contains no more members, and useradd will create by default a group with the name of the user.

## FILES
/etc/passwd

User account information.

/etc/shadow

Secure user account information.

/etc/group

Group account information.

/etc/gshadow

Secure group account information.

/etc/default/useradd

Default values for account creation.

/etc/skel/

Directory containing default files.

/etc/subgid

Per user subordinate group IDs.

/etc/subuid

Per user subordinate user IDs.

/etc/login.defs

Shadow password suite configuration.

## EXIT VALUES
The useradd command exits with the following values:

0

success

1

can't update password file

2

invalid command syntax

3

invalid argument to option

4

UID already in use (and no -o)

6

specified group doesn't exist

9

username already in use

10

can't update group file

12

can't create home directory

14

can't update SELinux user mapping

## SEE ALSO
chfn(1), chsh(1), passwd(1), crypt(3), groupadd(8), groupdel(8), groupmod(8), login.defs(5), newusers(8), subgid(5), subuid(5), userdel(8), usermod(8).