vgs

title: vgs(8)

summary: Display information about volume groups

text:
# vgs(8)

## NAME
vgs — Display information about volume groups

## SYNOPSIS
vgs

[ option_args ]

[ position_args ]

## DESCRIPTION
vgs produces formatted output about VGs.

## USAGE
vgs

[ -a|--all ]

[ -o|--options String ]

[ -S|--select String ]

[ -O|--sort String ]

[ --aligned ]

[ --binary ]

[ --configreport log|vg|lv|pv|pvseg|seg ]

[ --foreign ]

[ --ignorelockingfailure ]

[ --logonly ]

[ --nameprefixes ]

[ --noheadings ]

[ --nosuffix ]

[ --readonly ]

[ --reportformat basic|json ]

[ --rows ]

[ --separator String ]

[ --shared ]

[ --unbuffered ]

[ --units [Number]r|R|h|H|b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E ]

[ --unquoted ]

[ COMMON_OPTIONS ]

[ VG|Tag ... ]

Common options for lvm:

[ -d|--debug ]

[ -h|--help ]

[ -q|--quiet ]

[ -t|--test ]

[ -v|--verbose ]

[ -y|--yes ]

[ --commandprofile String ]

[ --config String ]

[ --devices PV ]

[ --devicesfile String ]

[ --driverloaded y|n ]

[ --journal String ]

[ --lockopt String ]

[ --longhelp ]

[ --nohints ]

[ --nolocking ]

[ --profile String ]

[ --version ]

## OPTIONS
--aligned

Use with --separator to align the output columns

-a|--all

List all VGs. Equivalent to not specifying any VGs.

--binary

Use binary values "0" or "1" instead of descriptive literal values for columns that have exactly two valid values to report (not counting the "unknown" value which denotes that the value could not be determined).

--commandprofile String

The command profile to use for command configuration. See lvm.conf(5) for more information about profiles.

--config String

Config settings for the command. These override lvm.conf(5) settings. The String arg uses the same format as lvm.conf(5), or may use section/field syntax. See lvm.conf(5) for more information about config.

--configreport log|vg|lv|pv|pvseg|seg

See lvmreport(7).

-d|--debug ...

Set debug level. Repeat from 1 to 6 times to increase the detail of messages sent to the log file and/or syslog (if configured).

--devices PV

Restricts the devices that are visible and accessible to the command. Devices not listed will appear to be missing. This option can be repeated, or accepts a comma separated list of devices. This overrides the devices file.

--devicesfile String

A file listing devices that LVM should use. The file must exist in /etc/lvm/devices/ and is managed with the lvmdevices(8) command. This overrides the lvm.conf(5) devices/devicesfile and devices/use_devicesfile settings.

--driverloaded y|n

If set to no, the command will not attempt to use device-mapper. For testing and debugging.

--foreign

Report/display foreign VGs that would otherwise be skipped. See lvmsystemid(7) for more information about foreign VGs.

-h|--help

Display help text.

--ignorelockingfailure

Allows a command to continue with read-only metadata operations after locking failures.

--journal String

Record information in the systemd journal. This information is in addition to information enabled by the lvm.conf log/journal setting. command: record information about the command. output: record the default command output. debug: record full command debugging.

--lockopt String

Used to pass options for special cases to lvmlockd. See lvmlockd(8) for more information.

--logonly

Suppress command report and display only log report.

--longhelp

Display long help text.

--nameprefixes

Add an "LVM2_" prefix plus the field name to the output. Useful with --noheadings to produce a list of field=value pairs that can be used to set environment variables (for example, in udev rules).

--noheadings

Suppress the headings line that is normally the first line of output. Useful if grepping the output.

--nohints

Do not use the hints file to locate devices for PVs. A command may read more devices to find PVs when hints are not used. The command will still perform standard hint file invalidation where appropriate.

--nolocking

Disable locking. Use with caution, concurrent commands may produce incorrect results.

--nosuffix

Suppress the suffix on output sizes. Use with --units (except h and H) if processing the output.

-o|--options String

