doveadm-search-query

package: dovecot

title: doveadm-search-query(7)

summary: Overview of search queries for doveadm mailbox \

text:
# doveadm-search-query(7)

## NAME
doveadm-search-query - Overview of search queries for doveadm mailbox commands

## DESCRIPTION
Several doveadm(1) commands use a search_query in order to act only on matching messages. This manual page describes all SEARCH KEYS, which can be used in a search_query. The query is mostly compatible with the IMAP SEARCH command parameters, although there are some differences.

Each search_query consists at least of one SEARCH KEY. Most of the SEARCH KEYS require an argument. All SEARCH KEYS are case-insensitive. The shortest valid search_query is ALL. For example:

```
doveadm search ALL
```

Multiple search query expressions will be combined with the AND operator by default. To find all messages that are new and greater than 50 kilobyte, one can use:

```
doveadm search NEW LARGER 50k
```

OR-ed SEARCH KEYS have to be written in parenthesis, when mixing ANDs and ORs. Shells commonly require escaping for parentheses. To find messages that were saved on the "13th of April 2007" AND have the \Seen and/or \Flagged flag set, one can use for example:

```
doveadm search SAVEDON 2007-04-13 \( SEEN OR FLAGGED \)
```

It's also possible to specify the mailbox, in which should be searched. Use either the keyword mailbox and the name of the mailbox or the keyword mailbox-guid and the mailbox's globally unique identifier in the search_query. To find all messages in the mailbox with the GUID "44f68b13ce97044b837f000035ca9452" use:

```
doveadm search mailbox-guid 44f68b13ce97044b837f000035ca9452 ALL
```

To list all deleted messages in the "Trash" folder use:

```
doveadm search mailbox Trash DELETED
```

## SEARCH KEYS
The following search keys from the specification of IMAP version 4 revision 1 (see: RFC 3501, section 6.4.4) are supported:

sequence-set

Matches messages with the given sequence numbers. The sequence-set may be a single UID. Can be a sequence range, written as from:to, e.g. 100:125. As comma separated list of sequences, e.g. 11,50,4. It's also possible to combine multiple sequences, e.g. 1,3,5,7,10:20. Using * selects the last mail in the mailbox.

For example 1:100 matches the first 100 mails and 101:200 the next second hundred mails. 1,5,* matches the first, the fifth and the last email.

ALL

Matches all messages.

ANSWERED

Matches messages with the IMAP flag \Answered set.

BCC string

Matches messages, which contain string in the BCC field of the message's IMAP envelope structure.

BEFORE date specification

Matches messages with an internal date before date specification.

BODY string

Matches messages, which contain string in the body part.

CC string

Matches messages, which contain string in the CC field of the message's IMAP envelope structure.

DELETED

Matches messages with the IMAP flag \Deleted set.

DRAFT

Matches messages with the IMAP flag \Draft set.

FLAGGED

Matches messages with the IMAP flag \Flagged set.

FROM string

Matches messages, which contain string in the FROM field of the message's IMAP envelope structure.

HEADER field string

Matches messages, which either have the named header field, when empty string was given. Or messages, where the given header field's value contains the specified string.

KEYWORD keyword

Matches messages with the given IMAP keyword (e.g. $Forwarded) flag set.

LARGER size

Matches messages that are larger than the specified size.

MAILBOX name

Matches messages in the mailbox with the specified name.

MAILBOX-GUID guid

Matches messages in the mailbox with the specified guid.

NEW

Matches messages, which have the IMAP flag \Recent set but not the IMAP flag \Seen.

NOT search key

Inverse matching - matches massages, where the search doesn't match the specified search key or its value.

OLD

Matches messages, which do not have the IMAP flag \Recent set.

ON date specification

Matches messages whose internal date matches the given date specification.

search key OR search key

Matches messages where one of the OR-ed search keys matches.

Note: IMAP4rev1 uses the syntax: OR search key search key

RECENT

Matches messages with the IMAP flag \Recent set.

SEEN

Matches messages with the IMAP flag \Seen set.

SENTBEFORE date specification

Matches messages with a Date: header before date specification.

SENTON date specification

Matches messages with a Date: header matching the given date specification.

SENTSINCE date specification

Matches messages with a Date: header matching or after the given date specification.

SINCE date specification

Matches messages whose internal date is within or after the given date specification.

SMALLER size

Matches messages with a size smaller than the given size.

SUBJECT string

Matches messages, which contain string in the SUBJECT field of the message's IMAP envelope structure.

TEXT string

Matches messages, which contain string in the message headers or body.

TO string

Matches messages, which contain string in the TO field of the message's IMAP envelope structure.

UID sequence-set

Matches messages with the given IMAP UID(s). See the sequence-set description for details on it. For example 1:10,100:200,* matches the UIDs from 1 to 10, 100 to 200 and also the last mail.

UNANSWERED

Matches messages, which do not have the IMAP flag \Answered set.

UNDELETED

Matches messages, which do not have the IMAP flag \Deleted set.

UNDRAFT

Matches messages, which do not have the IMAP flag \Draft set.

UNFLAGGED

Matches messages, which do not have the IMAP flag \Flagged set.

UNKEYWORD keyword

Matches messages, which do not have the given IMAP keyword flag set

UNSEEN

Matches messages, which do not have the IMAP flag \Seen set.

### DOVEADM SEARCH KEYS
Additional search keys, provided by doveadm(1).

SAVEDBEFORE date specification

Matches messages, which were saved before date specification.

SAVEDON date specification

Matches messages whose save date matches the given date specification.

SAVEDSINCE date specification

Matches messages with a save date matching or after the given date specification.

## DATE SPECIFICATION
doveadm(1) supports a few additional date specification formats. They can be used anywhere, where a date specification value is obligatory.

day-month-year

Default IMAP4rev1 date format.

day, the day of month: 1-31.

month, the abbreviated month name: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov or Dec.

year, four digits of year, e.g. 2007.

For example the "13th of April 2007" will be represented as 13-Apr-2007.

interval

Combination of a positive integer number and a time unit.

Available time units are: weeks (abbr: w), days (abbr: d), hours (abbr: h), mins (abbr: m) and secs (abbr: s).

To match messages from last week, you may specify for example: since 1w, since 1weeks or since 7days.

Unix timestamp

A 10 digit Unix timestamp, seconds since the 1st of January 1970, 00:00:00 UTC. For example the "13th of April 2007" will be represented as 1176418800.

YYYY-MM-DD

Extended ISO-8601 calendar date format. For example the "13th of April 2007" will be represented as 2007-04-13.

## SIZE
doveadm(1) provides also an additional size representation format. The following formats can be used anywhere, where a size value is obligatory.

octets

The message size in octets, as specified in the IMAP4rev1 specification.

size

The message size in B (byte), k (kilobyte), M (megabyte), G (gigabyte) or T (terabyte).

To match messages, bigger than 1 megabyte, you may specify for example: larger 1M or larger 1024k.

## SEE ALSO
doveadm(1), doveadm-search(1)


pigeonhole

package: dovecot-pigeonhole

title: pigeonhole(7)

