wdctl

title: wdctl(8)

summary: show hardware watchdog status

text:
# wdctl(8)

## NAME
wdctl - show hardware watchdog status

## SYNOPSIS
wdctl [options] [device...]

## DESCRIPTION
Show hardware watchdog status. The default device is /dev/watchdog. If more than one device is specified then the output is separated by one blank line.

If the device is already used or user has no permissions to read from the device, then wdctl reads data from sysfs. In this case information about supported features (flags) might be missing.

Note that the number of supported watchdog features is hardware specific.

## OPTIONS
-f, --flags list

Print only the specified flags.

-F, --noflags

Do not print information about flags.

-I, --noident

Do not print watchdog identity information.

-n, --noheadings

Do not print a header line for flags table.

-o, --output list

Define the output columns to use in table of watchdog flags. If no output arrangement is specified, then a default set is used. Use --help to get list of all supported columns.

-O, --oneline

Print all wanted information on one line in key="value" output format.

-p, --setpretimeout seconds

Set the watchdog pre-timeout in seconds. A watchdog pre-timeout is a notification generated by the watchdog before the watchdog reset might occur in the event the watchdog has not been serviced. This notification is handled by the kernel and can be configured to take an action using sysfs or by --setpregovernor.

-g, --setpregovernor governor

Set pre-timeout governor name. For available governors see default wdctl output.

-r, --raw

Use the raw output format.

-s, --settimeout seconds

Set the watchdog timeout in seconds.

-T, --notimeouts

Do not print watchdog timeouts.

-x, --flags-only

Same as -I -T.

-h, --help

Display help text and exit.

-V, --version

Print version and exit.

## AUTHORS
Karel Zak <kzak@redhat.com>, Lennart Poettering <lennart@poettering.net>

## REPORTING BUGS
For bug reports, use the issue tracker at <https://github.com/util-linux/util-linux/issues>.

## AVAILABILITY
The wdctl command is part of the util-linux package which can be downloaded from Linux Kernel Archive <https://www.kernel.org/pub/linux/utils/util-linux/>.


wipefs

package: util-linux

title: wipefs(8)

summary: wipe a signature from a device

text:
# wipefs(8)

## NAME
wipefs - wipe a signature from a device

## SYNOPSIS
wipefs [options] device...

wipefs [--backup] -o offset device...

wipefs [--backup] -a device...

## DESCRIPTION
wipefs can erase filesystem, raid or partition-table signatures (magic strings) from the specified device to make the signatures invisible for libblkid. wipefs does not erase the filesystem itself nor any other data from the device.

When used without any options, wipefs lists all visible filesystems and the offsets of their basic signatures. The default output is subject to change. So whenever possible, you should avoid using default outputs in your scripts. Always explicitly define expected columns by using --output columns-list in environments where a stable output is required.

wipefs calls the BLKRRPART ioctl when it has erased a partition-table signature to inform the kernel about the change. The ioctl is called as the last step and when all specified signatures from all specified devices are already erased. This feature can be used to wipe content on partitions devices as well as partition table on a disk device, for example by wipefs -a /dev/sdc1 /dev/sdc2 /dev/sdc.

Note that some filesystems and some partition tables store more magic strings on the device (e.g., FAT, ZFS, GPT). The wipefs command (since v2.31) lists all the offset where a magic strings have been detected.

When option -a is used, all magic strings that are visible for libblkid(3) are erased. In this case the wipefs scans the device again after each modification (erase) until no magic string is found.

Note that by default wipefs does not erase nested partition tables on non-whole disk devices. For this the option --force is required.

## OPTIONS
-a, --all

Erase all available signatures. The set of erased signatures can be restricted with the -t option.

-b, --backup

Create a signature backup to the file $HOME/wipefs-<devname>-<offset>.bak. For more details see the EXAMPLE section.

-f, --force

Force erasure, even if the filesystem is mounted. This is required in order to erase a partition-table signature on a block device.

-J, --json

Use JSON output format.

--lock[=mode]

Use exclusive BSD lock for device or file it operates. The optional argument mode can be yes, no (or 1 and 0) or nonblock. If the mode argument is omitted, it defaults to "yes". This option overwrites environment variable $LOCK_BLOCK_DEVICE. The default is not to use any lock at all, but it’s recommended to avoid collisions with udevd or other tools.

-i, --noheadings

Do not print a header line.

-O, --output list

Specify which output columns to print. Use --help to get a list of all supported columns.

-n, --no-act

Causes everything to be done except for the write(2) call.

-o, --offset offset

Specify the location (in bytes) of the signature which should be erased from the device. The offset number may include a "0x" prefix; then the number will be interpreted as a hex value. It is possible to specify multiple -o options. The offset argument may be followed by the multiplicative suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is optional, e.g., "K" has the same meaning as "KiB"), or the suffixes KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.

-p, --parsable

Print out in parsable instead of printable format. Encode all potentially unsafe characters of a string to the corresponding hex value prefixed by '\x'.

-q, --quiet

Suppress any messages after a successful signature wipe.

-t, --types list

Limit the set of printed or erased signatures. More than one type may be specified in a comma-separated list. The list or individual types can be prefixed with 'no' to specify the types on which no action should be taken. For more details see mount(8).

-h, --help

Display help text and exit.

-V, --version

Print version and exit.

## ENVIRONMENT
LIBBLKID_DEBUG=all

enables libblkid(3) debug output.

LOCK_BLOCK_DEVICE=<mode>

use exclusive BSD lock. The mode is "1" or "0". See --lock for more details.

## EXAMPLES
wipefs /dev/sda*

Prints information about sda and all partitions on sda.

wipefs --all --backup /dev/sdb

Erases all signatures from the device /dev/sdb and creates a signature backup file ~/wipefs-sdb-<offset>.bak for each signature.

dd if=~/wipefs-sdb-0x00000438.bak of=/dev/sdb seek=$((0x00000438)) bs=1 conv=notrunc

Restores an ext2 signature from the backup file ~/wipefs-sdb-0x00000438.bak.

## AUTHORS
Karel Zak <kzak@redhat.com>

## SEE ALSO
blkid(8), findfs(8)

## REPORTING BUGS
For bug reports, use the issue tracker at <https://github.com/util-linux/util-linux/issues>.

## AVAILABILITY
The wipefs command is part of the util-linux package which can be downloaded from Linux Kernel Archive <https://www.kernel.org/pub/linux/utils/util-linux/>.


zramctl

title: zramctl(8)

summary: set up and control zram devices

text:
# zramctl(8)

## NAME
zramctl - set up and control zram devices

## SYNOPSIS
Get info:

zramctl [options]

Reset zram:

zramctl -r zramdev...

Print name of first unused zram device:

zramctl -f

Set up a zram device:

zramctl [-f | zramdev] [-s size] [-t number] [-a algorithm]

## DESCRIPTION
zramctl is used to quickly set up zram device parameters, to reset zram devices, and to query the status of used zram devices.

If no option is given, all non-zero size zram devices are shown.

Note that zramdev node specified on command line has to already exist. The command zramctl creates a new /dev/zram<N> nodes only when --find option specified. It’s possible (and common) that after system boot /dev/zram<N> nodes are not created yet.

## OPTIONS
-a, --algorithm lzo|lz4|lz4hc|deflate|842|zstd

Set the compression algorithm to be used for compressing data in the zram device. The list of supported algorithms could be inaccurate as it depends on the current kernel configuration. A basic overview can be obtained by using the command "cat /sys/block/zram0/comp_algorithm"; however, please note that this list might also be incomplete. This is due to the fact that ZRAM utilizes the Crypto API, and if certain algorithms were built as modules, it becomes impossible to enumerate all of them.

-f, --find

Find the first unused zram device. If a --size argument is present, then initialize the device.

-n, --noheadings

Do not print a header line in status output.

-o, --output list

Define the status output columns to be used. If no output arrangement is specified, then a default set is used. Use --help to get a list of all supported columns.

--output-all

Output all available columns.

--raw

Use the raw format for status output.

-r, --reset

Reset the options of the specified zram device(s). Zram device settings can be changed only after a reset.

-s, --size size

Create a zram device of the specified size. Zram devices are aligned to memory pages; when the requested size is not a multiple of the page size, it will be rounded up to the next multiple. When not otherwise specified, the unit of the size parameter is bytes. The size argument may be followed by the multiplicative suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is optional, e.g., "K" has the same meaning as "KiB") or the suffixes KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.

-t, --streams number

Set the maximum number of compression streams that can be used for the device. The default is use all CPUs and one stream for kernels older than 4.6.

-h, --help

Display help text and exit.

-V, --version

Print version and exit.

## EXIT STATUS
zramctl returns 0 on success, nonzero on failure.

## FILES
/dev/zram[0..N]

zram block devices

## EXAMPLE
The following commands set up a zram device with a size of one gigabyte and use it as swap device.

```
 # zramctl --find --size 1024M

 /dev/zram0

 # mkswap /dev/zram0

 # swapon /dev/zram0

 ...

 # swapoff /dev/zram0

 # zramctl --reset /dev/zram0
```

## AUTHORS
Timofey Titovets <nefelim4ag@gmail.com>, Karel Zak <kzak@redhat.com>

## SEE ALSO
Linux kernel documentation <https://docs.kernel.org/admin-guide/blockdev/zram.html>

## REPORTING BUGS
For bug reports, use the issue tracker at <https://github.com/util-linux/util-linux/issues>.

## AVAILABILITY
The zramctl command is part of the util-linux package which can be downloaded from Linux Kernel Archive <https://www.kernel.org/pub/linux/utils/util-linux/>.


uucico

package: uucp

title: uucico(8)

summary: UUCP file transfer daemon

text:
# uucico(8)

## NAME
uucico - UUCP file transfer daemon

## SYNOPSIS
uucico [ options ]

## DESCRIPTION
The uucico daemon processes file transfer requests queued by uucp (1) and uux (1). It is started when uucp or uux is run (unless they are given the -r option). It is also typically started periodically using entries in the crontab table(s).

When invoked with -r1, --master, -s, --system, or -S, the daemon will place a call to a remote system, running in master mode. Otherwise the daemon will start in slave mode, accepting a call from a remote system. Typically a special login name will be set up for UUCP which automatically invokes uucico when a call is made.

When uucico terminates, it invokes the uuxqt (8) daemon, unless the -q or --nouuxqt option is given; uuxqt (8) executes any work orders created by uux (1) on a remote system, and any work orders created locally which have received remote files for which they were waiting.

If a call fails, uucico will normally refuse to retry the call until a certain (configurable) amount of time has passed. This may be overriden by the -f, --force, or -S option.

The -l, --prompt, -e, or --loop options may be used to force uucico to produce its own prompts of "login: " and "Password:". When another daemon calls in, it will see these prompts and log in as usual. The login name and password will normally be checked against a separate list kept specially for uucico rather than the /etc/passwd file; it is possible on some systems to direct uucico to use the /etc/passwd file. The -l or --prompt option will prompt once and then exit; in this mode the UUCP administrator or the superuser may use the -u or --login option to force a login name, in which case uucico will not prompt for one. The -e or --loop option will prompt again after the first session is over; in this mode uucico will permanently control a port.

