deb-postinst

title: deb-postinst(5)

summary: package post\-installation maintainer script

text:
# deb-postinst(5)

## NAME
deb-postinst - package post-installation maintainer script

## SYNOPSIS
DEBIAN/postinst

## DESCRIPTION
A package can perform several post-installation actions via maintainer scripts, by including an executable postinst file in its control archive (i.e. DEBIAN/postinst during package creation).

The script can be called in the following ways:

postinst configure old-version

After the package was installed.

postinst triggered "trigger-name..."

After the package was triggered. The list of space-separated trigger-names is passed as the second argument.

old-postinst abort-upgrade new-version

If prerm fails during upgrade or fails on failed-upgrade.

old-postinst abort-remove

If prerm fails during remove.

postinst abort-deconfigure in-favour new-package new-version

[ removing old-package old-version ]

If prerm fails during deconfigure in-favour of a package.

postinst abort-remove in-favour new-package new-version

If prerm fails during remove in-favour for replacement due to conflict.

## SEE ALSO
dpkg(1).


deb-postrm

package: dpkg

title: deb-postrm(5)

summary: package post\-removal maintainer script

text:
# deb-postrm(5)

## NAME
deb-postrm - package post-removal maintainer script

## SYNOPSIS
DEBIAN/postrm

## DESCRIPTION
A package can perform several post-removal actions via maintainer scripts, by including an executable postrm file in its control archive (i.e. DEBIAN/postrm during package creation).

The script can be called in the following ways:

postrm remove

After the package was removed.

postrm purge

After the package was purged.

old-postrm upgrade new-version

After the package was upgraded.

new-postrm failed-upgrade old-version new-version

If the above upgrade call fails. The new-version is passed only since dpkg 1.18.5.

postrm disappear overwriter-package overwriter-version

After all of the packages files have been replaced.

new-postrm abort-install

If preinst fails during install.

new-postrm abort-install old-version new-version

If preinst fails during install for an upgrade of a removed package. The new-version is passed only since dpkg 1.18.5.

new-postrm abort-upgrade old-version new-version

If preinst fails during upgrade. The new-version is passed only since dpkg 1.18.5.

## SEE ALSO
dpkg(1).


deb-preinst

title: deb-preinst(5)

summary: package pre\-installation maintainer script

text:
# deb-preinst(5)

## NAME
deb-preinst - package pre-installation maintainer script

## SYNOPSIS
DEBIAN/preinst

## DESCRIPTION
A package can perform several pre-installation actions via maintainer scripts, by including an executable preinst file in its control archive (i.e. DEBIAN/preinst during package creation).

The script can be called in the following ways:

new-preinst install

Before the package is installed.

new-preinst install old-version new-version

Before a removed package is upgraded. The new-version is passed only since dpkg 1.18.5.

new-preinst upgrade old-version new-version

Before the package is upgraded. The new-version is passed only since dpkg 1.18.5.

old-preinst abort-upgrade new-version

If postrm fails during upgrade or fails on failed upgrade.

## SEE ALSO
dpkg(1).


deb-prerm

title: deb-prerm(5)

summary: package pre\-removal maintainer script

text:
# deb-prerm(5)

## NAME
deb-prerm - package pre-removal maintainer script

## SYNOPSIS
DEBIAN/prerm

## DESCRIPTION
A package can perform several pre-removal actions via maintainer scripts, by including an executable prerm file in its control archive (i.e. DEBIAN/prerm during package creation).

The script can be called in the following ways:

prerm remove

Before the package is removed.

old-prerm upgrade new-version

Before an upgrade.

new-prerm failed-upgrade old-version new-version

If the above upgrade fails. The new-version is passed only since dpkg 1.18.5.

prerm deconfigure in-favour new-package new-version

[ removing old-package old-version ]

Before package is deconfigured while dependency is replaced due to conflict.

prerm remove in-favour new-package new-version

Before the package is replaced due to conflict.

## SEE ALSO
dpkg(1).


deb-shlibs

title: deb-shlibs(5)

summary: Debian shared library information file

text:
# deb-shlibs(5)

## NAME
deb-shlibs - Debian shared library information file

## SYNOPSIS
debian/shlibs, debian/binary-name.shlibs, DEBIAN/shlibs

## DESCRIPTION
shlibs files map shared library names and versions (SONAMEs) to dependencies suitable for a package control file. There is one entry per line. Blank lines are not allowed. Lines beginning with a # character are considered commentary, and are ignored. All other lines must have the format:

[type:] library version dependencies

The library and version fields are whitespace-delimited, but the dependencies field extends to the end of the line. The type field is optional and normally not needed.

The dependencies field has the same syntax as the Depends field in a binary control file, see deb-control(5).

## SONAME FORMATS
The SONAME formats supported are:

name.so.version

and

name-version.so

where name is usually prefixed by lib.

## EXAMPLES
The shlibs file for a typical library package, named libcrunch1, that provides one library whose SONAME is libcrunch.so.1, might read

```
 libcrunch 1 libcrunch1 (>= 1.2-1)
```

The dependencies must mention the most recent version of the package that added new symbols to the library: in the above example, new symbols were added to version 1.2 of libcrunch. This is not the only reason the dependencies might need to be tightened.

## SEE ALSO
deb-control(5), dpkg-shlibdeps(1), deb-symbols(5).


deb-split

title: deb-split(5)

summary: Debian multi\-part binary package format

text:
# deb-split(5)

## NAME
deb-split - Debian multi-part binary package format

## SYNOPSIS
filename.deb

## DESCRIPTION
The multi-part .deb format is used to split big packages into smaller pieces to ease transport in small media.

## FORMAT
The file is an ar archive with a magic value of !<arch>. The file names might contain a trailing slash (since dpkg 1.15.6).

The first member is named debian-split and contains a series of lines, separated by newlines. Currently eight lines are present:

- The format version number, 2.1 at the time this manual page was written.

- The package name.

- The package version.

- The md5sum of the package.

- The total size of the package.

- The maximum part size.

- The current part number, followed by a slash and the total amount of parts (as in ‘1/10’).

- The package architecture (since dpkg 1.16.1).

Programs which read multi-part archives should be prepared for the minor format version number to be increased and additional lines to be present, and should ignore these if this is the case.

If the major format version number has changed, an incompatible change has been made and the program should stop. If it has not, then the program should be able to safely continue, unless it encounters an unexpected member in the archive (except at the end), as described below.

The second, last required member is named data.N, where N denotes the part number. It contains the raw part data.

These members must occur in this exact order. Current implementations should ignore any additional members after data.N. Further members may be defined in the future, and (if possible) will be placed after these two.

## SEE ALSO
deb(5), dpkg-split(1).


deb-src-control

title: deb-src-control(5)

text:
# deb-src-control(5)

## NAME
deb-src-control - Debian source packages' master control file format

## SYNOPSIS
debian/control

## DESCRIPTION
Each Debian source package contains the master «debian/control» file, and its deb822(5) format is a superset of the control file shipped in Debian binary packages, see deb-control(5).

This file contains at least 2 stanzas, separated by a blank line. The first stanza lists all information about the source package in general, while each following stanza describes exactly one binary package. Each stanza consists of at least one field. A field starts with a fieldname, such as Package or Section (case insensitive), followed by a colon, the body of the field (case sensitive unless stated otherwise) and a newline. Multi-line fields are also allowed, but each supplementary line, without a fieldname, should start with at least one space. The content of the multi-line fields is generally joined to a single line by the tools (except in the case of the Description field, see below). To insert empty lines into a multi-line field, insert a dot after the space. Lines starting with a ‘#’ are treated as comments.

## SOURCE FIELDS
Source: source-package-name (required)

The value of this field is the name of the source package, and should match the name of the source package in the debian/changelog file. A package name must consist only of lowercase letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). Package names must be at least two characters long and must start with a lowercase alphanumeric character (a-z0-9).

Maintainer: fullname-email (recommended)

Should be in the format «Joe Bloggs <jbloggs@foo.com>», and references the person who currently maintains the package, as opposed to the author of the software or the original packager.

Uploaders: fullname-email

Lists all the names and email addresses of co-maintainers of the package, in the same format as the Maintainer field. Multiple co-maintainers should be separated by a comma.

Standards-Version: version-string

This documents the most recent version of the distribution policy standards this package complies with.

Description short-description

long-description

The format for the source package description is a short brief summary on the first line (after the Description field). The following lines should be used as a longer, more detailed description. Each line of the long description must be preceded by a space, and blank lines in the long description must contain a single ‘.’ following the preceding space.

Homepage: url

The upstream project home page URL.

Bugs: url

The url of the bug tracking system for this package. The current used format is bts-type://bts-address, like debbugs://bugs.debian.org. This field is usually not needed.

Rules-Requires-Root: no|binary-targets|impl-keywords

This field is used to indicate whether the debian/rules file requires (fake)root privileges to run some of its targets, and if so when.

no

The binary targets will not require (fake)root at all.

binary-targets

The binary targets must always be run under (fake)root. This value is the default when the field is omitted; adding the field with an explicit binary-targets while not strictly needed, marks it as having been analyzed for this requirement.

impl-keywords

This is a space-separated list of keywords which define when (fake)root is required. Keywords consist of namespace/cases. The namespace part cannot contain "/" or whitespace. The cases part cannot contain whitespace. Furthermore, both parts must consist entirely of printable ASCII characters.

Each tool/package will define a namespace named after itself and provide a number of cases where (fake)root is required. (See "Implementation provided keywords" in rootless-builds.txt).

When the field is set to one of the impl-keywords, the builder will expose an interface that is used to run a command under (fake)root. (See "Gain Root API" in rootless-builds.txt.)

Testsuite: name-list

Testsuite-Triggers: package-list

These fields are described in the dsc(5) manual page, as they are generated from information inferred from debian/tests/control or copied literally to the source control file.

Vcs-Arch: url

Vcs-Bzr: url

Vcs-Cvs: url

Vcs-Darcs: url

Vcs-Git: url

Vcs-Hg: url

Vcs-Mtn: url

Vcs-Svn: url

The url of the Version Control System repository used to maintain this package. Currently supported are Arch, Bzr (Bazaar), Cvs, Darcs, Git, Hg (Mercurial), Mtn (Monotone) and Svn (Subversion). Usually this field points to the latest version of the package, such as the main branch or the trunk.

Vcs-Browser: url

The url of a webinterface to browse the Version Control System repository.

Origin: name

The name of the distribution this package is originating from. This field is usually not needed.