summary: Overview of the Pigeonhole project\(aqs Sieve support for the

text:
# pigeonhole(7)

## NAME
pigeonhole - Overview of the Pigeonhole project's Sieve support for the Dovecot secure IMAP and POP3 server

## DESCRIPTION
The Pigeonhole project <http://pigeonhole.dovecot.org> adds support for the Sieve language (RFC 5228) and the ManageSieve protocol (RFC 5804) to the Dovecot Secure IMAP and POP3 Server (dovecot(1)). In the literal sense, a pigeonhole is a a hole or recess inside a dovecot for pigeons to nest in. It is, however, also the name for one of a series of small, open compartments in a cabinet used for filing or sorting mail. As a verb, it describes the act of putting an item into one of those pigeonholes. The name "Pigeonhole" therefore well describes an important part of the functionality that this project adds to Dovecot: sorting and filing e-mail messages.

The Sieve language is used to specify how e-mail needs to be processed. By writing Sieve scripts, users can customize how messages are delivered, e.g. whether they are forwarded or stored in special folders. Unwanted messages can be discarded or rejected, and, when the user is not available, the Sieve interpreter can send an automated reply. Above all, the Sieve language is meant to be simple, extensible and system independent. And, unlike most other mail filtering script languages, it does not allow users to execute arbitrary programs. This is particularly useful to prevent virtual users from having full access to the mail store. The intention of the language is to make it impossible for users to do anything more complex (and dangerous) than write simple mail filters.

Using the ManageSieve protocol, users can upload their Sieve scripts remotely, without needing direct filesystem access through FTP or SCP. Additionally, a ManageSieve server always makes sure that uploaded scripts are valid, preventing compile failures at mail delivery.

The Pigeonhole project provides the following items:

- The LDA Sieve plugin for Dovecot's Local Delivery Agent (LDA) (dovecot-lda(1)) that facilitates the actual Sieve filtering upon delivery.

- The ManageSieve service that implements the ManageSieve protocol through which users can remotely manage Sieve scripts on the server.

- A plugin for Dovecot's doveadm(1) command line tool that adds new the new doveadm-sieve(1) commands for management of Sieve filtering.

The functionality and configuration of the LDA Sieve plugin and the ManageSieve service is described in detail in the README and INSTALL files contained in the Pigeonhole package and in the Dovecot Wiki <http://wiki2.dovecot.org/Pigeonhole>.

The following command line tools are available outside of doveadm:

sievec(1)

Compiles Sieve scripts into a binary representation for later execution.

sieve-test(1)

The universal Sieve test tool for testing the effect of a Sieve script on a particular message.

sieve-filter(1)

Filters all messages in a particular source mailbox through a Sieve script.

sieve-dump(1)

Dumps the content of a Sieve binary file for (development) debugging purposes.

## REPORTING BUGS
Report bugs, including doveconf -n output, to the Dovecot Mailing List <dovecot@dovecot.org>. Information about reporting bugs is available at: http://dovecot.org/bugreport.html

## AUTHOR
Pigeonhole <http://pigeonhole.dovecot.org> and its manual pages were written by the Pigeonhole authors <http://pigeonhole.dovecot.org/doc/AUTHORS>, mainly Stephan Bosch <stephan at rename-it.nl>, and are licensed under the terms of the LGPLv2.1 license, which is the same license as Dovecot, see <http://dovecot.org/doc/COPYING> for details.

## SEE ALSO
dovecot(1), dovecot-lda(1), doveadm(1), doveadm-sieve(1), sieve-dump(1), sieve-test(1), sieve-filter(1), sievec(1)

Additional resources:

Dovecot website

http://www.dovecot.org

Dovecot v2.x Wiki

http://wiki2.dovecot.org/Pigeonhole

Pigeonhole website

http://pigeonhole.dovecot.org


dracut.bootup

package: dracut

title: dracut.bootup(7)

summary: boot ordering in the initramfs

text:
# dracut.bootup(7)

## NAME
dracut.bootup - boot ordering in the initramfs

## DESCRIPTION
This flow chart illustrates the ordering of the services, if systemd is used in the dracut initramfs.

```
                                    systemd-journal.socket

                                               |

                                               v

                                    dracut-cmdline.service

                                               |

                                               v

                                    dracut-pre-udev.service

                                               |

                                               v

                                     systemd-udevd.service

                                               |

                                               v
local-fs-pre.target                dracut-pre-trigger.service

         |                                     |

         v                                     v

 (various mounts)  (various swap  systemd-udev-trigger.service

         |           devices...)               |             (various low-level   (various low-level

         |               |                     |             services: seed,       API VFS mounts:

         v               v                     v             tmpfiles, random     mqueue, configfs,

  local-fs.target   swap.target     dracut-initqueue.service    sysctl, ...)        debugfs, ...)

         |               |                     |                    |                    |

         \_______________|____________________ | ___________________|____________________/

                                              \|/

                                               v

                                        sysinit.target

                                               |

                             _________________/|\___________________

                            /                  |                    \

                            |                  |                    |

                            v                  |                    v

                        (various               |              rescue.service

                       sockets...)             |                    |

                            |                  |                    v

                            v                  |              rescue.target

                     sockets.target            |

                            |                  |

                            \_________________ |                                 emergency.service

                                              \|                                         |

                                               v                                         v

                                         basic.target                             emergency.target

                                               |

                        ______________________/|

                       /                       |

                       |                       v

                       |            initrd-root-device.target

                       |                       |

                       |                       v

                       |            dracut-pre-mount.service

                       |                       |

                       |                       v

                       |                  sysroot.mount

                       |                       |

                       |                       v

                       |             initrd-root-fs.target

           (custom initrd services)            |

                       |                       v

                       |             dracut-mount.service

                       |                       |

                       |                       v

                       |            initrd-parse-etc.service

                       |                       |

                       |                       v

                       |            (sysroot-usr.mount and

                       |             various mounts marked

                       |               with fstab option

                       |                x-initrd.mount)

                       |                       |

                       |                       v

                       |                initrd-fs.target

                       \______________________ |

                                              \|

                                               v

                                          initrd.target

                                               |

                                               v

                                    dracut-pre-pivot.service

                                               |

                                               v

                                     initrd-cleanup.service

                                          isolates to

                                    initrd-switch-root.target

                                               |

                                               v

                        ______________________/|

                       /                       |

                       |        initrd-udevadm-cleanup-db.service

                       |                       |

           (custom initrd services)            |

                       |                       |

                       \______________________ |

                                              \|

                                               v

                                   initrd-switch-root.target

                                               |

                                               v

                                   initrd-switch-root.service

                                               |

                                               v

                                          switch-root
```

## AUTHOR
Harald Hoyer

## SEE ALSO
dracut(8) bootup(7)


dracut.cmdline

title: dracut.cmdline(7)

summary: dracut kernel command line options

text:
# dracut.cmdline(7)

## NAME
dracut.cmdline - dracut kernel command line options

## DESCRIPTION
The root device used by the kernel is specified in the boot configuration file on the kernel command line, as always.

The traditional root=/dev/sda1 style device specification is allowed, but not encouraged. The root device should better be identified by LABEL or UUID. If a label is used, as in root=LABEL=<label_of_root> the initramfs will search all available devices for a filesystem with the appropriate label, and mount that device as the root filesystem. root=UUID=<uuidnumber> will mount the partition with that UUID as the root filesystem.

In the following all kernel command line parameters, which are processed by dracut, are described.

"rd.*" parameters mentioned without "=" are boolean parameters. They can be turned on/off by setting them to {0|1}. If the assignment with "=" is missing "=1" is implied. For example rd.info can be turned off with rd.info=0 or turned on with rd.info=1 or rd.info. The last value in the kernel command line is the value, which is honored.

### Standard
init=<path to real init>

specify the path to the init program to be started after the initramfs has finished

root=<path to blockdevice>

specify the block device to use as the root filesystem. Example.

```
root=/dev/sda1
root=/dev/disk/by-path/pci-0000:00:1f.1-scsi-0:0:1:0-part1
root=/dev/disk/by-label/Root
root=LABEL=Root
root=/dev/disk/by-uuid/3f5ad593-4546-4a94-a374-bcfb68aa11f7
root=UUID=3f5ad593-4546-4a94-a374-bcfb68aa11f7
root=PARTUUID=3f5ad593-4546-4a94-a374-bcfb68aa11f7
```

rootfstype=<filesystem type>

"auto" if not specified. Example.

```
rootfstype=ext4
```

rootflags=<mount options>

specify additional mount options for the root filesystem. If not set, /etc/fstab of the real root will be parsed for special mount options and mounted accordingly.

ro

force mounting / and /usr (if it is a separate device) read-only. If none of ro and rw is present, both are mounted according to /etc/fstab.

rw

force mounting / and /usr (if it is a separate device) read-write. See also ro option.

rootfallback=<path to blockdevice>

specify the block device to use as the root filesystem, if the normal root cannot be found. This can only be a simple block device with a simple file system, for which the filesystem driver is either compiled in, or added manually to the initramfs. This parameter can be specified multiple times.

rd.auto rd.auto=1

enable autoassembly of special devices like cryptoLUKS, dmraid, mdraid or lvm. Default is off as of dracut version >= 024.

rd.hostonly=0

removes all compiled in configuration of the host system the initramfs image was built on. This helps booting, if any disk layout changed, especially in combination with rd.auto or other parameters specifying the layout.

rd.cmdline=ask

prompts the user for additional kernel command line parameters

rd.fstab=0

do not honor special mount options for the root filesystem found in /etc/fstab of the real root.

resume=<path to resume partition>

resume from a swap partition Example.

```
resume=/dev/disk/by-path/pci-0000:00:1f.1-scsi-0:0:1:0-part1
resume=/dev/disk/by-uuid/3f5ad593-4546-4a94-a374-bcfb68aa11f7
resume=UUID=3f5ad593-4546-4a94-a374-bcfb68aa11f7
```

rd.skipfsck

skip fsck for rootfs and /usr. If you’re mounting /usr read-only and the init system performs fsck before remount, you might want to use this option to avoid duplication.

### iso-scan/filename
Mount all mountable devices and search for ISO pointed by the argument. When the ISO is found set it up as a loop device. Device containing this ISO image will stay mounted at /run/initramfs/isoscandev. Using iso-scan/filename with a Fedora/Red Hat/CentOS Live iso should just work by copying the original kernel cmdline parameters.

Example.

```
menuentry 'Live Fedora 20' --class fedora --class gnu-linux --class gnu --class os {

    set isolabel=Fedora-Live-LXDE-x86_64-20-1

    set isofile="/boot/iso/Fedora-Live-LXDE-x86_64-20-1.iso"

    loopback loop $isofile

    linux (loop)/isolinux/vmlinuz0 boot=isolinux iso-scan/filename=$isofile root=live:LABEL=$isolabel ro rd.live.image quiet rhgb

    initrd (loop)/isolinux/initrd0.img
}
```

### Misc
rd.emergency=[reboot|poweroff|halt]

specify, what action to execute in case of a critical failure. rd.shell=0 must also be specified.

rd.driver.blacklist=<drivername>[,<drivername>,...]

do not load kernel module <drivername>. This parameter can be specified multiple times.

rd.driver.pre=<drivername>[,<drivername>,...]

force loading kernel module <drivername>. This parameter can be specified multiple times.

rd.driver.post=<drivername>[,<drivername>,...]

force loading kernel module <drivername> after all automatic loading modules have been loaded. This parameter can be specified multiple times.

rd.retry=<seconds>

specify how long dracut should retry the initqueue to configure devices. The default is 180 seconds. After 2/3 of the time, degraded raids are force started. If you have hardware, which takes a very long time to announce its drives, you might want to extend this value.

rd.timeout=<seconds>

specify how long dracut should wait for devices to appear. The default is 0, which means forever. Note that this timeout should be longer than rd.retry to allow for proper configuration.

rd.noverifyssl

accept self-signed certificates for ssl downloads.

rd.ctty=<terminal device>

specify the controlling terminal for the console. This is useful, if you have multiple "console=" arguments.

rd.shutdown.timeout.umount=<seconds>

specify how long dracut should wait for an individual umount to finish during shutdown. This avoids the system from blocking when unmounting a file system cannot complete and waits indefinitely. Value 0 means to wait forever. The default is 90 seconds.

### Debug
If you are dropped to an emergency shell, the file /run/initramfs/rdsosreport.txt is created, which can be saved to a (to be mounted by hand) partition (usually /boot) or a USB stick. Additional debugging info can be produced by adding rd.debug to the kernel command line. /run/initramfs/rdsosreport.txt contains all logs and the output of some tools. It should be attached to any report about dracut problems.

rd.info

print informational output though "quiet" is set

rd.shell

allow dropping to a shell, if root mounting fails

rd.debug

set -x for the dracut shell. If systemd is active in the initramfs, all output is logged to the systemd journal, which you can inspect with "journalctl -ab". If systemd is not active, the logs are written to dmesg and /run/initramfs/init.log. If "quiet" is set, it also logs to the console.

rd.memdebug=[0-5]

Print memory usage info at various points, set the verbose level from 0 to 5.

```
Higher level means more debugging output:
```

```
    0 - no output

    1 - partial /proc/meminfo

    2 - /proc/meminfo

    3 - /proc/meminfo + /proc/slabinfo

    4 - /proc/meminfo + /proc/slabinfo + memstrack summary

        NOTE: memstrack is a memory tracing tool that tracks the total memory

              consumption, and peak memory consumption of each kernel modules

              and userspace progress during the whole initramfs runtime, report

              is generated and the end of initramsfs run.

    5 - /proc/meminfo + /proc/slabinfo + memstrack (with top memory stacktrace)

        NOTE: memstrack (with top memory stacktrace) will print top memory

              allocation stack traces during the whole initramfs runtime.
```

rd.break

drop to a shell at the end

rd.break={cmdline|pre-udev|pre-trigger|initqueue|pre-mount|mount|pre-pivot|cleanup}

drop to a shell before the defined breakpoint starts

rd.udev.info

set udev to loglevel info

rd.udev.debug

set udev to loglevel debug

### I18N
rd.vconsole.keymap=<keymap base file name>

keyboard translation table loaded by loadkeys; taken from keymaps directory; will be written as KEYMAP to /etc/vconsole.conf in the initramfs. Example.

```
rd.vconsole.keymap=de-latin1-nodeadkeys
```

rd.vconsole.keymap.ext=<list of keymap base file names>

list of extra keymaps to bo loaded (sep. by space); will be written as EXT_KEYMAP to /etc/vconsole.conf in the initramfs

rd.vconsole.unicode

boolean, indicating UTF-8 mode; will be written as UNICODE to /etc/vconsole.conf in the initramfs

rd.vconsole.font=<font base file name>

console font; taken from consolefonts directory; will be written as FONT to /etc/vconsole.conf in the initramfs. Example.

```
rd.vconsole.font=eurlatgr
```

rd.vconsole.font.map=<console map base file name>

see description of -m parameter in setfont manual; taken from consoletrans directory; will be written as FONT_MAP to /etc/vconsole.conf in the initramfs

rd.vconsole.font.unimap=<unicode table base file name>

see description of -u parameter in setfont manual; taken from unimaps directory; will be written as FONT_UNIMAP to /etc/vconsole.conf in the initramfs

rd.locale.LANG=<locale>

taken from the environment; if no UNICODE is defined we set its value in basis of LANG value (whether it ends with ".utf8" (or similar) or not); will be written as LANG to /etc/locale.conf in the initramfs. Example.

```
rd.locale.LANG=pl_PL.utf8
```

rd.locale.LC_ALL=<locale>

taken from the environment; will be written as LC_ALL to /etc/locale.conf in the initramfs

### LVM
rd.lvm=0

disable LVM detection

rd.lvm.vg=<volume group name>

only activate all logical volumes in the the volume groups with the given name. rd.lvm.vg can be specified multiple times on the kernel command line.

rd.lvm.lv=<volume group name>/<logical volume name>

only activate the logical volumes with the given name. rd.lvm.lv can be specified multiple times on the kernel command line.

rd.lvm.conf=0

remove any /etc/lvm/lvm.conf, which may exist in the initramfs

### crypto LUKS
rd.luks=0

disable crypto LUKS detection

rd.luks.uuid=<luks uuid>

only activate the LUKS partitions with the given UUID. Any "luks-" of the LUKS UUID is removed before comparing to <luks uuid>. The comparisons also matches, if <luks uuid> is only the beginning of the LUKS UUID, so you don’t have to specify the full UUID. This parameter can be specified multiple times. <luks uuid> may be prefixed by the keyword keysource:, see rd.luks.key below.

rd.luks.allow-discards=<luks uuid>

Allow using of discards (TRIM) requests for LUKS partitions with the given UUID. Any "luks-" of the LUKS UUID is removed before comparing to <luks uuid>. The comparisons also matches, if <luks uuid> is only the beginning of the LUKS UUID, so you don’t have to specify the full UUID. This parameter can be specified multiple times.

rd.luks.allow-discards

Allow using of discards (TRIM) requests on all LUKS partitions.

rd.luks.crypttab=0

do not check, if LUKS partition is in /etc/crypttab

rd.luks.timeout=<seconds>

specify how long dracut should wait when waiting for the user to enter the password. This avoid blocking the boot if no password is entered. It does not apply to luks key. The default is 0, which means forever.

### crypto LUKS - key on removable device support
NB: If systemd is included in the dracut initrd, dracut’s built in removable device keying support won’t work. systemd will prompt for a password from the console even if you’ve supplied rd.luks.key. You may be able to use standard systemd fstab(5) syntax to get the same effect. If you do need rd.luks.key to work, you will have to exclude the "systemd" dracut module and any modules that depend on it. See dracut.conf(5) and https://bugzilla.redhat.com/show_bug.cgi?id=905683 for more information.

rd.luks.key=<keypath>[:<keydev>[:<luksdev>]]

<keypath> is the pathname of a key file, relative to the root of the filesystem on some device. It’s REQUIRED. When <keypath> ends with .gpg it’s considered to be key encrypted symmetrically with GPG. You will be prompted for the GPG password on boot. GPG support comes with the crypt-gpg module, which needs to be added explicitly. <keydev> identifies the device on which the key file resides. It may be the kernel name of the device (should start with "/dev/"), a UUID (prefixed with "UUID=") or a label (prefix with "LABEL="). You don’t have to specify a full UUID. Just its beginning will suffice, even if its ambiguous. All matching devices will be probed. This parameter is recommended, but not required. If it’s not present, all block devices will be probed, which may significantly increase boot time.

If <luksdev> is given, the specified key will only be used for the specified LUKS device. Possible values are the same as for <keydev>. Unless you have several LUKS devices, you don’t have to specify this parameter. The simplest usage is:

Example.

```
rd.luks.key=/foo/bar.key
```

As you see, you can skip colons in such a case.

Note Your LUKS partition must match your key file.

dracut provides keys to cryptsetup with -d (an older alias for --key-file). This uses the entire binary content of the key file as part of the secret. If you pipe a password into cryptsetup without -d or --key-file, it will be treated as text user input, and only characters before the first newline will be used. Therefore, when you’re creating an encrypted partition for dracut to mount, and you pipe a key into cryptsetup luksFormat,you must use -d -.

Here is an example for a key encrypted with GPG (warning: --batch-mode will overwrite the device without asking for confirmation):

```
gpg --quiet --decrypt rootkey.gpg | \
cryptsetup --batch-mode --key-file - \

           luksFormat /dev/sda47
```

If you use unencrypted key files, just use the key file pathname instead of the standard input. For a random key with 256 bits of entropy, you might use:

```
head -32c /dev/urandom > rootkey.key
cryptsetup --batch-mode --key-file rootkey.key \

           luksFormat /dev/sda47
```

You can also use regular key files on an encrypted keydev.

Compared to using GPG encrypted keyfiles on an unencrypted device this provides the following advantages:

•you can unlock your disk(s) using multiple passphrases

•better security by not losing the key stretching mechanism

To use an encrypted keydev you must ensure that it becomes available by using the keyword keysource, e.g. rd.luks.uuid=keysource:aaaa aaaa being the uuid of the encrypted keydev.

Example:

Lets assume you have three disks A, B and C with the uuids aaaa, bbbb and cccc. You want to unlock A and B using keyfile keyfile. The unlocked volumes be A', B' and C' with the uuids AAAA, BBBB and CCCC. keyfile is saved on C' as /keyfile.

One luks keyslot of each A, B and C is setup with a passphrase. Another luks keyslot of each A and B is setup with keyfile.

To boot this configuration you could use:

```
rd.luks.uuid=aaaa
rd.luks.uuid=bbbb
rd.luks.uuid=keysource:cccc
rd.luks.key=/keyfile:UUID=CCCC
```

Dracut asks for the passphrase for C and uses the keyfile to unlock A and B. If getting the passphrase for C fails it falls back to asking for the passphrases for A and B.

If you want C' to stay unlocked, specify a luks name for it, e.g. rd.luks.name=cccc=mykeys, otherwise it gets closed when not needed anymore.

rd.luks.key.tout=0

specify how many times dracut will try to read the keys specified in in rd.luk.key. This gives a chance to the removable device containing the key to initialise.

### MD RAID
rd.md=0

disable MD RAID detection

rd.md.imsm=0

disable MD RAID for imsm/isw raids, use DM RAID instead

rd.md.ddf=0

disable MD RAID for SNIA ddf raids, use DM RAID instead

rd.md.conf=0

ignore mdadm.conf included in initramfs

rd.md.waitclean=1

wait for any resync, recovery, or reshape activity to finish before continuing

rd.md.uuid=<md raid uuid>

only activate the raid sets with the given UUID. This parameter can be specified multiple times.

### DM RAID
rd.dm=0

disable DM RAID detection

rd.dm.uuid=<dm raid uuid>

only activate the raid sets with the given UUID. This parameter can be specified multiple times.

### MULTIPATH
rd.multipath=0

disable multipath detection

rd.multipath=default

use default multipath settings

### FIPS
rd.fips

enable FIPS

boot=<boot device>

specify the device, where /boot is located. Example.

```
boot=/dev/sda1
boot=/dev/disk/by-path/pci-0000:00:1f.1-scsi-0:0:1:0-part1
boot=UUID=<uuid>
boot=LABEL=<label>
```

rd.fips.skipkernel

skip checksum check of the kernel image. Useful, if the kernel image is not in a separate boot partition.

### Network

Important It is recommended to either bind an interface to a MAC with the ifname argument, or to use the systemd-udevd predictable network interface names.

Predictable network interface device names based on:

•firmware/bios-provided index numbers for on-board devices

•firmware-provided pci-express hotplug slot index number

•physical/geographical location of the hardware

•the interface’s MAC address

See: http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames

Two character prefixes based on the type of interface:

en

ethernet

wl

wlan

ww

wwan

Type of names:

o<index>

on-board device index number

s<slot>[f<function>][d<dev_id>]

hotplug slot index number

x<MAC>

MAC address

[P<domain>]p<bus>s<slot>[f<function>][d<dev_id>]

PCI geographical location

[P<domain>]p<bus>s<slot>[f<function>][u<port>][..][c<config>][i<interface>]

USB port number chain

All multi-function PCI devices will carry the [f<function>] number in the device name, including the function 0 device.

When using PCI geography, The PCI domain is only prepended when it is not 0.

For USB devices the full chain of port numbers of hubs is composed. If the name gets longer than the maximum number of 15 characters, the name is not exported. The usual USB configuration == 1 and interface == 0 values are suppressed.

PCI ethernet card with firmware index "1"

•eno1

PCI ethernet card in hotplug slot with firmware index number

•ens1

PCI ethernet multi-function card with 2 ports

•enp2s0f0

•enp2s0f1

PCI wlan card

•wlp3s0

USB built-in 3G modem

•wwp0s29u1u4i6

USB Android phone

•enp0s29u1u2

The following options are supported by the network-legacy dracut module. Other network modules might support a slightly different set of options; refer to the documentation of the specific network module in use. For NetworkManager, see nm-initrd-generator(8).

ip={dhcp|on|any|dhcp6|auto6|either6|link6|single-dhcp}

dhcp|on|any

get ip from dhcp server from all interfaces. If netroot=dhcp, loop sequentially through all interfaces (eth0, eth1, ...) and use the first with a valid DHCP root-path.

single-dhcp

Send DHCP on all available interfaces in parallel, as opposed to one after another. After the first DHCP response is received, stop DHCP on all other interfaces. This gives the fastest boot time by using the IP on interface for which DHCP succeeded first during early boot. Caveat: Does not apply to Network Manager.

auto6

IPv6 autoconfiguration

dhcp6

IPv6 DHCP

either6

if auto6 fails, then dhcp6

link6

bring up interface for IPv6 link-local addressing

ip=<interface>:{dhcp|on|any|dhcp6|auto6|link6}[:[<mtu>][:<macaddr>]]

This parameter can be specified multiple times. dhcp|on|any|dhcp6

get ip from dhcp server on a specific interface

auto6

do IPv6 autoconfiguration

link6

bring up interface for IPv6 link local address

<macaddr>

optionally set <macaddr> on the <interface>. This cannot be used in conjunction with the ifname argument for the same <interface>.

ip=<client-IP>:[<peer>]:<gateway-IP>:<netmask>:<client_hostname>:<interface>:{none|off|dhcp|on|any|dhcp6|auto6|ibft}[:[<mtu>][:<macaddr>]]

explicit network configuration. If you want do define a IPv6 address, put it in brackets (e.g. [2001:DB8::1]). This parameter can be specified multiple times. <peer> is optional and is the address of the remote endpoint for pointopoint interfaces and it may be followed by a slash and a decimal number, encoding the network prefix length. <macaddr>

optionally set <macaddr> on the <interface>. This cannot be used in conjunction with the ifname argument for the same <interface>.

ip=<client-IP>:[<peer>]:<gateway-IP>:<netmask>:<client_hostname>:<interface>:{none|off|dhcp|on|any|dhcp6|auto6|ibft}[:[<dns1>][:<dns2>]]

explicit network configuration. If you want do define a IPv6 address, put it in brackets (e.g. [2001:DB8::1]). This parameter can be specified multiple times. <peer> is optional and is the address of the remote endpoint for pointopoint interfaces and it may be followed by a slash and a decimal number, encoding the network prefix length.

ifname=<interface>:<MAC>

Assign network device name <interface> (i.e. "bootnet") to the NIC with MAC <MAC>.

Warning

Do not use the default kernel naming scheme for the interface name, as it can conflict with the kernel names. So, don’t use "eth[0-9]+" for the interface name. Better name it "bootnet" or "bluesocket".

rd.route=<net>/<netmask>:<gateway>[:<interface>]

Add a static route with route options, which are separated by a colon. IPv6 addresses have to be put in brackets. Example.

```
    rd.route=192.168.200.0/24:192.168.100.222:ens10

    rd.route=192.168.200.0/24:192.168.100.222

    rd.route=192.168.200.0/24::ens10

    rd.route=[2001:DB8:3::/8]:[2001:DB8:2::1]:ens10
```

bootdev=<interface>

specify network interface to use routing and netroot information from. Required if multiple ip= lines are used.

BOOTIF=<MAC>

specify network interface to use routing and netroot information from.

rd.bootif=0

Disable BOOTIF parsing, which is provided by PXE

nameserver=<IP> [nameserver=<IP> ...]

specify nameserver(s) to use

rd.peerdns=0

Disable DNS setting of DHCP parameters.

biosdevname=0

boolean, turn off biosdevname network interface renaming

rd.neednet=1

boolean, bring up network even without netroot set

vlan=<vlanname>:<phydevice>

Setup vlan device named <vlanname> on <phydevice>. We support the four styles of vlan names: VLAN_PLUS_VID (vlan0005), VLAN_PLUS_VID_NO_PAD (vlan5), DEV_PLUS_VID (eth0.0005), DEV_PLUS_VID_NO_PAD (eth0.5)

bond=<bondname>[:<bondslaves>:[:<options>[:<mtu>]]]

Setup bonding device <bondname> on top of <bondslaves>. <bondslaves> is a comma-separated list of physical (ethernet) interfaces. <options> is a comma-separated list on bonding options (modinfo bonding for details) in format compatible with initscripts. If <options> includes multi-valued arp_ip_target option, then its values should be separated by semicolon. if the mtu is specified, it will be set on the bond master. Bond without parameters assumes bond=bond0:eth0,eth1:mode=balance-rr

team=<teammaster>:<teamslaves>[:<teamrunner>]

Setup team device <teammaster> on top of <teamslaves>. <teamslaves> is a comma-separated list of physical (ethernet) interfaces. <teamrunner> is the runner type to be used (see teamd.conf(5)); defaults to activebackup. Team without parameters assumes team=team0:eth0,eth1:activebackup

bridge=<bridgename>:<ethnames>

Setup bridge <bridgename> with <ethnames>. <ethnames> is a comma-separated list of physical (ethernet) interfaces. Bridge without parameters assumes bridge=br0:eth0

### NFS
root=[<server-ip>:]<root-dir>[:<nfs-options>]

mount nfs share from <server-ip>:/<root-dir>, if no server-ip is given, use dhcp next_server. If server-ip is an IPv6 address it has to be put in brackets, e.g. [2001:DB8::1]. NFS options can be appended with the prefix ":" or "," and are separated by ",".

root=nfs:[<server-ip>:]<root-dir>[:<nfs-options>], root=nfs4:[<server-ip>:]<root-dir>[:<nfs-options>], root={dhcp|dhcp6}

netroot=dhcp alone directs initrd to look at the DHCP root-path where NFS options can be specified. Example.

```
    root-path=<server-ip>:<root-dir>[,<nfs-options>]

    root-path=nfs:<server-ip>:<root-dir>[,<nfs-options>]

    root-path=nfs4:<server-ip>:<root-dir>[,<nfs-options>]
```

root=/dev/nfs nfsroot=[<server-ip>:]<root-dir>[:<nfs-options>]

Deprecated! kernel Documentation_/filesystems/nfsroot.txt_ defines this method. This is supported by dracut, but not recommended.

rd.nfs.domain=<NFSv4 domain name>

Set the NFSv4 domain name. Will override the settings in /etc/idmap.conf.

rd.net.dhcp.retry=<cnt>

If this option is set, dracut will try to connect via dhcp <cnt> times before failing. Default is 1.

rd.net.timeout.dhcp=<arg>

If this option is set, dhclient is called with "--timeout <arg>".

rd.net.timeout.iflink=<seconds>

Wait <seconds> until link shows up. Default is 60 seconds.

rd.net.timeout.ifup=<seconds>

Wait <seconds> until link has state "UP". Default is 20 seconds.

rd.net.timeout.route=<seconds>

Wait <seconds> until route shows up. Default is 20 seconds.

rd.net.timeout.ipv6dad=<seconds>

Wait <seconds> until IPv6 DAD is finished. Default is 50 seconds.

rd.net.timeout.ipv6auto=<seconds>

Wait <seconds> until IPv6 automatic addresses are assigned. Default is 40 seconds.

rd.net.timeout.carrier=<seconds>

Wait <seconds> until carrier is recognized. Default is 10 seconds.

### CIFS
root=cifs://[<username>[:<password>]@]<server-ip>:<root-dir>

mount cifs share from <server-ip>:/<root-dir>, if no server-ip is given, use dhcp next_server. if server-ip is an IPv6 address it has to be put in brackets, e.g. [2001:DB8::1]. If a username or password are not specified as part of the root, then they must be passed on the command line through cifsuser/cifspass.

Warning

Passwords specified on the kernel command line are visible for all users via the file /proc/cmdline and via dmesg or can be sniffed on the network, when using DHCP with DHCP root-path.

cifsuser=<username>

Set the cifs username, if not specified as part of the root.

cifspass=<password>

Set the cifs password, if not specified as part of the root.

Warning

Passwords specified on the kernel command line are visible for all users via the file /proc/cmdline and via dmesg or can be sniffed on the network, when using DHCP with DHCP root-path.

### iSCSI
root=iscsi:[<username>:<password>[:<reverse>:<password>]@][<servername>]:[<protocol>]:[<port>][:[<iscsi_iface_name>]:[<netdev_name>]]:[<LUN>]:<targetname>

protocol defaults to "6", LUN defaults to "0". If the "servername" field is provided by BOOTP or DHCP, then that field is used in conjunction with other associated fields to contact the boot server in the Boot stage. However, if the "servername" field is not provided, then the "targetname" field is then used in the Discovery Service stage in conjunction with other associated fields. See rfc4173[1].

Warning

Passwords specified on the kernel command line are visible for all users via the file /proc/cmdline and via dmesg or can be sniffed on the network, when using DHCP with DHCP root-path.

Example.

```
root=iscsi:192.168.50.1::::iqn.2009-06.dracut:target0
```

If servername is an IPv6 address, it has to be put in brackets:

Example.

```
root=iscsi:[2001:DB8::1]::::iqn.2009-06.dracut:target0
```

root=??? netroot=iscsi:[<username>:<password>[:<reverse>:<password>]@][<servername>]:[<protocol>]:[<port>][:[<iscsi_iface_name>]:[<netdev_name>]]:[<LUN>]:<targetname> ...

multiple netroot options allow setting up multiple iscsi disks: Example.

```
root=UUID=12424547
netroot=iscsi:192.168.50.1::::iqn.2009-06.dracut:target0
netroot=iscsi:192.168.50.1::::iqn.2009-06.dracut:target1
```

If servername is an IPv6 address, it has to be put in brackets:

Example.

```
netroot=iscsi:[2001:DB8::1]::::iqn.2009-06.dracut:target0
```

Warning

Passwords specified on the kernel command line are visible for all users via the file /proc/cmdline and via dmesg or can be sniffed on the network, when using DHCP with DHCP root-path. You may want to use rd.iscsi.firmware.

root=??? rd.iscsi.initiator=<initiator> rd.iscsi.target.name=<target name> rd.iscsi.target.ip=<target ip> rd.iscsi.target.port=<target port> rd.iscsi.target.group=<target group> rd.iscsi.username=<username> rd.iscsi.password=<password> rd.iscsi.in.username=<in username> rd.iscsi.in.password=<in password>

manually specify all iscsistart parameter (see iscsistart --help)

Warning

Passwords specified on the kernel command line are visible for all users via the file /proc/cmdline and via dmesg or can be sniffed on the network, when using DHCP with DHCP root-path. You may want to use rd.iscsi.firmware.

root=??? netroot=iscsi rd.iscsi.firmware=1

will read the iscsi parameter from the BIOS firmware

rd.iscsi.login_retry_max=<num>

maximum number of login retries

rd.iscsi.param=<param>

<param> will be passed as "--param <param>" to iscsistart. This parameter can be specified multiple times. Example.

```
"netroot=iscsi rd.iscsi.firmware=1 rd.iscsi.param=node.session.timeo.replacement_timeout=30"
```

will result in

```
iscsistart -b --param node.session.timeo.replacement_timeout=30
```

rd.iscsi.ibft rd.iscsi.ibft=1: Turn on iBFT autoconfiguration for the interfaces

rd.iscsi.mp rd.iscsi.mp=1: Configure all iBFT interfaces, not only used for booting (multipath)

rd.iscsi.waitnet=0: Turn off waiting for all interfaces to be up before trying to login to the iSCSI targets.

rd.iscsi.testroute=0: Turn off checking, if the route to the iSCSI target IP is possible before trying to login.

### FCoE
rd.fcoe=0

disable FCoE and lldpad

fcoe=<edd|interface|MAC>:{dcb|nodcb}:{fabric|vn2vn}

Try to connect to a FCoE SAN through the NIC specified by <interface> or <MAC> or EDD settings. The second argument specifies if DCB should be used. The optional third argument specifies whether fabric or VN2VN mode should be used. This parameter can be specified multiple times.

Note

letters in the MAC-address must be lowercase!

### NVMf
rd.nonvmf

Disable NVMf

rd.nvmf.nonbft

Disable connecting to targets from the NVMe Boot Firmware Table. Without this parameter, NBFT connections will take precedence over rd.nvmf.discover.

rd.nvmf.nostatic

Disable connecting to targets that have been statically configured when the initramfs was built. Targets specified with rd.nvmf.discover on the kernel command line will still be tried.

rd.nvmf.hostnqn=<hostNQN>

NVMe host NQN to use

rd.nvmf.hostid=<hostID>

NVMe host id to use

rd.nvmf.discover={rdma|fc|tcp},<traddr>,[<host_traddr>],[<trsvcid>]

Discover and connect to a NVMe-over-Fabric controller specified by <traddr> and the optionally <host_traddr> or <trsvcid>. The first argument specifies the transport to use; currently only rdma, fc, or tcp are supported. This parameter can be specified multiple times. Examples.

```
rd.nvmf.discover=tcp,192.168.10.10,,4420
rd.nvmf.discover=fc,nn-0x201700a05634f5bf:pn-0x201900a05634f5bf,nn-0x200000109b579ef3:pn-0x100000109b579ef3
```

rd.nvmf.discover=fc,auto

This special syntax determines that Fibre Channel autodiscovery is to be used rather than regular NVMe discovery. It takes precedence over all other rd.nvmf.discover= arguments.

### NBD
root=??? netroot=nbd:<server>:<port/exportname>[:<fstype>[:<mountopts>[:<nbdopts>]]]

mount nbd share from <server>. NOTE: If "exportname" instead of "port" is given the standard port is used. Newer versions of nbd are only supported with "exportname".

root=/dev/root netroot=dhcp with dhcp root-path=nbd:<server>:<port/exportname>[:<fstype>[:<mountopts>[:<nbdopts>]]]

netroot=dhcp alone directs initrd to look at the DHCP root-path where NBD options can be specified. This syntax is only usable in cases where you are directly mounting the volume as the rootfs. NOTE: If "exportname" instead of "port" is given the standard port is used. Newer versions of nbd are only supported with "exportname".

### VIRTIOFS
root=virtiofs:<mount-tag>

mount virtiofs share using the tag <mount-tag>. The tag name is arbitrary and must match the tag given in the qemu -device command.

rootfstype=virtiofs root=<mount-tag>

mount virtiofs share using the tag <mount-tag>. The tag name is arbitrary and must match the tag given in the qemu -device command.

Both formats are supported by the virtiofs dracut module. See https://gitlab.com/virtio-fs/virtiofsd for more information.

Example.

```
root=virtiofs:host rw
```

### DASD
rd.dasd=....

same syntax as the kernel module parameter (s390 only)

### ZFCP
rd.zfcp=<zfcp adaptor device bus ID>,<WWPN>,<FCPLUN>

rd.zfcp can be specified multiple times on the kernel command line.

rd.zfcp=<zfcp adaptor device bus ID>

If NPIV is enabled and the allow_lun_scan parameter to the zfcp module is set to Y then the zfcp adaptor will be initiating a scan internally and the <WWPN> and <FCPLUN> parameters can be omitted. Example.

```
rd.zfcp=0.0.4000,0x5005076300C213e9,0x5022000000000000
rd.zfcp=0.0.4000
```

rd.zfcp.conf=0

ignore zfcp.conf included in the initramfs

### ZNET
rd.znet=<nettype>,<subchannels>,<options>

The whole parameter is appended to /etc/ccw.conf, which is used on RHEL/Fedora with ccw_init, which is called from udev for certain devices on z-series. rd.znet can be specified multiple times on the kernel command line.

rd.znet_ifname=<ifname>:<subchannels>

Assign network device name <interface> (i.e. "bootnet") to the NIC corresponds to the subchannels. This is useful when dracut’s default "ifname=" doesn’t work due to device having a changing MAC address. Example.

```
rd.znet=qeth,0.0.0600,0.0.0601,0.0.0602,layer2=1,portname=foo
rd.znet=ctc,0.0.0600,0.0.0601,protocol=bar
```

### Booting live images
Dracut offers multiple options for live booted images:

SquashFS with read-only filesystem image

The system will boot with a read-only filesystem from the SquashFS and apply a writable Device-mapper snapshot or an OverlayFS overlay mount for the read-only base filesystem. This method ensures a relatively fast boot and lower RAM usage. Users must be careful to avoid writing too many blocks to a snapshot volume. Once the blocks of the snapshot overlay are exhausted, the root filesystem becomes read-only and may cause application failures. The snapshot overlay file is marked Overflow, and a difficult recovery is required to repair and enlarge the overlay offline. Non-persistent overlays are sparse files in RAM that only consume content space as required blocks are allocated. They default to an apparent size of 32 GiB in RAM. The size can be adjusted with the rd.live.overlay.size= kernel command line option. The filesystem structure is traditionally expected to be:

```
squashfs.img          |  SquashFS from LiveCD .iso

   !(mount)

   /LiveOS

       |- rootfs.img  |  Filesystem image to mount read-only

            !(mount)

            /bin      |  Live filesystem

            /boot     |

            /dev      |

            ...       |
```

For OverlayFS mount overlays, the filesystem structure may also be a direct compression of the root filesystem:

```
squashfs.img          |  SquashFS from LiveCD .iso

   !(mount)

   /bin               |  Live filesystem

   /boot              |

   /dev               |

   ...                |
```

Dracut uses one of the overlay methods of live booting by default. No additional command line options are required other than root=live:<URL> to specify the location of your squashed filesystem.

•The compressed SquashFS image can be copied during boot to RAM at /run/initramfs/squashed.img by using the rd.live.ram=1 option.

•A device with a persistent overlay can be booted read-only by using the rd.live.overlay.readonly option on the kernel command line. This will either cause a temporary, writable overlay to be stacked over a read-only snapshot of the root filesystem or the OverlayFS mount will use an additional lower layer with the root filesystem.

Uncompressed live filesystem image

When the live system was installed with the --skipcompress option of the livecd-iso-to-disk installation script for Live USB devices, the root filesystem image, rootfs.img, is expanded on installation and no SquashFS is involved during boot.

•If rd.live.ram=1 is used in this situation, the full, uncompressed root filesystem is copied during boot to /run/initramfs/rootfs.img in the /run tmpfs.

•If rd.live.overlay=none is provided as a kernel command line option, a writable, linear Device-mapper target is created on boot with no overlay.

Writable filesystem image

The system will retrieve a compressed filesystem image, extract it to /run/initramfs/fsimg/rootfs.img, connect it to a loop device, create a writable, linear Device-mapper target at /dev/mapper/live-rw, and mount that as a writable volume at /. More RAM is required during boot but the live filesystem is easier to manage if it becomes full. Users can make a filesystem image of any size and that size will be maintained when the system boots. There is no persistence of root filesystem changes between boots with this option. The filesystem structure is expected to be:

```
rootfs.tgz            |  Compressed tarball containing filesystem image

   !(unpack)

   /rootfs.img        |  Filesystem image at /run/initramfs/fsimg/

      !(mount)

      /bin            |  Live filesystem

      /boot           |

      /dev            |

      ...             |
```

To use this boot option, ensure that rd.writable.fsimg=1 is in your kernel command line and add the root=live:<URL> to specify the location of your compressed filesystem image tarball or SquashFS image.

rd.writable.fsimg=1

Enables writable filesystem support. The system will boot with a fully writable (but non-persistent) filesystem without snapshots (see notes above about available live boot options). You can use the rootflags option to set mount options for the live filesystem as well (see documentation about rootflags in the Standard section above). This implies that the whole image is copied to RAM before the boot continues.

Note

There must be enough free RAM available to hold the complete image.

This method is very suitable for diskless boots.

rd.minmem=<megabyte>

Specify minimum free RAM in MB after copying a live disk image into memory. The default is 1024. This parameter only applies together with the parameters rd.writable.fsimg or rd.live.ram.

root=live:<url>

Boots a live image retrieved from <url>. Requires the dracut livenet module. Valid handlers: http, https, ftp, torrent, tftp. Examples.

```
root=live:http://example.com/liveboot.img
root=live:ftp://ftp.example.com/liveboot.img
root=live:torrent://example.com/liveboot.img.torrent
```

rd.live.debug=1

Enables debug output from the live boot process.

rd.live.dir=<path>

Specifies the directory within the boot device where the squashfs.img or rootfs.img can be found. By default, this is /LiveOS.

rd.live.squashimg=<filename of SquashFS image>

Specifies the filename for a SquashFS image of the root filesystem. By default, this is squashfs.img.

rd.live.ram=1

Copy the complete image to RAM and use this for booting. This is useful when the image resides on, e.g., a DVD which needs to be ejected later on.

rd.live.overlay={<devspec>[:{<pathspec>|auto}]|none}

Manage the usage of a permanent overlay.

•<devspec> specifies the path to a device with a mountable filesystem.

•<pathspec> is the path to a file within that filesystem, which shall be used to persist the changes made to the device specified by the root=live:<url> option. The default pathspec, when auto or no :<pathspec> is given, is /<rd.live.dir>/overlay-<label>-<uuid>, where <label> is the device LABEL, and <uuid> is the device UUID. * none (the word itself) specifies that no overlay will be used, such as when an uncompressed, writable live root filesystem is available.

If a persistent overlay is detected at the standard LiveOS path, the overlay & overlay type detected, whether Device-mapper or OverlayFS, will be used.

Examples.

```
rd.live.overlay=/dev/sdb1:persistent-overlay.img
rd.live.overlay=UUID=99440c1f-8daa-41bf-b965-b7240a8996f4
```

rd.live.overlay.cowfs=[btrfs|ext4|xfs]

Specifies the filesystem to use when formatting the overlay partition. The default is ext4.

rd.live.overlay.size=<size_MiB>

Specifies a non-persistent Device-mapper overlay size in MiB. The default is 32768.

rd.live.overlay.readonly=1

This is used to boot with a normally read-write persistent overlay in a read-only mode. With this option, either an additional, non-persistent, writable snapshot overlay will be stacked over a read-only snapshot, /dev/mapper/live-ro, of the base filesystem with the persistent overlay, or a read-only loop device, in the case of a writable rootfs.img, or an OverlayFS mount will use the persistent overlay directory linked at /run/overlayfs-r as an additional lower layer along with the base root filesystem and apply a transient, writable upper directory overlay, in order to complete the booted root filesystem.

rd.live.overlay.reset=1

Specifies that a persistent overlay should be reset on boot. All previous root filesystem changes are vacated by this action.

rd.live.overlay.thin=1

Enables the usage of thin snapshots instead of classic dm snapshots. The advantage of thin snapshots is that they support discards, and will free blocks that are not claimed by the filesystem. In this use case, this means that memory is given back to the kernel when the filesystem does not claim it anymore.

rd.live.overlay.overlayfs=1

Enables the use of the OverlayFS kernel module, if available, to provide a copy-on-write union directory for the root filesystem. OverlayFS overlays are directories of the files that have changed on the read-only base (lower) filesystem. The root filesystem is provided through a special overlay type mount that merges the lower and upper directories. If an OverlayFS upper directory is not present on the boot device, a tmpfs directory will be created at /run/overlayfs to provide temporary storage. Persistent storage can be provided on vfat or msdos formatted devices by supplying the OverlayFS upper directory within an embedded filesystem that supports the creation of trusted.* extended attributes and provides a valid d_type in readdir responses, such as with ext4 and xfs. On non-vfat-formatted devices, a persistent OverlayFS overlay can extend the available root filesystem storage up to the capacity of the LiveOS disk device. If a persistent overlay is detected at the standard LiveOS path, the overlay & overlay type detected, whether OverlayFS or Device-mapper, will be used.

The rd.live.overlay.readonly option, which allows a persistent overlayfs to be mounted read-only through a higher level transient overlay directory, has been implemented through the multiple lower layers feature of OverlayFS.

### ZIPL
rd.zipl=<path to blockdevice>

Update the dracut commandline with the values found in the dracut-cmdline.conf file on the given device. The values are merged into the existing commandline values and the udev events are regenerated. Example.

```
rd.zipl=UUID=0fb28157-99e3-4395-adef-da3f7d44835a
```

### CIO_IGNORE
rd.cio_accept=<device-ids>

Remove the devices listed in <device-ids> from the default cio_ignore kernel command-line settings. <device-ids> is a list of comma-separated CCW device ids. The default for this value is taken from the /boot/zipl/active_devices.txt file. Example.

```
rd.cio_accept=0.0.0180,0.0.0800,0.0.0801,0.0.0802
```

### Plymouth Boot Splash
plymouth.enable=0

disable the plymouth bootsplash completely.

rd.plymouth=0

disable the plymouth bootsplash only for the initramfs.

### Kernel keys
masterkey=<kernel master key path name>

Set the path name of the kernel master key. Example.

```
masterkey=/etc/keys/kmk-trusted.blob
```

masterkeytype=<kernel master key type>

Set the type of the kernel master key. Example.

```
masterkeytype=trusted
```

evmkey=<EVM HMAC key path name>

Set the path name of the EVM HMAC key. Example.

```
evmkey=/etc/keys/evm-trusted.blob
```

evmx509=<EVM X.509 cert path name>

Set the path name of the EVM X.509 certificate. Example.

```
evmx509=/etc/keys/x509_evm.der
```

ecryptfskey=<eCryptfs key path name>

Set the path name of the eCryptfs key. Example.

```
ecryptfskey=/etc/keys/ecryptfs-trusted.blob
```

### Deprecated, renamed Options
Here is a list of options, which were used in dracut prior to version 008, and their new replacement.

rdbreak

rd.break

rd.ccw

rd.znet

rd_CCW

rd.znet

rd_DASD_MOD

rd.dasd

rd_DASD

rd.dasd

rdinitdebug rdnetdebug

rd.debug

rd_NO_DM

rd.dm=0

rd_DM_UUID

rd.dm.uuid

rdblacklist

rd.driver.blacklist

rdinsmodpost

rd.driver.post

rdloaddriver

rd.driver.pre

rd_NO_FSTAB

rd.fstab=0

rdinfo

rd.info

check

rd.live.check

rdlivedebug

rd.live.debug

live_dir

rd.live.dir

liveimg

rd.live.image

overlay

rd.live.overlay

readonly_overlay

rd.live.overlay.readonly

reset_overlay

rd.live.overlay.reset

live_ram

rd.live.ram

rd_NO_CRYPTTAB

rd.luks.crypttab=0

rd_LUKS_KEYDEV_UUID

rd.luks.keydev.uuid

rd_LUKS_KEYPATH

rd.luks.keypath

rd_NO_LUKS

rd.luks=0

rd_LUKS_UUID

rd.luks.uuid

rd_NO_LVMCONF

rd.lvm.conf

rd_LVM_LV

rd.lvm.lv

rd_NO_LVM

rd.lvm=0

rd_LVM_VG

rd.lvm.vg

rd_NO_MDADMCONF

rd.md.conf=0

rd_NO_MDIMSM

rd.md.imsm=0

rd_NO_MD

rd.md=0

rd_MD_UUID

rd.md.uuid

rd_NO_MULTIPATH: rd.multipath=0

rd_NFS_DOMAIN

rd.nfs.domain

iscsi_initiator

rd.iscsi.initiator

iscsi_target_name

rd.iscsi.target.name

iscsi_target_ip

rd.iscsi.target.ip

iscsi_target_port

rd.iscsi.target.port

iscsi_target_group

rd.iscsi.target.group

iscsi_username

rd.iscsi.username

iscsi_password

rd.iscsi.password

iscsi_in_username

rd.iscsi.in.username

iscsi_in_password

rd.iscsi.in.password

iscsi_firmware

rd.iscsi.firmware=0

rd_NO_PLYMOUTH

rd.plymouth=0

rd_retry

rd.retry

rdshell

rd.shell

rd_NO_SPLASH

rd.splash

rdudevdebug

rd.udev.debug

rdudevinfo

rd.udev.info

rd_NO_ZFCPCONF

rd.zfcp.conf=0

rd_ZFCP

rd.zfcp

rd_ZNET

rd.znet

KEYMAP

vconsole.keymap

KEYTABLE

vconsole.keymap

SYSFONT

vconsole.font

CONTRANS

vconsole.font.map

UNIMAP

vconsole.font.unimap

UNICODE

vconsole.unicode

EXT_KEYMAP

vconsole.keymap.ext

### Configuration in the Initramfs
/etc/conf.d/

Any files found in /etc/conf.d/ will be sourced in the initramfs to set initial values. Command line options will override these values set in the configuration files.

/etc/cmdline

Can contain additional command line options. Deprecated, better use /etc/cmdline.d/*.conf.

/etc/cmdline.d/*.conf

Can contain additional command line options.

## AUTHOR
Harald Hoyer

## SEE ALSO
dracut(8) dracut.conf(5)

## NOTES
1.

rfc4173

http://tools.ietf.org/html/rfc4173#section-5


dracut.modules

title: dracut.modules(7)

summary: dracut modules

text:
# dracut.modules(7)

## NAME
dracut.modules - dracut modules

## DESCRIPTION
dracut uses a modular system to build and extend the initramfs image. All modules are located in /usr/lib/dracut/modules.d or in <git-src>/modules.d. The most basic dracut module is 99base. In 99base the initial shell script init is defined, which gets run by the kernel after initramfs loading. Although you can replace init with your own version of 99base, this is not encouraged. Instead you should use, if possible, the hooks of dracut. All hooks, and the point of time in which they are executed, are described in the section called “BOOT PROCESS STAGES”.

The main script, which creates the initramfs is dracut itself. It parses all arguments and sets up the directory, in which everything is installed. It then executes all check, install, installkernel scripts found in the modules, which are to be processed. After everything is installed, the install directory is archived and compressed to the final initramfs image. All helper functions used by check, install and installkernel are found in in the file dracut-functions. These shell functions are available to all module installer (install, installkernel) scripts, without the need to source dracut-functions.

A module can check the preconditions for install and installkernel with the check script. Also dependencies can be expressed with check. If a module passed check, install and installkernel will be called to install all of the necessary files for the module. To split between kernel and non-kernel parts of the installation, all kernel module related parts have to be in installkernel. All other files found in a module directory are module specific and mostly are hook scripts and udev rules.

## BOOT PROCESS STAGES
dracut modules can insert custom script at various points, to control the boot process. These hooks are plain directories containing shell scripts ending with ".sh", which are sourced by init. Common used functions are in dracut-lib.sh, which can be sourced by any script.

### Hook: cmdline
The cmdline hook is a place to insert scripts to parse the kernel command line and prepare the later actions, like setting up udev rules and configuration files.

In this hook the most important environment variable is defined: root. The second one is rootok, which indicates, that a module claimed to be able to parse the root defined. So for example, root=iscsi:.... will be claimed by the iscsi dracut module, which then sets rootok.

### Hook: pre-udev
This hook is executed right after the cmdline hook and a check if root and rootok were set. Here modules can take action with the final root, and before udev has been run.

### Start Udev
Now udev is started and the logging for udev is setup.

### Hook: pre-trigger
In this hook, you can set udev environment variables with udevadm control --property=KEY=value or control the further execution of udev with udevadm.

### Trigger Udev
udev is triggered by calling udevadm trigger, which sends add events for all devices and subsystems.

### Main Loop
In the main loop of dracut loops until udev has settled and all scripts in initqueue/finished returned true. In this loop there are three hooks, where scripts can be inserted by calling /sbin/initqueue.

Initqueue

This hook gets executed every time a script is inserted here, regardless of the udev state.

Initqueue settled

This hook (initqueue/settled) gets executed every time udev has settled.

Initqueue timeout

This hook (initqueue/timeout) gets executed, when the main loop counter becomes half of the rd.retry counter.

Initqueue online

This hook (initqueue/online) gets executed whenever a network interface comes online (that is, once it is up and configured by the configured network module).

Initqueue finished

This hook (initqueue/finished) is called after udev has settled and if all scripts herein return 0 the main loop will be ended. Arbitrary scripts can be added here, to loop in the initqueue until something happens, which a dracut module wants to wait for.

### Hook: pre-mount
Before the root device is mounted all scripts in the hook pre-mount are executed. In some cases (e.g. NFS) the real root device is already mounted, though.

### Hook: mount
This hook is mainly to mount the real root device.

### Hook: pre-pivot
This hook is called before cleanup hook, This is a good place for actions other than cleanups which need to be called before pivot.

### Hook: cleanup
This hook is the last hook and is called before init finally switches root to the real root device. This is a good place to clean up and kill processes not needed anymore.

### Cleanup and switch_root
Init (or systemd) kills all udev processes, cleans up the environment, sets up the arguments for the real init process and finally calls switch_root. switch_root removes the whole filesystem hierarchy of the initramfs, chroot()s to the real root device and calls /sbin/init with the specified arguments.

To ensure all files in the initramfs hierarchy can be removed, all processes still running from the initramfs should not have any open file descriptors left.

## NETWORK INFRASTRUCTURE
FIXME

## WRITING A MODULE
A simple example module is 90kernel-modules, which modprobes a kernel module after udev has settled and the basic device drivers have been loaded.

All module installation information is in the file module-setup.sh.

First we create a check() function, which just exits with 0 indicating that this module should be included by default.

check():

```
return 0
```

Then we create the install() function, which installs a cmdline hook with priority number 20 called parse-insmodpost.sh. It also installs the insmodpost.sh script in /sbin.

install():

```
inst_hook cmdline 20 "$moddir/parse-insmodpost.sh"
inst_simple "$moddir/insmodpost.sh" /sbin/insmodpost.sh
```

The parse-instmodpost.sh parses the kernel command line for a argument rd.driver.post, blacklists the module from being autoloaded and installs the hook insmodpost.sh in the initqueue/settled.

parse-insmodpost.sh:

```
for p in $(getargs rd.driver.post=); do

    echo "blacklist $p" >> /etc/modprobe.d/initramfsblacklist.conf

    _do_insmodpost=1
done
[ -n "$_do_insmodpost" ] && /sbin/initqueue --settled --unique --onetime /sbin/insmodpost.sh
unset _do_insmodpost
```

insmodpost.sh, which is called in the initqueue/settled hook will just modprobe the kernel modules specified in all rd.driver.post kernel command line parameters. It runs after udev has settled and is only called once (--onetime).

insmodpost.sh:

```
. /lib/dracut-lib.sh
for p in $(getargs rd.driver.post=); do

    modprobe $p
done
```

### module-setup.sh: check()
check() is called by dracut to evaluate the inclusion of a dracut module in the initramfs.

$hostonly

If the $hostonly variable is set, then the module check() function should be in "hostonly" mode, which means, that the check() should only return 0, if the module is really needed to boot this specific host.

check() should return with:

0

Include the dracut module in the initramfs.

1

Do not include the dracut module. The requirements are not fulfilled (missing tools, etc.)

255

Only include the dracut module, if another module requires it or if explicitly specified in the config file or on the argument list.

### module-setup.sh: depends()
The function depends() should echo all other dracut module names the module depends on.

### module-setup.sh: cmdline()
This function should print the kernel command line options needed to boot the current machine setup. It should start with a space and should not print a newline.

### module-setup.sh: install()
The install() function is called to install everything non-kernel related. To install binaries, scripts, and other files, you can use the functions mentioned in [creation].

To address a file in the current module directory, use the variable "$moddir".

### module-setup.sh: installkernel()
In installkernel() all kernel related files should be installed. You can use all of the functions mentioned in [creation] to install files.

### Creation Functions
inst_multiple [-o] <file> [ <file> ...]

installs multiple binaries and files. If executables are specified without a path, dracut will search the path PATH=/usr/sbin:/sbin:/usr/bin:/bin for the binary. If the option "-o" is given as the first parameter, a missing file does not lead to an error.

inst <src> [<dst>]

installs one file <src> either to the same place in the initramfs or to an optional <dst>. inst with more than two arguments is treated the same as inst_multiple, all arguments are treated as files to install and none as install destinations.

inst_hook <hookdir> <prio> <src>

installs an executable/script <src> in the dracut hook <hookdir> with priority <prio>.

inst_rules <udevrule> [ <udevrule> ...]

installs one or more udev rules. Non-existent udev rules are reported, but do not let dracut fail.

instmods <kernelmodule> [ <kernelmodule> ... ]

instmods should be used only in the installkernel() function.

instmods installs one or more kernel modules in the initramfs. <kernelmodule> can also be a whole subsystem, if prefixed with a "=", like "=drivers/net/team".

instmods will not install the kernel module, if $hostonly is set and the kernel module is not currently needed by any /sys/.../uevent MODALIAS. To install a kernel module regardless of the hostonly mode use the form:

```
hostonly='' instmods <kernelmodule>
```

### Initramfs Functions
FIXME

### Network Modules
FIXME

## AUTHOR
Harald Hoyer

## SEE ALSO
dracut(8)


drbd-configured.target

package: drbd-utils

title: drbd-configured.target(7)

text:
# drbd-configured.target(7)

## NAME
drbd-configured.target - System target unit indicating all (enabled) DRBD resources are configured

## SYNOPSIS
drbd-configured.target

## DESCRIPTION
This target should be enabled by default, and acts as a synchronization point to "install" the individual drbd@RESNAME.target instances.

You can then order any units that expect on one or more DRBD resources to be configured after drbd-configured.target.

## EXAMPLE

```
systemctl enable drbd-configured.target
for res in $(drbdadm sh-resources); do

    systemctl enable drbd@$(systemd-escape "$res").target
done
```

## SEE ALSO
drbd@.target(7)

## AUTHORS
LINBIT HA Solutions GmbH https://linbit.com


drbd-graceful-shutdown.service

title: drbd-graceful-shutdown.service(7)

text:
# drbd-graceful-shutdown.service(7)

## NAME
drbd-graceful-shutdown.service - Attempt graceful shut down of DRBD resource on system shut down

## SYNOPSIS
drbd-graceful-shutdown.service

## DESCRIPTION
This service is the attempt to shutdown DRBD resources while they still have a chance to communicate this with their peers so they can "gracefully" leave the DRBD replication.

For this reason, this unit is ordered after network-online.target: on system shut down, this service will be stopped before the network is torn down.

Resources that are explicitly managed by other systemd services should be stopped there. So this is also ordered before resource-agents-deps.target and drbd.service and the per-resource drbd@.service templates, which makes it be stopped only after those are stopped.

If you have some other foo.service that starts and stops DRBD resources, you should add a drop-in /etc/systemd/system/drbd-graceful-shutdown.service.d/foo.conf

```
[Unit]
Before=foo.service
```

(Or the inverse, add an After=drbd-graceful-shutdown.service to your foo.service).

If you for some reason want to opt-out of this service, you can still systemctl mask it.

## AUTHORS
LINBIT HA Solutions GmbH https://linbit.com


drbd-lvchange@.service

title: drbd-lvchange@.service(7)

text:
# drbd-lvchange@.service(7)

## NAME
drbd-lvchange@.service - System unit to (de)activate backing LVM2 LVs for a specific DRBD resource

## SYNOPSIS
drbd-lvchange@RESNAME.service

## DESCRIPTION
If you try to start (configure) a DRBD using the drbd@RESNAME.service, chances are that this fails because at the time its backing block devices are not (yet) available.

If you know those backing devices are LVM2 LVs, enable this optional service, to add an explicit dependency on those LVs and try to activate them first. It will also de-activate them on stop.

systemctl enable drbd-lvchange@RESNAME.service

## SEE ALSO
drbd@.service(7), drbd@.target(7), lvm(8), lvchange(8)

## AUTHORS
LINBIT HA Solutions GmbH https://linbit.com


drbd-promote@.service

title: drbd-promote@.service(7)

text:
# drbd-promote@.service(7)

## NAME
drbd-promote@.service - System unit to promote a specific DRBD resource

## SYNOPSIS
drbd-promote@RESNAME.service

## DESCRIPTION
Usually you do not want to "hardcode" an unconditional promotion attempt of DRBD resources, because you usually cannot know a-priory whether this instance of DRBD will have access to good data (yet).

So this is intended to be used for conditional promotion, for example using drbd-reactor to monitor DRBD internal states and react on specific state changes to try and bring up the drbd-services@RESNAME.target, starting with this unit and following the dependency chain of services as specified in the corresponding drbd-reactor promoter plugin configuration.

You typically should not use this unit directly.

## SEE ALSO
drbd-reactor(1) drbd-reactor.promoter(5)

## AUTHORS
LINBIT HA Solutions GmbH https://linbit.com


summary: System unit to re\-configure specific DRBD aspects

text:
# drbd-reconfigure-suspend-or-error@.service(7)

## NAME
drbd-reconfigure-suspend-or-error@.service - System unit to re-configure specific DRBD aspects

## SYNOPSIS
drbd-reconfigure-suspend-or-error@RESNAME.service

## DESCRIPTION
If a disk fails or a replication link goes down and as a consequence DRBD loses "quorum" or access to good data, DRBD can be configured to either suspend-io or return io-errors.

io-errors allow file systems and applications to notice and stop themselves or be unmounted. The assumption is that some other node(s) will still have good data and some cluster manager or other monitoring entity will notice the situation and try to bring up services there.

suspend-io allows the problematic incident to be hidden from file systems and applications, they would just block until access to good data is restored. This can be useful to cope with supposedly short "network hickup" like incidents without causing service restarts.

But if IO is "suspended" (blocked, frozen, also known as "un-interruptible sleep" or "D state"), applications cannot be killed, file systems cannot be unmounted.

If some other node was told to take over services meanwhile, we need to demote DRBD on the "frozen" node before we can re-integrate it.

In these scenarios it may be useful to configure DRBD for suspend-io during normal operation, so it would mask intermittent problems, but if services had been taken over by some other partition of nodes in the storage cluster, reconfigure for io-error, to be able to bring down services and unmount file systems before trying to re-integrate this node.

This service reconfigures RESNAME for suspend-io when started and for io-error when stopped.

You should test a lot and maybe talk to LINBIT support before using this.

See also the DRBD User’s Guide[1]

## AUTHORS
LINBIT HA Solutions GmbH https://linbit.com

## NOTES
1.

DRBD User’s Guide

https://linbit.com/drbd-user-guide/drbd-guide-9_0-en/


drbd-services@.target

title: drbd-services@.target(7)

text:
# drbd-services@.target(7)

## NAME
drbd-services@.target - System target unit to group services depending on a specific DRBD resource

## SYNOPSIS
drbd-services@RESNAME.target

## DESCRIPTION
This target is intended to be used by drbd-reactor as a "handle" for the services depending on the specific DRBD resource RESNAME. See drbd-reactor for how the dependency chain of services is meant to be defined and parameterized.

## SEE ALSO
drbd-reactor(1), drbd-reactor.promoter(5)

## AUTHORS
LINBIT HA Solutions GmbH https://linbit.com


drbd-wait-promotable@.service

title: drbd-wait-promotable@.service(7)

summary: Wait for DRBD to become promotable

text:
# drbd-wait-promotable@.service(7)

## NAME
drbd-wait-promotable@.service - Wait for DRBD to become promotable

## SYNOPSIS
drbd-wait-promotable@RESNAME.service - Wait for DRBD to become promotable

## DESCRIPTION
Usually you do not want to "hardcode" an unconditional promotion attempt of DRBD resources, because you usually cannot know a-priory whether this instance of DRBD will have access to good data (yet).

If you try to promote (mount, use) DRBD before it can be certain to have access to good data, the attempt will fail in various ways, typically claiming "wrong medium type", "need access to good data".

This unit will wait for the DRBD internal state to indicate that it has access to good data. It does not monitor the state further, so this is good enough only to avoid trying to mount "too early" if you hard-code the mount attempt into your boot sequence, for example using an fstab entry or similar.

To monitor and react to DRBD state changes, use drbd-reactor or a cluster manager like pacemaker.

If you systemctl enable this unit, it will be required by drbd@.target, so anything depending on that target, for example an fstab entry, will implicitly wait until this DRBD indicated it was "healthy enough" to be used.

It can still timeout, in which case systemd sees this as a start failure, and starting of any dependencies (e.g. the mount) won’t be attempted at this point.

## SEE ALSO
drbd@.service(7), drbd@.target(7), drbd-lvchange@.service(7)

## AUTHORS
LINBIT HA Solutions GmbH https://linbit.com


drbd.service

title: drbd.service(7)

summary: System unit to configure all DRBD resources

text:
# drbd.service(7)

## NAME
drbd.service - System unit to configure "all" DRBD resources

## SYNOPSIS
drbd.service

## DESCRIPTION
Do not confuse this with the templated, resource specific drbd@RESNAME.service.

This unit is basically a wrapper for the old style init script that will attempt to configure all DRBD resources as defined in the global configuration files.

It can not be parameterized, and there is no useful way to wait for any or all DRBD resources to become "ready".

You should usually disable this unit.

If you use a cluster manager like pacemaker, that should bring up the DRBD resources instead, and via the DRBD ocf resource agent integration also notices when DRBD is "ready" to be used.

If you use LINSTOR and/or drbd-reactor, LINSTOR will bring up the resources, and drbd-reactor will attempt to bring up the services once DRBD becomes ready.

If you want to "hardcode" a promotion/mount attempt of specific DRBD resources into your boot sequence, you should be using drbd@RESNAME.target (see there) and drbd-wait-promotable@RESNAME.service, implicitly drbdRESNAME.service, and maybe optionally drbd-lvchange@RESNAME.service.

If you think you want to enable this unit, you probably still should disable this unit, as this unit may not do what you think it does, and there likely are better ways to do what you expected this unit to do.

Usually you are better of with

```
systemctl enable drbd-configured.target
for res in $(drbdadm sh-resources); do

    systemctl enable drbd@$(systemd-escape "$res").target
done
```

## SEE ALSO
drbd-reactor(1), drbd-reactor.promoter(5), drbd@.target(7)

## AUTHORS
LINBIT HA Solutions GmbH https://linbit.com


drbd@.service

title: drbd@.service(7)

text:
# drbd@.service(7)

## NAME
drbd@.service - System unit to configure a specific DRBD resource

## SYNOPSIS
drbd@RESNAME.service

## DESCRIPTION
Do not confuse this with the global, unspecific drbd.service.

This service unit is part of drbd@RESNAME.target, and used to configure/reconfigure/unconfigure the DRBD RESNAME on start/reload/stop.

Since we want the network to be online before configuring DRBD, you may need to enable one of these:

systemctl enable systemd-networkd-wait-online.service or systemctl enable NetworkManager-wait-online.service.

## SEE ALSO
drbd@.target(7), drbd-wait-promotable@.service(7), drbd-lvchange@.service(7)

## AUTHORS
LINBIT HA Solutions GmbH https://linbit.com


drbd@.target

title: drbd@.target(7)

text:
# drbd@.target(7)

## NAME
drbd@.target - System target unit indicating a configured (optionally: promotable) DRBD resource

## SYNOPSIS
drbd@.target

## DESCRIPTION
Usually you do not want to "hardcode" an unconditional promotion attempt of DRBD resources, because you usually cannot know a-priory whether this instance of DRBD will have access to good data (yet).

Typical setups are using a cluster manager like pacemaker or the less feature rich but also less complex drbd-reactor to coordinate promotion attempts and service starts.

But in situation where you "know" that you always want this node to promote and use DRBD and the peer(s) are never going to take over, but only used for "DR" purposes, then this target unit may be useful.

It is intended to be used as dependency of any mount or other use of the specific DRBD resource. The implicit dependency on drbd@RESNAME.service will configure DRBD, an optional drbd-lvchange@RESNAME.service can be used to attempt to activate the backend logical volumes first. The optional (but in this scenario necessary) drbd-wait-promotable@RESNAME.service is then used to wait for DRBD to connect to its peers and establish access to good data.

## EXAMPLE
Assuming you have a DRBD resource named webdata, its backing devices being LVM logical volumes, with an xfs on one volume showing up as /dev/drbd0, this should make your boot sequence successfully mount that drbd to /mnt/point (unless DRBD really finds no access to good data in time, or some peer is already primary):

```
systemctl enable drbd-lvchange@webdata.service
systemctl enable drbd-wait-promotable@webdata.service
echo "/dev/drbdX /mnt/point xfs defaults,nofail,x-systemd.requires=drbd@webdata.target 0 0" >> /etc/fstab
```

But you really should let drbd-reactor handle the mount (and services using it) instead.

## SEE ALSO
drbd-reactor(1), drbd-reactor.promoter(5)

## AUTHORS
LINBIT HA Solutions GmbH https://linbit.com


package: drbd-utils-pacemaker

title: ocf_linbit_drbd(7)

text:
# ocf_linbit_drbd(7)

## NAME
ocf_linbit_drbd - Manages a DRBD device as a Master/Slave resource

## SYNOPSIS
drbd [start | stop | monitor | promote | demote | meta-data | validate-all]

## DESCRIPTION
This resource agent manages a DRBD resource as a master/slave resource. DRBD is a shared-nothing replicated storage device.

NOTE: To avoid data-divergence, you should enable either DRBD "quorum" and "on-no-quorum io-error" (recommended), or configure proper fencing policies in both DRBD *and* Pacemaker (fencing resource-and-stonith). This cannot be done from this resource agent alone.

See the DRBD User's Guide for more information. https://docs.linbit.com/

## SUPPORTED PARAMETERS
drbd_resource

The name of the drbd resource from the drbd.conf file. (unique, required, string, no default)

drbdconf

Full path to the drbd.conf file. (optional, string, default "/etc/drbd.conf")

adjust_master_score

Space separated list of four master score adjustments for different scenarios: - only access to 'consistent' data - only remote access to 'uptodate' data - currently Secondary, local access to 'uptodate' data, but remote is unknown - local access to 'uptodate' data, and currently Primary or remote is known Numeric values are expected to be non-decreasing.

The first value is 0 by default to prevent pacemaker from trying to promote while it is unclear whether the data is really the most recent copy. (DRBD knows it is "consistent", but is unsure about "uptodate"ness). Please configure proper fencing methods both in DRBD (fencing resource-and-stonith; appropriate (un)fence-peer handlers) AND in Pacemaker to make this work reliably.

Advanced use: Adjust the other values to better fit into complex dependency score calculations.

Intentionally diskless nodes ("Diskless Clients") with access to good data via some (or all) their peers will use the 3rd or 4th value (minus one) when they are (Secondary, not all peers up-to-date) or (ALL peers are up-to-date, or they are Primary themselves). This may need to change if this should become a frequent use case.

Special considerations:

If a Secondary DRBD is connected to a peer in Primary role, but Pacemaker does not know about any Primary (using crm_resource --locate), we conclude that there likely is a cluster-split-brain, and may try to "help" Pacemaker by removing the master-score. Also see "remove_master_score_if_peer_primary".

(optional, string, default "0 10 1000 10000")

stop_outdates_secondary

Recommended setting: leave at default (disabled). Note that this feature depends on the passed in information in OCF_RESKEY_CRM_meta_notify_master_uname to be correct, which unfortunately is not reliable for pacemaker versions up to at least 1.0.10 / 1.1.4.

If a Secondary is stopped (unconfigured), it may be marked as outdated in the drbd meta data, if we know there is still a Primary running in the cluster. Note that this does not affect fencing policies set in drbd config, but is an additional safety feature of this resource agent only. You can enable this behaviour by setting the parameter to true.

If this feature seems to not do what you expect, make sure you have defined fencing policies in the drbd configuration as well.

(optional, boolean, default false)

ignore_missing_notifications

Some setups do not benefit from notifications. Allow to disable notifications without patching this resource agent. (optional, boolean, default false)

wfc_timeout

Unless set to the empty string or any non-digits, wait (at most) this many seconds for the connection(s) to be established after bringing them up during "start". (optional, integer, default 5)

remove_master_score_if_peer_primary

See also "adjust_master_score" and "fail_promote_early_if_peer_primary". To prevent a potentially failed promotion attempt in case of cluster split-brain (Pacemaker communication loss) while DRBD is still connected to a Primary, you can request to remove any master score while DRBD is connected to a Primary (and that Primary peer looks like it has all disks up-to-date).

This may delay legitimate failovers after Primary crash by up to some TCP timeout (until DRBD realizes that the Primary is gone) plus one monitoring interval.

This parameter is interpreted almost as an "ocf boolean", with the exception of a literal "unexpected", that is:

- (yes|true|1) [actually, according to the OCF spec, also (YES|TRUE|True|ja|ON), but please don't go there]: is "true": remove (or never assign) master scores, if DRBD appears to see a (healthy) Primary

- "unexpected": assign master scores as described under "adjust_master_score", while removing it if DRBD appears to see a (healthy) Primary that Pacemaker does not know about (as determined by crm_resource --locate).

- everything else is "false": ignore the peer role while assigning master scores.

(optional, string, default "false")

fail_promote_early_if_peer_primary

See also "adjust_master_score" and "remove_master_score_if_peer_primary". To avoid a useless retry loop during promotion attempts in case of cluster split-brain (Pacemaker communication loss) while DRBD is still connected to a Primary, you can chose to give up after the first try if this situation is detected.

If a Primary "vanishes", TCP may not immediately detect this, and an idle DRBD may take some time until it does in-DRBD-protocol "pings". Pacemaker may well detect Primary loss earlier than DRBD, and try to promote while DRBD thinks it can still see a Primary. Which means, in general, trying to promote at least once is necessary, as that implies an in-DRBD-protocol "peer alive" check.

But if that does not succeed, re-trying until we hit the operation timeout may not be desired, so you can disable it.

(optional, boolean, default false)

unfence_if_all_uptodate

If all volumes of this resource report to be UpToDate, call an unfence script hook, just in case some stale fencing constraint or similar is still around. - With DRBD utils version <= 8.9.4, this is hardcoded to /usr/lib/drbd/crm-unfence-peer.sh -r $DRBD_RESOURCE

- With DRBD utils version >= 8.9.5, this is dispatched to $DRBDADM unfence-peer $DRBD_RESOURCE

In any case, the hook itself is responsible to fetch $OCF_RESKEY_unfence_extra_args from its environment.

(optional, boolean, default false)

unfence_extra_args

This may be used to pass extra hints to the unfence hook. See description of unfence_if_all_uptodate. (optional, boolean, default --quiet --flock-required --flock-timeout 0 --unfence-only-if-owner-match)

require_drbd_module_version_ge

Use this you want to force failure of this resource agent if the detected DRBD kernel (module) driver version is lower than a required minimum. Example: use require_drbd_module_version_ge=9.0.16 to fail unless DRBD module version >= 9.0.16 is available (effectively requires DRBD 9).

The intention of this is to give a more useful failure message after accidentally downgrading the DRBD version by installing/upgrading a new kernel.

Note: "ge", "greater-or-equal", inclusive. Required format: x.y.z

Set empty to skip this check.

(optional, string, default "8.0.0")

require_drbd_module_version_lt

Use this you want to force failure of this resource agent if the detected DRBD kernel (module) driver version is higher than a required maximum. Example: use require_drbd_module_version_lt=9.0.0 to fail unless DRBD module version < 9.0 is available (effectively requires DRBD 8.4).

Note: "lt", "less-than", exclusive. Required format: x.y.z

Set empty to skip this check.

(optional, string, default "10.0.0")

connect_only_after_promote

This may be useful for "stacked" setups without proper fencing on the lower layer (which we obviously do not recommend), to avoid some of the ugly side effects that may arise after resolving a split-brain on the lower layer. Keep this DRBD instance disconnected until it is promoted. After promotion we issue an additional "adjust", which is supposed to initiate the connection attempts.

This causes a new data generation identifier ("current uuid") to be generated after the failover of a "healthy" DRBD.

(optional, boolean, default false)

## SUPPORTED ACTIONS
This resource agent supports the following actions (operations):

start

Starts the resource. Suggested minimum timeout: 240.

reload

Suggested minimum timeout: 30.

promote

Promotes the resource to the Master role. Suggested minimum timeout: 90.

demote

Demotes the resource to the Slave role. Suggested minimum timeout: 90.

notify

Suggested minimum timeout: 90.

stop

Stops the resource. Suggested minimum timeout: 100.

monitor (Slave role)

Performs a detailed status check. Suggested minimum timeout: 20. Suggested interval: 20.

monitor (Master role)

Performs a detailed status check. Suggested minimum timeout: 20. Suggested interval: 10.

meta-data

Retrieves resource agent metadata (internal use only). Suggested minimum timeout: 5.

validate-all

Performs a validation of the resource configuration.

## EXAMPLE CRM SHELL
The following is an example configuration for a drbd resource using the crm(8) shell:

```
primitive p_drbd ocf:linbit:drbd \

  params \

    drbd_resource=string \

  op monitor timeout="20" interval="20" role="Slave" \

  op monitor timeout="20" interval="10" role="Master"
```

```
ms ms_drbd p_drbd \

  meta notify="true" interleave="true"
```

## EXAMPLE PCS
The following is an example configuration for a drbd resource using pcs(8)

```
pcs resource create p_drbd ocf:linbit:drbd \

  drbd_resource=string \

  op monitor timeout="20" interval="20" role="Slave" \

  op monitor timeout="20" interval="10" role="Master" --master
```

## SEE ALSO
https://docs.linbit.com/, https://clusterlabs.org/, https://www.linbit.com/drbd-community/

## AUTHORS
LINBIT HA Solutions GmbH


title: ocf_linbit_drbd-attr(7)

text:
# ocf_linbit_drbd-attr(7)

## NAME
ocf_linbit_drbd-attr - import DRBD state change events as transient node attributes

## SYNOPSIS
drbd-attr [start | stop | monitor | meta-data | validate-all]

## DESCRIPTION
This listens for DRBD state change events, and sets or deletes transient node attributes based on the "promotion_score" and "may_promote" values as presented by the DRBD events2 interface.

Optionally using a dampening delay, see attrd_updater for details.

To be used as a clone on all DRBD nodes. The idea is to start DRBD outside of pacemaker, use DRBD auto-promote, and add location constraints for the Filesystem or other resource agents which are using DRBD.

## SUPPORTED PARAMETERS
dampening_delay

To be used as dampening delay in attrd_updater. (optional, integer, default 5)

attr_name_prefix

The attributes will be named "*prefix*-drbd_resource_name". You can chose that prefix here. (optional, string, default "drbd-promotion-score")

record_event_details

It may be convenient to know which event lead to the current score. This setting toggles the recording of the event. The attributes will be named "*prefix*:event-details-drbd_resource_name". (optional, boolean, default false)

## SUPPORTED ACTIONS
This resource agent supports the following actions (operations):

start

Starts the resource. Suggested minimum timeout: 20s.

stop

Stops the resource. Suggested minimum timeout: 20s.

monitor

Performs a detailed status check. Suggested minimum timeout: 20s. Suggested interval: 60s.

validate-all

Performs a validation of the resource configuration. Suggested minimum timeout: 20s.

meta-data

Retrieves resource agent metadata (internal use only). Suggested minimum timeout: 5s.

## EXAMPLE CRM SHELL
The following is an example configuration for a drbd-attr resource using the crm(8) shell:

```
primitive p_drbd-attr ocf:linbit:drbd-attr \

  op monitor timeout="20s" interval="60s" depth="0"
```

## EXAMPLE PCS
The following is an example configuration for a drbd-attr resource using pcs(8)

```
pcs resource create p_drbd-attr ocf:linbit:drbd-attr \

  op monitor timeout="20s" interval="60s" depth="0"
```

## SEE ALSO
https://docs.linbit.com/, https://clusterlabs.org/, https://www.linbit.com/drbd-community/

## AUTHORS
LINBIT HA Solutions GmbH