If uucico receives a SIGQUIT, SIGTERM or SIGPIPE signal, it will cleanly abort any current conversation with a remote system and exit. If it receives a SIGHUP signal it will abort any current conversation, but will continue to place calls to (if invoked with -r1 or --master) and accept calls from (if invoked with -e or --loop) other systems. If it receives a SIGINT signal it will finish the current conversation, but will not place or accept any more calls.

## OPTIONS
The following options may be given to uucico.

-r1, --master

Start in master mode (call out to a system); implied by -s, --system, or -S. If no system is specified, call any system for which work is waiting to be done.

-r0, --slave

Start in slave mode. This is the default.

-s system, --system system

Call the named system.

-S system

Call the named system, ignoring any required wait. This is equivalent to -s system -f.

-f, --force

Ignore any required wait for any systems to be called.

-l, --prompt

Prompt for login name and password using "login: " and "Password:". This allows uucico to be easily run from inetd (8). The login name and password are checked against the UUCP password file, which probably has no connection to the file /etc/passwd. The --login option may be used to force a login name, in which cause uucico will only prompt for a password.

-p port, --port port

Specify a port to call out on or to listen to.

-e, --loop

Enter endless loop of login/password prompts and slave mode daemon execution. The program will not stop by itself; you must use kill (1) to shut it down.

-w, --wait

After calling out (to a particular system when -s, --system, or -S is specifed, or to all systems which have work when just -r1 or --master is specifed), begin an endless loop as with --loop.

-q, --nouuxqt

Do not start the uuxqt (8) daemon when finished.

-c, --quiet

If no calls are permitted at this time, then don't make the call, but also do not put an error message in the log file and do not update the system status (as reported by uustat (1)). This can be convenient for automated polling scripts, which may want to simply attempt to call every system rather than worry about which particular systems may be called at the moment. This option also suppresses the log message indicating that there is no work to be done.

-C, --ifwork

Only call the system named by -s, --system or -S if there is work for that system.

-D, --nodetach

Do not detach from the controlling terminal. Normally uucico detaches from the terminal before each call out to another system and before invoking uuxqt. This option prevents this.

-u name, --login name

Set the login name to use instead of that of the invoking user. This option may only be used by the UUCP administrator or the superuser. If used with --prompt, this will cause uucico to prompt only for the password, not the login name.

-z, --try-next

If a call fails after the remote system is reached, try the next alternate rather than simply exiting.

-i type, --stdin type

Set the type of port to use when using standard input. The only support port type is TLI, and this is only available on machines which support the TLI networking interface. Specifying -iTLI causes uucico to use TLI calls to perform I/O.

-x type, -X type, --debug type

Turn on particular debugging types. The following types are recognized: abnormal, chat, handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. Multiple types may be given, separated by commas, and the --debug option may appear multiple times. A number may also be given, which will turn on that many types from the foregoing list; for example, --debug 2 is equivalent to --debug abnormal,chat.

The debugging output is sent to the debugging file, which may be printed using uulog -D.

-I file, --config file

Set configuration file to use. This option may not be available, depending upon how uucico was compiled.

-v, --version

Report version information and exit.

--help

Print a help message and exit.

## SEE ALSO
kill(1), uucp(1), uux(1), uustat(1), uuxqt(8)

## AUTHOR
Ian Lance Taylor <ian@airs.com>


uuxqt

title: uuxqt(8)

summary: UUCP execution daemon

text:
# uuxqt(8)

## NAME
uuxqt - UUCP execution daemon

## SYNOPSIS
uuxqt [ options ]

## DESCRIPTION
The uuxqt daemon executes commands requested by uux (1) from either the local system or from remote systems. It is started automatically by the uucico (8) daemon (unless uucico (8) is given the -q or --nouuxqt option).

There is normally no need to run this command, since it will be invoked by uucico (8). However, it can be used to provide greater control over the processing of the work queue.

Multiple invocations of uuxqt may be run at once, as controlled by the max-uuxqts configuration command.

## OPTIONS
The following options may be given to uuxqt.

-c command, --command command

Only execute requests for the specified command. For example:

```
uuxqt --command rmail
```

-s system, --system system

Only execute requests originating from the specified system.

-x type, --debug type

Turn on particular debugging types. The following types are recognized: abnormal, chat, handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. Only abnormal, config, spooldir and execute are meaningful for uuxqt. Multiple types may be given, separated by commas, and the --debug option may appear multiple times. A number may also be given, which will turn on that many types from the foregoing list; for example, --debug 2 is equivalent to --debug abnormal,chat.

The debugging output is sent to the debugging file, which may be printed using uulog -D.

-I file, --config

Set configuration file to use. This option may not be available, depending upon how uuxqt was compiled.

-v, --version

Report version information and exit.

--help

Print a help message and exit.

## SEE ALSO
uucp(1), uux(1), uucico(8)

## AUTHOR
Ian Lance Taylor (ian@airs.com)


uuidd

package: uuidd

title: uuidd(8)

summary: UUID generation daemon

text:
# uuidd(8)

## NAME
uuidd - UUID generation daemon

## SYNOPSIS
uuidd [options]

## DESCRIPTION
The uuidd daemon is used by the UUID library to generate universally unique identifiers (UUIDs), especially time-based UUIDs, in a secure and guaranteed-unique fashion, even in the face of large numbers of threads running on different CPUs trying to grab UUIDs.

## OPTIONS
-C, --cont-clock[=time]

Activate continuous clock handling for time based UUIDs. uuidd could use all possible clock values, beginning with the daemon’s start time. The optional argument can be used to set a value for the max_clock_offset. This gurantees, that a clock value of a UUID will always be within the range of the max_clock_offset. The option '-C' or '--cont-clock' enables the feature with a default max_clock_offset of 2 hours.

The option '-C<NUM>[hd]' or '--cont-clock=<NUM>[hd]' enables the feature with a max_clock_offset of NUM seconds. In case of an appended h or d, the NUM value is read in hours or days. The minimum value is 60 seconds, the maximum value is 365 days.

-d, --debug

Run uuidd in debugging mode. This prevents uuidd from running as a daemon.

-F, --no-fork

Do not daemonize using a double-fork.

-k, --kill

If currently a uuidd daemon is running, kill it.

-n, --uuids number

When issuing a test request to a running uuidd, request a bulk response of number UUIDs.

-P, --no-pid

Do not create a pid file.

-p, --pid path

Specify the pathname where the pid file should be written. By default, the pid file is written to {runstatedir}/uuidd/uuidd.pid.

-q, --quiet

Suppress some failure messages.

-r, --random

Test uuidd by trying to connect to a running uuidd daemon and request it to return a random-based UUID.

-S, --socket-activation

Do not create a socket but instead expect it to be provided by the calling process. This implies --no-fork and --no-pid. This option is intended to be used only with systemd(1). It needs to be enabled with a configure option.

-s, --socket path

Make uuidd use this pathname for the unix-domain socket. By default, the pathname used is {runstatedir}/uuidd/request. This option is primarily for debugging purposes, since the pathname is hard-coded in the libuuid library.

-T, --timeout number

Make uuidd exit after number seconds of inactivity.

-t, --time

Test uuidd by trying to connect to a running uuidd daemon and request it to return a time-based UUID.

-h, --help

Display help text and exit.

-V, --version

Print version and exit.

## EXAMPLE
Start up a daemon, print 42 random keys, and then stop the daemon:

```
uuidd -p /tmp/uuidd.pid -s /tmp/uuidd.socket
uuidd -d -r -n 42 -s /tmp/uuidd.socket
uuidd -d -k -s /tmp/uuidd.socket
```

## AUTHOR
The uuidd daemon was written by Theodore Ts’o <tytso@mit.edu>.

## SEE ALSO
uuid(3), uuidgen(1)

## REPORTING BUGS
For bug reports, use the issue tracker at <https://github.com/util-linux/util-linux/issues>.

## AVAILABILITY
The uuidd command is part of the util-linux package which can be downloaded from Linux Kernel Archive <https://www.kernel.org/pub/linux/utils/util-linux/>.


imapd

package: uw-imap

title: imapd(8)

summary: Internet Message Access Protocol server

text:
# imapd(8)

## NAME
IMAPd - Internet Message Access Protocol server

## SYNOPSIS
/usr/sbin/imapd

## DESCRIPTION
imapd is a server which supports the IMAP4rev1 remote mail access protocol as documented in RFC-3501. imapd is invoked by the internet server (see inetd(8)), normally for requests to connect to the IMAP port as indicated by the /etc/services file (see services(5)). Normally, this is port 143 for plaintext IMAP and 993 for SSL IMAP.

This daemons contains CRAM-MD5 support. See the md5.txt documentation file for additional information.

imapd can also be accessed via rsh(1) by many Unix-based clients. To do this, the imapd binary must have a link to /usr/sbin/rimapd since this is where this software expects it to be located.

## SEE ALSO
rsh(1) ipopd(8)


ipopd

title: ipopd(8)

summary: Post Office Protocol server

text:
# ipopd(8)

## NAME
IPOPd - Post Office Protocol server

## SYNOPSIS
/usr/sbin/ipop2d

/usr/sbin/ipop3d

## DESCRIPTION
ipop2d and ipop3d are servers which support the POP2 and POP3 remote mail access protocols respectively. ipop2d and ipop3d can also be used by POP2 and POP3 clients respecitively to access mailboxes on IMAP servers by specifying a login user name in the form <host>:<user> e.g., SERVER.WASHINGTON.EDU:SMITH.

These daemons contain CRAM-MD5 and APOP support. See the md5.txt documentation file for additional information.

ipop2d and ipop3d are invoked by the internet server (see inetd(8)), normally for requests to connect to the POP port as indicated by the /etc/services file (see services(5)).

## SEE ALSO
imapd(8)

## BUGS
The POP2 and POP3 protocols are intrinsically less flexible than IMAP and do not maintain `read' vs `unread' state on the server. As a result, most POP based software transfers all the mail from the server to the client and deletes it from the server. This necessarily locks the user into using only a single client.

POP3 does not allow you to specify an alternate folder from the user's default.


vblade

package: vblade

title: vblade(8)

summary: export data via ATA over Ethernet

text:
# vblade(8)

## NAME
vblade, vbladed - export data via ATA over Ethernet

## SYNOPSIS

```
vblade [ -m mac[,mac...] ] shelf slot netif filename
```

## DESCRIPTION
The vblade command starts a process that uses raw sockets to perform ATA over Ethernet, acting like a virtual EtherDrive (R) blade.

The vbladed script can be used to daemonize the vblade process, detaching it from your terminal and sending its output to the system logs.

### Arguments
shelf

This should be the shelf address (major AoE address) of the AoE device to create.

slot

This should be the slot address (minor AoE address) of the AoE device to create.

netif

The name of the ethernet network interface to use for AoE communications.

filename

The name of the regular file or block device to export.

### Options
-b

The -b flag takes an argument, the advertised buffer count, specifying the maximum number of outstanding messages the server can queue for processing.

-d

The -d flag selects O_DIRECT mode for accessing the underlying block device.