Section: section

This is a general field that gives the package a category based on the software that it installs. Some common sections are utils, net, mail, text, x11, etc.

Priority: priority

Sets the importance of this package in relation to the system as a whole. Common priorities are required, standard, optional, extra, etc. The Section and Priority fields usually have a defined set of accepted values based on the specific distribution policy.

Build-Depends: package-list

A list of packages that need to be installed and configured to be able to build from source package. These dependencies need to be satisfied when building binary architecture dependent or independent packages and source packages. Including a dependency in this field does not have the exact same effect as including it in both Build-Depends-Arch and Build-Depends-Indep, because the dependency also needs to be satisfied when building the source package.

Build-Depends-Arch: package-list

Same as Build-Depends, but they are only needed when building the architecture dependent packages. The Build-Depends are also installed in this case. This field is supported since dpkg 1.16.4; in order to build with older dpkg versions, Build-Depends should be used instead.

Build-Depends-Indep: package-list

Same as Build-Depends, but they are only needed when building the architecture independent packages. The Build-Depends are also installed in this case.

Build-Conflicts: package-list

A list of packages that should not be installed when the package is built, for example because they interfere with the build system used. Including a dependency in this list has the same effect as including it in both Build-Conflicts-Arch and Build-Conflicts-Indep, with the additional effect of being used for source-only builds.

Build-Conflicts-Arch: package-list

Same as Build-Conflicts, but only when building the architecture dependent packages. This field is supported since dpkg 1.16.4; in order to build with older dpkg versions, Build-Conflicts should be used instead.

Build-Conflicts-Indep: package-list

Same as Build-Conflicts, but only when building the architecture independent packages.

The syntax of the Build-Depends, Build-Depends-Arch and Build-Depends-Indep fields is a list of groups of alternative packages. Each group is a list of packages separated by vertical bar (or “pipe”) symbols, ‘|’. The groups are separated by commas ‘,’, and can end with a trailing comma that will be eliminated when generating the fields for deb-control(5) (since dpkg 1.10.14). Commas are to be read as “AND”, and pipes as “OR”, with pipes binding more tightly. Each package name is optionally followed by an architecture qualifier appended after a colon ‘:’, optionally followed by a version number specification in parentheses ‘(’ and ‘)’, an architecture specification in square brackets ‘[’ and ‘]’, and a restriction formula consisting of one or more lists of profile names in angle brackets ‘<’ and ‘>’.

The syntax of the Build-Conflicts, Build-Conflicts-Arch and Build-Conflicts-Indep fields is a list of comma-separated package names, where the comma is read as an “AND”, and where the list can end with a trailing comma that will be eliminated when generating the fields for deb-control(5) (since dpkg 1.10.14). Specifying alternative packages using a “pipe” is not supported. Each package name is optionally followed by a version number specification in parentheses, an architecture specification in square brackets, and a restriction formula consisting of one or more lists of profile names in angle brackets.

An architecture qualifier name can be a real Debian architecture name (since dpkg 1.16.5), any (since dpkg 1.16.2) or native (since dpkg 1.16.5). If omitted, the default for Build-Depends fields is the current host architecture, the default for Build-Conflicts fields is any. A real Debian architecture name will match exactly that architecture for that package name, any will match any architecture for that package name if the package is marked with Multi-Arch: allowed, and native will match the current build architecture if the package is not marked with Multi-Arch: foreign.

A version number may start with a ‘>>’, in which case any later version will match, and may specify or omit the Debian packaging revision (separated by a hyphen). Accepted version relationships are ‘>>’ for greater than, ‘<<’ for less than, ‘>=’ for greater than or equal to, ‘<=’ for less than or equal to, and ‘=’ for equal to.

An architecture specification consists of one or more architecture names, separated by whitespace. Exclamation marks may be prepended to each of the names, meaning “NOT”.

A restriction formula consists of one or more restriction lists, separated by whitespace. Each restriction list is enclosed in angle brackets. Items in the restriction list are build profile names, separated by whitespace and can be prefixed with an exclamation mark, meaning “NOT”. A restriction formula represents a disjunctive normal form expression.

Note that dependencies on packages in the build-essential set can be omitted and that declaring build conflicts against them is impossible. A list of these packages is in the build-essential package.

## BINARY FIELDS
Note that the Priority, Section and Homepage fields can also be in a binary stanza to override the global value from the source package.

Package: binary-package-name (required)

This field is used to name the binary package name. The same restrictions as to a source package name apply.

Package-Type: deb|udeb|type

This field defines the type of the package. udeb is for size-constrained packages used by the debian installer. deb is the default value, it is assumed if the field is absent. More types might be added in the future.

Architecture: arch|all|any (required)

The architecture specifies on which type of hardware this package runs. For packages that run on all architectures, use the any value. For packages that are architecture independent, such as shell and Perl scripts or documentation, use the all value. To restrict the packages to a certain set of architectures, specify the architecture names, separated by a space. It's also possible to put architecture wildcards in that list (see dpkg-architecture(1) for more information about them).

Build-Profiles: restriction-formula

This field specifies the conditions for which this binary package does or does not build. To express that condition, the same restriction formula syntax from the Build-Depends field is used (including the angle brackets). If a binary package stanza does not contain this field, then it implicitly means that it builds with all build profiles (including none at all).

In other words, if a binary package stanza is annotated with a non-empty Build-Profiles field, then this binary package is generated if and only if the condition expressed by the conjunctive normal form expression evaluates to true.

Protected: yes|no

Essential: yes|no

Build-Essential: yes|no

Multi-Arch: same|foreign|allowed|no

Tag: tag-list

Description: short-description (recommended)

These fields are described in the deb-control(5) manual page, as they are copied literally to the control file of the binary package.

Depends: package-list

Pre-Depends: package-list

Recommends: package-list

Suggests: package-list

Breaks: package-list

Enhances: package-list

Replaces: package-list

Conflicts: package-list

Provides: package-list

Built-Using: package-list

Static-Built-Using: package-list

These fields declare relationships between packages. They are discussed in the deb-control(5) manpage. When these fields are found in debian/control they can also end with a trailing comma (since dpkg 1.10.14), have architecture specifications and restriction formulas which will all get reduced when generating the fields for deb-control(5).

Subarchitecture: value

Kernel-Version: value

Installer-Menu-Item: value

These fields are used by the debian-installer in udebs and are usually not needed. For more details about them, see <https://salsa.debian.org/installer-team/debian-installer/-/raw/master/doc/devel/modules.txt>.

## USER-DEFINED FIELDS
It is allowed to add additional user-defined fields to the control file. The tools will ignore these fields. If you want the fields to be copied over to the output files, such as the binary packages, you need to use a custom naming scheme: the fields should start with an X, followed by zero or more of the letters SBC and a hyphen.

S

The field will appear in the source package control file, see dsc(5).

B

The field will appear in the control file in the binary package, see deb-control(5).

C

The field will appear in the upload control (.changes) file, see deb-changes(5).

Note that the X[SBC]- prefixes are stripped when the fields are copied over to the output files. A field XC-Approved-By will appear as Approved-By in the changes file and will not appear in the binary or source package control files.

Take into account that these user-defined fields will be using the global namespace, which might at some point in the future collide with officially recognized fields. To avoid such potential situation you can prefix those fields with Private-, such as XB-Private-New-Field.

## EXAMPLE

```
 # Comment
 Source: dpkg
 Section: admin
 Priority: required
 Maintainer: Dpkg Developers <debian-dpkg@lists.debian.org>
 # this field is copied to the binary and source packages
 XBS-Upstream-Release-Status: stable
 Homepage: https://wiki.debian.org/Teams/Dpkg
 Vcs-Browser: https://git.dpkg.org/cgit/dpkg/dpkg.git
 Vcs-Git: https://git.dpkg.org/git/dpkg/dpkg.git
 Standards-Version: 3.7.3
 Build-Depends: pkg-config, debhelper (>= 4.1.81),
  libselinux1-dev (>= 1.28-4) [!linux-any]
 Package: dpkg-dev
 Section: utils
 Priority: optional
 Architecture: all
 # this is a custom field in the binary package
 XB-Mentoring-Contact: Raphael Hertzog <hertzog@debian.org>
 Depends: dpkg (>= 1.14.6), perl5, perl-modules, cpio (>= 2.4.2-2),
  bzip2, lzma, patch (>= 2.2-1), make, binutils, libtimedate-perl
 Recommends: gcc | c-compiler, build-essential
 Suggests: gnupg, debian-keyring
 Conflicts: dpkg-cross (<< 2.0.0), devscripts (<< 2.10.26)
 Replaces: manpages-pl (<= 20051117-1)
 Description: Debian package development tools
  This package provides the development tools (including dpkg-source)
  required to unpack, build and upload Debian source packages.
  .
  Most Debian source packages will require additional tools to build;
  for example, most packages need make and the C compiler gcc.
```

## SEE ALSO
/usr/share/doc/dpkg/spec/rootless-builds.txt, deb822(5), deb-control(5), deb-version(7), dpkg-source(1)


deb-src-files

title: deb-src-files(5)

summary: Debian distribute files format

text:
# deb-src-files(5)

## NAME
deb-src-files - Debian distribute files format

## SYNOPSIS
debian/files

## DESCRIPTION
This file contains the list of artifacts that are to be distributed via the .changes control file.

The debian/files file has a simple whitespace-delimited format.

filename section priority [ keyword=value... ]

filename is the name of the artifact to distribute.

section and priority correspond to the respective control fields available in the .deb. The allowed values are specific to each distribution archive.

keyword=value... corresponds to an optional whitespace-delimited list of attributes for this entry. The only currently supported keyword is automatic with value yes, to mark automatically generated files.

## NOTES
This file is not intended to be modified directly, please use one of dpkg-gencontrol or dpkg-distaddfile to add entries to it.

## SEE ALSO
dpkg-genchanges(1), dpkg-distaddfile(1).


deb-src-rules

title: deb-src-rules(5)

summary: Debian source package rules file

text:
# deb-src-rules(5)

## NAME
deb-src-rules - Debian source package rules file

## SYNOPSIS
debian/rules

## DESCRIPTION
This file contains the instructions necessary to build the binary packages from the source package.

The debian/rules file is an executable Makefile, with a shebang that is usually set to "#!/usr/bin/make -f".

It must support the following make targets:

clean

Clean up the source tree, by undoing any change done by any of the build and binary targets. This target will be called with root privileges.

build-indep