Comma-separated, ordered list of fields to display in columns. String arg syntax is: [+|-|#]Field1[,Field2 ...] The prefix + will append the specified fields to the default fields, - will remove the specified fields from the default fields, and # will compact specified fields (removing them when empty for all rows.) Use -o help to view the list of all available fields. Use separate lists of fields to add, remove or compact by repeating the -o option: -o+field1,field2 -o-field3,field4 -o#field5. These lists are evaluated from left to right. Use field name lv_all to view all LV fields, vg_all all VG fields, pv_all all PV fields, pvseg_all all PV segment fields, seg_all all LV segment fields, and pvseg_all all PV segment columns. See the lvm.conf(5) report section for more config options. See lvmreport(7) for more information about reporting.

--profile String

An alias for --commandprofile or --metadataprofile, depending on the command.

-q|--quiet ...

Suppress output and log messages. Overrides --debug and --verbose. Repeat once to also suppress any prompts with answer 'no'.

--readonly

Run the command in a special read-only mode which will read on-disk metadata without needing to take any locks. This can be used to peek inside metadata used by a virtual machine image while the virtual machine is running. No attempt will be made to communicate with the device-mapper kernel driver, so this option is unable to report whether or not LVs are actually in use.

--reportformat basic|json

Overrides current output format for reports which is defined globally by the report/output_format setting in lvm.conf(5). basic is the original format with columns and rows. If there is more than one report per command, each report is prefixed with the report name for identification. json produces report output in JSON format. See lvmreport(7) for more information.

--rows

Output columns as rows.

-S|--select String

Select objects for processing and reporting based on specified criteria. The criteria syntax is described by --select help and lvmreport(7). For reporting commands, one row is displayed for each object matching the criteria. See --options help for selectable object fields. Rows can be displayed with an additional "selected" field (-o selected) showing 1 if the row matches the selection and 0 otherwise. For non-reporting commands which process LVM entities, the selection is used to choose items to process.

--separator String

String to use to separate each column. Useful if grepping the output.

--shared

Report/display shared VGs that would otherwise be skipped when lvmlockd is not being used on the host. See lvmlockd(8) for more information about shared VGs.

-O|--sort String

Comma-separated ordered list of columns to sort by. Replaces the default selection. Precede any column with - for a reverse sort on that column.

-t|--test

Run in test mode. Commands will not update metadata. This is implemented by disabling all metadata writing but nevertheless returning success to the calling function. This may lead to unusual error messages in multi-stage operations if a tool relies on reading back metadata it believes has changed but hasn't.

--unbuffered

Produce output immediately without sorting or aligning the columns properly.

--units [Number]r|R|h|H|b|B|s|S|k|K|m|M|g|G|t|T|p|P|e|E

All sizes are output in these units: human-(r)eadable with '<' rounding indicator, (h)uman-readable, (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, (g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. Capitalise to use multiples of 1000 (S.I.) instead of 1024. Custom units can be specified, e.g. --units 3M.

--unquoted

When used with --nameprefixes, output values in the field=value pairs are not quoted.

-v|--verbose ...

Set verbose level. Repeat from 1 to 4 times to increase the detail of messages sent to stdout and stderr.

--version

Display version information.

-y|--yes

Do not prompt for confirmation interactively but always assume the answer yes. Use with extreme caution. (For automatic no, see -qq.)

## VARIABLES
VG

Volume Group name. See lvm(8) for valid names.

Tag

Tag name. See lvm(8) for information about tag names and using tags in place of a VG, LV or PV.

String

See the option description for information about the string content.

Size[UNIT]

Size is an input number that accepts an optional unit. Input units are always treated as base two values, regardless of capitalization, e.g. 'k' and 'K' both refer to 1024. The default input unit is specified by letter, followed by |UNIT. UNIT represents other possible input units: b|B is bytes, s|S is sectors of 512 bytes, k|K is KiB, m|M is MiB, g|G is GiB, t|T is TiB, p|P is PiB, e|E is EiB. (This should not be confused with the output control --units, where capital letters mean multiple of 1000.)

## ENVIRONMENT VARIABLES
See lvm(8) for information about environment variables used by lvm. For example, LVM_VG_NAME can generally be substituted for a required VG parameter.

## NOTES
The vg_attr bits are:

1

Permissions: (w)riteable, (r)ead-only

2

Resi(z)eable

3

E(x)ported

4

(p)artial: one or more physical volumes belonging to the volume group are missing from the system

5

Allocation policy: (c)ontiguous, c(l)ing, (n)ormal, (a)nywhere

6

(c)lustered, (s)hared

## SEE ALSO
lvm(8), lvm.conf(5), lvmconfig(8), lvmdevices(8),

pvchange(8), pvck(8), pvcreate(8), pvdisplay(8), pvmove(8), pvremove(8), pvresize(8), pvs(8), pvscan(8),

vgcfgbackup(8), vgcfgrestore(8), vgchange(8), vgck(8), vgcreate(8), vgconvert(8), vgdisplay(8), vgexport(8), vgextend(8), vgimport(8), vgimportclone(8), vgimportdevices(8), vgmerge(8), vgmknodes(8), vgreduce(8), vgremove(8), vgrename(8), vgs(8), vgscan(8), vgsplit(8),

lvcreate(8), lvchange(8), lvconvert(8), lvdisplay(8), lvextend(8), lvreduce(8), lvremove(8), lvrename(8), lvresize(8), lvs(8), lvscan(8),

lvm-fullreport(8), lvm-lvpoll(8), blkdeactivate(8), lvmdump(8),

dmeventd(8), lvmpolld(8), lvmlockd(8), lvmlockctl(8), cmirrord(8), lvmdbusd(8), fsadm(8),

lvmsystemid(7), lvmreport(7), lvmraid(7), lvmthin(7), lvmcache(7)


vgscan

title: vgscan(8)

summary: Search for all volume groups

text:
# vgscan(8)

## NAME
vgscan — Search for all volume groups

## SYNOPSIS
vgscan

[ option_args ]

## DESCRIPTION
vgscan scans all supported LVM block devices in the system for VGs.

## USAGE
vgscan

[ --ignorelockingfailure ]

[ --mknodes ]

[ --notifydbus ]

[ --reportformat basic|json ]

[ COMMON_OPTIONS ]

Common options for lvm:

[ -d|--debug ]

[ -h|--help ]

[ -q|--quiet ]

[ -t|--test ]

[ -v|--verbose ]

[ -y|--yes ]

[ --commandprofile String ]

[ --config String ]

[ --devices PV ]

[ --devicesfile String ]

[ --driverloaded y|n ]

[ --journal String ]

[ --lockopt String ]

[ --longhelp ]

[ --nohints ]

[ --nolocking ]

[ --profile String ]

[ --version ]

## OPTIONS
--commandprofile String

The command profile to use for command configuration. See lvm.conf(5) for more information about profiles.

--config String

Config settings for the command. These override lvm.conf(5) settings. The String arg uses the same format as lvm.conf(5), or may use section/field syntax. See lvm.conf(5) for more information about config.

-d|--debug ...

Set debug level. Repeat from 1 to 6 times to increase the detail of messages sent to the log file and/or syslog (if configured).

--devices PV

Restricts the devices that are visible and accessible to the command. Devices not listed will appear to be missing. This option can be repeated, or accepts a comma separated list of devices. This overrides the devices file.

--devicesfile String

A file listing devices that LVM should use. The file must exist in /etc/lvm/devices/ and is managed with the lvmdevices(8) command. This overrides the lvm.conf(5) devices/devicesfile and devices/use_devicesfile settings.

--driverloaded y|n

If set to no, the command will not attempt to use device-mapper. For testing and debugging.

-h|--help

Display help text.

--ignorelockingfailure

Allows a command to continue with read-only metadata operations after locking failures.

--journal String

Record information in the systemd journal. This information is in addition to information enabled by the lvm.conf log/journal setting. command: record information about the command. output: record the default command output. debug: record full command debugging.

--lockopt String

Used to pass options for special cases to lvmlockd. See lvmlockd(8) for more information.

--longhelp

Display long help text.

--mknodes

Also checks the LVM special files in /dev that are needed for active LVs and creates any missing ones and removes unused ones.

--nohints

Do not use the hints file to locate devices for PVs. A command may read more devices to find PVs when hints are not used. The command will still perform standard hint file invalidation where appropriate.

--nolocking

Disable locking. Use with caution, concurrent commands may produce incorrect results.

--notifydbus

Send a notification to D-Bus. The command will exit with an error if LVM is not built with support for D-Bus notification, or if the notify_dbus config setting is disabled.

--profile String

An alias for --commandprofile or --metadataprofile, depending on the command.

-q|--quiet ...

Suppress output and log messages. Overrides --debug and --verbose. Repeat once to also suppress any prompts with answer 'no'.

--reportformat basic|json

Overrides current output format for reports which is defined globally by the report/output_format setting in lvm.conf(5). basic is the original format with columns and rows. If there is more than one report per command, each report is prefixed with the report name for identification. json produces report output in JSON format. See lvmreport(7) for more information.

-t|--test

Run in test mode. Commands will not update metadata. This is implemented by disabling all metadata writing but nevertheless returning success to the calling function. This may lead to unusual error messages in multi-stage operations if a tool relies on reading back metadata it believes has changed but hasn't.

-v|--verbose ...

Set verbose level. Repeat from 1 to 4 times to increase the detail of messages sent to stdout and stderr.

--version

Display version information.

-y|--yes

Do not prompt for confirmation interactively but always assume the answer yes. Use with extreme caution. (For automatic no, see -qq.)

## VARIABLES
String

See the option description for information about the string content.

Size[UNIT]

Size is an input number that accepts an optional unit. Input units are always treated as base two values, regardless of capitalization, e.g. 'k' and 'K' both refer to 1024. The default input unit is specified by letter, followed by |UNIT. UNIT represents other possible input units: b|B is bytes, s|S is sectors of 512 bytes, k|K is KiB, m|M is MiB, g|G is GiB, t|T is TiB, p|P is PiB, e|E is EiB. (This should not be confused with the output control --units, where capital letters mean multiple of 1000.)

## ENVIRONMENT VARIABLES
See lvm(8) for information about environment variables used by lvm. For example, LVM_VG_NAME can generally be substituted for a required VG parameter.

## SEE ALSO
lvm(8), lvm.conf(5), lvmconfig(8), lvmdevices(8),

pvchange(8), pvck(8), pvcreate(8), pvdisplay(8), pvmove(8), pvremove(8), pvresize(8), pvs(8), pvscan(8),

vgcfgbackup(8), vgcfgrestore(8), vgchange(8), vgck(8), vgcreate(8), vgconvert(8), vgdisplay(8), vgexport(8), vgextend(8), vgimport(8), vgimportclone(8), vgimportdevices(8), vgmerge(8), vgmknodes(8), vgreduce(8), vgremove(8), vgrename(8), vgs(8), vgscan(8), vgsplit(8),

lvcreate(8), lvchange(8), lvconvert(8), lvdisplay(8), lvextend(8), lvreduce(8), lvremove(8), lvrename(8), lvresize(8), lvs(8), lvscan(8),

lvm-fullreport(8), lvm-lvpoll(8), blkdeactivate(8), lvmdump(8),

dmeventd(8), lvmpolld(8), lvmlockd(8), lvmlockctl(8), cmirrord(8), lvmdbusd(8), fsadm(8),

lvmsystemid(7), lvmreport(7), lvmraid(7), lvmthin(7), lvmcache(7)


vgsplit

title: vgsplit(8)

text:
# vgsplit(8)

## NAME
vgsplit — Move physical volumes into a new or existing volume group

## SYNOPSIS
vgsplit option_args position_args

[ option_args ]

## DESCRIPTION
vgsplit moves one or more PVs from a source VG (the first VG arg) to a destination VG (the second VG arg). The PV(s) to move are named after the source and destination VGs, or an LV is named, in which case the PVs underlying the LV are moved.

If the destination VG does not exist, a new VG is created (command options can be used to specify properties of the new VG, also see vgcreate(8)).

LVs cannot be split between VGs; each LV must be entirely on the PVs in the source or destination VG.

vgsplit can only move complete PVs. (See pvmove(8) for moving part of a PV.)

## USAGE
Split a VG by specified PVs.

vgsplit VG VG PV ...

[ COMMON_OPTIONS ]

Split a VG by PVs in a specified LV.

vgsplit -n|--name LV VG VG

[ COMMON_OPTIONS ]

Common options for command:

[ -A|--autobackup y|n ]

[ -l|--maxlogicalvolumes Number ]

[ -p|--maxphysicalvolumes Number ]

[ -M|--metadatatype lvm2 ]

[ --alloc contiguous|cling|cling_by_tags|normal|anywhere|inherit ]

[ --poolmetadataspare y|n ]

[ --[vg]metadatacopies all|unmanaged|Number ]

Common options for lvm:

[ -d|--debug ]

[ -h|--help ]

[ -q|--quiet ]

[ -t|--test ]

[ -v|--verbose ]

[ -y|--yes ]

[ --commandprofile String ]

[ --config String ]

[ --devices PV ]

[ --devicesfile String ]

[ --driverloaded y|n ]

[ --journal String ]

[ --lockopt String ]

[ --longhelp ]

[ --nohints ]

[ --nolocking ]

[ --profile String ]

[ --version ]

## OPTIONS
--alloc contiguous|cling|cling_by_tags|normal|anywhere|inherit

Determines the allocation policy when a command needs to allocate Physical Extents (PEs) from the VG. Each VG and LV has an allocation policy which can be changed with vgchange/lvchange, or overridden on the command line. normal applies common sense rules such as not placing parallel stripes on the same PV. inherit applies the VG policy to an LV. contiguous requires new PEs be placed adjacent to existing PEs. cling places new PEs on the same PV as existing PEs in the same stripe of the LV. If there are sufficient PEs for an allocation, but normal does not use them, anywhere will use them even if it reduces performance, e.g. by placing two stripes on the same PV. Optional positional PV args on the command line can also be used to limit which PVs the command will use for allocation. See lvm(8) for more information about allocation.

-A|--autobackup y|n

Specifies if metadata should be backed up automatically after a change. Enabling this is strongly advised! See vgcfgbackup(8) for more information.

--commandprofile String

The command profile to use for command configuration. See lvm.conf(5) for more information about profiles.

--config String

Config settings for the command. These override lvm.conf(5) settings. The String arg uses the same format as lvm.conf(5), or may use section/field syntax. See lvm.conf(5) for more information about config.

-d|--debug ...

Set debug level. Repeat from 1 to 6 times to increase the detail of messages sent to the log file and/or syslog (if configured).

--devices PV

Restricts the devices that are visible and accessible to the command. Devices not listed will appear to be missing. This option can be repeated, or accepts a comma separated list of devices. This overrides the devices file.

--devicesfile String

A file listing devices that LVM should use. The file must exist in /etc/lvm/devices/ and is managed with the lvmdevices(8) command. This overrides the lvm.conf(5) devices/devicesfile and devices/use_devicesfile settings.

--driverloaded y|n

If set to no, the command will not attempt to use device-mapper. For testing and debugging.

-h|--help

Display help text.

--journal String

Record information in the systemd journal. This information is in addition to information enabled by the lvm.conf log/journal setting. command: record information about the command. output: record the default command output. debug: record full command debugging.

--lockopt String

Used to pass options for special cases to lvmlockd. See lvmlockd(8) for more information.

--longhelp

Display long help text.

-l|--maxlogicalvolumes Number

Sets the maximum number of LVs allowed in a VG.

-p|--maxphysicalvolumes Number

Sets the maximum number of PVs that can belong to the VG. The value 0 removes any limitation. For large numbers of PVs, also see options --pvmetadatacopies, and --vgmetadatacopies for improving performance.

-M|--metadatatype lvm2

Specifies the type of on-disk metadata to use. lvm2 (or just 2) is the current, standard format. lvm1 (or just 1) is no longer used.

-n|--name String

Move only PVs used by the named LV.

--nohints

Do not use the hints file to locate devices for PVs. A command may read more devices to find PVs when hints are not used. The command will still perform standard hint file invalidation where appropriate.

--nolocking

Disable locking. Use with caution, concurrent commands may produce incorrect results.

--poolmetadataspare y|n

Enable or disable the automatic creation and management of a spare pool metadata LV in the VG. A spare metadata LV is reserved space that can be used when repairing a pool.

--profile String

An alias for --commandprofile or --metadataprofile, depending on the command.

-q|--quiet ...

Suppress output and log messages. Overrides --debug and --verbose. Repeat once to also suppress any prompts with answer 'no'.

-t|--test

Run in test mode. Commands will not update metadata. This is implemented by disabling all metadata writing but nevertheless returning success to the calling function. This may lead to unusual error messages in multi-stage operations if a tool relies on reading back metadata it believes has changed but hasn't.

-v|--verbose ...

Set verbose level. Repeat from 1 to 4 times to increase the detail of messages sent to stdout and stderr.

--version

Display version information.

--[vg]metadatacopies all|unmanaged|Number

Number of copies of the VG metadata that are kept. VG metadata is kept in VG metadata areas on PVs in the VG, i.e. reserved space at the start and/or end of the PVs. Keeping a copy of the VG metadata on every PV can reduce performance in VGs containing a large number of PVs. When this number is set to a non-zero value, LVM will automatically choose PVs on which to store metadata, using the metadataignore flags on PVs to achieve the specified number. The number can also be replaced with special string values: unmanaged causes LVM to not automatically manage the PV metadataignore flags. all causes LVM to first clear the metadataignore flags on all PVs, and then to become unmanaged.

-y|--yes

Do not prompt for confirmation interactively but always assume the answer yes. Use with extreme caution. (For automatic no, see -qq.)

## VARIABLES
VG

Volume Group name. See lvm(8) for valid names.

PV

Physical Volume name, a device path under /dev. For commands managing physical extents, a PV positional arg generally accepts a suffix indicating a range (or multiple ranges) of physical extents (PEs). When the first PE is omitted, it defaults to the start of the device, and when the last PE is omitted it defaults to end. Start and end range (inclusive): PV[:PE-PE]... Start and length range (counting from 0): PV[:PE+PE]...

String

See the option description for information about the string content.

Size[UNIT]

Size is an input number that accepts an optional unit. Input units are always treated as base two values, regardless of capitalization, e.g. 'k' and 'K' both refer to 1024. The default input unit is specified by letter, followed by |UNIT. UNIT represents other possible input units: b|B is bytes, s|S is sectors of 512 bytes, k|K is KiB, m|M is MiB, g|G is GiB, t|T is TiB, p|P is PiB, e|E is EiB. (This should not be confused with the output control --units, where capital letters mean multiple of 1000.)

## ENVIRONMENT VARIABLES
See lvm(8) for information about environment variables used by lvm. For example, LVM_VG_NAME can generally be substituted for a required VG parameter.

## SEE ALSO
lvm(8), lvm.conf(5), lvmconfig(8), lvmdevices(8),

pvchange(8), pvck(8), pvcreate(8), pvdisplay(8), pvmove(8), pvremove(8), pvresize(8), pvs(8), pvscan(8),

vgcfgbackup(8), vgcfgrestore(8), vgchange(8), vgck(8), vgcreate(8), vgconvert(8), vgdisplay(8), vgexport(8), vgextend(8), vgimport(8), vgimportclone(8), vgimportdevices(8), vgmerge(8), vgmknodes(8), vgreduce(8), vgremove(8), vgrename(8), vgs(8), vgscan(8), vgsplit(8),

lvcreate(8), lvchange(8), lvconvert(8), lvdisplay(8), lvextend(8), lvreduce(8), lvremove(8), lvrename(8), lvresize(8), lvs(8), lvscan(8),

lvm-fullreport(8), lvm-lvpoll(8), blkdeactivate(8), lvmdump(8),

dmeventd(8), lvmpolld(8), lvmlockd(8), lvmlockctl(8), cmirrord(8), lvmdbusd(8), fsadm(8),

lvmsystemid(7), lvmreport(7), lvmraid(7), lvmthin(7), lvmcache(7)


cmirrord

title: cmirrord(8)

summary: cluster mirror log daemon

text:
# cmirrord(8)

## NAME
cmirrord — cluster mirror log daemon

## SYNOPSIS
cmirrord [-f|--foreground] [-h|--help]

## DESCRIPTION
cmirrord is the daemon that tracks mirror log information in a cluster. It is specific to device-mapper based mirrors (and by extension, LVM cluster mirrors). Cluster mirrors are not possible without this daemon running.

This daemon relies on the cluster infrastructure provided by the corosync, which must be set up and running in order for cmirrord to function.

Output is logged via syslog(3). The SIGUSR1 signal(7) can be issued to cmirrord to gather current status information for debugging purposes.

Once started, cmirrord will run until it is shutdown via SIGINT signal. If there are still active cluster mirrors, however, the signal will be ignored. Active cluster mirrors should be shutdown before stopping the cluster mirror log daemon.

## OPTIONS
-f|--foreground

Do not fork and log to the terminal.

-h|--help

Print usage.

## SEE ALSO
lvmlockd(8), lvm(8), syslog(3), signal(7)


lvmlockd

title: lvmlockd(8)

summary: LVM locking daemon

text:
# lvmlockd(8)

## NAME
lvmlockd — LVM locking daemon

## SYNOPSIS
lvmlockd [options]

## DESCRIPTION
LVM commands use lvmlockd to coordinate access to shared storage.

When LVM is used on devices shared by multiple hosts, locks will:

• coordinate reading and writing of LVM metadata

• validate caching of LVM metadata

• prevent conflicting activation of logical volumes

lvmlockd uses an external lock manager to perform basic locking.

Lock manager (lock type) options are:

• sanlock: places locks on disk within LVM storage.

• dlm: uses network communication and a cluster manager.

## OPTIONS
-h|--help

Show this help information.

-V|--version

Show version of lvmlockd.

-T|--test

Test mode, do not call lock manager.

-f|--foreground

Don't fork.

-D|--daemon-debug

Don't fork and print debugging to stdout.

-p|--pid-file path

Set path to the pid file.

-s|--socket-path path

Set path to the socket to listen on.

--adopt-file path

Set path to the adopt file.

-S|--syslog-priority err|warning|debug

Write log messages from this level up to syslog.

-g|--gl-type sanlock|dlm

Set global lock type to be sanlock or dlm.

-i|--host-id num

Set the local sanlock host id.

-F|--host-id-file path

A file containing the local sanlock host_id.

-o|--sanlock-timeout seconds

Override the default sanlock I/O timeout.

-A|--adopt 0|1

Enable (1) or disable (0) lock adoption.

## USAGE

### Initial set up
Setting up LVM to use lvmlockd and a shared VG for the first time includes some one time set up steps:

### 1. choose a lock manager
dlm

If dlm (or corosync) are already being used by other cluster software, then select dlm. dlm uses corosync which requires additional configuration beyond the scope of this document. See corosync and dlm documentation for instructions on configuration, set up and usage.

sanlock

Choose sanlock if dlm/corosync are not otherwise required. sanlock does not depend on any clustering software or configuration.

### 2. configure hosts to use lvmlockd
On all hosts running lvmlockd, configure lvm.conf:

```
use_lvmlockd = 1
```

sanlock

Assign each host a unique host_id in the range 1-2000 by setting

/etc/lvm/lvmlocal.conf local/host_id

### 3. start lvmlockd
Start the lvmlockd daemon.

Use systemctl, a cluster resource agent, or run directly, e.g.

systemctl start lvmlockd

### 4. start lock manager
sanlock

Start the sanlock and wdmd daemons.

Use systemctl or run directly, e.g.

systemctl start wdmd sanlock

dlm

Start the dlm and corosync daemons.

Use systemctl, a cluster resource agent, or run directly, e.g.

systemctl start corosync dlm

### 5. create VG on shared devices
vgcreate --shared <vgname> <devices>

The shared option sets the VG lock type to sanlock or dlm depending on which lock manager is running. LVM commands acquire locks from lvmlockd, and lvmlockd uses the chosen lock manager.

### 6. start VG on all hosts
vgchange --lock-start

Shared VGs must be started before they are used. Starting the VG performs lock manager initialization that is necessary to begin using locks (i.e. creating and joining a lockspace). Starting the VG may take some time, and until the start completes the VG may not be modified or activated.

### 7. create and activate LVs
Standard lvcreate and lvchange commands are used to create and activate LVs in a shared VG.

An LV activated exclusively on one host cannot be activated on another. When multiple hosts need to use the same LV concurrently, the LV can be activated with a shared lock (see lvchange options -aey vs -asy.) (Shared locks are disallowed for certain LV types that cannot be used from multiple hosts.)

### Normal start up and shut down
After initial set up, start up and shut down include the following steps. They can be performed directly or may be automated using systemd or a cluster resource manager/agents.

• start lvmlockd

• start lock manager

• vgchange --lock-start

• activate LVs in shared VGs

The shut down sequence is the reverse:

• deactivate LVs in shared VGs

• vgchange --lock-stop

• stop lock manager

• stop lvmlockd

## TOPICS

### Protecting VGs on shared devices
The following terms are used to describe the different ways of accessing VGs on shared devices.

shared VG

A shared VG exists on shared storage that is visible to multiple hosts. LVM acquires locks through lvmlockd to coordinate access to shared VGs. A shared VG has lock_type "dlm" or "sanlock", which specifies the lock manager lvmlockd will use.

When the lock manager for the lock type is not available (e.g. not started or failed), lvmlockd is unable to acquire locks for LVM commands. In this situation, LVM commands are only allowed to read and display the VG; changes and activation will fail.

local VG

A local VG is meant to be used by a single host. It has no lock type or lock type "none". A local VG typically exists on local (non-shared) devices and cannot be used concurrently from different hosts.

If a local VG does exist on shared devices, it should be owned by a single host by having the system ID set, see lvmsystemid(7). The host with a matching system ID can use the local VG and other hosts will ignore it. A VG with no lock type and no system ID should be excluded from all but one host using lvm.conf filters. Without any of these protections, a local VG on shared devices can be easily damaged or destroyed.

clvm VG

A clvm VG (or clustered VG) is a VG on shared storage (like a shared VG) that requires clvmd for clustering and locking. See below for converting a clvm/clustered VG to a shared VG.

### Shared VGs from hosts not using lvmlockd
Hosts that do not use shared VGs will not be running lvmlockd. In this case, shared VGs that are still visible to the host will be ignored (like foreign VGs, see lvmsystemid(7)).

The --shared option for reporting and display commands causes shared VGs to be displayed on a host not using lvmlockd, like the --foreign option does for foreign VGs.

### Creating the first sanlock VG
When use_lvmlockd is first enabled in lvm.conf, and before the first sanlock VG is created, no global lock will exist. In this initial state, LVM commands try and fail to acquire the global lock, producing a warning, and some commands are disallowed. Once the first sanlock VG is created, the global lock will be available, and LVM will be fully operational.

When a new sanlock VG is created, its lockspace is automatically started on the host that creates it. Other hosts need to run 'vgchange --lock-start' to start the new VG before they can use it.

Creating the first sanlock VG is not protected by locking, so it requires special attention. This is because sanlock locks exist on storage within the VG, so they are not available until after the VG is created. The first sanlock VG that is created will automatically contain the "global lock". Be aware of the following special considerations:

•

The first vgcreate command needs to be given the path to a device that has not yet been initialized with pvcreate. The pvcreate initialization will be done by vgcreate. This is because the pvcreate command requires the global lock, which will not be available until after the first sanlock VG is created.

•

Because the first sanlock VG will contain the global lock, this VG needs to be accessible to all hosts that will use sanlock shared VGs. All hosts will need to use the global lock from the first sanlock VG.

•

The device and VG name used by the initial vgcreate will not be protected from concurrent use by another vgcreate on another host.

See below for more information about managing the sanlock global lock.

### Using shared VGs
In the 'vgs' command, shared VGs are indicated by "s" (for shared) in the sixth attr field, and by "shared" in the "--options shared" report field. The specific lock type and lock args for a shared VG can be displayed with 'vgs -o+locktype,lockargs'.

Shared VGs need to be "started" and "stopped", unlike other types of VGs. See the following section for a full description of starting and stopping.

Removing a shared VG will fail if other hosts have the VG started. Run vgchange --lock-stop <vgname> on all other hosts before vgremove. (It may take several seconds before vgremove recognizes that all hosts have stopped a sanlock VG.)

### Starting and stopping VGs
Starting a shared VG (vgchange --lock-start) causes the lock manager to start (join) the lockspace for the VG on the host where it is run. This makes locks for the VG available to LVM commands on the host. Before a VG is started, only LVM commands that read/display the VG are allowed to continue without locks (and with a warning).

Stopping a shared VG (vgchange --lock-stop) causes the lock manager to stop (leave) the lockspace for the VG on the host where it is run. This makes locks for the VG inaccessible to the host. A VG cannot be stopped while it has active LVs.

When using the lock type sanlock, starting a VG can take a long time (potentially minutes if the host was previously shut down without cleanly stopping the VG.)

A shared VG can be started after all the following are true:

• lvmlockd is running

• the lock manager is running

• the VG's devices are visible on the system

A shared VG can be stopped if all LVs are deactivated.

All shared VGs can be started/stopped using:

vgchange --lock-start

vgchange --lock-stop

Individual VGs can be started/stopped using:

vgchange --lock-start <vgname> ...

vgchange --lock-stop <vgname> ...

To make vgchange not wait for start to complete:

vgchange --lock-start --lock-opt nowait ...

lvmlockd can be asked directly to stop all lockspaces:

lvmlockctl -S|--stop-lockspaces

To start only selected shared VGs, use the lvm.conf activation/lock_start_list. When defined, only VG names in this list are started by vgchange. If the list is not defined (the default), all visible shared VGs are started. To start only "vg1", use the following lvm.conf configuration:

```
activation {

    lock_start_list = [ "vg1" ]

    ...
}
```

### Internal command locking
To optimize the use of LVM with lvmlockd, be aware of the three kinds of locks and when they are used:

Global lock

The global lock is associated with global information, which is information not isolated to a single VG. This includes:

• The global VG namespace.

• The set of orphan PVs and unused devices.

• The properties of orphan PVs, e.g. PV size.

The global lock is acquired in shared mode by commands that read this information, or in exclusive mode by commands that change it. For example, the command 'vgs' acquires the global lock in shared mode because it reports the list of all VG names, and the vgcreate command acquires the global lock in exclusive mode because it creates a new VG name, and it takes a PV from the list of unused PVs.

When an LVM command is given a tag argument, or uses select, it must read all VGs to match the tag or selection, which causes the global lock to be acquired.

VG lock

A VG lock is associated with each shared VG. The VG lock is acquired in shared mode to read the VG and in exclusive mode to change the VG or activate LVs. This lock serializes access to a VG with all other LVM commands accessing the VG from all hosts.

The command 'vgs <vgname>' does not acquire the global lock (it does not need the list of all VG names), but will acquire the VG lock on each VG name argument.

LV lock

An LV lock is acquired before the LV is activated, and is released after the LV is deactivated. If the LV lock cannot be acquired, the LV is not activated. (LV locks are persistent and remain in place when the activation command is done. Global and VG locks are transient, and are held only while an LVM command is running.)

lock retries

If a request for a global or VG lock fails due to a lock conflict with another host, lvmlockd automatically retries for a short time before returning a failure to the LVM command. If those retries are insufficient, the LVM command will retry the entire lock request a number of times specified by global/lvmlockd_lock_retries before failing. If a request for an LV lock fails due to a lock conflict, the command fails immediately.

### Managing the global lock in sanlock VGs
The global lock exists in one of the sanlock VGs. The first sanlock VG created will contain the global lock. Subsequent sanlock VGs will each contain a disabled global lock that can be enabled later if necessary.

The VG containing the global lock must be visible to all hosts using sanlock VGs. For this reason, it can be useful to create a small sanlock VG, visible to all hosts, and dedicated to just holding the global lock. While not required, this strategy can help to avoid difficulty in the future if VGs are moved or removed.

The vgcreate command typically acquires the global lock, but in the case of the first sanlock VG, there will be no global lock to acquire until the first vgcreate is complete. So, creating the first sanlock VG is a special case that skips the global lock.

vgcreate determines that it's creating the first sanlock VG when no other sanlock VGs are visible on the system. It is possible that other sanlock VGs do exist, but are not visible when vgcreate checks for them. In this case, vgcreate will create a new sanlock VG with the global lock enabled. When the another VG containing a global lock appears, lvmlockd will then see more than one VG with a global lock enabled. LVM commands will report that there are duplicate global locks.

If the situation arises where more than one sanlock VG contains a global lock, the global lock should be manually disabled in all but one of them with the command:

lvmlockctl --gl-disable <vgname>

(The one VG with the global lock enabled must be visible to all hosts.)

An opposite problem can occur if the VG holding the global lock is removed. In this case, no global lock will exist following the vgremove, and subsequent LVM commands will fail to acquire it. In this case, the global lock needs to be manually enabled in one of the remaining sanlock VGs with the command:

lvmlockctl --gl-enable <vgname>

(Using a small sanlock VG dedicated to holding the global lock can avoid the case where the global lock must be manually enabled after a vgremove.)

### Internal lvmlock LV
A sanlock VG contains a hidden LV called "lvmlock" that holds the sanlock locks. vgreduce cannot yet remove the PV holding the lvmlock LV. To remove this PV, change the VG lock type to "none", run vgreduce, then change the VG lock type back to "sanlock". Similarly, pvmove cannot be used on a PV used by the lvmlock LV.

To place the lvmlock LV on a specific device, create the VG with only that device, then use vgextend to add other devices.

### LV activation
In a shared VG, LV activation involves locking through lvmlockd, and the following values are possible with lvchange/vgchange -a:

y|ey

The command activates the LV in exclusive mode, allowing a single host to activate the LV. Before activating the LV, the command uses lvmlockd to acquire an exclusive lock on the LV. If the lock cannot be acquired, the LV is not activated and an error is reported. This would happen if the LV is active on another host.

sy

The command activates the LV in shared mode, allowing multiple hosts to activate the LV concurrently. Before activating the LV, the command uses lvmlockd to acquire a shared lock on the LV. If the lock cannot be acquired, the LV is not activated and an error is reported. This would happen if the LV is active exclusively on another host. If the LV type prohibits shared access, such as a snapshot, the command will report an error and fail. The shared mode is intended for a multi-host/cluster application or file system. LV types that cannot be used concurrently from multiple hosts include thin, cache, raid, mirror, and snapshot.

n

The command deactivates the LV. After deactivating the LV, the command uses lvmlockd to release the current lock on the LV.

### Manually repairing a shared VG
Some failure conditions may not be repairable while the VG has a shared lock type. In these cases, it may be possible to repair the VG by forcibly changing the lock type to "none". This is done by adding "--lock-opt force" to the normal command for changing the lock type: vgchange --lock-type none VG. The VG lockspace should first be stopped on all hosts, and be certain that no hosts are using the VG before this is done.

### Recover from lost PV holding sanlock locks
In a sanlock VG, the sanlock locks are held on the hidden "lvmlock" LV. If the PV holding this LV is lost, a new lvmlock LV needs to be created. To do this, ensure no hosts are using the VG, then forcibly change the lock type to "none" (see above). Then change the lock type back to "sanlock" with the normal command for changing the lock type: vgchange --lock-type sanlock VG. This recreates the internal lvmlock LV with the necessary locks.

### Locking system failures
lvmlockd failure

If lvmlockd fails or is killed while holding locks, the locks are orphaned in the lock manager. Orphaned locks must be cleared or adopted before the associated resources can be accessed normally. If lock adoption is enabled, lvmlockd keeps a record of locks in the adopt-file. A subsequent instance of lvmlockd will then adopt locks orphaned by the previous instance. Adoption must be enabled in both instances (--adopt|-A 1). Without adoption, the lock manager or host would require a reset to clear orphaned lock state.

dlm/corosync failure

If dlm or corosync fail, the clustering system will fence the host using a method configured within the dlm/corosync clustering environment.

LVM commands on other hosts will be blocked from acquiring any locks until the dlm/corosync recovery process is complete.

sanlock lease storage failure

If the PV under a sanlock VG's lvmlock LV is disconnected, unresponsive or too slow, sanlock cannot renew the lease for the VG's locks. After some time, the lease will expire, and locks that the host owns in the VG can be acquired by other hosts. The VG must be forcibly deactivated on the host with the expiring lease before other hosts can acquire its locks. This is necessary for data protection.

When the sanlock daemon detects that VG storage is lost and the VG lease is expiring, it runs the command lvmlockctl --kill <vgname>. This command emits a syslog message stating that storage is lost for the VG, and that LVs in the VG must be immediately deactivated.

If no LVs are active in the VG, then the VG lockspace will be removed, and errors will be reported when trying to use the VG. Use the lvmlockctl --drop command to clear the stale lockspace from lvmlockd.

If the VG has active LVs, they must be quickly deactivated before the locks expire. After all LVs are deactivated, run lvmlockctl --drop <vgname> to clear the expiring lockspace from lvmlockd.

If all LVs in the VG are not deactivated within about 40 seconds, sanlock uses wdmd and the local watchdog to reset the host. The machine reset is effectively a severe form of "deactivating" LVs before they can be activated on other hosts. The reset is considered a better alternative than having LVs used by multiple hosts at once, which could easily damage or destroy their content.

sanlock lease storage failure automation

When the sanlock daemon detects that the lease storage is lost, it runs the command lvmlockctl --kill <vgname>. This lvmlockctl command can be configured to run another command to forcibly deactivate LVs, taking the place of the manual process described above. The other command is configured in the lvm.conf lvmlockctl_kill_command setting. The VG name is appended to the end of the command specified.

The lvmlockctl_kill_command should forcibly deactivate LVs in the VG, ensuring that existing writes to LVs in the VG are complete and that further writes to the LVs in the VG will be rejected. If it is able to do this successfully, it should exit with success, otherwise it should exit with an error. If lvmlockctl --kill gets a successful result from lvmlockctl_kill_command, it tells lvmlockd to drop locks for the VG (the equivalent of running lvmlockctl --drop). If this completes in time, a machine reset can be avoided.

One possible option is to create a script my_vg_kill_script.sh:

```
  #!/bin/bash

  VG=$1

  # replace dm table with the error target for top level LVs

  dmsetup wipe_table -S "uuid=~LVM && vgname=$VG && lv_layer=\"\""

  # check that the error target is in place

  dmsetup table -c -S "uuid=~LVM && vgname=$VG && lv_layer=\"\"" |grep -vw error

  if [[ $? -ne 0 ]] ; then

    exit 0

  fi

  exit 1
```

Set in lvm.conf:

```
  lvmlockctl_kill_command="/usr/sbin/my_vg_kill_script.sh"
```

(The script and dmsetup commands should be tested with the actual VG to ensure that all top level LVs are properly disabled.)

If the lvmlockctl_kill_command is not configured, or fails, lvmlockctl --kill will emit syslog messages as described in the previous section, notifying the user to manually deactivate the VG before sanlock resets the machine.

sanlock daemon failure

If the sanlock daemon fails or exits while a lockspace is started, the local watchdog will reset the host. This is necessary to protect any application resources that depend on sanlock leases.

### Changing dlm cluster name
When a dlm VG is created, the cluster name is saved in the VG metadata. To use the VG, a host must be in the named dlm cluster. If the dlm cluster name changes, or the VG is moved to a new cluster, the dlm cluster name saved in the VG must also be changed.

To see the dlm cluster name saved in the VG, use the command:

vgs -o+locktype,lockargs <vgname>

To change the dlm cluster name in the VG when the VG is still used by the original cluster:

•

Start the VG on the host changing the lock type

vgchange --lock-start <vgname>

•

Stop the VG on all other hosts:

vgchange --lock-stop <vgname>

•

Change the VG lock type to none on the host where the VG is started:

vgchange --lock-type none <vgname>

•

Change the dlm cluster name on the hosts or move the VG to the new cluster. The new dlm cluster must now be running on the host. Verify the new name by:

cat /sys/kernel/config/dlm/cluster/cluster_name

•

Change the VG lock type back to dlm which sets the new cluster name:

vgchange --lock-type dlm <vgname>

•

Start the VG on hosts to use it:

vgchange --lock-start <vgname>

To change the dlm cluster name in the VG when the dlm cluster name has already been changed on the hosts, or the VG has already moved to a different cluster:

•

Ensure the VG is not being used by any hosts.

•

The new dlm cluster must be running on the host making the change. The current dlm cluster name can be seen by:

cat /sys/kernel/config/dlm/cluster/cluster_name

•

Change the VG lock type to none:

vgchange --lock-type none --lock-opt force <vgname>

•

Change the VG lock type back to dlm which sets the new cluster name:

vgchange --lock-type dlm <vgname>

•

Start the VG on hosts to use it:

vgchange --lock-start <vgname>

### Changing a local VG to a shared VG
All LVs must be inactive to change the lock type.

lvmlockd must be configured and running as described in USAGE.

•

Change a local VG to a shared VG with the command:

vgchange --lock-type sanlock|dlm <vgname>

•

Start the VG on hosts to use it:

vgchange --lock-start <vgname>

### Changing a shared VG to a local VG
All LVs must be inactive to change the lock type.

•

Start the VG on the host making the change:

vgchange --lock-start <vgname>

•

Stop the VG on all other hosts:

vgchange --lock-stop <vgname>

•

Change the VG lock type to none on the host where the VG is started:

vgchange --lock-type none <vgname>

If the VG cannot be started with the previous lock type, then the lock type can be forcibly changed to none with:

vgchange --lock-type none --lock-opt force <vgname>

To change a VG from one lock type to another (i.e. between sanlock and dlm), first change it to a local VG, then to the new type.

### Changing a clvm/clustered VG to a shared VG
All LVs must be inactive to change the lock type.

First change the clvm/clustered VG to a local VG. Within a running clvm cluster, change a clustered VG to a local VG with the command:

vgchange -cn <vgname>

If the clvm cluster is no longer running on any nodes, then extra options can be used to forcibly make the VG local. Caution: this is only safe if all nodes have stopped using the VG:

vgchange --lock-type none --lock-opt force <vgname>

After the VG is local, follow the steps described in "changing a local VG to a shared VG".

### Extending an LV active on multiple hosts
With lvmlockd and dlm, a special clustering procedure is used to refresh a shared LV on remote cluster nodes after it has been extended on one node.

When an LV holding gfs2 or ocfs2 is active on multiple hosts with a shared lock, lvextend is permitted to run with an existing shared LV lock in place of the normal exclusive LV lock.

After lvextend has finished extending the LV, it sends a remote request to other nodes running the dlm to run 'lvchange --refresh' on the LV. This uses dlm_controld and corosync features.

Some special --lockopt values can be used to modify this process. "shupdate" permits the lvextend update with an existing shared lock if it isn't otherwise permitted. "norefresh" prevents the remote refresh operation.

### Limitations of shared VGs
Things that do not yet work in shared VGs:

• using external origins for thin LVs

• splitting snapshots from LVs

• splitting mirrors in sanlock VGs

• pvmove of entire PVs, or under LVs activated with shared locks

• vgsplit and vgmerge (convert to a local VG to do this)

### lvmlockd changes from clvmd
(See above for converting an existing clvm VG to a shared VG.)

While lvmlockd and clvmd are entirely different systems, LVM command usage remains similar. Differences are more notable when using lvmlockd's sanlock option.

Visible usage differences between shared VGs (using lvmlockd) and clvm/clustered VGs (using clvmd):

•

lvm.conf is configured to use lvmlockd by setting use_lvmlockd=1. clvmd used locking_type=3.

•

vgcreate --shared creates a shared VG. vgcreate --clustered y created a clvm/clustered VG.

•

lvmlockd adds the option of using sanlock for locking, avoiding the need for network clustering.

•

lvmlockd defaults to the exclusive activation mode whenever the activation mode is unspecified, i.e. -ay means -aey, not -asy.

•

lvmlockd commands always apply to the local host, and never have an effect on a remote host. (The activation option 'l' is not used.)

•

lvmlockd saves the cluster name for a shared VG using dlm. Only hosts in the matching cluster can use the VG.

•

lvmlockd requires starting/stopping shared VGs with vgchange --lock-start and --lock-stop.

•

vgremove of a sanlock VG may fail indicating that all hosts have not stopped the VG lockspace. Stop the VG on all hosts using vgchange --lock-stop.

•

vgreduce or pvmove of a PV in a sanlock VG will fail if it holds the internal "lvmlock" LV that holds the sanlock locks.

•

lvmlockd uses lock retries instead of lock queueing, so high lock contention may require increasing global/lvmlockd_lock_retries to avoid transient lock failures.

•

lvmlockd includes VG reporting options lock_type and lock_args, and LV reporting option lock_args to view the corresponding metadata fields.

•

In the 'vgs' command's sixth VG attr field, "s" for "shared" is displayed for shared VGs.

•

If lvmlockd fails or is killed while in use, locks it held remain but are orphaned in the lock manager. lvmlockd can be restarted with an option to adopt the orphan locks from the previous instance of lvmlockd.

## SEE ALSO
lvm(8), lvmlockctl(8)


lynis

package: lynis

title: lynis(8)

summary: System and security auditing tool

text:
# lynis(8)

## NAME
Lynis - System and security auditing tool

## SYNOPSIS

```
lynis [scan mode] [other options]
```

## DESCRIPTION
Lynis is a security auditing tool for Linux, macOS, and other systems based on UNIX. The tool checks the system and the software configuration, to see if there is any room for improvement the security defenses. All details are stored in a log file. Findings and other discovered data is stored in a report file. This can be used to compare differences between audits. Lynis can run interactively or as a cronjob. Root permissions (e.g. sudo) are not required, however provide more details during the audit.

The following system areas may be checked:

- Boot loader files

- Configuration files

- Software packages

- Directories and files related to logging and auditing

## FIRST TIME USAGE
When running Lynis for the first time, run: lynis audit system

## COMMANDS
audit <type>

Perform an audit of the selected type

upload-only

Upload the available report data file See HELPERS section for more commands.

## SCAN TYPES
audit system

Performs a system audit, which is the most common audit.

audit system remote <host>

Provide commands to do a remote scan.

For more scan modes, see the helper utilities.

## OPTIONS
--auditor <name>

Define the name of the auditor/pentester. When a full name is used, add double quotes, like "Your Name".

--cronjob

Perform automatic scan with cron safe options (no colors, no questions, no breaks).

--debug

Display debug information to screen for troubleshooting purposes.

--developer

Display detailed information useful for developers when creating tests.

--forensics

Perform the audit on a running or mounted system (see --rootdir)

--help

Show available commands and most-used options.

--logfile </path/to/logfile>

Defines location and name of log file, instead of default /var/log/lynis.log.

--man

Show the man page. Useful for systems that do not have the man page installed.

--no-colors

Disable colored output.

--no-log

Redirect all logging information to /dev/null, prevents sensitive information to be written to disk.

--no-plugins

Do not run any of the enabled plugins.

--pentest

Run a non-privileged scan, usually used for penetration testing. Some of the tests will be skipped if they require root permissions.

--plugin-dir </path/to/plugins>

Define location where plugins can be found.

--profile <file>

Provide alternative profile to perform the scan.

--quick (-Q)

Do a quick scan (default: don't wait for user input).

--quiet (-q)

Run quietly and do not show anything to the screen. Will also enable quick mode.

--report-file <file>

Provide an alternative name for report file.

--reverse-colors

Optimize screen output for light backgrounds.

--tests TEST-IDs

Only run the specific test(s). When using multiple tests, add quotes around the line.

--tests-from-category <category>

Tests are only performed if they belong to the defined category. Use the command 'show categories' to determine all valid options.

--tests-from-group <group>

Similar to --tests-from-category. Only perform tests from a particular group. Use 'show groups' to determine valid options.

--use-cwd

Run from the current working directory.

--upload

Upload data to Lynis Enterprise server (profile option: upload=yes).

--verbose

Show more details on screen, such as components that could not found. These details are hidden by default.

--wait

Wait for user to continue. This adds a break after each section (opposed of --quick).

--warnings-only

Run quietly, except show warnings.

Multiple parameters are allowed, though some parameters can only be used together with others. When running Lynis without any parameters, help will be shown and the program will exit.

## HELPERS
Lynis has special helpers to do certain tasks. This way the framework of Lynis is used, while at the same time storing most of the functionality in a separated file. This speeds up execution and keeps the code clean.

audit

Run audit on the system or on other targets

configure <parameter>

Change or add settings to the config file

generate <parameter>

Generate specific details such as host IDs

show <parameter>

Show information, such as configuration and paths

update <parameter>

Perform activities regarding updating

To use a helper, run 'lynis' followed by the helper name.

## EXIT CODES
Lynis uses exit codes to signal any invoking script. Currently the following codes are used:

0

Program exited normally

1

Fatal error

64

An unknown parameter is used, or incomplete

65

Incorrect data encountered

66

Can't open file or directory

78

Lynis found 1 or more warnings or configurations errors (with error-on-warnings=yes)

## BUGS
Bugs can be reported via GitHub at https://github.com/CISOfy/lynis or via support@cisofy.com

## DOCUMENTATION
Supporting documentation can be found via https://cisofy.com/support/

## LICENSING
Lynis is licensed as GPLv3. The tool was created by Michael Boelen in 2007. Since 2013 its development has been taken over by CISOfy under the management of Michael Boelen. Plugins may have a different license.

## CONTACT INFORMATION
Support requests and project related questions can be addressed via e-mail: lynis-dev@cisofy.com.


package: madwifi-utils

title: 80211debug(8)

text:
# 80211debug(8)

## NAME
80211debug - control the debug output from the madwifi 802.11 stack

## SYNOPSIS
80211debug [-i interface] +/- bitmap

## DESCRIPTION
Set and clear debug bitmaps for the madwifi 802.11 stack. Each argument is a bitmap or its alias. If a bitmap alias is used then it must be prefixed by either "-" to clear or "+" to set the corresponding bitmap.

## OPTIONS
-?

Display usage and list all debug bitmaps.

-i interface

The madwifi interface to debug. If no interface is specified, 80211debug defaults to ath0.

+/- bitmap

Set (+) or clear (-) a bitmap. It's quite tedious to remember the bitmaps, fortunately there is a user friendly interface which can be used to enable or disable debugging output by giving the name of the component or subsystem.

All debugging output can be enabled with 0xffffffff bitmap, while 0x0 disables all debug output.

## BITMAP ALIASES
debug - IFF_DEBUG equivalent

dumppkts - IFF_LINK2 equivalent, dump packets

crypto - crypto modules

input - packet input handling

xrate - rate set handling

elemid - element id parsing

node - node management

assoc - association handling

auth - authentication handling

scan - scanning

output - packet output handling

state - 802.11 state machine

power - power save functions

dot1x - 802.1x authenticator

dot1xsm - 802.1x state machine

radius - 802.1x radius client

raddump - 802.1x radius packet dump

radkeys - 802.1x key dump

wpa - WPA/RSN protocol

ac1 - ACL handling

wme - WME protocol

superg - super G turbo mode

doth - 802.11h (DFS/TPC) handling

inact - timeout of inactive nodes

roam - station mode roaming

## EXAMPLES
80211debug -i ath1 0xffffffff

Enable all debug bitmaps on ath1.

80211debug +state +assoc

Set state and assoc bitmaps to on for ath0.

80211debug -state

Disable state bitmap for ath0.

## SEE ALSO
athdebug(8), http://madwifi-project.org/wiki/DevDocs/AthDebug

## AUTHOR
This manual page was written by Kel Modderman <kelrin@tpg.com.au> and was based upon previous text written by Eric S. Raymond.


title: 80211stats(8)

text:
# 80211stats(8)

## NAME
80211stats - simple tool to display collected madwifi 802.11 statistics

## SYNOPSIS
80211stats [-i interface] [-a] [mac...]

## DESCRIPTION
Provide statistics about the madwifi 802.11 stack. 80211stats will print a summary of statistical elements including rx errors, node, crypto and key management data.

If a madwifi interface is specified, 80211stats will contain the output of statistics derived from interactions between the specified interface and the madwifi 802.11 stack.

## OPTIONS
-i interface

The madwifi interface to derive statistics for. If no interface is specified, 80211stats defaults to ath0.

-a

Print statstics for each station/neighbor in interface.

mac...

Print statistics for given list of MAC addresses.

## EXAMPLES
80211stats

Print summary of statistics derived from the madwifi 802.11 stack, not specific to any madwifi device present in the system.

80211stats -i ath0

Print summary of statistics specific for ath0.

## SEE ALSO
athstats(8)

## AUTHOR
This manual page was written by Kel Modderman <kelrin@tpg.com.au>.


athchans

title: athchans(8)

summary: define channel range of madwifi devices

text:
# athchans(8)

## NAME
athchans - define channel range of madwifi devices

## SYNOPSIS
athchans [-i device] channel_range

## DESCRIPTION
Athchans constrains the set of channels used when scanning for access points, peers in an IBSS network, or looking for unoccupied channels when operating as an access point.

The set of channels is specified as a range of the form x-y. Channel numbers must be in the range 1 to 255 and be permissible according to the operating characteristics of the device.

## OPTIONS
-i device

The madwifi device to apply the settings to. If no device is specified, athchans defaults to wifi0.

channel_range

Range of channel constraint applied to the specified device. The range must be specified in the form of x-y and be within 1 to 255.

## EXAMPLES
athchans 5-9 Restrict wifi0 to channels in the range of 5 to 9.

athchans -i wifi1 1-3

Restrict wifi1 to channels in the range of 1 to 3.

## SEE ALSO
athctrl(8), athkey(8), athstats(8)

## AUTHOR
This manual page was written by Kel Modderman <kelrin@tpg.com.au> and was based upon previous text written by Eric S. Raymond and Thorsten von Eicken.


athctrl

title: athctrl(8)

text:
# athctrl(8)

## NAME
athctrl - sets the maximum distance between communicating stations

## SYNOPSIS
athctrl [-h] [-i device] [-d distance]

## DESCRIPTION
athctrl sets the maximum distance in meters of stations with which communication occurs. This distance metric determines how much time the radio waits for an acknowledgment after every transmission and it sets a few other derived timing parameters. This limits the distance between two stations at which the collision avoidance, acknowledgment, retransmission protocols will work correctly.

In particular, when transmitting to too distant stations the radio will start retransmitting packets before an ACK can possibly have been received causing unnecessary retransmissions and collisions. The distance parameter needs to be set properly on all stations that perform long-distance communication irrespective of their mode of operation (master/managed/ad-hoc). For best operation all stations communicating with each other should be set to the same value.

## OPTIONS
-i device

The madwifi device to apply the settings to. If no device is specified, athctrl defaults to wifi0.

-d distance

Distance in metric meters.

-h

Display usage.

## EXAMPLES
athctrl -i wifi1 -d 500

Set maximum distance of 500m for wifi1.

athctrl 1000

Set maximum distance of 1000m for wifi0.

## SEE ALSO
athchans(8), athkey(8), athstats(8)

## AUTHOR
This manual page was written by Kel Modderman <kelrin@tpg.com.au> and was based upon previous text written by Eric S. Raymond and Thorsten von Eicken.


athdebug

title: athdebug(8)

text:
# athdebug(8)

## NAME
athdebug - control the debug output from the madwifi device subsystem

## SYNOPSIS
athdebug [-i device] +/- bitmap

## DESCRIPTION
Set and clear debug bitmaps for the madwifi ath device subsystem. Each argument is a bitmap or its alias. If a bitmap alias is used then it must be prefixed by either "-" to clear or "+" to set the corresponding bitmap.

All debugging output can be enabled with the 0xffffffff bitmap, while 0x0 disables all debug output.

## OPTIONS
-?

Display usage and list all debug flags.

-i device

The madwifi device to apply the settings to. If no interface is specified, athdebug defaults to wifi0.

+/- bitmap

Set (+) or clear (-) a debug flag.

## BITMAP ALIASES
xmit - transmit of packets, just before they go out to the HW

xmit_desc - transmit descriptors

recv - received packets, directly from the HW

recv_desc - recv descriptors

rate - rate control modules

reset - reset processing and inititalization

mode - mode initialization and changes

beacon - beacon handling

watchdog - watchdog timeout

intr - interrupt processing

xmit_proc - processing of transmit descriptors

recv_proc - processing of receive descriptors

beacon_proc - beacon processing

calibrate - periodic re-calibration

keycache - key cache management

state - 802.11 state transitions

node - node management ff - fast frame handling

fatal fatal errors

## EXAMPLES
athdebug -i wifi1 0xffffffff

Enable all debug bitmaps on wifi1.

athdebug +rate

Enable rate debug bitmap on wifi0.

athdebug -rate

Clear rate bitmap on wifi0.

## SEE ALSO
80211debug(8), http://madwifi-project.org/wiki/DevDocs/AthDebug

## AUTHOR
This manual page was written by Kel Modderman <kelrin@tpg.com.au> and was based upon previous text written by Eric S. Raymond.


athkey

title: athkey(8)

text:
# athkey(8)

## NAME
athkey - manage encryption type and keys of madwifi devices

## SYNOPSIS
athkey [-i device] [-d] keyix cipher keyval [mac]

## DESCRIPTION
Each device may have up to four keys; the first argument required is the key index. The "-d" option may be specified to delete the key associated with the selected key index. Otherwise, the other arguments required are a cipher type and a key value encoded as a hexadecimal literal. A MAC address may be given as a final argument; if given, the key will be considered valid only for the specified MAC address.

## OPTIONS
-i device

The madwifi device to apply the settings to. If no device is specified, athkey defaults to wifi0.

-d keyix

Delete a specified key index.

keyix

A key index of 1, 2, 3 or 4.

cipher

Cipher type values: [wep|tkip|ocb|ccm|aes|ckip|none]

keyval

A key value encoded as a hexadecimal literal with an optional leading 0x or 0X. Embedded periods, colons and dashes are ignored.

mac

MAC address encoded as an hexadecimal literal. If a MAC address is specified when adding a key value, the key will be valid only for the specified MAC.

## EXAMPLES
athkey -i wifi1 -d 1

Remove key value of index 1 for wifi1.

athkey 1 wep 0123456789

Set a wep key of "0123456789" on index 1 on wifi0.

athkey -i wifi2 2 tkip 0123456789 00:9b:5c:63:e6:b4

Set a key of 0123456789 using the tkip cipher for a MAC of 00:9b:5c:63:e6:b4 on index 2 on wifi2.

## SEE ALSO
athchans(8), athctrl(8), athstats(8)

## AUTHOR
This manual page was written by Kel Modderman <kelrin@tpg.com.au> and was based upon previous text written by Eric S. Raymond and Thorsten von Eicken.


athstats

title: athstats(8)

text:
# athstats(8)

## NAME
athstats - simple tool to inspect and monitor network traffic statistics

## SYNOPSIS
athstats [-i device] [interval]

## DESCRIPTION
Provide statistics about a madwifi device. Without any arguments, athstats will print a summary of statistical elements for the specified device (defaults to wifi0 when no device is given). If an additional argument is given as an integer, athstats will print progressive statistical data at an interval equal to the integer in seconds.

Statistical elements of the summary report include packets sent/received, tx/rx errors, calibration information and antenna profile data.

The progressive report elements include packet input/output as well as altrate, short, long, xretry, crcerr, crypt, phyerror packet count, rssi and rate data.

The statistical data is derived from device ioctls and /proc/net/dev. For further understanding of how the statistical information is collected and what it represents, please refer to the athstats source code (tools/athstats.c).

## OPTIONS
-i device

The madwifi device to apply the settings to. If no device is specified, athstats defaults to wifi0.

interval

Define the interval between realtime statistical feedback in seconds.

## EXAMPLES
athstats

Print summary of statistics for wifi0.

athstats 1

Update a progressive statistical report every 1 second for wifi0.

athstats -i wifi1 5

Update a progressive statistical report every 5 seconds for wifi1.

## SEE ALSO
80211stats(8)

## AUTHOR
This manual page was written by Kel Modderman <kelrin@tpg.com.au>.


wlanconfig

title: wlanconfig(8)

text:
# wlanconfig(8)

## NAME
wlanconfig - Create, destroy and manipulate madwifi VAPs

## SYNOPSIS
wlanconfig <vap> create wlandev <base device> wlanmode <mode>

wlanconfig <vap> destroy

wlanconfig <vap> list <list item>

## DESCRIPTION
The current MadWifi driver supports multiple AP's and concurrent AP/Station mode operation on the same device. The devices are restricted to using the same underlying hardware, thus are limited to coexisting on the same channel and using the same physical layer features. Each instance of an AP or station is called a Virtual AP (or VAP). Each VAP can be in either AP mode, Station Mode, "special" station mode, and Monitor mode. Every VAP has an associated underlying base device which is created when the driver is loaded.

## ARGUMENTS
<vap> create [nounit] wlandev <base device> wlanmode <mode> [bssid|-bssid] [nosbeacon]

Create the interface <vap> using the specified <base device> and <mode>. <vap> can either be a full interface name (e.g. 'ath0'), or just the suffix (e.g. 'ath'), in which case, the kernel will automatically append the next vacant integer. [nounit] will turn off the automatic integer increments.

<vap> destroy

Removes the given VAP interface. You must specify the full interface name. I.e 'ath0' rather than just 'ath'.

<vap> list <list item>

Show information about connected peers, keys, channels etc.

## AVAILABLE MODES
ahdemo

Create the station in ad-hoc demo (aka pseudo IBSS) mode.

adhoc

Create the station in ad-hoc mode.

ap

Create the VAP in AP mode.

monitor

Create the station in monitor mode.

sta

Create the VAP in station mode.

wds

Create the station in WDS mode.

## OPTIONS
bssid

Create the VAP using a different MAC address from the underlying device.

-bssid

Create the VAP using the MAC address of the underlying device.

nosbeacon

When both station VAPS and AP VAPs coexist, the station should be created with the nosbeacon flag set in order to disable the use of hardware beacon times for the station.

## LIST ITEMS
sta or no parameters.

Show information on associated stations.

scan or ap

List all visible stations.

chan or freq

List all channels and frequencies.

active

List all available channels and frequencies.

keys

List all of the keys associated with the VAP

caps

List the capabilities of the given VAP.

wme

List WME (Wireless multimedia extensions, aka WMM) parameters.

## EXAMPLES
wlanconfig ath create wlandev wifi0 wlanmode sta

Create a station mode VAP, using wifi0 as the underlying device. The interface wil be called athN, where N is the first free integer. The MAC address will be the same as the underlying device.

wlanconfig ath0 create wlandev wifi0 wlanmode sta

Create a station mode VAP (ath0) using wifi0 as the underlying device. The MAC address will be the same as the underlying device.

wlanconfig ath0 create wlandev wifi0 wlanmode ap

wlanconfig ath1 create wlandev wifi0 wlanmode sta nosbeacon Create both an AP and a station mode interface. wlanconfig ath0 destroy

Destroy VAP ath0.

wlanconfig ath0 list scan

Scan for local stations and access points.

wlanconfig ath0 create wlandev wifi0 wlanmode ap

wlanconfig ath1 create wlandev wifi0 wlanmode wds iwconfig ath0 essid "Normal atheros AP" channel 1 iwpriv ath1 wds_add <mac of the peer wds ap> iwpriv ath1 wds 1 ifconfig ath1 up ifconfig ath0 up brctl addbr br0 brctl addif br0 ath1 brctl addif br0 ath0 ifconfig br0 up Create a WDS bridge. See http://madwifi-project.org/ for more information.

## AUTHOR
This manual page was written by Matt Foster <mattfoster@clara.co.uk>, using information from the Atheros user documentation, and MadWiFi users mailing list.


madwimax

package: madwimax

title: madwimax(8)

text:
# madwimax(8)

## NAME
madwimax - driver for mobile WiMAX equipment based on Samsung CMC-730

## SYNOPSIS
madwimax [OPTIONS]

## DESCRIPTION
madwimax is an experimental reverse-engineered linux driver for mobile WiMAX (802.16e) devices based on Samsung CMC-730 chip. These devices are currently supported:

•

Samsung SWC-U200

•

Samsung SWC-E100

•

Samsung SWM-S10R (it is built in Samsung NC-10 netbook)

The driver is completely user-space. It requires libusb-1.0 and TUN/TAP driver to work.

## OPTIONS
-d, --daemonize

Daemonize after startup.

--device=VID:PID

Specify the USB device by VID:PID combination.

-e FILE, --event-script=FILE

Specify path to the event script.

--exact-device=BUS/DEVICE

Specify the exact USB BUS/DEVICE (use with care!).

-f, --detach-dvd

Detach pseudo-DVD kernel driver on startup.

-h, --help

Display help.

-l FILE, --log-file=FILE

Write log to the specified FILE instead of the other methods.

-o, --diode-off

Turn off the diode (diode is turned on by default).

-q, --quiet

Switch off logging.

-V, --version

Print the program version number.

-v, --verbose

Increase the log level.

--ssid=SSID

Specify service set identifier, or SSID, which is a friendly name that identifies a particular 802.16e wireless network.

## EXIT STATUS
0

Success

1

Failure (syntax or usage error; hardware error; underlying software error; unexpected error).

## BUGS
See the madwimax issue tracker: ⟨http://code.google.com/p/madwimax/issues/list⟩

## AUTHOR
Written by Alexander Gordeev, <mailto:lasaine@lvk.cs.msu.su>

## RESOURCES
Main web site: ⟨http://code.google.com/p/madwimax/⟩

## COPYING
Copyright (C) 2008-2009 Alexander Gordeev. Free use of this software is granted under the terms of the GNU General Public License (GPL).


package: mailman

title: add_members(8)

text:
# add_members(8)

## NAME
add_members - Add members to a Mailman mailing list from the command line.

## SYNOPSIS
add_members [-r <file>] [-d <file>] [-y <y|n>] [-w <y|n>] [-h] listname

## DESCRIPTION
Add members from a file to a mailman list. Listname is the name of the Mailman list you are adding members to. It must already exist.

## OPTIONS
-r file, --regular-members-file=file

A file containing addresses of the members to be added, one address per line. This list of people become non-digest members. If file is `-', read addresses from stdin. Note that -n/--non-digest-members-file are deprecated synonyms for this option.

-d file, --digest-members-file=file

Similar to above, but these people become digest members.

-a [y|n], --admin-notify=[y|n]

Set whether or not to send the list administrators a notification on the success/failure of these subscriptions, overriding whatever the list's `admin_notify_mchanges' setting is.

-w [y|n], --welcome-msg=[y|n]

Set whether or not to send the list members a welcome message, overriding whatever the list's `send_welcome_msg' setting is.

-h, --help

Print a help message and exit.

## NOTES
You must supply at least one of -r and -d options. At most one of the files can be `-'.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


title: check_db(8)

text:
# check_db(8)

## NAME
check_db - Check the integrity of a Mailman mailing list's database file

## SYNOPSIS
check_db [options] [listname [listname ...]]

## DESCRIPTION
check_db checks the integrity of a list's config.db and config.db.last database files.

## OPTIONS
-a, --all

Check the databases for all lists. Otherwise only the lists named on the command line are checked.

-v, --verbose

Verbose output. The state of every tested file is printed. Otherwise only corrupt files are displayed.

-h, --help

Print a help text and exit.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


title: check_perms(8)

summary: Check permissions of Mailman's files

text:
# check_perms(8)

## NAME
check_perms - Check permissions of Mailman's files

## SYNOPSIS
check_perms [-f] [-v] [-h]

## OPTIONS
-f

Fix any problems found (when run as root)

-v

Be verbose

-h

Print a help message and exit

## DESCRIPTION
With no arguments, just check and report all the files that have bogus permissions or group ownership.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


title: clone_member(8)

text:
# clone_member(8)

## NAME
clone_member - Clone a Mailman mailing list subscriber address

## SYNOPSIS
clone_member [options] fromoldaddr tonewaddr

## DESCRIPTION
Cloning a member address means that a new member will be added who has all the same options and passwords as the original member address. Note that this operation is fairly trusting of the user who runs it -- it does no verification to the new address, it does not send out a welcome message, etc.

The existing member's subscription is usually not modified in any way. If you want to remove the old address, use the -r flag. If you also want to change any list admin addresses, use the -a flag.

## OPTIONS
-l listname, --listname=listname

Check and modify only the named mailing lists. If -l is not given, then all mailing lists are scanned from the address. Multiple -l options can be supplied.

-r, --remove

Remove the old address from the mailing list after it's been cloned.

-a, --admin

Scan the list admin addresses for the old address, and clone or change them too.

-q, --quiet

Do the modifications quietly.

-n, --nomodify

Print what would be done, but don't actually do it. Inhibits the 0

fromoldaddr (`from old address') is the old address of the user. tonewaddr (`to new address') is the new address of the user.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


title: config_list(8)

text:
# config_list(8)

## NAME
config_list - Configure a Mailman mailing list from a text file description

## SYNOPSIS
config_list [options] listname

## DESCRIPTION
This is a very powerful script which lets you view and modify a list's configuration variables from the command line. E.g. you can dump out all the list options into a plain text file (actually a valid Python file!), complete with comments explaining each variable. Or you can apply the configuration from such a file to a particular list.

## OPTIONS
-i filename, --inputfile=filename

Configure the list by assigning each module-global variable in the file to an attribute on the list object, then saving the list. The named file is loaded with execfile() and must be legal Python code. Any variable that isn't already an attribute of the list object is ignored (a warning message is printed). See also the -c option. A special variable named `mlist' is put into the globals during the execfile, which is bound to the actual MailList object. This lets you do all manner of bizarre thing to the list object, but BEWARE! Using this can severely (and possibly irreparably) damage your mailing list!

-o filename, --outputfile=filename

Instead of configuring the list, print out a list's configuration variables in a format suitable for input using this script. In this way, you can easily capture the configuration settings for a particular list and imprint those settings on another list. filename is the file to output the settings to. If filename is `-', standard out is used.

-c, --checkonly

The modified list is not actually changed. Only useful with -i.

-v, --verbose

Print the name of each attribute as it is being changed. Only useful with -i.

-h, --help

Print a small help text and exit

## NOTES
The options -o and -i are mutually exclusive.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


title: find_member(8)

text:
# find_member(8)

## NAME
find_member - Find all Mailman mailing lists that a member's address is on

## SYNOPSIS
find_member [options] regex [regex [...]]

## OPTIONS
-l listname, --listname=listname

Include only the named list in the search.

-x listname, --exclude=listname

Exclude the named list from the search.

-w, --owners

Search list owners as well as members.

-o file, --output=file

Append the alias setting recommendations to file, in addition to printing them to standard output.

-h, --help

Print a small help text and exit

regex

A Python regular expression to match against.

## NOTES
The interaction between -l and -x is as follows. If any -l option is given then only the named list will be included in the search. If any -x option is given but no -l option is given, then all lists will be search except those specifically excluded.

Regular expression syntax is Perl5-like, using the Python re module. Complete specifications are at:

http://www.python.org/doc/current/lib/module-re.html

Address matches are case-insensitive, but case-preserved addresses are displayed.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


title: list_admins(8)

text:
# list_admins(8)

## NAME
list_admins - List all the owners of a Mailman mailing list.

## SYNOPSIS
list_admins [options] listname ...

## OPTIONS
-v=vhost, --all-vhost=vhost

List the owners of all the mailing lists for the given virtual host.

-a, --all

List the owners of all the mailing lists on this system.

-h, --help

Print a small help text and exit

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written for Debian by Bernd S. Brentrup <bsb@debian.org>, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


title: list_lists(8)

text:
# list_lists(8)

## NAME
list_lists - List all Mailman mailing lists on this host

## SYNOPSIS
list_lists [options]

## OPTIONS
-a, --advertised

List only those mailing lists that are publically advertised

-V domain, --virtual-host-overview=domain

List only those mailing lists that are homed to the given virtual domain. This only works if the VIRTUAL_HOST_OVERVIEW variable is set.

-b, --bare

Displays only the list name, with no description.

-h, --help

Print a small help text and exit

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


title: list_members(8)

text:
# list_members(8)

## NAME
list_members - List all the members of a Mailman mailing list

## SYNOPSIS
list_members [-o file] [-r] [-d] [-p] [-h] listname

## OPTIONS
-o file, --output file

Write output to specified file instead of standard out.

-r, --regular

Print just the regular (non-digest) members.

-d [kind], --digest[=kind]

Print just the digest members. Optional argument can be "mime" or "plain" which prints just the digest members receiving that kind of digest.

--nomail[=why], -n [why]

Print the members that have delivery disabled. Optional argument can be "byadmin", "byuser", "bybounce", or "unknown" which prints just the users who have delivery disabled for that reason. It can also be "enabled" which prints just those member for whom delivery is enabled.

-f, --fullnames

Include the full names in the output.

-p, --preserve

Output member addresses case preserved the way they were added to the list. Otherwise, addresses are printed in all lowercase.

-i, --invalid

Print only the addresses in the membership list that are invalid. Ignores -r, -d, -n.

-u, --unicode

Print addresses which are stored as Unicode objects instead of normal string objects. Ignores -r, -d, -n.

-h, --help

Print a small help text and exit

listname is the name of the mailing list to use.

## NOTES
Note that if neither -r or -d is supplied, both regular members are printed first, followed by digest members, but no indication is given as to address status.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


mmarch

title: mmarch(8)

text:
# mmarch(8)

## NAME
mmarch - Rebuild a Mailman mailing list's archive.

## SYNOPSIS
mmarch [options] <listname> [<mbox>]

## DESCRIPTION
Use this command to rebuild the archives for a mailing list. You may want to do this if you edit some messages in an archive, or remove some messages from an archive.

-h, --help

Print this error message and exit.

-q, --quiet

Make the archiver output less verbose.

--wipe

First wipe out the original archive before regenerating. You usually want to specify this argument unless you're generating the archive in chunks.

-s N, --start=N

Start indexing at article N, where article 0 is the first in the mbox. Defaults to 0.

-e M, --end=M

End indexing at article M. This script is not very efficient with respect to memory management, and for large archives, it may not be possible to index the mbox entirely. For that reason, you can specify the start and end article numbers.

mbox is the path to a list's complete mbox archive. Usually this will be some path in the archives/private directory. For example:

% mmarch mylist archives/private/mylist.mbox/mylist.mbox

mbox is optional. If it is missing, it is calculated.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


mmsitepass

title: mmsitepass(8)

text:
# mmsitepass(8)

## NAME
mmsitepass - Set the Mailman site password, prompting from the terminal.

## SYNOPSIS
mmsitepass [options] [password]

## OPTIONS
-c, --listcreator

Set the list creator password instead of the site password. The list creator is authorized to create and remove lists, but does not have the total power of the site administrator.

-h, --help

Print a small help text and exit

## SECURITY
Including the admin-password on the command line is a small security risk if you have untrusted users on the system.

## DESCRIPTION
The site password can be used in most if not all places that the list administrator's password can be used, which in turn can be used in most places that a list users password can be used.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


newlist

title: newlist(8)

text:
# newlist(8)

## NAME
newlist - Create a new, unpopulated Mailman mailing list.

## SYNOPSIS
newlist [options] [listname] [listadmin-addr] [admin-password]

## OPTIONS
-l language, --language=language

Make the list's preferred language `language', which must be the (mostly two letter) language code as found under /usr/share/mailman.

-u urlhost, --urlhost=urlhost

Gives the list's web interface host name.

-e emailhost, --emailhost=emailhost

Gives the list's email domain name.

-q, --quiet

Normally the administrator is notified by email (after a prompt) that their list has been created. This option suppresses that notification and the prompting.

-h, --help

Print a small help text and exit

## SECURITY
Including the admin-password on the command line is a small security risk if you have untrusted users on the system.

## NOTES
You can specify as many of the arguments as you want on the command line: you will be prompted for the missing ones.

Every Mailman list has two parameters which define the default host name for outgoing email, and the default URL for all web interfaces. When you configured Mailman, certain defaults were calculated, but if you are running multiple virtual Mailman sites, then the defaults may not be appropriate for the list you are creating.

You also specify the domain to create your new list in by typing the command like so:

newlist --urlhost=www.example.com mylist

where `www.example.com' should be the base hostname for the URL to this virtual hosts's lists. E.g. with this setting people will view the general list overviews at http://www.example.com/mailman/listinfo. Also, www.example.com should be a key in the VIRTUAL_HOSTS mapping in mm_cfg.py/Defaults.py if the email hostname to be automatically determined.

If you want the email hostname to be different from the one looked up by the VIRTUAL_HOSTS or if urlhost is not registered in VIRTUAL_HOSTS, you can specify `emailhost' like so:

newlist --urlhost=www.example.com --emailhost=example.com mylist

where `example.com' is the mail domain name. If you don't specify emailhost but urlhost is not in the virtual host list, then mm_cfg.DEFAULT_EMAIL_HOST will be used for the email interface.

For backward compatibility, you can also specify the domain to create your new list in by spelling the listname like so:

mylist@www.example.com

where www.example.com is used for `urlhost' but it will also be used for `emailhost' if it is not found in the virtual host table. Note `--urlhost' and `--emailhost' have precedence to this notation.

If you spell the list name as just `mylist', then the email hostname will be taken from DEFAULT_EMAIL_HOST and the url will be taken from DEFAULT_URL (as defined in your Defaults.py file or overridden by settings in mm_cfg.py).

Note that listnames are forced to lowercase.

The list admin address need to be a fully-qualified address, like owner@example.com, not just owner.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


title: remove_members(8)

text:
# remove_members(8)

## NAME
remove_members - Remove members from a Mailman mailing list.

## SYNOPSIS
remove_members [options] listname [addr1 ...]

## OPTIONS
-f file, --file=file

Remove member addresses found in the given file. If file is `-', read stdin.

-a, --all

Remove all members of the mailing list. (mutually exclusive with --fromall)

--fromall

Removes the given addresses from all the lists on this system regardless of virtual domains if you have any. This option cannot be used with -a/--all. Also, you should not specify a listname when using this option.

-n, --nouserack

Don't send the user acknowledgements. If not specified, the list default value is used.

-N, --noadminack

Don't send the admin acknowledgements. If not specified, the list default value is used.

-h, --help

Print a small help text and exit

listname is the name of the mailing list to use.

addr1 ... are additional addresses to remove.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


rmlist

title: rmlist(8)

summary: Remove the components of a Mailman mailing list with impunity \- beware!

text:
# rmlist(8)

## NAME
rmlist - Remove the components of a Mailman mailing list with impunity - beware!

## SYNOPSIS
rmlist [-a] [-h] listname

## DESCRIPTION
This removes (almost) all traces of a mailing list. By default, the lists archives are not removed, which is very handy for retiring old lists.

## OPTIONS
-a, --archives

Remove the list's archives too, or if the list has already been deleted, remove any residual archives.

-h, --help

Print a small help text and exit

listname is the name of the mailing list to use.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.


title: sync_members(8)

text:
# sync_members(8)

## NAME
sync_members - Synchronize a Mailman mailing list's membership with a flat file.

## SYNOPSIS
sync_members [options] -f file listname

## DESCRIPTION
This script is useful if you have a Mailman mailing list and a sendmail :include: style list of addresses (also as is used in Majordomo). For every address in the file that does not appear in the mailing list, the address is added. For every address in the mailing list that does not appear in the file, the address is removed. Other options control what happens when an address is added or removed.

## OPTIONS
-n, --no-change

Don't actually make the changes. Instead, print out what would be done to the list.

-w={ yes | no }, --welcome-msg={ yes | no }

Sets whether or not to send the newly added members a welcome message, overriding whatever the list's `send_welcome_msg' setting is. With -w=yes or -w, the welcome message is sent. With -w=no, no message is sent.

-g={ yes | no }, --goodbye-msg={ yes | no }

Sets whether or not to send the goodbye message to removed members, overriding whatever the list's `send_goodbye_msg' setting is. With -g=yes or -g, the goodbye message is sent. With -g=no, no message is sent.

-d={ yes | no }, --digest={ yes | no }

Selects whether to make newly added members receive messages in digests. With -d=yes or -d, they become digest members. With -d=no (or if no -d option given) they are added as regular members.

-a={ yes | no }, --notifyadmin={ yes | no }

Specifies whether the admin should be notified for each subscription or unsubscription. If you're adding a lot of addresses, you definitely want to turn this off! With -a=yes or -a, the admin is notified. With -a=no, the admin is not notified. With no -a option, the default for the list is used.

-f=filename, --file=filename

This option is required. It specifies the flat file to synchronize against. Email addresses must appear one per line. If filename is `-' then stdin is used.

-h, --help

Print a small help text and exit.

listname specifies the list to synchronize.

## AUTHOR
Author of Mailman is the Mailman Cabal, see http://www.list.org/ for information. This manpage is written by Tollef Fog Heen <tfheen@debian.org> for Debian, but may be used by others.

## SEE ALSO
Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.