-s

The -s flag selects O_SYNC mode for accessing the underlying block device, so all writes are committed to disk before returning to the client.

-r

The -r flag restricts the export of the device to be read-only.

-m

The -m flag takes an argument, a comma separated list of MAC addresses permitted access to the vblade. A MAC address can be specified in upper or lower case, with or without colons.

-o

The -o flag takes an argument, the number of sectors at the beginning of the exported file that are excluded from AoE export (default zero).

-l

The -l flag takes an argument, the number of sectors to export. Defaults to the file size in sectors minus the offset.

## EXAMPLE
In this example, the root user on a host named nai exports a file named "3TB" to the LAN on eth0 using AoE shelf address 11 and slot address 1. The process runs in the foreground. Using vbladed would have resulted in the process running as a daemon in the background.

```
nai:~# vblade 11 1 eth0 /data/3TB
```

## BUGS
Users of Jumbo frames should read the README file distributed with vblade to learn about a workaround for kernel buffering limitations.

## AUTHOR
Brantley Coile (brantley@coraid.com)


title: vde_tunctl(8)

text:
# vde_tunctl(8)

## NAME
vde_tunctl — create and manage persistent TUN/TAP interfaces

## SYNOPSIS
vde_tunctl [-f clone-dev] [-u owner] [-g group] [-n] [-t dev-name]

vde_tunctl [-f clone-dev] -d dev-name

## DESCRIPTION
vde_tunctl allows the host sysadmin to preconfigure a TUN/TAP device for use by a particular user. That user may open and use the device, but may not change any aspects of the host side of the interface.

vde_tunctl is an extension of tunctl.

vde_tunctl defines tap interfaces unless dev-name begins by "tun" or the option -n appears in the command line.

## USAGE
To create an interface for use by a particular user, invoke tunctl without the -d option:

```
# vde_tunctl -u someuser
Set 'tap0' persistent and owned by uid 500
```

Then, configure the interface as normal:

```
# ifconfig tap0 192.168.0.254 up
# route add -host 192.168.0.253 dev tap0
# bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'
# arp -Ds 192.168.0.253 eth0 pub
```

To delete the interface, use the -d option:

```
# vde_tunctl -d tap0
Set 'tap0' nonpersistent
```

To create or destroy a tun interface (instead of tap):

```
# vde_tunctl -n -u someuser
Set 'tun0' persistent and owned by uid 500
# vde_tunctl -d tun0
Set 'tun0' nonpersistent
```

## SEE ALSO
vde_switch(1) vde_plug2tap(1)

## AUTHOR
tunctl was written by Jeff Dike jdike@karaya.com

This manual page is based on tunctl manual page written by Matt Zimmerman mdz@debian.org for the Debian GNU/Linux system.


vdodmeventd

package: vdo

title: vdodmeventd(8)

text:
# vdodmeventd(8)

## NAME
vdodmeventd - register/unregister a VDO device with dmeventd

## SYNOPSIS
vdodmeventd [options...] vdo

## DESCRIPTION
vdodmeventd handles registration/unregistration by specifying vdo which is the name of a VDO device.

## OPTIONS
--help

Print this help message and exit.

--register

Register a VDO device with dmeventd.

--unregister

Unregister a VDO device with dmeventd.

--version

Show the version of vdodmevent.

## EXAMPLES
vdodmeventd --register is used to register VDO devices.

vdodmeventd --register vdo0

vdodmeventd --unregister is used to unregister VDO devices.

vdodmeventd --unregister vdo0

## SEE ALSO
vdo(8).


vdodumpconfig

title: vdodumpconfig(8)

text:
# vdodumpconfig(8)

## NAME
vdodumpconfig - dump the configuration of a VDO volume from its backing store

## SYNOPSIS
vdodumpconfig vdoBacking

## DESCRIPTION
vdodumpconfig dumps the configuration of a VDO volume.

vdoBacking must be the path of the VDODataLV as described in lvmvdo(7).

## OPTIONS
vdoBacking

The name of the file or block device used as the backing store for VDO.

## EXAMPLE

```
# lvchange -ay vdo1/vdo0pool_vdata
# vdodumpconfig /dev/mapper/vdo1-vdo0pool_vdata
# lvchange -an vdo1/vdo0pool_vdata
```

## SEE ALSO
lvmvdo(7), lvchange(8)


vdoforcerebuild

title: vdoforcerebuild(8)

text:
# vdoforcerebuild(8)

## NAME
vdoforcerebuild - prepare a VDO device to exit read-only mode

## SYNOPSIS
vdoforcerebuild filename

## DESCRIPTION
vdoforcerebuild forces an existing VDO device to exit read-only mode and to attempt to regenerate as much metadata as possible.

filename must be the path of the VDODataLV as described in lvmvdo(7). Since lvchange(8) will only mount that as read-only, a writable version of that device must be manually created, as shown in the example below.

## OPTIONS
--help

Print this help message and exit.

--version

Show the version of vdoforcerebuild.

## EXAMPLE

```
# lvchange -ay vdo1/vdo0pool_vdata
# dmsetup table vdo1-vdo0pool_vdata > vdata.table
# lvchange -an vdo1/vdo0pool_vdata
# dmsetup create vdo1-vdo0pool_vdata --table "`cat vdata.table`"
# vdoforcerebuild /dev/mapper/vdo1-vdo0pool_vdata
# dmsetup remove vdo1-vdo0pool_vdata
```

## SEE ALSO
lvmvdo(7), lvchange(8), dmsetup(8)


vdoformat

title: vdoformat(8)

summary: format a VDO device

text:
# vdoformat(8)

## NAME
vdoformat - format a VDO device

## SYNOPSIS
vdoformat [options...] filename

## DESCRIPTION
vdoformat formats the file named by filename as a VDO device. This is analogous to low-level device formatting. The device will not be formatted if it already contains a VDO, unless the --force flag is used.

vdoformat can also modify some of the formatting parameters.

## OPTIONS
--format

Format the block device, even if there is already a VDO formatted thereupon.

--help

Print this help message and exit.

--logical-size=size

Set the logical (provisioned) size of the VDO device to size. A size suffix of K for kilobytes, M for megabytes, G for gigabytes, T for terabytes, or P for petabytes is optional. The default unit is megabytes.

--slab-bits=bits

Set the free space allocator's slab size to 2^bits 4 KB blocks. bits must be a value between 4 and 23 (inclusive), corresponding to a slab size between 128 KB and 32 GB. The default value is 19 which results in a slab size of 2 GB. This allocator manages the space VDO uses to store user data. The maximum number of slabs in the system is 8192, so this value determines the maximum physical size of a VDO volume. One slab is the minimum amount by which a VDO volume can be grown. Smaller slabs also increase the potential for parallelism if the device has multiple physical threads. Therefore, this value should be set as small as possible, given the eventual maximal size of the volume.

--uds-memory-size=gigabytes

Specify the amount of memory, in gigabytes, to devote to the index. Accepted options are .25, .5, .75, and all positive integers.

--uds-sparse

Specify whether or not to use a sparse index.

--verbose

Describe what is being formatted and with what parameters.

--version

Show the version of vdoformat.

## SEE ALSO
vdo(8).


vdosetuuid

title: vdosetuuid(8)

text:
# vdosetuuid(8)

## NAME
vdosetuuid - sets a new uuid for the vdo volume stored on a backing store

## SYNOPSIS
vdosetuuid [options...] vdoBacking

## DESCRIPTION
vdosetuuid sets a new uuid for the VDO volume stored on the vdoBacking device.

vdoBacking must be the path of the VDODataLV as described in lvmvdo(7). Since lvchange(8) will only mount that as read-only, a writable version of that device must be manually created, as shown in the example below.

## OPTIONS
--help

Print this help message and exit.

--uuid

Sets the uuid value that is stored in the VDO device. If not specified, the uuid is randomly generated.

--version

Show the version of vdosetuuid.

## EXAMPLE

```
# lvchange -ay vdo1/vdo0pool_vdata
# dmsetup table vdo1-vdo0pool_vdata > vdata.table
# lvchange -an vdo1/vdo0pool_vdata
# dmsetup create vdo1-vdo0pool_vdata --table "`cat vdata.table`"
# vdosetuuid --uuid 6ecb9db8-[...] /dev/mapper/vdo1-vdo0pool_vdata
# dmsetup remove vdo1-vdo0pool_vdata
```

## SEE ALSO
lvmvdo(7), lvchange(8), dmsetup(8)


vdostats

title: vdostats(8)

text:
# vdostats(8)

## NAME
vdostats - Display configuration and statistics of VDO volumes

## SYNOPSIS
vdostats [options ...] [device [device ...]]

## DESCRIPTION
vdostats displays configuration and statistics information for the given VDO devices. If no devices are given, it displays information about all VDO devices.

The VDO devices must be running in order for configuration and statistics

information to be reported.

## OPTIONS
-h, --help

Show help message and exit.

-a, --all

This option is only for backwards compatibility. It is now equivalent to --verbose.

--human-readable

Display block values in readable form (Base 2: 1 KB = 2^10 bytes = 1024 bytes).

--si

Modifies the output of the --human-readable option to use SI units (Base 10: 1 KB = 10^3 bytes = 1000 bytes). If the --human-readable option is not supplied, this option has no effect.

-v, --verbose

Displays the utilization and block I/O (bios) statistics for the selected VDO devices.

-V, --version

Prints the vdostats version number and exits

## OUTPUT
The default output format is a table with the following columns, similar to that of the Linux df utility:

Device

The path to the VDO volume

1K-blocks

The total number of 1K blocks allocated for a VDO volume (= physical volume size * block size / 1024)

Used

The total number of 1K blocks used on a VDO volume (= physical blocks used * block size / 1024)

Available

The total number of 1K blocks available on a VDO volume (= physical blocks free * block size / 1024)

Use%

The percentage of physical blocks used on a VDO volume (= used blocks / allocated blocks * 100)

Space Saving%

The percentage of physical blocks saved on a VDO volume (= [logical blocks used - physical blocks used] / logical blocks used)

## VERBOSE OUTPUT
The --verbose option displays VDO device statistics in YAML format for the specified VDO devices. The following fields will continue to be reported in future releases. Management tools should not rely upon the order in which any of the statistics are reported.

version

The version of these statistics.

release version

The release version of the VDO.

data blocks used

The number of physical blocks currently in use by a VDO volume to store data.

overhead blocks used

The number of physical blocks currently in use by a VDO volume to store VDO metadata.

logical blocks used

The number of logical blocks currently mapped.

physical blocks

The total number of physical blocks allocated for a VDO volume.

logical blocks

The maximum number of logical blocks that can be mapped by a VDO volume.

1K-blocks

The total number of 1K blocks allocated for a VDO volume (= physical volume size * block size / 1024)

1K-blocks used

The total number of 1K blocks used on a VDO volume (= physical blocks used * block size / 1024)

1K-blocks available

The total number of 1K blocks available on a VDO volume (= physical blocks free * block size / 1024)

used percent

The percentage of physical blocks used on a VDO volume (= used blocks / allocated blocks * 100)

saving percent