Build architecture independent files required to build any architecture independent binary package. If there are no architecture independent binary packages to generate, the target must still exist but do nothing. This target must not require root privileges.

build-arch

Build architecture dependent files required to build any architecture dependent binary package. If there are no architecture dependent binary packages to generate, the target must still exist but do nothing. This target must not require root privileges.

build

Build architecture independent and dependent files, either by depending (at least transitively) on build-indep and/or build-arch or by inlining what those targets would do. This target must not require root privileges.

binary-indep

Build architecture independent binary packages. This target must depend (at least transitively) on either build-indep or build. This target will be called with root privileges.

binary-arch

Build architecture dependent binary packages. This target must depend (at least transitively) on either build-arch or build. This target will be called with root privileges.

binary

Build architecture independent and dependent binary packages, either by depending (at least transitively) on binary-indep and/or binary-arch or by inlining what those targets would do. This target will be called with root privileges.

## SEE ALSO
dpkg-architecture(1), dpkg-vendor(1), dpkg-buildflags(1), dpkg-parsechangelog(1), dpkg-shlibdeps(1), dpkg-gencontrol(1), dpkg-deb(1), dpkg-distaddfile(1).


deb-src-symbols

title: deb-src-symbols(5)

text:
# deb-src-symbols(5)

## NAME
deb-src-symbols - Debian's extended shared library template file

## SYNOPSIS
debian/package.symbols.arch, debian/symbols.arch, debian/package.symbols, debian/symbols

## DESCRIPTION
The symbol file templates are shipped in Debian source packages, and its format is a superset of the symbols files shipped in binary packages, see deb-symbols(5).

### Comments
Comments are supported in template symbol files. Any line with ‘#’ as the first character is a comment except if it starts with ‘#include’ (see section Using includes). Lines starting with ‘#MISSING:’ are special comments documenting symbols that have disappeared.

### Using #PACKAGE# substitution
In some rare cases, the name of the library varies between architectures. To avoid hardcoding the name of the package in the symbols file, you can use the marker #PACKAGE#. It will be replaced by the real package name during installation of the symbols files. Contrary to the #MINVER# marker, #PACKAGE# will never appear in a symbols file inside a binary package.

### Using symbol tags
Symbol tagging is useful for marking symbols that are special in some way. Any symbol can have an arbitrary number of tags associated with it. While all tags are parsed and stored, only some of them are understood by dpkg-gensymbols and trigger special handling of the symbols. See subsection Standard symbol tags for reference of these tags.

Tag specification comes right before the symbol name (no whitespace is allowed in between). It always starts with an opening bracket (, ends with a closing bracket ) and must contain at least one tag. Multiple tags are separated by the | character. Each tag can optionally have a value which is separated form the tag name by the = character. Tag names and values can be arbitrary strings except they cannot contain any of the special ) | = characters. Symbol names following a tag specification can optionally be quoted with either ' or " characters to allow whitespaces in them. However, if there are no tags specified for the symbol, quotes are treated as part of the symbol name which continues up until the first space.

```
  (tag1=i am marked|tag name with space)"tagged quoted symbol"@Base 1.0
  (optional)tagged_unquoted_symbol@Base 1.0 1
  untagged_symbol@Base 1.0
```

The first symbol in the example is named tagged quoted symbol and has two tags: tag1 with value i am marked and tag name with space that has no value. The second symbol named tagged_unquoted_symbol is only tagged with the tag named optional. The last symbol is an example of the normal untagged symbol.

Since symbol tags are an extension of the deb-symbols(5) format, they can only be part of the symbols files used in source packages (those files should then be seen as templates used to build the symbols files that are embedded in binary packages). When dpkg-gensymbols is called without the -t option, it will output symbols files compatible to the deb-symbols(5) format: it fully processes symbols according to the requirements of their standard tags and strips all tags from the output. On the contrary, in template mode (-t) all symbols and their tags (both standard and unknown ones) are kept in the output and are written in their original form as they were loaded.

### Standard symbol tags
optional

A symbol marked as optional can disappear from the library at any time and that will never cause dpkg-gensymbols to fail. However, disappeared optional symbols will continuously appear as MISSING in the diff in each new package revision. This behaviour serves as a reminder for the maintainer that such a symbol needs to be removed from the symbol file or readded to the library. When the optional symbol, which was previously declared as MISSING, suddenly reappears in the next revision, it will be upgraded back to the “existing” status with its minimum version unchanged. This tag is useful for symbols which are private where their disappearance do not cause ABI breakage. For example, most of C++ template instantiations fall into this category. Like any other tag, this one may also have an arbitrary value: it could be used to indicate why the symbol is considered optional.

arch=architecture-list

arch-bits=architecture-bits

arch-endian=architecture-endianness

These tags allow one to restrict the set of architectures where the symbol is supposed to exist. The arch-bits and arch-endian tags are supported since dpkg 1.18.0. When the symbols list is updated with the symbols discovered in the library, all arch-specific symbols which do not concern the current host architecture are treated as if they did not exist. If an arch-specific symbol matching the current host architecture does not exist in the library, normal procedures for missing symbols apply and it may cause dpkg-gensymbols to fail. On the other hand, if the arch-specific symbol is found when it was not supposed to exist (because the current host architecture is not listed in the tag or does not match the endianness and bits), it is made arch neutral (i.e. the arch, arch-bits and arch-endian tags are dropped and the symbol will appear in the diff due to this change), but it is not considered as new. When operating in the default non-template mode, among arch-specific symbols only those that match the current host architecture are written to the symbols file. On the contrary, all arch-specific symbols (including those from foreign arches) are always written to the symbol file when operating in template mode.

The format of architecture-list is the same as the one used in the Build-Depends field of debian/control (except the enclosing square brackets []). For example, the first symbol from the list below will be considered only on alpha, any-amd64 and ia64 architectures, the second only on linux architectures, while the third one anywhere except on armel.

```
  (arch=alpha any-amd64 ia64)64bit_specific_symbol@Base 1.0
  (arch=linux-any)linux_specific_symbol@Base 1.0
  (arch=!armel)symbol_armel_does_not_have@Base 1.0

```

The architecture-bits is either 32 or 64.

```
  (arch-bits=32)32bit_specific_symbol@Base 1.0
  (arch-bits=64)64bit_specific_symbol@Base 1.0

```

The architecture-endianness is either little or big.

```
  (arch-endian=little)little_endian_specific_symbol@Base 1.0
  (arch-endian=big)big_endian_specific_symbol@Base 1.0

```

Multiple restrictions can be chained.

```
  (arch-bits=32|arch-endian=little)32bit_le_symbol@Base 1.0

```

allow-internal

dpkg-gensymbols has a list of internal symbols that should not appear in symbols files as they are usually only side-effects of implementation details of the toolchain (since dpkg 1.20.1). If for some reason, you really want one of those symbols to be included in the symbols file, you should tag the symbol with allow-internal. It can be necessary for some low level toolchain libraries like “libgcc”.

ignore-blacklist

A deprecated alias for allow-internal (since dpkg 1.20.1, supported since dpkg 1.15.3).

c++

Denotes c++ symbol pattern. See Using symbol patterns subsection below.

symver

Denotes symver (symbol version) symbol pattern. See Using symbol patterns subsection below.

regex

Denotes regex symbol pattern. See Using symbol patterns subsection below.

### Using symbol patterns
Unlike a standard symbol specification, a pattern may cover multiple real symbols from the library. dpkg-gensymbols will attempt to match each pattern against each real symbol that does not have a specific symbol counterpart defined in the symbol file. Whenever the first matching pattern is found, all its tags and properties will be used as a basis specification of the symbol. If none of the patterns matches, the symbol will be considered as new.

A pattern is considered lost if it does not match any symbol in the library. By default this will trigger a dpkg-gensymbols failure under -c1 or higher level. However, if the failure is undesired, the pattern may be marked with the optional tag. Then if the pattern does not match anything, it will only appear in the diff as MISSING. Moreover, like any symbol, the pattern may be limited to the specific architectures with the arch tag. Please refer to Standard symbol tags subsection above for more information.

Patterns are an extension of the deb-symbols(5) format hence they are only valid in symbol file templates. Pattern specification syntax is not any different from the one of a specific symbol. However, symbol name part of the specification serves as an expression to be matched against name@version of the real symbol. In order to distinguish among different pattern types, a pattern will typically be tagged with a special tag.

At the moment, dpkg-gensymbols supports three basic pattern types:

c++

This pattern is denoted by the c++ tag. It matches only C++ symbols by their demangled symbol name (as emitted by c++filt(1) utility). This pattern is very handy for matching symbols which mangled names might vary across different architectures while their demangled names remain the same. One group of such symbols is non-virtual thunks which have architecture specific offsets embedded in their mangled names. A common instance of this case is a virtual destructor which under diamond inheritance needs a non-virtual thunk symbol. For example, even if _ZThn8_N3NSB6ClassDD1Ev@Base on 32bit architectures will probably be _ZThn16_N3NSB6ClassDD1Ev@Base on 64bit ones, it can be matched with a single c++ pattern:

```
 libdummy.so.1 libdummy1 #MINVER#
  [...]
  (c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
  [...]

```

The demangled name above can be obtained by executing the following command:

```
  $ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt

```

Please note that while mangled name is unique in the library by definition, this is not necessarily true for demangled names. A couple of distinct real symbols may have the same demangled name. For example, that's the case with non-virtual thunk symbols in complex inheritance configurations or with most constructors and destructors (since g++ typically generates two real symbols for them). However, as these collisions happen on the ABI level, they should not degrade quality of the symbol file.

symver

This pattern is denoted by the symver tag. Well maintained libraries have versioned symbols where each version corresponds to the upstream version where the symbol got added. If that's the case, you can use a symver pattern to match any symbol associated to the specific version. For example:

```
 libc.so.6 libc6 #MINVER#
  (symver)GLIBC_2.0 2.0
  [...]
  (symver)GLIBC_2.7 2.7
  access@GLIBC_2.0 2.2

```

All symbols associated with versions GLIBC_2.0 and GLIBC_2.7 will lead to minimal version of 2.0 and 2.7 respectively with the exception of the symbol access@GLIBC_2.0. The latter will lead to a minimal dependency on libc6 version 2.2 despite being in the scope of the "(symver)GLIBC_2.0" pattern because specific symbols take precedence over patterns.