The percentage of physical blocks saved on a VDO volume (= [logical blocks used - physical blocks used] / logical blocks used)

block map cache size

The size of the block map cache, in bytes.

write policy

The write policy (sync, async, or async-unsafe). This is configured via vdo modify --writePolicy=policy.

block size

The block size of a VDO volume, in bytes.

completed recovery count

The number of times a VDO volume has recovered from an unclean shutdown.

read-only recovery count

The number of times a VDO volume has been recovered from read-only mode (via vdo start --forceRebuild).

operating mode

Indicates whether a VDO volume is operating normally, is in recovery mode, or is in read-only mode.

recovery progress (%)

Indicates online recovery progress, or N/A if the volume is not in recovery mode.

compressed fragments written

The number of compressed fragments that have been written since the VDO volume was last restarted.

compressed blocks written

The number of physical blocks of compressed data that have been written since the VDO volume was last restarted.

The remaining fields are primarily intended for software support and are subject to change in future releases; management tools should not rely upon them.

compressed fragments in packer

The number of compressed fragments being processed that have not yet been written.

slab count

The total number of slabs.

slabs opened

The total number of slabs from which blocks have ever been allocated.

slabs reopened

The number of times slabs have been re-opened since the VDO was started.

journal disk full count

The number of times a request could not make a recovery journal entry because the recovery journal was full.

journal commits requested count

The number of times the recovery journal requested slab journal commits.

journal entries batching

The number of journal entry writes started minus the number of journal entries written.

journal entries started

The number of journal entries which have been made in memory.

journal entries writing

The number of journal entries in submitted writes minus the number of journal entries committed to storage.

journal entries written

The total number of journal entries for which a write has been issued.

journal entries committed

The number of journal entries written to storage.

journal blocks batching

The number of journal block writes started minus the number of journal blocks written.

journal blocks started

The number of journal blocks which have been touched in memory.

journal blocks writing

The number of journal blocks written (with metadatata in active memory) minus the number of journal blocks committed.

journal blocks written

The total number of journal blocks for which a write has been issued.

journal blocks committed

The number of journal blocks written to storage.

slab journal disk full count

The number of times an on-disk slab journal was full.

slab journal flush count

The number of times an entry was added to a slab journal that was over the flush threshold.

slab journal blocked count

The number of times an entry was added to a slab journal that was over the blocking threshold.

slab journal blocks written

The number of slab journal block writes issued.

slab journal tail busy count

The number of times write requests blocked waiting for a slab journal write.

slab summary blocks written

The number of slab summary block writes issued.

reference blocks written

The number of reference block writes issued.

block map dirty pages

The number of dirty pages in the block map cache.

block map clean pages

The number of clean pages in the block map cache.

block map free pages

The number of free pages in the block map cache.

block map failed pages

The number of block map cache pages that have write errors.

block map incoming pages

The number of block map cache pages that are being read into the cache.

block map outgoing pages

The number of block map cache pages that are being written.

block map cache pressure

The number of times a free page was not available when needed.

block map read count

The total number of block map page reads.

block map write count

The total number of block map page writes.

block map failed reads

The total number of block map read errors.

block map failed writes

The total number of block map write errors.

block map reclaimed

The total number of block map pages that were reclaimed.

block map read outgoing

The total number of block map reads for pages that were being written.

block map found in cache

The total number of block map cache hits.

block map discard required

The total number of block map requests that required a page to be discarded.

block map wait for page

The total number of requests that had to wait for a page.

block map fetch required

The total number of requests that required a page fetch.

block map pages loaded

The total number of page fetches.

block map pages saved

The total number of page saves.

block map flush count

The total number of flushes issued by the block map.

invalid advice PBN count

The number of times the index returned invalid advice

no space error count

The number of write requests which failed due to the VDO volume being out of space.

read only error count

The number of write requests which failed due to the VDO volume being in read-only mode.

instance

The VDO instance.

512 byte emulation

Indicates whether 512 byte emulation is on or off for the volume.

current VDO IO requests in progress

The number of I/O requests the VDO is current processing.

maximum VDO IO requests in progress

The maximum number of simultaneous I/O requests the VDO has processed.

current dedupe queries

The number of deduplication queries currently in flight.

maximum dedupe queries

The maximum number of in-flight deduplication queries.

dedupe advice valid

The number of times deduplication advice was correct.

dedupe advice stale

The number of times deduplication advice was incorrect.

dedupe advice timeouts

The number of times deduplication queries timed out.

concurrent data matches

The number of writes with the same data as another in-flight write.

concurrent hash collisions

The number of writes whose hash collided with an in-flight write.

flush out

The number of flush requests submitted by VDO to the underlying storage.

write amplification ratio

The average number of block writes to the underlying storage per block written to the VDO device.

bios in...

bios in partial...

bios out...

bios meta...

bios journal...

bios page cache...

bios out completed...

bios meta completed...

bios journal completed...

bios page cache completed...

bios acknowledged...

bios acknowledged partial...

bios in progress...

These statistics count the number of bios in each category with a given flag. The categories are: bios in

The number of block I/O requests received by VDO.

bios in partial

The number of partial block I/O requests received by VDO. Applies only to 512-byte emulation mode.

bios out

The number of non-metadata block I/O requests submitted by VDO to the storage device.

bios meta

The number of metadata block I/O requests submitted by VDO to the storage device.

bios journal

The number of recovery journal block I/O requests submitted by VDO to the storage device.

bios page cache

The number of block map I/O requests submitted by VDO to the storage device.

bios out completed

The number of non-metadata block I/O requests completed by the storage device.

bios meta completed

The number of metadata block I/O requests completed by the storage device.

bios journal completed

The number of recovery journal block I/O requests completed by the storage device.

bios page cache completed

The number of block map I/O requests completed by the storage device.

bios acknowledged

The number of block I/O requests acknowledged by VDO.

bios acknowledged partial

The number of partial block I/O requests acknowledged by VDO. Applies only to 512-byte emulation mode.

bios in progress

The number of bios submitted to the VDO which have not yet been acknowledged.

There are five types of flags:

read

The number of non-write bios (bios without the REQ_WRITE flag set)

write

The number of write bios (bios with the REQ_WRITE flag set)

discard

The number of bios with a REQ_DISCARD flag set

flush

The number of flush bios (bios with the REQ_FLUSH flag set)

fua

The number of "force unit access" bios (bios with the REQ_FUA flag set)

Note that all bios will be counted as either read or write bios, depending on the REQ_WRITE flag setting, regardless of whether any of the other flags are set.

KVDO module bytes used

The current count of bytes allocated by the kernel VDO module.

KVDO module peak bytes used

The peak count of bytes allocated by the kernel VDO module, since the module was loaded.

## EXAMPLES
The following example shows sample output if no options are provided:

```
Device             1K-blocks  Used       Available   Use% Space Saving%
/dev/mapper/my_vdo 1932562432 427698104  1504864328  22%  21%
```

With the --human-readable option, block counts are converted to conventional units (1 KB = 1024 bytes):

```
Device             Size   Used    Available   Use%   Space Saving%
/dev/mapper/my_vdo 1.8T   407.9G  1.4T        22%    21%
```

With the --si option as well, the block counts are reported using SI units (1 KB = 1000 bytes):

```
Device             Size   Used    Available   Use%    Space Saving%
/dev/mapper/my_vdo 2.0T   438G    1.5T        22%     21%
```

## NOTES
The output may be incomplete when the command is run by an unprivileged user.

## SEE ALSO
vdo(8).


adaptlvm

package: vdo-support

title: adaptlvm(8)

summary: Adapts an LVMVDO base storage to RW

text:
# adaptlvm(8)

## NAME
adaptlvm - Adapts an LVMVDO base storage to RW

## SYNOPSIS
adaptlvm filename

## DESCRIPTION
adaptlvm Tears down an LVMVDO stack to expose the VDO backing device as read only.

## OPTIONS
setRW

Set the backing storage as Read/Write

setRO

Sets the backing storage back to Read-Only

volume_group/logical_volume

The volume group name and logical volume name for the LVMVDO volume

## SEE ALSO
vdo(8).


vdoaudit

title: vdoaudit(8)

text:
# vdoaudit(8)

## NAME
vdoaudit - confirm the reference counts of a VDO device

## SYNOPSIS
vdoaudit [options...] filename

## DESCRIPTION
vdoaudit adds up the logical block references to all physical blocks of a VDO device found in filename, then compares that sum to the stored number of logical blocks. It also confirms all of the actual reference counts on all physical blocks against the stored reference counts. Finally, it validates that the slab summary approximation of the free blocks in each slab is correct.

filename must be the path of the VDODataLV as described in lvmvdo(7).

If --verbose is specified, a line item will be reported for each inconsistency; otherwise a summary of the problems will be displayed.

## OPTIONS
--help

Print this help message and exit.

--summary

Display a summary of any problems found on the volume.

--verbose

Display a line item for each inconsistency found on the volume.

--version

Show the version of vdoaudit.

## EXAMPLE

```
# lvchange -ay vdo1/vdo0pool_vdata
# vdoaudit --verbose /dev/mapper/vdo1-vdo0pool_vdata
# lvchange -an vdo1/vdo0pool_vdata
```

## SEE ALSO
lvmvdo(7), lvchange(8)


vdodebugmetadata

title: vdodebugmetadata(8)

summary: load a metadata dump of a VDO device

text:
# vdodebugmetadata(8)

## NAME
vdodebugmetadata - load a metadata dump of a VDO device

## SYNOPSIS
vdodebugmetadata [--pbn=pbn ...] [--searchLBN=lbn ...] filename

## DESCRIPTION
vdodebugmetadata loads the metadata regions dumped by vdodumpmetadata. It should be run under GDB, with a breakpoint on the function doNothing.

Variables vdo, slabSummary, slabs, and recoveryJournal are available, providing access to the VDO super block state, the slab summary blocks, all slab journal and reference blocks per slab, and all recovery journal blocks.

Please note that this tool does not provide access to block map pages.

## OPTIONS
--pbn

Print the slab journal entries for the given PBN. This option may be specified up to 255 times.

--searchLBN

Print the recovery journal entries for the given LBN. This includes PBN, increment/decrement, mapping state, recovery journal position information, and whether the recovery journal block is valid. This option may be specified up to 255 times.

## SEE ALSO
vdo(8), vdodumpmetadata(8).


vdodumpblockmap

title: vdodumpblockmap(8)

text:
# vdodumpblockmap(8)

## NAME
vdodumpblockmap - dump the LBA->PBA mappings of a VDO device

## SYNOPSIS
vdodumpblockmap [--lba=lba] filename

## DESCRIPTION
vdodumpblockmap dumps all (or only the specified) LBA->PBA mappings from a cleanly shut down VDO device.

filename must be the path of the VDODataLV as described in lvmvdo(7).

## OPTIONS
--help

Print this help message and exit.

--lba

Dump only the mapping for the specified LBA.

--version

Show the version of vdodumpblockmap.

## EXAMPLE

```
# lvchange -ay vdo1/vdo0pool_vdata
# vdodumpblockmap /dev/mapper/vdo1-vdo0pool_vdata
# lvchange -an vdo1/vdo0pool_vdata
```

## SEE ALSO
lvmvdo(7), lvchange(8)


vdodumpmetadata

title: vdodumpmetadata(8)

text:
# vdodumpmetadata(8)

## NAME
vdodumpmetadata - dump the metadata regions from a VDO device

## SYNOPSIS
vdodumpmetadata [--no-block-map] [--lbn=lbn] vdoBacking outputFile

## DESCRIPTION
vdodumpmetadata dumps the metadata regions of a VDO device to another file, to enable save and transfer of metadata from a VDO without transfer of the entire backing store.

vdoBacking must be the path of the VDODataLV as described in lvmvdo(7).

vdodumpmetadata will produce a large output file. The expected size is roughly equal to VDO's metadata size. A rough estimate of the storage needed is 1.4 GB per TB of logical space.

## OPTIONS
--no-block-map

Omit the block map. The output file will be of size no higher than 130MB + (9 MB per slab).

--lbn

Saves the block map page associated with the specified LBN in the output file. This option may be specified up to 255 times. Implies --no-block-map.

## EXAMPLE

```
# lvchange -ay vdo1/vdo0pool_vdata
# vdodumpmetadata /dev/mapper/vdo1-vdo0pool_vdata vdo1-meta-dump
# lvchange -an vdo1/vdo0pool_vdata
```

## SEE ALSO
lvmvdo(7), lvchange(8), vdodebugmetadata(8)


vdolistmetadata

title: vdolistmetadata(8)

text:
# vdolistmetadata(8)

## NAME
vdolistmetadata - list the metadata regions on a VDO device

## SYNOPSIS
vdolistmetadata filename

## DESCRIPTION
vdolistmetadata lists the metadata regions of a VDO device as ranges of block numbers. Each range is on a separate line of the form:

```
  startBlock .. endBlock: label
```

Both endpoints are included in the range, and are the zero-based indexes of 4KB VDO metadata blocks on the backing device.

filename must be the path of the VDODataLV as described in lvmvdo(7).

## OPTIONS
--help

Print this help message and exit.

--version

Show the version of vdolistmetadata.

## EXAMPLE

```
# lvchange -ay vdo1/vdo0pool_vdata
# vdolistmetadata /dev/mapper/vdo1-vdo0pool_vdata
# lvchange -an vdo1/vdo0pool_vdata
```

## SEE ALSO
lvmvdo(7), lvchange(8)


vdoreadonly

title: vdoreadonly(8)

summary: puts a VDO device into read-only mode

text:
# vdoreadonly(8)

## NAME
vdoreadonly - puts a VDO device into read-only mode

## SYNOPSIS
vdoreadonly filename

## DESCRIPTION
vdoreadonly forces an existing VDO device into read-only mode.

filename must be the path of the VDODataLV as described in lvmvdo(7). Since lvchange(8) will only mount that as read-only, a writable version of that device must be manually created, as shown in the example below.

## OPTIONS
--help

Print this help message and exit.

--version

Show the version of vdoreadonly.

## EXAMPLE

```
# lvchange -ay vdo1/vdo0pool_vdata
# dmsetup table vdo1-vdo0pool_vdata > vdata.table
# lvchange -an vdo1/vdo0pool_vdata
# dmsetup create vdo1-vdo0pool_vdata --table "`cat vdata.table`"
# vdoreadonly /dev/mapper/vdo1-vdo0pool_vdata
# dmsetup remove vdo1-vdo0pool_vdata
```

## SEE ALSO
lvmvdo(7), lvchange(8), dmsetup(8)


vdorecover

title: vdorecover(8)

text:
# vdorecover(8)

## NAME
vdorecover - Recovers available storage by discarding a full VDO volume.

## SYNOPSIS
vdorecover vdo_device

## DESCRIPTION
vdorecover Recovers available physical space on a full VDO volume by mounting it temporarily with snapshots and sending discards to it.

## OPTIONS
vdo_device

The VDO device to recover

## SEE ALSO
vdo(8).


vdoregenerategeometry

title: vdoregenerategeometry(8)

text:
# vdoregenerategeometry(8)

## NAME
vdoregenerategeometry - regenerate a VDO whose first few blocks have been wiped

## SYNOPSIS
vdoregenerategeometry [options...] filename

## DESCRIPTION
vdoregenerategeometry will attempt to regenerate the geometry block of a VDO device in the event that the beginning of the backing store was wiped. This tool will fail if enough of the device was wiped that the VDO super block was also erased, or if there are multiple valid super block candidates on the volume.

filename must be the path of the VDODataLV as described in lvmvdo(7). Since lvchange(8) will only mount that as read-only, a writable version of that device must be manually created, as shown in the example below.

If the super block location is known, or to select one of the candidate super blocks in the event that multiple candidates were found, the --offset option can be used to specify the location (in bytes) of the super block on the backing store.

## OPTIONS
--help

Print this help message and exit.

--offset

Specify the location (in bytes) of the super block.

--version

Show the version of vdoregenerategeometry.

## EXAMPLE

```
# lvchange -ay vdo1/vdo0pool_vdata
# dmsetup table vdo1-vdo0pool_vdata > vdata.table
# lvchange -an vdo1/vdo0pool_vdata
# dmsetup create vdo1-vdo0pool_vdata --table "`cat vdata.table`"
# vdoregenerategeometry /dev/mapper/vdo1-vdo0pool_vdata
# dmsetup remove vdo1-vdo0pool_vdata
```

## SEE ALSO
lvmvdo(7), lvchange(8), dmsetup(8)


vdsmd

package: vdsm

title: vdsmd(8)

summary: Virtual Desktops and Servers Manager

text:
# vdsmd(8)

## NAME
vdsmd - Virtual Desktops and Servers Manager

@ENGINENAME@ host agent

## SYNOPSIS
service vdsmd start

## DESCRIPTION
The VDSM service is required by a @ENGINENAME@ to manage oVirt Nodes and Linux hosts. Currently, only Fedora and Red Hat Enterprise Linux are supported. VDSM manages and monitors the host's storage, memory and networks as well as virtual machine creation, other host administration tasks, statistics gathering, and log collection.

VDSM should be run as a daemon on each node managed by @ENGINENAME@. It answers XML-RPC calls from clients (mostly @ENGINENAME@).

## HOOKS
VDSM is extendible: it has hooks in strategic locations, where it executes external scripts. Hooks API is new and is subject to future changes. Currently-supported hooks have self-explanatory names:

before_vm_start, after_vm_start,

before_vm_cont, after_vm_cont,

before_vm_pause, after_vm_pause,

before_vm_hibernate, after_vm_hibernate,

before_vm_dehibernate, after_vm_dehibernate,

before_vm_migrate_source, after_vm_migrate_source,

before_vm_migrate_destination, after_vm_migrate_destination,

before_device_migrate_source, after_device_migrate_source,

before_device_migrate_destination, after_device_migrate_destination,

before_vm_destroy, after_vm_destroy,

before_vm_set_ticket, after_vm_set_ticket,

before_device_create, after_device_create,

before_device_destroy, after_device_destroy,

before_nic_hotplug, after_nic_hotplug, after_nic_hotplug_fail,

before_nic_hotunplug, after_nic_hotunplug, after_nic_hotunplug_fail,

before_update_device, after_update_device, after_update_device_fail,

after_disk_prepare,

before_disk_hotplug, after_disk_hotplug,

before_disk_hotunplug, after_disk_hotunplug,

before_vdsm_start, after_vdsm_stop,

before_network_setup, after_network_setup, after_network_setup_fail,

before_set_num_of_cpus, after_set_num_of_cpus,

before_get_vm_stats, after_get_vm_stats,

before_get_all_vm_stats, after_get_all_vm_stats,

before_get_caps, after_get_caps,

before_get_stats, after_get_stats,

after_hostdev_list_by_caps,

before_memory_hotplug, after_memory_hotplug.

Each hook executes the scripts under /usr/libexec/vdsm/hooks/<hook-name>/ in lexicographic order.

### Hook environment
Each hook script (except before_vdsm_start, after_vdsm_stop, before_network_setup, after_network_setup and after_network_setup_fail, before_get_vm_stats, after_get_vm_stats, before_get_all_vm_stats, after_get_all_vm_stats, before_get_caps, after_get_caps, before_get_stats, after_get_stats, after_hostdev_list_by_caps) inherit the environment of the VDSM process, with an additional variable _hook_domxml which holds the path of libvirt's domain xml representation of the relevant virtual machine. The uuid of the virtual machine may be deduced from that xml, but it is also available as the environment variable vmId.

The before_network_setup, after_network_setup and after_network_setup_fail hooks do also include an extra environment variable _hook_json which holds a pointer to a file with the network parameters that vdsm is setting up ( request ) , the request may be modified by the before_network_setup hook as thus affect the operation ultimately taken place by Vdsm.

The JSON format of this file for before_network_setup, after_network_setup and after_network_setup_fail has one section: request, this section contains networks, bondings and options, those parameters are specified in the setupNetworks VDSM API call.

```
{"request":

    {

    "networks": {"virtnet": {"bonding" : "bond0", "bridged": true, "vlan":27}},

    "bondings": {"bond0": {"nics":["eth1","eth2"]}},

    "options":  {"conectivityCheck":false}

    }

 }
```

The after_disk_prepare hook is invoked after a disk is prepared during VM create, resume, recovery and incoming migration flows. Warning: In incoming migration flow, the hook should finish quickly to avoid migration timeout.

The after_disk_prepare hook includes only a _hook_json key with a filename where the disk info is stored in JSON format:

```
{

    "disk": {

        "diskType": "file",

        "device": "disk",

        "domainID": "uuid",

        "format": "cow",

        "imageID": "uuid",

        "path": "/path/to/disk",

        "volumeID": "uuid"

        ...

    }
}
```

See the VmDiskDevice type in vdsm schema for the complete contents of the disk info dict.

If the after_disk_prepare hook modify the disk, vdsm will use the modified disk instead of the original disk. See vdsm_hooks/localdisk for example for converting a shared disk of any type to a local block device.

Hooks that handle NIC hotplug, hotunplug and update device have the _hook_domxml variable but it contains the representation of the NIC rather than the VM. Hotplug/hotunplug disk hooks also have the _hook_dom_xml variable, which contains the drive definition (not the VM). All hook points that are device specific get the xml of the device instead of the entire VM. Such hooks are listed below.

On top of these, @ENGINENAME@ allows to set a collection of "custom parameters" for each virtual machine. Each of these parameters is provided to hooks as an environment variable.

before_migration_destination (and before_dehibernation) hooks currently receive the xml of the domain from the source host. The xml of the domain at the destination will differ in various details.

The environment of before_vm_set_ticket and after_vm_set_ticket hooks is augmented with a set of params passed by the caller of setVmTicket.

The environment of before_vm_dehibernate and after_vm_dehibernate hooks have FROM_SNAPSHOT variable set to True if the VM is being restored from a live snapshot.

The environment of hooks specific to devices:

before_nic_hotplug, after_nic_hotplug, after_nic_hotplug_fail,

before_nic_hotunplug, after_nic_hotunplug, after_nic_hotunplug_fail,