Please note that while old style wildcard patterns (denoted by "*@version" in the symbol name field) are still supported, they have been deprecated by new style syntax "(symver|optional)version". For example, "*@GLIBC_2.0 2.0" should be written as "(symver|optional)GLIBC_2.0 2.0" if the same behaviour is needed.

regex

Regular expression patterns are denoted by the regex tag. They match by the perl regular expression specified in the symbol name field. A regular expression is matched as it is, therefore do not forget to start it with the ^ character or it may match any part of the real symbol name@version string. For example:

```
 libdummy.so.1 libdummy1 #MINVER#
  (regex)"^mystack_.*@Base$" 1.0
  (regex|optional)"private" 1.0

```

Symbols like "mystack_new@Base", "mystack_push@Base", "mystack_pop@Base", etc., will be matched by the first pattern while "ng_mystack_new@Base" would not. The second pattern will match all symbols having the string "private" in their names and matches will inherit optional tag from the pattern.

Basic patterns listed above can be combined where it makes sense. In that case, they are processed in the order in which the tags are specified. For example, both:

```
  (c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
  (regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
```

will match symbols "_ZN3NSA6ClassA7Private11privmethod1Ei@Base" and "_ZN3NSA6ClassA7Private11privmethod2Ei@Base". When matching the first pattern, the raw symbol is first demangled as C++ symbol, then the demangled name is matched against the regular expression. On the other hand, when matching the second pattern, regular expression is matched against the raw symbol name, then the symbol is tested if it is C++ one by attempting to demangle it. A failure of any basic pattern will result in the failure of the whole pattern. Therefore, for example, "__N3NSA6ClassA7Private11privmethod\dEi@Base" will not match either of the patterns because it is not a valid C++ symbol.

In general, all patterns are divided into two groups: aliases (basic c++ and symver) and generic patterns (regex, all combinations of multiple basic patterns). Matching of basic alias-based patterns is fast (O(1)) while generic patterns are O(N) (N - generic pattern count) for each symbol. Therefore, it is recommended not to overuse generic patterns.

When multiple patterns match the same real symbol, aliases (first c++, then symver) are preferred over generic patterns. Generic patterns are matched in the order they are found in the symbol file template until the first success. Please note, however, that manual reordering of template file entries is not recommended because dpkg-gensymbols generates diffs based on the alphanumerical order of their names.

### Using includes
When the set of exported symbols differ between architectures, it may become inefficient to use a single symbol file. In those cases, an include directive may prove to be useful in a couple of ways:

- You can factorize the common part in some external file and include that file in your package.symbols.arch file by using an include directive like this:

```
 #include "I<packages>.symbols.common"

```

- The include directive may also be tagged like any symbol:

```
 (tag|...|tagN)#include "file-to-include"

```

As a result, all symbols included from file-to-include will be considered to be tagged with tag ... tagN by default. You can use this feature to create a common package.symbols file which includes architecture specific symbol files:

```
  common_symbol1@Base 1.0
 (arch=amd64 ia64 alpha)#include "package.symbols.64bit"
 (arch=!amd64 !ia64 !alpha)#include "package.symbols.32bit"
  common_symbol2@Base 1.0

```