before_update_device, after_update_device, after_update_device_fail,

before_disk_hotplug, after_disk_hotplug,

before_disk_hotunplug, after_disk_hotunplug,

before_device_create, after_device_create,

before_device_destroy, after_device_destroy,

before_device_migrate_source, after_device_migrate_source,

before_device_migrate_destination, after_device_migrate_destination,

before_memory_hotplug, after_memory_hotplug.

Are all augmented by custom properties specific to those devices, sent by the caller of the hook. For example if before_nic_hotplug is called with custom: {qos: '0.5', color: 'red'} then qos and color will be directly available as environment variables when before_nic_hotplug is called.

before_get_vm_stats and before_get_all_vm_stats are called upon API request to get VM statistics, before getVmStats and getAllVmStats respectively. Those hooks do not receive any parameters.

after_get_vm_stats and after_get_all_vm_stats are called upon getVmStats and getAllVmStats respectively. Both receive a parameter in _hook_json containing a list of dictionaries of VM stats (in case of after_get_vm_stats the list will have a single element):

```
[
	{"vm_id": "...", ... },
	{"vm_id": "...", ... },
	...
]
```

before_get_caps and after_get_caps are called before (and after) a getVdsCapabilities API request. after_get_caps receives the complete capabilities dictionary within _hook_json.

before_get_stats and after_get_stats are called before (and after) a getVdsStats API request. after_get_stats receives the complete host statistics dictionary within _hook_json.

### Hook execution
before_vdsm_start script is executed as user root. All the other hooks are executed as user vdsm.

before_vm_start scripts may edit the domain xml file (pointed by _hook_domxml ) in order to change VDSM's definition of a virtual machine before it reaches libvirt. As with all hooks, the China Store Rule applies - if you break something, you own it. Any script can mess up VDSM's operation badly. In particular, you may never change the uuid of the domain, and should better know what you are doing if you remove a device from the domain.

before_vm_start and before_device_create may alter the vm start behavior by modifying the vm libvirt vm startup flags. The flag must be written to the /run/vdsm/hook/<vm id>/launchflags file, the required value being a decimal based on the libvirt virDomainCreateFlags enum values.

Standard error of hook scripts is collected into VDSM's log, which may be used by scripts for debugging.

As a somewhat silly example, let us think of a script that warns when a domain with too much memory is started on a host:

```
    #!/bin/bash

    mem=`/usr/bin/xpath $_hook_domxml '/domain/memory/text()' 2> /dev/null`

    if [ "$mem" -gt 1073741824 ]; then

        echo "Domain with more than Gb!" >&2

    fi

    exit 0
```

### Hook return code
Hook script must return one of the following return codes:

0

the hook script ended successfully.

1

the hook script failed, other hooks should be processed.

2

the hook script failed, no further hooks should be processed.

>2

reserved.

If a before_<action> hook fails, the <action> would be aborted.

However, before_vm_destroy's failure does not abort destroy().

## FILES
/etc/vdsm/vdsm.conf

VDSM main configuration file. Use with great caution; some information about available variables and their meaning appear in /usr/share/doc/vdsm-<version>/vdsm.conf.sample

/var/log/vdsm/vdsm.log

Default log location for vdsm.

/usr/share/doc/vdsm-<version>/vdsm-api.html

vdsm QAPI documentation.

/etc/pki/vdsm

VDSM's trust store: server key, certificate, and @ENGINENAME@ CA's certificate.

/var/lib/vdsm/data-center

VDSM's image repository, or more exactly, links to NFS exports and iSCSI or FiberChannel devices which VDSM uses.

## SEE ALSO
vdsm-client(1)

https://www.ovirt.org/develop/developer-guide/vdsm/vdsm/

https://github.com/oVirt/vdsm

https://travis-ci.org/oVirt/vdsm

## AUTHOR
VDSM was written by Ayal Baron, Barak Azulay, Cyril Plisko, Dan Kenigsberg, Doron Fediuck, Igor Lvovsky, Saggi Mizrahi, Shahar Frank, Simon Grinberg, and probably others.

## BUGS
Report bugs to <http://bugzilla.redhat.com>

## COPYRIGHT
Copyright 2010-2017 Red Hat, Inc. License GPLv2: GNU GPL Version 2 <http://gnu.org/licenses/gpl.html>.


vhostmd

package: vhostmd

title: vhostmd(8)

summary: A metrics gathering daemon.

text:
# vhostmd(8)

## NAME
vhostmd - A metrics gathering daemon.

## SYNOPSIS
vhostmd [ OPTION ]

## DESCRIPTION
vhostmd provides a "metrics communication channel" between a host and its hosted virtual machines, allowing limited introspection of host resource usage from within virtual machines. This functionality may be useful in hosting environments, giving virtual machine administrators a limited view of host resource consumption - potentially explaining a performance degradation within the virtual machine.

vhostmd will periodically write metrics to a disk. The metrics to write, how often, and where to write them are all adjustable via the /etc/vhostmd/vhostmd.conf configuration file. The disk can then be surfaced read-only to virtual machines using tools provided by the host's virtualization platform.

## OPTIONS
-h, --help

Display help and exit

-v, --verbose

Verbose messages

-d, --no-daemonize

Process will not daemonize

-c, --connect <uri>

Set the libvirt URI. If unspecified then we connect to the default libvirt hypervisor. It is recommended that you specify this since libvirt's method for choosing the default hypervisor can give unexpected results.

-u, --user <user>

Drop root privileges and run as the named non-root user.

-p, --pid-file <file>

Specify an alternate path for vhostmd to record its process-id in. Normally /var/run/vhostmd.pid

-f, --config <file>

Specify a different configuration file. Normally /etc/vhostmd/vhostmd.conf

## CONFIG FILE
At startup, vhostmd reads /etc/vhostmd/vhostmd.conf, if it exists.

(See the -f option.)

The default configuration file (listed below) defines a 256Kbyte metrics disk in /dev/shm/vhostmd0, updated every 5 seconds. It also includes a few examples of user-defined metrics, which provide a (currently simplistic) mechanism for extending metrics gathered by vhostmd.

<vhostmd>

<globals>

<disk>

<name>host-metrics-disk</name>

<path>/dev/shm/vhostmd0</path>

<size unit="k">256</size>

</disk>

<update_period>5</update_period>

<path>/usr/bin:/usr/sbin:/usr/share/vhostmd/scripts</path>

</globals>

<metrics>

<metric type="string" context="host">

<name>HostName</name>

<action>virsh hostname | tr -d '[:space:]'</action>

</metric>

<metric type="string" context="host">

<name>VirtualizationVendor</name>

<action>/bin/rpm -q --info xen | grep Vendor: |

awk '{print substr($0, index($0,$5)) }'</action>

</metric>

<metric type="uint32" context="host">

<name>TotalPhyCPUs</name>

<action>xm info | gawk '/^nr_cpus/ {print $3}'</action>

</metric>

<metric type="uint32" context="host">

<name>NumCPUs</name>

<action>xm info | gawk '/^nr_cpus/ {print $3}'</action>

</metric>

<metric type="uint64" context="host">

<name>TotalPhyMem</name>

<action>xm info | gawk '/^total_memory/ {print $3}'</action>

</metric>

<metric type="uint64" context="host">

<name>UsedMem</name>

<action>xentop -b -i 1 | gawk '/Domain-0/ {print $5}'</action>

</metric>

<metric type="uint64" context="host">

<name>FreeMem</name>

<action>xm info | gawk '/^max_free_memory/ {print $3}'</action>

</metric>

<metric type="uint64" context="host">

<name>PagedInMemory</name>

<action>vmstat -s | gawk '/pages paged in/ {print $1}'</action>

</metric>

<metric type="uint64" context="host">

<name>PagedOutMemory</name>

<action>vmstat -s | gawk '/pages paged out/ {print $1}'</action>

</metric>

<metric type="group" context="host">

<name>PageRates</name>

<action>pagerate.pl</action>

<variable name="PageInRate" type="uint64"/>

<variable name="PageFaultRate" type="uint64"/>

</metric>

<metric type="real64" context="host">

<name>TotalCPUTime</name>

<action>virsh dominfo 0 | sed 's/: */:/' |

gawk -F: '/CPU time/ {print $2;}'</action>

</metric>

<metric type="real64" context="vm">

<name>TotalCPUTime</name>

<action>virsh dominfo NAME | sed 's/: */:/' |

gawk -F: '/CPU time/ {print $2;}'</action>

</metric>

<metric type="xml" context="vm">

<name>my-metric</name>

<action>xml-metrics-test.sh</action>

</metric>

</metrics>

</vhostmd>

A valid configuration file must contain the root element <vhostmd>. The <globals> element contains configuration global to vhostmd, such as the metrics disk path and the metrics refresh interval. The <metrics> element is a container for all of the <metric> elements. A metric element is used to define a metric, giving it a name and an action that produces the metric value.

The supplied vhostmd configuration file provides a useful set of default metrics to be collected. This can be extended or modified by editing /etc/vhostmd/vhostmd.conf and changing existing metric definitions or adding new metric definitions under the metrics container.

Defined metrics begin with the <metric> element, which contains three attributes: type, context, and unit. The type attribute is used to describe the metric's value type. Supported types are int32, uint32, int64, uint64, real32, real64, string, group, and xml. group is used when an action returns more than one metric value. xml is the most flexible type and specifies that the metric's action returns valid metric XML. The context attribute is used to indicate whether this is a host or vm metric. Supported contexts are host and vm. The optional unit attribute describes the unit of measure produced for the metric by the defined action.

Currently, the metric element contains 3 elements: name, action, and variable. The name element defines the metric's name. The action element describes a command or pipeline of commands used to gather the metric.

Any <action> element can contain the magic token CONNECT which is replaced with the string "--connect 'uri'" where uri is the libvirt connection URI (specified on the command line to vhostmd as the -c option). If it wasn't specified, then the token CONNECT is substituted with the empty string. This allows you to write virsh commands like this:

virsh -r CONNECT command ...

For metrics of vm context, the tokens NAME, VMID, and UUID may be used where these attributes of a VM are normally provided in a command. When the metric is sampled, these tokens will be substituted with the actual name, ID, or UUID of the vm currently being sampled by vhostmd.

If the metric type is xml, action is expected to return valid metric XML as defined below in "XML Format of Content".

## Metrics Disk Format
Currently, the disk format is quite simple: a raw, file-backed disk containing a header, immediately followed by metric content.

The header contains the following, all in network-byte order

- 4 byte signature, 'mvbd'

- 4 byte busy flag

- 4 byte content checksum

- 4 byte content length

The busy flag permits simple reader/writer synchronization. The busy flag can be checked for clear, content read into a buffer, and the busy flag checked again for clear to ensure stable content.

## XML Format of Content
The content is an XML document containing default and user-defined metrics. The format is quite similar to the metrics definitions found in the vhostmd configuration file. A notable addition, as illustrated below, is the value element containing the metric's current value.

<metrics>

<metric type='real64' context='host'>

<name>TotalCPUTime</name>

<value>846.600000</value>

</metric>

<metric type='uint64' context='host'>

<name>PageInRate</name>

<value>0.000000</value>

</metric>

<metric type='uint64' context='host'>

<name>PageFaultRate</name>

<value>0.000000</value>

</metric>

<metric type='uint64' context='host'>

<name>PagedOutMemory</name>

<value>6885044</value>

</metric>

<metric type='uint64' context='host'>

<name>PagedInMemory</name>

<value>2367980</value>

</metric>

<metric type='uint64' context='host'>

<name>FreeMem</name>

<value>829</value>

</metric>

<metric type='uint64' context='host'>

<name>UsedMem</name>

<value>1369088</value>

</metric>

<metric type='uint64' context='host'>

<name>TotalPhyMem</name>

<value>1919</value>

</metric>

<metric type='uint32' context='host'>

<name>NumCPUs</name>

<value>2</value>

</metric>

<metric type='uint32' context='host'>

<name>TotalPhyCPUs</name>

<value>2</value>

</metric>

<metric type='string' context='host'>

<name>VirtualizationVendor</name>

<value>SUSE LINUX Products GmbH</value>

</metric>

<metric type='string' context='host'>

<name>HostName</name>

<value>laptop</value>

</metric>

<metric type='real64' context='vm' id='0'

uuid='00000000-0000-0000-0000-000000000000'>

<name>TotalCPUTime</name>

<value>847.700000</value>

</metric>

<metric type='real64' context='vm' id='2'

uuid='6be3fdb8-bef5-6fec-b1b7-e61bbceab708'>

<name>TotalCPUTime</name>

<value>69.400000</value>

</metric>

</metrics>

## FILES
/etc/vhostmd/vhostmd.conf

/etc/vhostmd/vhostmd.dtd

/etc/vhostmd/metric.dtd

/var/run/vhostmd.pid

## AUTHORS

Pat Campbell <plc@novell.com>.

Jim Fehlig <jfehlig@novell.com>.


cron

package: vixie-cron

title: cron(8)

summary: clock daemon

text:
# cron(8)

## NAME
cron — clock daemon

## SYNOPSIS
cron

[-l load_avg] [-n] [-x [ext,sch,proc,pars,load,misc,test,bit]]

## DESCRIPTION
The cron daemon schedules commands to be run at specified dates and times. Commands that are to be run periodically are specified within crontab(5) files. Commands that are only to be run once are scheduled via the at(1) and batch(1) commands. Normally, the cron daemon is started from the /etc/init.d/crond command script. Because it can execute commands on a user's behalf, cron should be run late in the startup sequence, as close to the time when logins are accepted as possible.

cron loads crontab(5) and at(1) files when it starts up and also when changes are made via the crontab(1) and at(1) commands. Additionally, cron checks the modification time on the system crontab file (/etc/crontab), the crontab spool (/var/spool/cron), and the at spool (/var/spool/at) once a minute. If the modification time has changed, the affected files are reloaded.

Any output produced by a command is sent to the user specified in the MAILTO environment variable as set in the crontab(5) file or, if no MAILTO variable is set (or if this is an at(1) or batch(1) job), to the job's owner. If a command produces no output or if the MAILTO environment variable is set to the empty string, no mail will be sent. The exception to this is at(1) or batch(1) jobs submitted with the -m flag. In this case, mail will be sent even if the job produces no output.

### Daylight Saving Time and other time changes
Local time changes of less than three hours, such as those caused by the start or end of Daylight Saving Time, are handled specially. This only applies to jobs that run at a specific time and jobs that are run with a granularity greater than one hour. Jobs that run more frequently are scheduled normally.

If time has moved forward, those jobs that would have run in the interval that has been skipped will be run immediately. Conversely, if time has moved backward, care is taken to avoid running jobs twice.

Time changes of more than 3 hours are considered to be corrections to the clock or time zone, and the new time is used immediately.

The options are as follows:

-l load_avg

If the current load average is greater than load_avg, batch(1) jobs will not be run. The default value is 1.5. To allow batch(1) jobs to run regardless of the load, a value of 0.0 may be used.

-n

By default, cron will detach from the current tty and become a daemon. The -n option disables this behavior and causes it to run in the foreground.

-x debug_flags

If cron was compiled with debugging support, a number of debugging flags are available to show what cron is doing. The following flags may be specified: ext

show extended information; used in conjunction with other debug flags to provide even more information

sch

print information related to scheduling jobs

proc

print information related to running processes

pars

print information related to parsing crontab(5) files

load

print when loading the databases

misc

show misc other debugging information

test

test mode; don't actually execute commands

Multiple flags may be specified, separated by a comma (‘,’). Regardless of which flags were specified, the -x flag will cause cron to stay in the foreground and not become a daemon.

## SIGNALS
SIGHUP

causes cron to close and reopen its log file. This is useful in scripts which rotate and age log files. On Linux this has no effect because cron logs via syslog(3).

## FILES
/etc/crontab

system crontab file

/etc/cron.d

directory containing system crontab files

/var/spool/at

directory containing at(1) jobs

/var/spool/cron

directory containing individual crontab files

/var/spool/cron/.sock

used by crontab(1) and at(1) to tell cron to check for crontab changes immediately

## SEE ALSO
at(1), crontab(1), syslog(3), crontab(5)

## AUTHORS
Paul Vixie ⟨vixie@isc.org⟩

## CAVEATS
All crontab(5) files must not be readable or writable by any user other than their owner. In practice this means they should be mode 0600. This restriction is enforced automatically by crontab(1).


debugvmfs

package: vmfs-tools

title: debugvmfs(8)

summary: VMFS file system debugger

text:
# debugvmfs(8)

## NAME
debugvmfs - VMFS file system debugger

## SYNOPSIS
debugvmfs VOLUME... COMMAND [ OPTIONS ]

## DESCRIPTION
The debugvmfs program allows to display various informations about VMFS file systems, and to access data within the file systems.

The VOLUME to be opened can be either a block device or an image file. When the VMFS spreads accross several extents, all extents must be given.

Please note that most commands are still likely to change in future versions.

## SPECIFYING FILES
Some commands take a filespec as an argument. A filespec may take either of the following forms:

•A path name, relative to the root of the filesystem if it starts with '/', or relative to the current working directory otherwise (interactive mode only).

•An inode number, enclosed between angle brackets, e.g. '<4>', '<0x1400004>'

## COMMANDS
cat filespec [ ... ]

Outputs the content of the given files from the VMFS.

ls [ -l ] filespec

Lists files contained at the given location within the VMFS. With -l, gives some more information, much like the output from ls(1) when given the -l option.

truncate filespec length

Truncate the file to the specified length. R/W support must be enabled.

chmod filespec mode

Change file permissions to the given mode.

df

Outputs information about file system size.

get_file_block filespec position

Get file block corresponding to position in the specified file.

check_vol_bitmaps

Checks volume bitmaps consistency.

show_heartbeats

Outputs active heartbeats on the file system.

read_block block_id [ ... ]

Outputs content within the specified block_id in binary

get_block_status block_id

Get status (allocated or free) of the specified block_id.

alloc_block_fixed block_id

Allocate the specified block_id. R/W support must be enabled.

alloc_block block_type

Allocate a block of the specified type. R/W support must be enabled. Allowed block types are: 1 (File Block), 2 (Sub-Block), 3 (Pointer Block) and 4 (File Descriptor / Inode).

free_block block_id

Free the specified block_id. R/W support must be enabled. Warning: can cause damage since no heartbeat is used at this time and a block used by a file can be freed.

show

Display value(s) of the given variable. See the VARIABLES section for more details. When no variable is given, it lists the top-level properties.

shell

Starts an interactive session. All of the above commands can be executed from within the interactive session. The current working directory can be changed with the cd command, followed by a filespec.

The following output redirections are supported within the shell:

•cmd > output Puts the output of cmd in the output file.

•cmd >> output Appends the output of cmd to the output file.

•cmd | external command Sends the output of cmd to the input of external command. The external command itself can contain output redirection.

Examples:

•read_block 0x00000681 | less

•cat /.fdc.sf | hexdump -C

•cat /.fdc.sf | hexdump -C > /tmp/fdc.hex

•cat /.fdc.sf | hexdump -C | less

## VARIABLES
Variables in debugvmfs represent structures on the filesystem. The currently supported top-level variables are the following:

•vol_version

•version

•label

•mode

•uuid

•ctime

•block_size

•subblock_size

•fdc_header_size

•fdc_bitmap_count

•fbb

•fdc

•pbc

•sbc

•fs

•lvm

•blkid[blk]

•dirent["path"]

•inode["filespec"]

The vol_version, version, label, mode, uuid, ctime, block_size, subblock_size, fdc_header_size, and fdc_bitmap_count properties are low-level information about the filesystem.

The fbb, fdc, pbc and sbc variables are bitmaps. Running them through the show command will display all the bitmaps header fields. Each of these fields can also be displayed individually:

•bitmap.items_per_bitmap_entry

•bitmap.bmp_entries_per_area

•bitmap.hdr_size

•bitmap.data_size

•bitmap.area_size

•bitmap.area_count

•bitmap.total_items

•bitmap.used_items

•bitmap.free_items

•bitmap.entry[n]

e.g. to display the data size of the fdc bitmap, type show fdc.data_size.

Each bitmap.entry[n] (where 0 ≤ n < bitmap.bmp_entries_per_area * bitmap.area_count) contains information about each entry in the bitmap. The available fields are:

•bitmap.entry[n].id

•bitmap.entry[n].total

•bitmap.entry[n].free

•bitmap.entry[n].ffree

•bitmap.entry[n].mdh

•bitmap.entry[n].item[m]

The bitmap.entry[n].mdh is a metadata header. See further below for more details about metadata headers.

Each bitmap.entry[n].item[m] (where 0 ≤ m < bitmap.items_per_bitmap_entry) contains information about a given item in the given entry. The available fields are:

•bitmap.entry[n].item[m].used

•bitmap.entry[n].item[m].dump

The pbc bitmap has an additional field:

•pbc.entry[n].item[m].blocks

The lvm variable contains low-level information about the physical and logical volumes. The available fields are:

•lvm.uuid

•lvm.size

•lvm.blocks

•lvm.num_extents

•lvm.extent[n]

Each lvm.extent[n] (where 0 ≤ n < lvm.num_extents) contains low-level information about the physical volumes. The available fields are:

•lvm.extent[n].device

•lvm.extent[n].uuid

•lvm.extent[n].lun

•lvm.extent[n].version

•lvm.extent[n].name

•lvm.extent[n].size

•lvm.extent[n].num_segments

•lvm.extent[n].first_segment

•lvm.extent[n].last_segment

Each blkid[blk] (where blk is a block id) contains information on the given block id. The available fields are:

•blkid[blk].item

•blkid[blk].flags

Each dirent[path] (where path is a path relative to the current directory in the shell or / outside the shell) contains information on the directory entry corresponding to the given path. The available fields are:

•dirent["path"].type

•dirent["path"].block_id

•dirent["path"].record_id

•dirent["path"].name

Each inode[filespec] contains information on the inode corresponding to the given filespec. The available fields are:

•inode["filespec"].id

•inode["filespec"].id2