The symbols files are read line by line, and include directives are processed as soon as they are encountered. This means that the content of the included file can override any content that appeared before the include directive and that any content after the directive can override anything contained in the included file. Any symbol (or even another #include directive) in the included file can specify additional tags or override values of the inherited tags in its tag specification. However, there is no way for the symbol to remove any of the inherited tags.

An included file can repeat the header line containing the SONAME of the library. In that case, it overrides any header line previously read. However, in general it's best to avoid duplicating header lines. One way to do it is the following:

```
 #include "libsomething1.symbols.common"
  arch_specific_symbol@Base 1.0
```

## SEE ALSO
deb-symbols(5), dpkg-shlibdeps(1), dpkg-gensymbols(1).


deb-substvars

title: deb-substvars(5)

summary: Debian source substitution variables

text:
# deb-substvars(5)

## NAME
deb-substvars - Debian source substitution variables

## SYNOPSIS
debian/substvars, debian/binary-package.substvars, variables

## DESCRIPTION
Before dpkg-source, dpkg-gencontrol and dpkg-genchanges write their control information (to the source control file .dsc for dpkg-source and to standard output for dpkg-gencontrol and dpkg-genchanges) they perform some variable substitutions on the output file.

### Variable Syntax
A variable substitution has the form ${variable-name}. Variable names consist of alphanumerics (a-zA-Z0-9), hyphens (-) and colons (:) and start with an alphanumeric, and are case-sensitive, even though they might refer to other entities which are case-preserving. Variable substitutions are performed repeatedly until none are left; the full text of the field after the substitution is rescanned to look for more substitutions.

### File Syntax
Substitution variables can be specified in a file. These files consist of lines of the form name=value or name?=value. The = operator assigns a normal substitution variable, while the ?= operator (since dpkg 1.21.8) assigns an optional substitution variable which will emit no warnings even if unused. Trailing whitespace on each line, blank lines, and lines starting with a # symbol (comments) are ignored.

### Substitution
Variables can be set using the -V common option. They can be also specified in the file debian/substvars (or whatever other file is specified using the -T common option).

After all the substitutions have been done each occurrence of the string ${} (which is not an actual substitution variable) is replaced with a $ sign. This can be used as an escape sequence such as ${}{VARIABLE} which will end up as ${VARIABLE} on the output.

If a variable is referred to but not defined it generates a warning and an empty value is assumed.

While variable substitution is done on all control fields, some of those fields are used and needed during the build when the substitution did not yet occur. That's why you can't use variables in the Package, Source and Architecture fields.

Variable substitution happens on the content of the fields after they have been parsed, thus if you want a variable to expand over multiple lines you do not have to include a space after the newline. This is done implicitly when the field is output. For example, if the variable ${Description} is set to "foo is bar.${Newline}foo is great." and if you have the following field:

```
 Description: foo application
  ${Description}
  .
  More text.
```

It will result in:

```
 Description: foo application
  foo is bar.
  foo is great.
  .
  More text.
```

### Built-in Variable
Additionally, the following standard variables are always available:

Arch

The current host architecture (i.e. the architecture the package is being built for, the equivalent of DEB_HOST_ARCH).

vendor:Name

The current vendor name (since dpkg 1.20.0). This value comes from the Vendor field for the current vendor's origin file, as dpkg-vendor(1) would retrieve it.

vendor:Id

The current vendor ID (since dpkg 1.20.0). This is just the lowercase variant of vendor:Name.

source:Version

The source package version (since dpkg 1.13.19).

source:Upstream-Version

The upstream source package version, including the Debian version epoch if any (since dpkg 1.13.19).

binary:Version

The binary package version (which may differ from source:Version in a binNMU for example; since dpkg 1.13.19).

Source-Version

The source package version (from the changelog file). This variable is now obsolete and emits an error when used as its meaning is different from its function, please use the source:Version or binary:Version as appropriate.

source:Synopsis

The source package synopsis, extracted from the source stanza Description field, if it exists (since dpkg 1.19.0).

source:Extended-Description

The source package extended description, extracted from the source stanza Description field, if it exists (since dpkg 1.19.0).

Installed-Size

The approximate total size of the package's installed files. This value is copied into the corresponding control file field; setting it will modify the value of that field. If this variable is not set dpkg-gencontrol will compute the default value by accumulating the size of each regular file and symlink rounded to 1 KiB used units, and a baseline of 1 KiB for any other filesystem object type. With hardlinks only being counted once as a regular file. Note: Take into account that this can only ever be an approximation, as the actual size used on the installed system will depend greatly on the filesystem used and its parameters, which might end up using either more or less space than the specified in this field.

Extra-Size

Additional disk space used when the package is installed. If this variable is set its value is added to that of the Installed-Size variable (whether set explicitly or using the default value) before it is copied into the Installed-Size control file field.

S:fieldname

The value of the source stanza field fieldname (which must be given in the canonical capitalization; since dpkg 1.18.11). Setting these variables has no effect other than on places where they are expanded explicitly. These variables are only available when generating binary control files.

F:fieldname

The value of the output field fieldname (which must be given in the canonical capitalization). Setting these variables has no effect other than on places where they are expanded explicitly.

Format

The .changes file format version generated by this version of the source packaging scripts. If you set this variable the contents of the Format field in the .changes file will change too.

Newline, Space, Tab

These variables each hold the corresponding character.

shlibs:dependencyfield

Variable settings with names of this form are generated by dpkg-shlibdeps.

dpkg:Upstream-Version

The upstream version of dpkg (since dpkg 1.13.19).

dpkg:Version

The full version of dpkg (since dpkg 1.13.19).

## FILES
debian/substvars

List of substitution variables and values.

## SEE ALSO
dpkg(1), dpkg-vendor(1), dpkg-genchanges(1), dpkg-gencontrol(1), dpkg-shlibdeps(1), dpkg-source(1).


deb-symbols

title: deb-symbols(5)

text:
# deb-symbols(5)

## NAME
deb-symbols - Debian's extended shared library information file

## SYNOPSIS
DEBIAN/symbols

## DESCRIPTION
The symbol files are shipped in Debian binary packages, and its format is a subset of the template symbol files used by dpkg-gensymbols(1) in Debian source packages, see deb-src-symbols(5).

The format for an extended shared library dependency information entry in these files is:

library-soname main-dependency-template

[| alternative-dependency-template]

[...]

[* field-name: field-value]

[...]

symbol minimal-version [id-of-dependency-template]

The library-soname is exactly the value of the SONAME field as exported by objdump(1). A dependency-template is a dependency where #MINVER# is dynamically replaced either by a version check like “(>= minimal-version)” or by nothing (if an unversioned dependency is deemed sufficient).

Each exported symbol (listed as name@version, with version being “Base” if the library is not versioned) is associated to a minimal-version of its dependency template (the main dependency template is always used and will end up being combined with the dependency template referenced by id-of-dependency-template if present). The first alternative dependency template is numbered 1, the second one 2, etc. Each column is separated by exactly a single whitespace.

Each entry for a library can also have some fields of meta-information. Those fields are stored on lines starting with an asterisk. Currently, the only valid fields are:

Build-Depends-Package

It indicates the name of the “-dev” package associated to the library and is used by dpkg-shlibdeps to make sure that the dependency generated is at least as strict as the corresponding build dependency (since dpkg 1.14.13).

Build-Depends-Packages

The same as Build-Depends-Package but accepts a comma-separated list of package names (since dpkg 1.20.0). This field will override any Build-Depends-Package field present, and is mostly useful with “-dev” packages and metapackages depending on these, say for a transition period.

Allow-Internal-Symbol-Groups

It indicates what internal symbol groups should be ignored, as a whitespace separated list, so that the symbols contained in those groups get included in the output file (since dpkg 1.20.1). This should only be necessary for toolchain packages providing those internal symbols. The available groups are system dependent, for ELF and GNU-based systems these are aeabi and gomp.

Ignore-Blacklist-Groups

A deprecated alias for Allow-Internal-Symbol-Groups (since dpkg 1.20.1, supported since dpkg 1.17.6).

## EXAMPLES

### Simple symbols file

```
 libftp.so.3 libftp3 #MINVER#
  DefaultNetbuf@Base 3.1-1-6
  FtpAccess@Base 3.1-1-6
  [...]
```

### Advanced symbols file

```
 libGL.so.1 libgl1
 | libgl1-mesa-glx #MINVER#
 * Build-Depends-Package: libgl1-mesa-dev
  publicGlSymbol@Base 6.3-1
  [...]
  implementationSpecificSymbol@Base 6.5.2-7 1
  [...]
```

## SEE ALSO
<https://wiki.debian.org/Projects/ImprovedDpkgShlibdeps>, deb-src-symbols(5), dpkg-shlibdeps(1), dpkg-gensymbols(1).


deb-triggers

title: deb-triggers(5)

summary: package triggers

text:
# deb-triggers(5)

## NAME
deb-triggers - package triggers

## SYNOPSIS
debian/triggers, debian/binary-package.triggers, DEBIAN/triggers

## DESCRIPTION
A package declares its relationship to some trigger(s) by including a triggers file in its control archive (i.e. DEBIAN/triggers during package creation).

This file contains directives, one per line. Leading and trailing whitespace and everything after the first # on any line will be trimmed, and empty lines will be ignored.

The trigger control directives currently supported are:

interest trigger-name

interest-await trigger-name

interest-noawait trigger-name

Specifies that the package is interested in the named trigger. All triggers in which a package is interested must be listed using this directive in the triggers control file. The “await” variants put the triggering package in triggers-awaited state depending on how the trigger was activated. The “noawait” variant does not put the triggering packages in triggers-awaited state, even if the triggering package declared an “await” activation (either with an activate-await or activate directive, or by using the dpkg-trigger --no-await command-line option). The “noawait” variant should be used when the functionality provided by the trigger is not crucial.

activate trigger-name

activate-await trigger-name

activate-noawait trigger-name

Arranges that changes to this package's state will activate the specified trigger. The trigger will be activated at the start of the following operations: unpack, configure, remove (including for the benefit of a conflicting package), purge and deconfigure. The “await” variants only put the triggering package in triggers-awaited state if the interest directive is also “await”. The “noawait” variant never puts the triggering packages in triggers-awaited state. The “noawait” variant should be used when the functionality provided by the trigger is not crucial.

If this package disappears during the unpacking of another package the trigger will be activated when the disappearance is noted towards the end of the unpack. Trigger processing, and transition from triggers-awaited to installed, does not cause activations. In the case of unpack, triggers mentioned in both the old and new versions of the package will be activated.

Unknown directives are an error which will prevent installation of the package.

The “-noawait” variants should always be favored when possible since triggering packages are not put in triggers-awaited state and can thus be immediately configured without requiring the processing of the trigger. If the triggering packages are dependencies of other upgraded packages, it will avoid an early trigger processing run and make it possible to run the trigger only once as one of the last steps of the upgrade.

The “-noawait” variants are supported since dpkg 1.16.1, and will lead to errors if used with an older dpkg.

The “-await” alias variants are supported since dpkg 1.17.21, and will lead to errors if used with an older dpkg.

When a package provides an interest-noawait directive, any activation will set the triggering package into “noawait” mode, regardless of the awaiting mode requested by the activation (either “await” or “noawait”). When a package provides an interest or interest-await directive, any activation will set the triggering package into “await” or “noawait“ depending on how it was activated.

## SEE ALSO
dpkg-trigger(1), dpkg(1), /usr/share/doc/dpkg/spec/triggers.txt.


title: deb822(5)

summary: Debian RFC822 control data format

text:
# deb822(5)

## NAME
deb822 - Debian RFC822 control data format

## DESCRIPTION
The package management system manipulates data represented in a common format, known as control data, stored in control files. Control files are used for source packages, binary packages and the .changes files which control the installation of uploaded files (dpkg's internal databases are in a similar format).

## SYNTAX
A control file consists of one or more stanzas of fields (the stanzas sometimes used to be referred to as paragraphs). The stanzas are separated by empty lines. Parsers may accept lines consisting solely of U+0020 SPACE and U+0009 TAB as stanza separators, but control files should use empty lines. Some control files allow only one stanza; others allow several, in which case each stanza usually refers to a different package. (For example, in source packages, the first stanza refers to the source package, and later stanzas refer to binary packages generated from the source.) The ordering of the stanzas in control files is significant.

Each stanza consists of a series of data fields. Each field consists of the field name followed by a colon (U+003A ‘:’), and then the data/value associated with that field. The field name is composed of US-ASCII characters excluding control characters, space, and colon (i.e., characters in the ranges U+0021 ‘!’ through U+0039 ‘9’, and U+003B ‘;’ through U+007E ‘~’, inclusive). Field names must not begin with the comment character (U+0023 ‘#’), nor with the hyphen character (U+002D ‘-’).

The field ends at the end of the line or at the end of the last continuation line (see below). Horizontal whitespace (U+0020 SPACE and U+0009 TAB) may occur immediately before or after the value and is ignored there; it is conventional to put a single space after the colon. For example, a field might be:

```
 Package: dpkg
```

the field name is Package and the field value dpkg.

Empty field values are only permitted in source package control files (debian/control). Such fields are ignored.

A stanza must not contain more than one instance of a particular field name.

There are three types of fields:

simple

The field, including its value, must be a single line. Folding of the field is not permitted. This is the default field type if the definition of the field does not specify a different type.

folded

The value of a folded field is a logical line that may span several lines. The lines after the first are called continuation lines and must start with a U+0020 SPACE or a U+0009 TAB. Whitespace, including any newlines, is not significant in the field values of folded fields. This folding method is similar to RFC5322, allowing control files that contain only one stanza and no multiline fields to be read by parsers written for RFC5322.

multiline

The value of a multiline field may comprise multiple continuation lines. The first line of the value, the part on the same line as the field name, often has special significance or may have to be empty. Other lines are added following the same syntax as the continuation lines of the folded fields. Whitespace, including newlines, is significant in the values of multiline fields.

Whitespace must not appear inside names (of packages, architectures, files or anything else) or version numbers, or between the characters of multi-character version relationships.

The presence and purpose of a field, and the syntax of its value may differ between types of control files.

Field names are not case-sensitive, but it is usual to capitalize the field names using mixed case as shown below. Field values are case-sensitive unless the description of the field says otherwise.

Stanza separators (empty lines) and lines consisting only of U+0020 SPACE and U+0009 TAB, are not allowed within field values or between fields. Empty lines in field values are usually escaped by representing them by a U+0020 SPACE followed by a dot (U+002E ‘.’).

Lines starting with U+0023 ‘#’, without any preceding whitespace are comments lines that are only permitted in source package control files (debian/control) and in deb-origin(5) files. These comment lines are ignored, even between two continuation lines. They do not end logical lines.

All control files must be encoded in UTF-8.

## SEE ALSO
RFC822, RFC5322.


dpkg.cfg

title: dpkg.cfg(5)

summary: dpkg configuration file

text:
# dpkg.cfg(5)

## NAME
dpkg.cfg - dpkg configuration file

## DESCRIPTION
This file contains default options for dpkg. Each line contains a single option which is exactly the same as a normal command line option for dpkg except for the leading hyphens which are not used here. Quotes surrounding option values are stripped. Comments are allowed by starting a line with a hash sign (‘#’).

## FILES
/etc/dpkg/dpkg.cfg.d/[0-9a-zA-Z_-]*

/etc/dpkg/dpkg.cfg

~/.dpkg.cfg

## SEE ALSO
dpkg(1).


dsc

title: dsc(5)

text:
# dsc(5)

## NAME
dsc - Debian source packages' control file format

## SYNOPSIS
filename.dsc

## DESCRIPTION
Each Debian source package is composed of a .dsc control file, which contains a number of fields, in deb822(5) format.

Each field begins with a tag, such as Source or Binary (case insensitive), followed by a colon, and the body of the field (case sensitive unless stated otherwise). Fields are delimited only by field tags. In other words, field text may be multiple lines in length, but the installation tools will generally join lines when processing the body of the field (except in case of the multiline fields Package-List, Files, Checksums-Sha1 and Checksums-Sha256, see below).

The control data might be enclosed in an OpenPGP ASCII Armored signature, as specified in RFC4880.

## FIELDS
Format: format-version (required)

The value of this field declares the format version of the source package. The field value is used by programs acting on a source package to interpret the list of files in the source package and determine how to unpack it. The syntax of the field value is a numeric major revision (“0-9”), a period (“.”), a numeric minor revision (“0-9”), and then an optional subtype after whitespace (“ \t”), which if specified is a lowercase alphanumeric (“a-z0-9”) word in parentheses (“()”). The subtype is optional in the syntax but may be mandatory for particular source format revisions. The source formats currently supported by dpkg are 1.0, 2.0, 3.0 (native), 3.0 (quilt), 3.0 (git), 3.0 (bzr) and 3.0 (custom). See dpkg-source(1) for their description.

Source: source-name (required)

The value of this field determines the package name, and is used to generate file names by most installation tools.

Binary: binary-package-list

This folded field lists binary packages which this source package can produce, separated by commas. This field has now been superseded by the Package-List field, which gives enough information about what binary packages are produced on which architecture, build-profile and other involved restrictions.

Architecture: arch-list (recommended)

A list of architectures and architecture wildcards separated by spaces which specify the type of hardware this package can be compiled for. Common architecture names and architecture wildcards are amd64, armel, i386, linux-any, any-amd64, etc. Note that the all value is meant for packages that are architecture independent, and any for packages that are architecture dependent. The list may include (or consist solely of) the special value all. When the list contains the architecture wildcard any, the only other value allowed in the list is all.

The field value is generally generated from Architecture fields from in the debian/control in the source package.

Version: version-string (required)

Typically, this is the original package's version number in whatever form the program's author uses. It may also include a Debian revision number (for non-native packages). The exact format and sorting algorithm are described in deb-version(7).

Origin: name

The name of the distribution this package is originating from.

Maintainer: fullname-email (recommended)

Should be in the format “Joe Bloggs <jbloggs@foo.com>”, and is typically the person who created the package, as opposed to the author of the software that was packaged.

Uploaders: fullname-email-list

Lists all the names and email addresses of co-maintainers of the package, in the same format as the Maintainer field. Multiple co-maintainers should be separated by a comma.

Description short-description

long-description

The format for the source package description is a short brief summary on the first line (after the Description field). The following lines should be used as a longer, more detailed description. Each line of the long description must be preceded by a space, and blank lines in the long description must contain a single ‘.’ following the preceding space.

Homepage: url

The upstream project home page url.

Standards-Version: version-string (recommended)

This documents the most recent version of the distribution policy standards this package complies with.

Vcs-Browser: url

The url of a web interface to browse the Version Control System repository.

Vcs-Arch: url

Vcs-Bzr: url

Vcs-Cvs: url

Vcs-Darcs: url

Vcs-Git: url

Vcs-Hg: url

Vcs-Mtn: url

Vcs-Svn: url

These fields declare the url of the Version Control System repository used to maintain this package. See deb-src-control(5) for more details.

Testsuite: name-list

This field declares that the source package contains the specified test suites. The value is a comma-separated list of test suites. If the autopkgtest value is present, a debian/tests/control is expected to be present, if the file is present but not the value, then dpkg-source will automatically add it, preserving previous values.

Testsuite-Triggers: package-list

This field declares the comma-separated union of all test dependencies (Depends fields in debian/tests/control file), with all restrictions removed, and OR dependencies flattened (that is, converted to separate AND relationships), except for binaries generated by this source package and its meta-dependency equivalent @. Rationale: this field is needed because otherwise to be able to get the test dependencies, each source package would need to be unpacked.

Build-Depends: package-list

Build-Depends-Arch: package-list

Build-Depends-Indep: package-list

Build-Conflicts: package-list

Build-Conflicts-Arch: package-list

Build-Conflicts-Indep: package-list

These fields declare relationships between the source package and packages used to build it. They are discussed in the deb-src-control(5) manpage.

Package-List:

package package-type section priority key-value-list

This multiline field contains a list of binary packages generated by this source package. The package is the binary package name.

The package-type is the binary package type, usually deb, another common value is udeb.

The section and priority match the binary package fields of the same name.

The key-value-list is a space separated key=value list, and the currently known optional keys are:

arch

The architecture restriction from the binary package Architecture field, with spaces converted to ‘,’.

profile

The normalized build-profile restriction formula from the binary package Build-Profile field, with ORs converted to ‘+’ and ANDs to ‘,’.

protected

If the binary package is protected, this key will contain the value of the Protected field, that is a yes value. Supported since dpkg 1.20.1.

essential

If the binary package is essential, this key will contain the value of the Essential field, that is a yes value.

Files: (required)

Checksums-Sha1: (required)

Checksums-Sha256: (required)

checksum size filename

These multiline fields contain a list of files with a checksum and size for each one. These fields have the same syntax and differ only in the checksum algorithm used: MD5 for Files, SHA-1 for Checksums-Sha1 and SHA-256 for Checksums-Sha256. The first line of the field value (the part on the same line as the field name followed by a colon) is always empty. The content of the field is expressed as continuation lines, one line per file. Each line consists of the checksum, a space, the file size, a space, and the file name.

These fields list all files that make up the source package. The list of files in these fields must match the list of files in the other related fields.

## BUGS
The Format field conflates the format for the .dsc file itself and the format of the extracted source package.

## SEE ALSO
deb822(5), deb-src-control(5), deb-version(7), dpkg-source(1).


dracut.conf

package: dracut

title: dracut.conf(5)

summary: configuration file(s) for dracut

text:
# dracut.conf(5)

## NAME
dracut.conf - configuration file(s) for dracut

## SYNOPSIS
/etc/dracut.conf /etc/dracut.conf.d/*.conf /usr/lib/dracut/dracut.conf.d/*.conf

## DESCRIPTION
dracut.conf is loaded during the initialization phase of dracut. Command line parameter will override any values set here.

*.conf files are read from /usr/lib/dracut/dracut.conf.d and /etc/dracut.conf.d. Files with the same name in /etc/dracut.conf.d will replace files in /usr/lib/dracut/dracut.conf.d. The files are then read in alphanumerical order and will override parameters set in /etc/dracut.conf. Each line specifies an attribute and a value. A # indicates the beginning of a comment; following characters, up to the end of the line are not interpreted.

dracut command line options will override any values set here.

Configuration files must have the extension .conf; other extensions are ignored.

add_dracutmodules+=" <dracut modules> "

Add a space-separated list of dracut modules to call when building the initramfs. Modules are located in /usr/lib/dracut/modules.d.

force_add_dracutmodules+=" <dracut modules> "

Force to add a space-separated list of dracut modules to the default set of modules, when host-only mode is specified. This parameter can be specified multiple times.

omit_dracutmodules+=" <dracut modules> "

Omit a space-separated list of dracut modules to call when building the initramfs. Modules are located in /usr/lib/dracut/modules.d.

dracutmodules+=" <dracut modules> "

Specify a space-separated list of dracut modules to call when building the initramfs. Modules are located in /usr/lib/dracut/modules.d. This option forces dracut to only include the specified dracut modules. In most cases the "add_dracutmodules" option is what you want to use.

add_drivers+=" <kernel modules> "

Specify a space-separated list of kernel modules to add to the initramfs. The kernel modules have to be specified without the ".ko" suffix.

force_drivers+=" <list of kernel modules> "

See add_drivers above. But in this case it is ensured that the drivers are tried to be loaded early via modprobe.

omit_drivers+=" <kernel modules> "

Specify a space-separated list of kernel modules not to add to the initramfs. The kernel modules have to be specified without the ".ko" suffix.

drivers+=" <kernel modules> "

Specify a space-separated list of kernel modules to exclusively include in the initramfs. The kernel modules have to be specified without the ".ko" suffix.

filesystems+=" <filesystem names> "

Specify a space-separated list of kernel filesystem modules to exclusively include in the generic initramfs.

drivers_dir="<kernel modules directory>"

Specify the directory where to look for kernel modules.

fw_dir+=" :<dir>[:<dir> ...] "

Specify additional colon-separated list of directories where to look for firmware files.

libdirs+=" <dir>[ <dir> ...] "

Specify a space-separated list of directories where to look for libraries.

install_items+=" <file>[ <file> ...] "

Specify additional files to include in the initramfs, separated by spaces.

install_optional_items+=" <file>[ <file> ...] "

Specify additional files to include in the initramfs, separated by spaces, if they exist.

compress="{cat|bzip2|lzma|xz|gzip|lzop|lz4|zstd|<compressor [args ...]>}"

Compress the generated initramfs using the passed compression program. If you pass it just the name of a compression program, it will call that program with known-working arguments. If you pass arguments, it will be called with exactly those arguments. Depending on what you pass, this may result in an initramfs that the kernel cannot decompress. To disable compression, use "cat".

squash_compress="{<compressor [args ...]>}"

Compress the squashfs image using the passed compressor and compressor specific options for mksquashfs. You can refer to mksquashfs manual for supported compressors and compressor specific options. If squash module is not called when building the initramfs, this option will not take effect.

do_strip="{yes|no}"

Strip binaries in the initramfs (default=yes).

aggressive_strip="{yes|no}"

Strip more than just debug symbol and sections, for a smaller initramfs build. The "do_strip=yes" option must also be specified (default=no).

do_hardlink="{yes|no}"

Hardlink files in the initramfs (default=yes).

prefix=" <directory> "

Prefix initramfs files with <directory>.

hostonly="{yes|no}"

Host-only mode: Install only what is needed for booting the local host instead of a generic host and generate host-specific configuration (default=no).

hostonly_mode="{sloppy|strict}"

Specify the host-only mode to use (default=sloppy). In "sloppy" host-only mode, extra drivers and modules will be installed, so minor hardware change won’t make the image unbootable (e.g. changed keyboard), and the image is still portable among similar hosts. With "strict" mode enabled, anything not necessary for booting the local host in its current state will not be included, and modules may do some extra job to save more space. Minor change of hardware or environment could make the image unbootable.

hostonly_cmdline="{yes|no}"

If set to "yes", store the kernel command line arguments needed in the initramfs. If hostonly="yes" and this option is not configured, it’s automatically set to "yes".

hostonly_nics+=" [<nic>[ <nic> ...]] "

Only enable listed NICs in the initramfs. The list can be empty, so other modules can install only the necessary network drivers.

persistent_policy="<policy>"

Use <policy> to address disks and partitions. <policy> can be any directory name found in /dev/disk (e.g. "by-uuid", "by-label"), or "mapper" to use /dev/mapper device names (default=mapper).

tmpdir="<temporary directory>"

Specify temporary directory to use.

Warning If chrooted to another root other than the real root device, use --fstab and provide a valid /etc/fstab.

use_fstab="{yes|no}"

Use /etc/fstab instead of /proc/self/mountinfo (default=no).

add_fstab+=" <filename> "

Add entries of <filename> to the initramfs /etc/fstab.

add_device+=" <device> "

Bring up <device> in initramfs, <device> should be the device name. This can be useful in host-only mode for resume support when your swap is on LVM an encrypted partition.

mdadmconf="{yes|no}"

Include local /etc/mdadm.conf (default=no).

lvmconf="{yes|no}"

Include local /etc/lvm/lvm.conf (default=no).

fscks=" <fsck tools> "

Add a space-separated list of fsck tools. If nothing is specified, the default is: "umount mount /sbin/fsck* xfs_db xfs_check xfs_repair e2fsck jfs_fsck btrfsck". The installation is opportunistic (non-existing tools are ignored).

nofscks="{yes|no}"

If specified, inhibit installation of any fsck tools (default=no).

ro_mnt="{yes|no}"

Mount / and /usr read-only by default (default=no).

kernel_cmdline="parameters"

Specify default kernel command line parameters. Despite its name, this command only sets initrd parameters.

kernel_only="{yes|no}"

Only install kernel drivers and firmware files (default=no).

no_kernel="{yes|no}"

Do not install kernel drivers and firmware files (default=no).

acpi_override="{yes|no}"

[WARNING] ONLY USE THIS IF YOU KNOW WHAT YOU ARE DOING! Override BIOS provided ACPI tables. For further documentation read Documentation/acpi/initrd_table_override.txt in the kernel sources. Search for ACPI table files (must have .aml suffix) in acpi_table_dir= directory (see below) and add them to a separate uncompressed cpio archive. This cpio archive gets glued (concatenated, uncompressed one must be the first one) to the compressed cpio archive. The first, uncompressed cpio archive is for data which the kernel must be able to access very early (and cannot make use of uncompress algorithms yet) like microcode or ACPI tables (default=no).

acpi_table_dir="<dir>"

Directory to search for ACPI tables if acpi_override= is set to yes.

early_microcode="{yes|no}"

Combine early microcode with ramdisk (default=yes).

stdloglvl="{0-6}"

Specify logging level for standard error (default=4).

Note Logging levels:

```
    0 - suppress any messages

    1 - only fatal errors

    2 - all errors

    3 - warnings

    4 - info

    5 - debug info (here starts lots of output)

    6 - trace info (and even more)
```

sysloglvl="{0-6}"

Specify logging level for syslog (default=0).

fileloglvl="{0-6}"

Specify logging level for logfile (default=4).

logfile="<file>"

Path to logfile.

sshkey="<file>"

SSH key file used with ssh-client module.

show_modules="{yes|no}"

Print the name of the included modules to standard output during build (default=no).

i18n_vars="<variable mapping>"

Distribution specific variable mapping. See dracut/modules.d/10i18n/README for a detailed description.

i18n_default_font="<fontname>"

The font <fontname> to install, if not specified otherwise. Default is "eurlatgr".

i18n_install_all="{yes|no}"

Install everything regardless of generic or host-only mode (default=no).

reproducible="{yes|no}"

Create reproducible images (default=no).

noimageifnotneeded="{yes|no}"

Do not create an image in host-only mode, if no kernel driver is needed and no /etc/cmdline/*.conf will be generated into the initramfs (default=no).

loginstall="<directory>"

Log all files installed from the host to <directory>.

uefi="{yes|no}"

Instead of creating an initramfs image, dracut will create an UEFI executable, which can be executed by an UEFI BIOS (default=no). The default output filename is <EFI>/EFI/Linux/linux-$kernel$-<MACHINE_ID>-<BUILD_ID>.efi. <EFI> might be /efi, /boot or /boot/efi depending on where the ESP partition is mounted. The <BUILD_ID> is taken from BUILD_ID in /usr/lib/os-release or if it exists /etc/os-release and is left out, if BUILD_ID is non-existent or empty.

machine_id="{yes|no}"

Affects the default output filename of the UEFI executable, including the <MACHINE_ID> part (default=yes).

uefi_stub="<file>"

Specifies the UEFI stub loader, which will load the attached kernel, initramfs and kernel command line and boots the kernel. The default is /lib/systemd/boot/efi/linux<EFI-MACHINE-TYPE-NAME>.efi.stub.

uefi_splash_image="<file>"

Specifies the UEFI stub loader’s splash image. Requires bitmap (.bmp) image format.

uefi_secureboot_cert="<file>", uefi_secureboot_key="<file>"

Specifies a certificate and corresponding key, which are used to sign the created UEFI executable. Requires both certificate and key need to be specified and sbsign to be installed.

uefi_secureboot_engine="parameter"

Specifies an engine to use when signing the created UEFI executable. E.g. "pkcs11"

kernel_image="<file>"

Specifies the kernel image, which to include in the UEFI executable. The default is /lib/modules/<KERNEL-VERSION>/vmlinuz or /boot/vmlinuz-<KERNEL-VERSION>.

sbat="parameters"

Specifies the SBAT parameters, which to include in the UEFI executable. By default the default SBAT string added is "sbat,1,SBAT Version,sbat,1, https://github.com/rhboot/shim/blob/main/SBAT.md".

enhanced_cpio="{yes|no}"

Attempt to use the dracut-cpio binary, which optimizes archive creation for copy-on-write filesystems (default=no). When specified, initramfs archives are also padded to ensure optimal data alignment for extent sharing. To retain reflink data deduplication benefits, this should be used alongside the compress="cat" and do_strip="no" parameters, with initramfs source files, tmpdir staging area and destination all on the same copy-on-write capable filesystem.

parallel="{yes|no}"

If set to yes, try to execute tasks in parallel (currently only supported for --regenerate-all).

initrdname="<filepattern>"

Specifies the file name for the generated initramfs if it is not set otherwise. file pattern and only one file with this pattern should exists in the

## FILES
/etc/dracut.conf

Old configuration file. You better use your own file in /etc/dracut.conf.d/.

/etc/dracut.conf.d/

Any /etc/dracut.conf.d/*.conf file can override the values in /etc/dracut.conf. The configuration files are read in alphanumerical order.

## AUTHOR
Harald Hoyer

## SEE ALSO
dracut(8) dracut.cmdline(7)


drbd-reactor.agentx

package: drbd-reactor

title: drbd-reactor.agentx(5)

summary: drbd-reactor agentx plugin

text:
# drbd-reactor.agentx(5)

## NAME
drbd-reactor.agentx — drbd-reactor agentx plugin

## DESCRIPTION
drbd-reactor.agentx is the SNMP plugin (via AgentX) for drbd-reactor(1).

This plugin serves a AgentX subagent for SNMP monitoring of DRBD resources exposing various DRBD metrics.

## METRICS
The plugin exposes a wide variety of metrics, for more details please check

## EXAMPLES
Configure net-snmp to include the LINBIT ID and turn on agentx:

```
...
view    systemview    included   .1.3.6.1.2.1.25.1.1
# add LINBIT ID to the system view and enable agentx
view    systemview    included   .1.3.6.1.4.1.23302
master agentx
agentXSocket tcp:127.0.0.1:705
...
```

After preparing the SNMP daemon a plugin configuration looks like this:

```
[[agentx]]
address = "localhost:705"
cache-max = 60 # seconds
agent-timeout = 60 # seconds snmpd waits for an answer
peer-states = true # include peer connection and disk states
```

## AUTHORS
The drbd-reactor(1) program was written by the following authors:

Roland Kammerer <rck@linbit.com>

Moritz Wanzenböck <moritz.wanzenboeck@linbit.com>


drbd-reactor.debugger

title: drbd-reactor.debugger(5)

summary: drbd-reactor debugger plugin

text:
# drbd-reactor.debugger(5)

## NAME
drbd-reactor.debugger — drbd-reactor debugger plugin

## DESCRIPTION
drbd-reactor.debugger is the debugger plugin for drbd-reactor(1).

This is a simple plugin that prints change events to stderr. This is mainly useful as a simple showcase for users or plugin writers. It also helps developers to detect bugs in drbd-reactor's core.

Messages are printed on debug level, so make sure to set an apropriate log level.

## EXAMPLES

```
[[log]]
level = "debug"

## Enable the debugger
[[debugger]]
```

## AUTHORS
The drbd-reactor(1) program was written by the following authors:

Roland Kammerer <rck@linbit.com>

Moritz Wanzenböck <moritz.wanzenboeck@linbit.com>


drbd-reactor.prometheus

title: drbd-reactor.prometheus(5)

summary: drbd-reactor prometheus plugin

text:
# drbd-reactor.prometheus(5)

## NAME
drbd-reactor.prometheus — drbd-reactor prometheus plugin

## DESCRIPTION
drbd-reactor.prometheus is the prometheus plugin for drbd-reactor(1).

This plugin provides a prometheus compatible http endpoint serving DRBD metrics.

## METRICS

- drbdreactor_up gauge: Boolean indicating whether or not drbdreactor is running. Always 1

- drbd_kernel_version gauge: Version of the loaded DRBD kernel module and DRBD utils

- drbd_connection_apinflight_bytes gauge: Number of application requests in flight (not completed)

- drbd_connection_congested gauge: Boolean whether the TCP send buffer of the data connection is more than 80% filled

- drbd_connection_rsinflight_bytes gauge: Number of resync requests in flight

- drbd_connection_state gauge: DRBD connection state

- drbd_device_alsuspended gauge: Boolean whether the Activity-Log is suspended

- drbd_device_alwrites_total counter: Number of updates of the activity log area of the meta data

- drbd_device_bmwrites_total counter: Number of updates of the bitmap area of the meta data

- drbd_device_client gauge: Boolean whether this device is a client (i.e., intentional diskless)

- drbd_device_lowerpending gauge: Number of open requests to the local I/O sub-system issued by DRBD

- drbd_device_quorum gauge: Boolean if this device has DRBD quorum

- drbd_device_read_bytes_total counter: Net data read from local hard disk

- drbd_device_size_bytes gauge: Device size in bytes

- drbd_device_state gauge: DRBD device state

- drbd_device_unintentionaldiskless gauge: Boolean whether the devices is unintentional diskless

- drbd_device_upperpending gauge: Number of block I/O requests forwarded to DRBD, but not yet answered by DRBD.

- drbd_device_written_bytes_total counter: Net data written on local disk

- drbd_peerdevice_outofsync_bytes gauge: Number of bytes currently out of sync with this peer, according to the bitmap that DRBD has for it

- drbd_peerdevice_sent_bytes: Number of bytes currently sent to this peer

- drbd_peerdevice_received_bytes: Number of bytes currently received from this peer

- drbd_resource_maypromote gauge: Boolean whether the resource may be promoted to Primary

- drbd_resource_promotionscore gauge: The promotion score (higher is better) for the resource

- drbd_resource_resources gauge: Number of resources

- drbd_resource_role gauge: DRBD role of the resource

- drbd_resource_suspended gauge: Boolean whether the resource is suspended

## EXAMPLES
Configure an exporter also generating enums on the standard port.

```
[[log]]
level = "debug"

# Enable a prometheus exporter
[[prometheus]]
enums = true
```

## AUTHORS
The drbd-reactor(1) program was written by the following authors:

Roland Kammerer <rck@linbit.com>

Moritz Wanzenböck <moritz.wanzenboeck@linbit.com>


drbd-reactor.promoter

title: drbd-reactor.promoter(5)

summary: drbd-reactor promoter plugin

text:
# drbd-reactor.promoter(5)

## NAME
drbd-reactor.promoter — drbd-reactor promoter plugin

## DESCRIPTION
drbd-reactor.promoter is the promoter plugin for drbd-reactor(1).

The promoter plugin monitors events on resources an executes systemd units. This plugin can be used for simple high-availability.

By default the plugin generates a series of systemd service overrides (i.e., what systemd calls "Drop-In") and a systemd target unit that contains dependencies on these generated services. The services, and their order, is defined via the list specified in start.

The plugin generates two implicit extra units:

- a drbd-promote@ override that promotes the DRBD resource (i.e., switches it to Primary). This is a dependency for all the other units from start (according overrides are generated).

- a drbd-services@ target that subsumes all the generated dependencies from the start list.

Let's look at a simple example to see which overrides get generated from a dummy start list like this:

```
[[promoter]]
[promoter.resources.foo]
start = [ "a.service", "b.service", "c.service" ]
```

- /var/run/systemd/system/drbd-promote@foo.d/reactor.conf containing the necessary pieces to wait for the backing devices of DRBD resource “foo” and to promote it to Primary.

- /var/run/systemd/system/a.service.d/reactor.conf containing a dependency on drbd-promote@foo

- /var/run/systemd/system/b.service.d/reactor.conf containing dependencies on drbd-promote@foo and on a.service.

- /var/run/systemd/system/c.service.d/reactor.conf containing dependencies on drbd-promote@foo and on b.service.

- /var/run/systemd/system/drbd-services@foo.target.d/reactor.conf containing dependencies on a.service, b.service, and c.service.

If a DRBD resource changes its state to “may promote”, the plugin (i.e., all plugins on all nodes in the cluster) start the generated systemd target (e.g., drbd-services@foo.target ). All will try to start the drbd-promote@ unit first, but only one will succeed and continue to start the rest of the services. All the others will fail intentionally.

In order to promote the resource with the best disk state, the plugin evaluates its local disk states and waits a short period of time, which might give a promoter on another host the chance (i.e., because its sleep time is shorter) to promote the resource first. Sleep times are calculated as follows:

DiskState

Sleep time in seconds

Diskless

6

Attaching

6

Detaching

6

Failed

6

Negotiating

6

Unknown

6

Inconsistent

3

Outdated

2

Consistent

1

UpToDate

0

The actual sleep time is calculated as the worst case of all the volumes in a resource and can be scaled by setting sleep-before-promote-factor.

If a resource loses “quorum”, it stops the systemd drbd-services@ target and all the dependencies. Stopping services on the node that lost quorum is the standard behavior one would expect from a cluster manger. There might be scenarios where it is preferable to freeze the started service until quorum is gained again. As this requires multiple prerequisites to hold true, freezing a resource on quorum loss is described in FREEZING RESOURCES.

The plugin's configuration can contain an action that is executed if a stop action fails (e.g., triggering a reboot). Start actions in start are interpreted as systemd.unit(5). and have to have an according postfix like .service or .mount. ocf resource agents are supported via the ocf.rs@ service. Please see OCF RESOURCE AGENTS for a detailed overview.

The configuration can contain a setting that specifies that resources are stopped whenever the plugin exits (e.g., on service restart).

It also contains a runner that can be set to shell. Then the items in start are interpreted as shell scripts and started in order (no explicit targets or anything) and stopped in reverse order or as defined via stop. This can be used on systems without systemd and might be useful for Windows systems in the future. If you can, use the default systemd method, it is the preferred one.

In order for DRBD to use quorum as needed by this plugin, make sure the resource file of the DRBD resource contains the following option (this is the default for LINSTOR, but your resources needs to qualify for quorum).

```
options {
   auto-promote no;
   quorum majority;
   on-suspended-primary-outdated force-secondary;
   on-no-quorum io-error; # for the default drbd-reactor on-quorum-loss policy (i.e., Shutdown)
   # on-no-quorum suspend-io; # for freezing resources
   on-no-data-accessible io-error # always set this to the value of on-no-quorum!
   # on-no-data-accessible suspend-io # for freezing, always set this to the value of on-no-quorum!
}
# net { rr-conflict retry-connect; } # for freezing resources
```

drbd-reactor itself is pretty relaxed about these settings, don't expect too much hand holding or even auto-configuration, you as the admin are the one that should understand your system, but it checks properties and writes warnings to the log (file/journal) if misconfiguration is detected.

## SERVICE DEPENDENCIES
Let's get back to our simple example:

```
[[promoter]]
[promoter.resources.foo]
start = [ "a.service", "b.service", "c.service" ]
```

As we noted in previously we generate a dependency chain for these services (i.e., all depend on drbd-promote@ as well as on the previous services). The strictness of these dependencies can be set via dependencies-as , where the default is Requires systemd.unit(5)

We also generate the mentioned drbd-services@.target , which lists all the services from start. The dependencies for that are generated via the value set in target-as.

Especially when one debugs services it might make sense to lower these defaults to for example Wants. Otherwise a failed service might prohibit a successful start of the drbd-services@.target , which then triggers a stop of the target and its dependencies, which might again trigger a start because the resource is DRBD promotable again and so on.

It is really up to you and how strict/hard you want your dependencies and what their outcome should be. Requires should be a good default, you might lower or increase the strictness depending on the scenario.

## OCF RESOURCE AGENTS
It is possible to use resource agents in the start list of services via ocf:$vendor:$agent instance-id name=value ... The instance-id is user defined and gets postfixed with _$resourcename. For example the generated systemd unit for an instance-id of “p_iscsi_demo1” for a DRBD resource “foo” would be ocf.rs@p_iscsi_demo1_foo. name / value pairs are passed to the unit as environment variables prefixed with OCF_RESKEY_. In a concrete example using the “heartbeat:IPaddr2” agent this could look like this:

```
start = [
  "foo.service",
  "ocf:heartbeat:IPaddr2 p_iscsi_demo1_ip ip=10.43.7.223 cidr_netmask=16",
  "bar.service"
]
```

## FREEZING RESOURCES
The default behavior when a DRBD Primary loses quorum is to immediately stop the generated target unit and hope that other nodes still having quorum will successfully start the service. This works well if services can be failed over/started on another node in reasonable time. Unfortunately there are services that take a very long time to start, for example huge data bases.

When a DRBD Primary loses its quorum we basically have two possibilities:

- the rest of the nodes, or at least parts of it still have quorum: Then these have to start the service, they are the only ones with quorum, but still we could keep the old Primary in a frozen state. And then, when the nodes with quorum come into contact with the old Primary, then it should stop the service and its storage should become in sync with the other nodes.

- the rest of the nodes are not able to form a partition with quorum. In such a scenario there are no alternatives anyways, we would need to keep the Primary frozen. But if the nodes eventually join the old Primary again, and quorum would be restored, we could just unfreeze/thaw the old Primary (which is also the new Primary).

There are several requirements for this to work properly:

- A system with unified cgroups. If the file /sys/fs/cgroup/cgroup.controllers exists you should be fine. That requires a relatively “new” kernel. Note that “even” RHEL8 for example needs the addition of systemd.unified_cgroup_hierarchy on the kernel command line.

- a service that can tolerate to be frozen

- DRBD option on-suspended-primary-outdated set to force-secondary

- DRBD option on-no-quorum set to suspend-io

- DRBD option on-no-data-accessible set to suspend-io

- DRBD net option rr-conflict set to retry-connect

If these requirements are fulfilled, then one can set the promoter option on-quorum-loss to freeze.

## PREFERRED NODES
While in a HA cluster that deserves the name every node needs to be able to run all services, some users like to add preferences for nodes. This can be done by setting a list of preferred-nodes. On resource startup a delay based on the node's position in the list is added. Node names need to match the output of uname -n. Nodes with a lower preference will sleep longer. By default, if a node joins on DRBD level, and that peer's disk becomes UpToDate, and the peer has a higher preference, then the active node stops the services locally. As it will then have a higher sleep penalty as the preferred node, the preferred one will take over the service (if it can). If preferred-nodes-policy is set to always the system behaves as described above. If it is set to start-only, then preferred nodes are only taken into account when a service can be startet, but it will not fall back to a more preferred node when the service is already running on a lower priority node and a higher priority nodes joins later.

## FILES
/usr/lib/ocf/resource.d/

Path used for for OCF agents.

## EXAMPLES
This configures a promoter for resource “foo”. If the resource might be promoted the “foo.mount” and “foo.service” units get started. On DRBD demote failures a systemd "reboot" is triggered.

```
[promoter.resources.foo]
start = ["foo.mount", "foo.service"]
on-drbd-demote-failure =  "reboot"
stop-services-on-exit = false
preferred-nodes = ["nodeA", "nodeB" ]
```

## SEE ALSO
For further design notes and handled failure scenarios see doc/promoter.md in the source code. An online version is available at promoter.md

## AUTHORS
The drbd-reactor(1) program was written by the following authors:

Roland Kammerer <rck@linbit.com>

Moritz Wanzenböck <moritz.wanzenboeck@linbit.com>


drbd-reactor.toml

title: drbd-reactor.toml(5)

summary: DRBD-REACTOR daemon configuration file

text:
# drbd-reactor.toml(5)

## NAME
drbd-reactor.toml — DRBD-REACTOR daemon configuration file

## DESCRIPTION
drbd-reactor.toml is the configuration file for the DRBD-REACTOR daemon, drbd-reactor(1). The file has to be valid toml file.

The configuration file consists of sections for global settings, logging, and the actual plugin configuration. While this is rarely used and should be used with caution, it is possible to have multiple instances of a plugin as well as multiple loggers. The program ships with a commented version of the configuration file, please refer to that for further details.

Note that plugin settings are shown here for demonstration purposes only, plugin configuration should be stored in /etc/drbd-reactor.d/

## EXAMPLES

```
snippets = "/etc/drbd-reactor.d"
# update statistics every 45 seconds
statistics-poll-interval = 45

[[log]]
level = "debug"

# Configure a promoter
[[promoter]]
[promoter.resources.foo]
start = ["foo.mount", "foo.service"]
on-drbd-demote-failure = "reboot"

# Configure a user mode helper filter
[[umh]]
[[umh.resource]]
command = "drbd-reactor-role-change.sh"
event-type = "Change"
old.role = { operator = "NotEquals", value = "Primary" }
new.role = "Primary"

# Configure a prometheus exporter
[[prometheus]]
enums = true

# Configure an agentx subagent
[[agentx]]
peer-states = false
```

## AUTHORS
The drbd-reactor(1) program was written by the following authors:

Roland Kammerer <rck@linbit.com>

Moritz Wanzenböck <moritz.wanzenboeck@linbit.com>

## CAVEATS
Please note that the path specified in snippets gets path-joined with “*.toml” and the result is then subject to glob expansion.