•inode["filespec"].nlink

•inode["filespec"].type

•inode["filespec"].flags

•inode["filespec"].size

•inode["filespec"].blk_size

•inode["filespec"].blk_count

•inode["filespec"].uid

•inode["filespec"].gid

•inode["filespec"].mode

•inode["filespec"].zla

•inode["filespec"].tbz

•inode["filespec"].cow

•inode["filespec"].atime

•inode["filespec"].mtime

•inode["filespec"].ctime

•inode["filespec"].rdm_id

•inode["filespec"].mdh

•inode["filespec"].blocks

Metadata headers are being used in several places, such as bitmap.entry[n].mdh and inode["filespec"].mdh. They mostly contain information about clustered accesses to metadata on the filesystem. The available fields are:

•mdh.magic

•mdh.pos

•mdh.hb_pos

•mdh.hb_lock

•mdh.hb_uuid

•mdh.hb_seq

•mdh.obj_seq

•mdh.mtime

Variable values can also be used in expressions using square brackets to use the variable value as an index. For example:

•blkid[inode["filespec"].id]

Enclosing a variable name with parentheses will use that variable value as a variable name. For example:

•(blkid[blk].item).status

## AUTHORS
Christophe Fillot <cf@utc.fr[1]>, Mike Hommey <mh@glandium.org[2]>

## SEE ALSO
vmfs-fuse(8)

## NOTES
1.

cf@utc.fr

mailto:cf@utc.fr

2.

mh@glandium.org

mailto:mh@glandium.org


fsck.vmfs

title: fsck.vmfs(8)

summary: VMFS file system check utility

text:
# fsck.vmfs(8)

## NAME
fsck.vmfs - VMFS file system check utility

## SYNOPSIS
fsck.vmfs VOLUME...

## DESCRIPTION
The fsck.vmfs performs various integrity checks on a VMFS file system.

The VOLUME to be opened can be either a block device or an image file. When the VMFS spreads accross several extents, all extents must be given.

## AUTHORS
Christophe Fillot <cf@utc.fr[1]>, Mike Hommey <mh@glandium.org[2]>

## SEE ALSO
debugvmfs(8)

## NOTES
1.

cf@utc.fr

mailto:cf@utc.fr

2.

mh@glandium.org

mailto:mh@glandium.org


vmfs-fuse

title: vmfs-fuse(8)

summary: mount VMFS file system

text:
# vmfs-fuse(8)

## NAME
vmfs-fuse - mount VMFS file system

## SYNOPSIS
vmfs-fuse VOLUME... MOUNT_POINT

## DESCRIPTION
The vmfs-fuse program allows to mount VMFS file systems.

The VOLUME to be opened can be either a block device or an image file. When the VMFS spreads accross several extents, all extents must be given.

The MOUNT_POINT indicates where the file system will be attached on the system.

## AUTHORS
Christophe Fillot <cf@utc.fr[1]>, Mike Hommey <mh@glandium.org[2]>

## SEE ALSO
debugvmfs(8)

## NOTES
1.

cf@utc.fr

mailto:cf@utc.fr

2.

mh@glandium.org

mailto:mh@glandium.org


vmfs-lvm

title: vmfs-lvm(8)

summary: VMFS logical volume manager tool

text:
# vmfs-lvm(8)

## NAME
vmfs-lvm - VMFS logical volume manager tool

## SYNOPSIS
vmfs-lvm VOLUME... COMMAND

## DESCRIPTION
The vmfs-lvm program allows handle VMFS physical and logical volumes.

The VOLUME to be opened can be either a block device or an image file. When the VMFS spreads accross several extents, all extents must be given.

## COMMANDS
remove

Removes the last extent of the logical volume. THIS IS EXPERIMENTAL. USE AT YOUR OWN RISK. It is highly recommended that the volume is not mounted at the same time. This means the tool shouldn’t be run on the ESX service console.

## AUTHORS
Christophe Fillot <cf@utc.fr[1]>, Mike Hommey <mh@glandium.org[2]>

## SEE ALSO
vmfs-fuse(8)

## NOTES
1.

cf@utc.fr

mailto:cf@utc.fr

2.

mh@glandium.org

mailto:mh@glandium.org


vmtouch

package: vmtouch

title: vmtouch(8)

summary: the Virtual Memory Toucher

text:
# vmtouch(8)

## NAME
vmtouch - the Virtual Memory Toucher

## SYNOPSIS

```
    vmtouch [OPTIONS] ... FILES OR DIRECTORIES ...
```

## DESCRIPTION
Portable file system cache diagnostics and control.

vmtouch opens every file provided on the command line and maps it into virtual memory with mmap(2). The mappings are opened read-only. It recursively crawls any directories and does the same to all files it finds within them.

With no options, vmtouch will not read from (touch) any memory pages. It will only use mincore(2) to determine how many pages of each file are actually resident in memory. Before exiting, it will print a summary of the total pages encountered and how many were resident.

-t

Touch virtual memory pages. Reads a byte from each page of the file. If the page is not resident in memory, a page fault will be generated and the page will be read from disk into the file system's memory cache. Note: Although each page is guaranteed to have been brought into memory, the page might be evicted from memory by the time the vmtouch command completes.

-e

Evict the mapped pages from the file system cache. They will need to be read in from disk the next time they are accessed. This is the inverse of "-t". Note: Even if the eviction is successful, pages may be paged back into memory by the time the vmtouch command completes.

Note: This option is not portable to all systems. See PORTABILITY below.

-l

Lock pages into physical memory. This option works the same as "-t" except it calls mlock(2) on all the memory mappings and doesn't close the descriptors when finished. At the end of the crawl, if successful, vmtouch will block indefinitely. The files will be locked in physical memory until the vmtouch process is killed. Note: While the vmtouch process is holding memory locks, any processes that access the locked pages will not cause non-resident page faults or address-translation faults although they may still cause TLB misses.

Note: Because vmtouch holds file descriptors open it may reach the "RLIMIT_NOFILE" process file descriptor limit. In this case it will try to increase the descriptor limit which will only work if the process is run with root privileges. Similarly, root privileges are required to exceed the "RLIMIT_MEMLOCK" limit. Even with root privileges, "-l" is limited by both the system file descriptor limit and the system limit on "wired memory".

-L

This option is the same as "-l" except that it uses mlockall(2) at the end of the crawl rather than individually mlock(2)ing each file. Because of this, other unrelated pages belonging to the vmtouch process will also be locked in memory.

-d

Daemon mode. After performing the crawl, disassociate from the terminal and run in the background as a daemon. This option can only be used with the "-l" or "-L" locking modes.

-m <max file size>

Maximum file size to map into virtual memory. Files that are larger than this will be skipped. Examples: 4096, 4k, 100M, 1.5G. The default is 500M.

-p <size range> or <size>

Page mode. Maps the portion of the file specified by a range instead of the entire file. Size format same as for "-m". Omitted range start (end) value means start (end) of file. Single <size> value is equivalent to -<size>, i.e. map the first <size> bytes. Examples: 4k-50k, 100M-2G, -5M, -.

-f

Follow symbolic links. With this option, vmtouch will descend into symbolic links that point to directories and will touch regular files pointed to by symbolic links. Symbolic link loops are detected and issue warnings.

-F

During the crawl, don't recurse into directories that have separate filesystems mounted on them. This is handy to avoid accidentally touching other filesystems that have been mounted underneath your target directory.

-i <pattern>

Can be specified multiple times. Ignores files and directories that match any of the provided patterns. The pattern may include wildcards (remember to escape them from your shell). This option stops the crawl, so can be used to ignore directories and all their contents. Example: vmtouch -i .git -i '*.bak' .

-I <pattern>

Can be specified multiple times. Only processes filenames matching one or more of the provided patterns. The pattern may include wildcards (remember to escape them from your shell). Example: vmtouch -I '*.c' -I '*.h' .

-b <list file>

The list of files/directories to crawl is read from the specified list file, which by default should be a newline-separated list, for example the output from the find command. If the list file is "-" then this list is read from standard input. Example: find /usr/lib -type f | vmtouch -b -

-0

If -b ("batch mode") is in effect, assume the list file is delimited with NUL bytes instead of newlines, for example the output from find -print0. This is useful in case your filenames contain newline characters themselves.

-P <pidfile>

Create a PID file. This option can only be provided in combination with -l or -L. The PID file will be automatically deleted when vmtouch gets a termination signal (SIGINT, SIGTERM, SIGQUIT).

-v

Verbose mode. While crawling, print out every file being processed along with its total number of pages and the number of its pages that are currently resident in memory to standard output.

-q

Quiet mode. Suppress the end of crawl summary and all warnings that are normally printed to standard error. On success print nothing. Fatal errors print a single error message line to standard error.

-h

Normally, if multiple files both point to the same inode then vmtouch will ignore all but the first it finds so as to avoid double-counting their pages. This option overrides this behaviour and double-counts anyways.

## PORTABILITY
The page residency summaries depend on mincore(2) which first appeared in 4.4BSD but is not present on all unix systems.

The "-l" and "-L" locking options depends on mlock(2) or mlockall(2), both of which are specified by POSIX.1b-1993, Real-Time Extensions.

The "-e" page eviction option is the least portable. On Linux it uses posix_fadvise(2) with "POSIX_FADV_DONTNEED" advice to inform the kernel that the file should be evicted from the file system cache. posix_fadvise(2) is specified by POSIX.1-2003 TC1. On FreeBSD, the pages are invalidated with msync(2)'s "MS_INVALIDATE" flag. msync(2) is specified by POSIX.1b-1993, Real-Time Extensions, although this call is not required to remove pages from the file system cache. Some systems like OpenBSD 4.3 don't have posix_fadvise(2), don't evict the pages on an msync(2)/"MS_INVALIDATE", and don't evict the pages with madvise(2)/"MADV_DONTNEED" so "-e" isn't supported on those systems yet. Using "-e" on systems that don't yet support it is a fatal error.

## SUPPORTED SYSTEMS
All vmtouch features have been confirmed to work on the following systems:

Linux 2.6+

FreeBSD 4.X

FreeBSD 7.X

Solaris 10

OS X 10.x

HP-UX 11.31+patches (see below)

Systems that support everything except eviction:

OpenBSD 4.3

CPUs that have been tested:

x86

amd64 (x86-64)

SPARC

ARMv7

We would like to support as many systems as possible so please send us any success reports, failure reports or patches. Thanks!

## SYSTEM NOTES
Shane Seymour did the HP-UX port and says that either 32-bit or 64-bit binaries can be compiled (just use "+DD64" for 64-bit). However, mincore(2) was added to HP-UX 11.31 via patches and at least the following patches need to be installed: PHKL_38651, PHKL_38708, PHKL_38686, PHKL_38688, and PHCO_38658 (or patches that supersede those ones).

## SEE ALSO
Not all the following manual pages may exist in every unix dialect to which vmtouch has been ported.

vmstat(8), touch(1), mmap(2), mincore(2), mlock(2), mlockall(2), msync(2), madvise(2), posix_fadvise(2)

## AUTHOR
Written by Doug Hoyte <doug@hcsw.org>