dnf-transaction-json

package: dnf

title: dnf-transaction-json(5)

summary: DNF Stored Transaction JSON

text:
# dnf-transaction-json(5)

## NAME
dnf-transaction-json - DNF Stored Transaction JSON

The stored transaction format is considered unstable and may change in an incompatible way at any time. It will work if the same version of dnf is used to store and replay (or between versions as long as it stays the same).

## TOP-LEVEL OBJECT
version

Type: string The version of the stored transaction format, in the form MAJOR.MINOR.

MAJOR version denotes backwards incompatible changes (old dnf won't work with new transaction JSON).

MINOR version denotes extending the format without breaking backwards compatibility (old dnf can work with new transaction JSON).

rpms

Type: an array of rpm objects A list of RPM packages in the transaction.

groups

Type: an array of group objects A list of groups in the transaction.

environments

Type: an array of group objects A list of environment groups in the transaction.

## RPM OBJECT
action

Type: string Possible values: Downgrade, Downgraded, Install, Obsoleted, Reason Change, Reinstall, Reinstalled, Removed, Upgrade, Upgraded

The action performed on the package in the transaction.

nevra

Type: string NEVRA (name-epoch:version-release.arch) of the package.

reason

Type: string Possible values: dependency, clean, group, unknown, user, weak-dependency

The reason why the package was pulled into the transaction.

repo_id

Type: string The id of the repository this package is coming from. Note repository ids are defined in the local repository configuration and may differ between systems.

## GROUP OBJECT
action

Type: string Possible values: Install, Upgrade, Removed

The action performed on the group in the transaction.

id

Type: string The id of the group.

package_types

Type: string Possible values: conditional, default, mandatory, optional

The types of packages in the group that will be installed. Valid only for the Install action.

packages

Type: an array of group-package objects The packages belonging to the group in the transaction.

## ENVIRONMENT OBJECT
action

Type: string Possible values: Install, Upgrade, Removed

The action performed on the environment group in the transaction.

id

Type: string The id of the environment group.

package_types

Type: string Possible values: conditional, default, mandatory, optional

The types of packages in the environment group that will be installed. Valid only for the Install action.

group

Type: an array of environment-group objects The groups belonging to the environment in the transaction.

## GROUP-PACKAGE OBJECT
installed

Type: boolean Whether the package is considered installed as part of the group.

name

Type: string The name of the package.

package_type

Type: string Possible values: conditional, default, mandatory, optional

The type of the package in the group.

## ENVIRONMENT-GROUP OBJECT
group_type

Type: string Possible values: mandatory, optional

The type of the group in the environment.

id

Type: string The id of the group.

installed

Type: boolean Whether the group is considered installed as part of the environment.

## AUTHOR
See AUTHORS in DNF source distribution.

## COPYRIGHT
2012-2024, Red Hat, Licensed under GPLv2+


dnf.conf

title: dnf.conf(5)

summary: DNF Configuration Reference

text:
# dnf.conf(5)

## NAME
dnf.conf - DNF Configuration Reference

## DESCRIPTION
DNF by default uses the global configuration file at /etc/dnf/dnf.conf and all *.repo files found under /etc/yum.repos.d. The latter is typically used for repository configuration and takes precedence over global configuration.

The configuration file has INI format consisting of section declaration and name=value options below each on separate line. There are two types of sections in the configuration files: main and repository. Main section defines all global configuration options and should be only one.

The repository sections define the configuration for each (remote or local) repository. The section name of the repository in brackets serve as repo ID reference and should be unique across configuration files. The allowed characters of repo ID string are lower and upper case alphabetic letters, digits, -, _, . and :. The minimal repository configuration file should aside from repo ID consists of baseurl, metalink or mirrorlist option definition.

## DISTRIBUTION-SPECIFIC CONFIGURATION
Configuration options, namely best and skip_if_unavailable, can be set in the DNF configuration file by your distribution to override the DNF defaults.

## [MAIN] OPTIONS
allow_vendor_change

boolean If disabled dnf will stick to vendor when upgrading or downgrading rpms. Default is True

WARNING:

This option is currently not supported for downgrade and distro-sync commands

arch

string The architecture used for installing packages. By default this is auto-detected. Often used together with ignorearch option.

assumeno

boolean If enabled dnf will assume No where it would normally prompt for confirmation from user input. Default is False.

assumeyes

boolean If enabled dnf will assume Yes where it would normally prompt for confirmation from user input (see also defaultyes). Default is False.

autocheck_running_kernel

boolean Automatic check whether there is installed newer kernel module with security update than currently running kernel. Default is True.

basearch

string The base architecture used for installing packages. By default this is auto-detected.

best

boolean True instructs the solver to either use a package with the highest available version or fail. On False, do not fail if the latest version cannot be installed and go with the lower version. The default is False. Note this option in particular can be set in your configuration file by your distribution. Also note that the use of the highest available version is only guaranteed for the packages directly requested and not for their dependencies.

cachedir

string Path to a directory used by various DNF subsystems for storing cache data. Has a reasonable root-writable default depending on the distribution. DNF needs to be able to create files and directories at this location.

cacheonly

boolean If set to True DNF will run entirely from system cache, will not update the cache and will use it even in case it is expired. Default is False.

API Notes: Must be set before repository objects are created. Plugins must set this in the pre_config hook. Later changes are ignored.

check_config_file_age

boolean Specifies whether dnf should automatically expire metadata of repos, which are older than their corresponding configuration file (usually the dnf.conf file and the foo.repo file). Default is True (perform the check). Expire of metadata is also affected by metadata age. See also metadata_expire.

clean_requirements_on_remove

boolean Remove dependencies that are no longer used during dnf remove. A package only qualifies for removal via clean_requirements_on_remove if it was installed through DNF but not on explicit user request, i.e. it was pulled in as a dependency. The default is True. (installonlypkgs are never automatically removed.)

config_file_path

string Path to the default main configuration file. Default is /etc/dnf/dnf.conf.

debuglevel

integer Debug messages output level, in the range 0 to 10. The higher the number the more debug output is put to stdout. Default is 2.

debug_solver

boolean Controls whether the libsolv debug files should be created when solving the transaction. The debug files are created in the ./debugdata directory. Default is False.

defaultyes

boolean If enabled the default answer to user confirmation prompts will be Yes. Not to be confused with assumeyes which will not prompt at all. Default is False.

diskspacecheck

boolean Controls whether rpm should check available disk space during the transaction. Default is True.

errorlevel

integer Error messages output level, in the range 0 to 10. The higher the number the more error output is put to stderr. Default is 3. This is deprecated in DNF and overwritten by --verbose commandline option.

exclude_from_weak

list Prevent installing packages as weak dependencies (recommends or supplements). The packages can be specified by a name or a glob and separated by a comma. Defaults to [].

exclude_from_weak_autodetect

boolean If enabled, dnf will autodetect unmet weak dependencies (recommends or supplements) of packages installed on the system. Providers of these weak dependencies will not be installed by dnf as weak dependencies any more (they will still be installed if pulled in as a regular dependency). Defaults to true.

exit_on_lock

boolean Should the dnf client exit immediately when something else has the lock. Default is False.

gpgkey_dns_verification

boolean Should the dnf attempt to automatically verify GPG verification keys using the DNS system. This option requires the unbound python module (python3-unbound) to be installed on the client system. This system has two main features. The first one is to check if any of the already installed keys have been revoked. Automatic removal of the key is not yet available, so it is up to the user, to remove revoked keys from the system. The second feature is automatic verification of new keys when a repository is added to the system. In interactive mode, the result is written to the output as a suggestion to the user. In non-interactive mode (i.e. when -y is used), this system will automatically accept keys that are available in the DNS and are correctly signed using DNSSEC. It will also accept keys that do not exist in the DNS system and their NON-existence is cryptographically proven using DNSSEC. This is mainly to preserve backward compatibility. Default is False.

group_package_types

list List of the following: optional, default, mandatory. Tells dnf which type of packages in groups will be installed when 'groupinstall' is called. Default is: default, mandatory.

ignorearch

boolean If set to True, RPM will allow attempts to install packages incompatible with the CPU's architecture. Defaults to False. Often used together with arch option.

installonlypkgs

list List of provide names of packages that should only ever be installed, never upgraded. Kernels in particular fall into this category. These packages are never removed by dnf autoremove even if they were installed as dependencies (see clean_requirements_on_remove for auto removal details). This option append the list values to the default installonlypkgs list used by DNF. The number of kept package versions is regulated by installonly_limit.

installonly_limit

integer Number of installonly packages allowed to be installed concurrently. Defaults to 3. The minimal number of installonly packages is 2. Value 0 means unlimited number of installonly packages. Value 1 is explicitly not allowed since it complicates kernel upgrades due to protection of the running kernel from removal.

installroot

string The root of the filesystem for all packaging operations. It requires an absolute path. See also --installroot commandline option.

install_weak_deps

boolean When this option is set to True and a new package is about to be installed, all packages linked by weak dependency relation (Recommends or Supplements flags) with this package will be pulled into the transaction. Default is True.

keepcache

boolean Keeps downloaded packages in the cache when set to True. Even if it is set to False and packages have not been installed they will still persist until next successful transaction. The default is False.

logdir

string Directory where the log files will be stored. Default is /var/log.

logfilelevel

integer Log file messages output level, in the range 0 to 10. The higher the number the more debug output is put to logs. Default is 9.

This option controls dnf.log, dnf.librepo.log and hawkey.log. Although dnf.librepo.log and hawkey.log are affected only by setting the logfilelevel to 10.

log_compress

boolean When set to True, log files are compressed when they are rotated. Default is False.

log_rotate

integer Log files are rotated log_rotate times before being removed. If log_rotate is 0, the rotation is not performed. Default is 4.

log_size

storage size Log files are rotated when they grow bigger than log_size bytes. If log_size is 0, the rotation is not performed. The default is 1 MB. Valid units are 'k', 'M', 'G'.

The size applies for individual log files, not the sum of all log files. See also log_rotate.

metadata_timer_sync

time in seconds The minimal period between two consecutive makecache timer runs. The command will stop immediately if it's less than this time period since its last run. Does not affect simple makecache run. Use 0 to completely disable automatic metadata synchronizing. The default corresponds to three hours. The value is rounded to the next commenced hour.

module_obsoletes

boolean This option controls whether dnf should apply modular obsoletes when possible. Default is False.

module_platform_id

string Set this to $name:$stream to override PLATFORM_ID detected from /etc/os-release. It is necessary to perform a system upgrade and switch to a new platform.

module_stream_switch

boolean This option controls whether it's possible to switch enabled streams of a module. Default is False.

multilib_policy

string Controls how multilib packages are treated during install operations. Can either be "best" (the default) for the depsolver to prefer packages which best match the system's architecture, or "all" to install packages for all available architectures.

obsoletes

boolean This option only has affect during an install/update. It enables dnf's obsoletes processing logic, which means it makes dnf check whether any dependencies of given package are no longer required and removes them. Useful when doing distribution level upgrades. Default is 'true'.

Command-line option: --obsoletes

persistdir

string Directory where DNF stores its persistent data between runs. Default is "/var/lib/dnf".

pluginconfpath

list List of directories that are searched for plugin configurations to load. All configuration files found in these directories, that are named same as a plugin, are parsed. The default path is /etc/dnf/plugins.

pluginpath

list List of directories that are searched for plugins to load. Plugins found in any of the directories in this configuration option are used. The default contains a Python version-specific path.

plugins

boolean Controls whether the plugins are enabled. Default is True.

protected_packages

list List of packages that DNF should never completely remove. They are protected via Obsoletes as well as user/plugin removals.

The default is: dnf, glob:/etc/yum/protected.d/*.conf and glob:/etc/dnf/protected.d/*.conf. So any packages which should be protected can do so by including a file in /etc/dnf/protected.d with their package name in it.

DNF will protect also the package corresponding to the running version of the kernel. See also protect_running_kernel option.

protect_running_kernel

boolean Controls whether the package corresponding to the running version of kernel is protected from removal. Default is True.

releasever

string Used for substitution of $releasever in the repository configuration. See also repo variables.

reposdir

list DNF searches for repository configuration files in the paths specified by reposdir. The behavior of reposdir could differ when it is used along with --installroot option.

rpmverbosity

string RPM debug scriptlet output level. One of: critical, emergency, error, warn, info or debug. Default is info.

strict

boolean If disabled, all unavailable packages or packages with broken dependencies given to DNF command will be skipped without raising the error causing the whole operation to fail. Currently works for install command only. The default is True.

tsflags

list List of strings adding extra flags for the RPM transaction.

tsflag value

RPM Transaction Flag

noscripts

RPMTRANS_FLAG_NOSCRIPTS

test

RPMTRANS_FLAG_TEST

notriggers

RPMTRANS_FLAG_NOTRIGGERS

nodocs

RPMTRANS_FLAG_NODOCS

justdb

RPMTRANS_FLAG_JUSTDB

nocontexts

RPMTRANS_FLAG_NOCONTEXTS

nocaps

RPMTRANS_FLAG_NOCAPS

nocrypto

RPMTRANS_FLAG_NOFILEDIGEST

The nocrypto option will also set the _RPMVSF_NOSIGNATURES and _RPMVSF_NODIGESTS VS flags. The test option provides a transaction check without performing the transaction. It includes downloading of packages, gpg keys check (including permanent import of additional keys if necessary), and rpm check to prevent file conflicts. The nocaps is supported with rpm-4.14 or later. When nocaps is used but rpm doesn't support it, DNF only reports it as an invalid tsflag.

upgrade_group_objects_upgrade

boolean Set this to False to disable the automatic running of group upgrade when running the upgrade command. Default is True (perform the operation).

varsdir

list List of directories where variables definition files are looked for. Defaults to "/etc/dnf/vars", "/etc/yum/vars". See variable files in Configuration reference.

zchunk

boolean Enables or disables the use of repository metadata compressed using the zchunk format (if available). Default is True.

## [MAIN] OPTIONS - COLORS
color

string Controls if DNF uses colored output on the command line. Possible values: "auto", "never", "always". Default is "auto".

color_list_available_downgrade

color Color of available packages that are older than installed packages. The option is used during list operations. Default is magenta.

color_list_available_install

color Color of packages that are available for installation and none of their versions in installed. The option is used during list operations. Default is bold,cyan.

color_list_available_reinstall

color Color of available packages that are identical to installed versions and are available for reinstalls. Default is bold,underline,green. The option is used during list operations.

color_list_available_upgrade

color Color of available packages that are newer than installed packages. Default is bold,blue. The option is used during list operations.

color_list_installed_extra

color Color of installed packages that do not have any version among available packages. The option is used during list operations. Default is bold,red.

color_list_installed_newer

color Color of installed packages that are newer than any version among available packages. The option is used during list operations. Default is bold,yellow.

color_list_installed_older

color Color of installed packages that are older than any version among available packages. The option is used during list operations. Default is yellow.

color_list_installed_reinstall

color Color of installed packages that are among available packages and can be reinstalled. The option is used during list operations. Default is cyan.

color_search_match

color Color of patterns matched in search output. Default is bold,magenta.

color_update_installed

color Color of removed packages. Default is red. This option is used during displaying transactions.

color_update_local

color Color of local packages that are installed from the @commandline repository. This option is used during displaying transactions. Default is green.

color_update_remote

color Color of packages that are installed/upgraded/downgraded from remote repositories. This option is used during displaying transactions. Default is bold,green.

## REPO OPTIONS
baseurl

list List of URLs for the repository. Defaults to [].

URLs are tried in the listed order (equivalent to yum's "failovermethod=priority" behaviour).

cost

integer The relative cost of accessing this repository, defaulting to 1000. This value is compared when the priorities of two repositories are the same. The repository with the lowest cost is picked. It is useful to make the library prefer on-disk repositories to remote ones.

enabled

boolean Include this repository as a package source. The default is True.

gpgkey

list of strings URLs of a GPG key files that can be used for signing metadata and packages of this repository, empty by default. If a file can not be verified using the already imported keys, import of keys from this option is attempted and the keys are then used for verification.

metalink

string URL of a metalink for the repository. Defaults to None.

mirrorlist

string URL of a mirrorlist for the repository. Defaults to None.

module_hotfixes

boolean Set this to True to disable module RPM filtering and make all RPMs from the repository available. The default is False. This allows user to create a repository with cherry-picked hotfixes that are included in a package set on a modular system.

name

string A human-readable name of the repository. Defaults to the ID of the repository.

priority

integer The priority value of this repository, default is 99. If there is more than one candidate package for a particular operation, the one from a repo with the lowest priority value is picked, possibly despite being less convenient otherwise (e.g. by being a lower version).

type

string Type of repository metadata. Supported values are: rpm-md. Aliases for rpm-md: rpm, repomd, rpmmd, yum, YUM.

## REPO VARIABLES
Right side of every repo option can be enriched by the following variables:

$arch

Refers to the system’s CPU architecture e.g, aarch64, i586, i686 and x86_64.

$basearch

Refers to the base architecture of the system. For example, i686 and i586 machines both have a base architecture of i386, and AMD64 and Intel64 machines have a base architecture of x86_64.

$releasever

Refers to the release version of operating system which DNF derives from information available in RPMDB.

In addition to these hard coded variables, user-defined ones can also be used. They can be defined either via variable files, or by using special environmental variables. The names of these variables must be prefixed with DNF_VAR_ and they can only consist of alphanumeric characters and underscores:

```
$ DNF_VAR_MY_VARIABLE=value
```

To use such variable in your repository configuration remove the prefix. E.g.:

```
[myrepo]
baseurl=https://example.site/pub/fedora/$MY_VARIABLE/releases/$releasever
```

Note that it is not possible to override the arch and basearch variables using either variable files or environmental variables.

Although users are encouraged to use named variables, the numbered environmental variables DNF0 - DNF9 are still supported:

```
$ DNF1=value
[myrepo]
baseurl=https://example.site/pub/fedora/$DNF1/releases/$releasever
```

## OPTIONS FOR BOTH [MAIN] AND REPO
Some options can be applied in either the main section, per repository, or in a combination. The value provided in the main section is used for all repositories as the default value, which repositories can then override in their configuration.

bandwidth

storage size Total bandwidth available for downloading. Meaningful when used with the throttle option. Storage size is in bytes by default but can be specified with a unit of storage. Valid units are 'k', 'M', 'G'.

countme

boolean Determines whether a special flag should be added to a single, randomly chosen metalink/mirrorlist query each week. This allows the repository owner to estimate the number of systems consuming it, by counting such queries over a week's time, which is much more accurate than just counting unique IP addresses (which is subject to both overcounting and undercounting due to short DHCP leases and NAT, respectively).

The flag is a simple "countme=N" parameter appended to the metalink and mirrorlist URL, where N is an integer representing the "longevity" bucket this system belongs to. The following 4 buckets are defined, based on how many full weeks have passed since the beginning of the week when this system was installed: 1 = first week, 2 = first month (2-4 weeks), 3 = six months (5-24 weeks) and 4 = more than six months (> 24 weeks). This information is meant to help distinguish short-lived installs from long-term ones, and to gather other statistics about system lifecycle.

Default is False.

deltarpm

boolean When enabled, DNF will save bandwidth by downloading much smaller delta RPM files, rebuilding them to RPM locally. However, this is quite CPU and I/O intensive. Default is True.

deltarpm_percentage

integer When the relative size of delta vs pkg is larger than this, delta is not used. Default value is 75 (Deltas must be at least 25% smaller than the pkg). Use 0 to turn off delta rpm processing. Local repositories (with file:// baseurl) have delta rpms turned off by default.

enablegroups

boolean Determines whether DNF will allow the use of package groups for this repository. Default is True (package groups are allowed).

excludepkgs

list Exclude packages of this repository, specified by a name or a glob and separated by a comma, from all operations. Can be disabled using --disableexcludes command line switch. Defaults to [].

fastestmirror

boolean If enabled a metric is used to find the fastest available mirror. This overrides the order provided by the mirrorlist/metalink file itself. This file is often dynamically generated by the server to provide the best download speeds and enabling fastestmirror overrides this. The default is False.

gpgcheck

boolean Whether to perform GPG signature check on packages found in this repository. The default is False.

This option can only be used to strengthen the active RPM security policy set with the %_pkgverify_level macro (see the /usr/lib/rpm/macros file for details). That means, if the macro is set to 'signature' or 'all' and this option is False, it will be overridden to True during DNF runtime, and a warning will be printed. To squelch the warning, make sure this option is True for every enabled repository, and also enable localpkg_gpgcheck.

includepkgs

list Include packages of this repository, specified by a name or a glob and separated by a comma, in all operations. Inverse of excludepkgs, DNF will exclude any package in the repository that doesn't match this list. This works in conjunction with excludepkgs and doesn't override it, so if you 'excludepkgs=*.i386' and 'includepkgs=python*' then only packages starting with python that do not have an i386 arch will be seen by DNF in this repo. Can be disabled using --disableexcludes command line switch. Defaults to [].

ip_resolve

IP address type Determines how DNF resolves host names. Set this to '4'/'IPv4' or '6'/'IPv6' to resolve to IPv4 or IPv6 addresses only. By default, DNF resolves to either addresses.

localpkg_gpgcheck

boolean Whether to perform a GPG signature check on local packages (packages in a file, not in a repository). The default is False. This option is subject to the active RPM security policy (see gpgcheck for more details).

max_parallel_downloads

integer Maximum number of simultaneous package downloads. Defaults to 3. Maximum of 20.

metadata_expire

time in seconds The period after which the remote repository is checked for metadata update and in the positive case the local metadata cache is updated. The default corresponds to 48 hours. Set this to -1 or never to make the repo never considered expired. Expire of metadata can be also triggered by change of timestamp of configuration files (dnf.conf, <repo>.repo). See also check_config_file_age.

minrate

storage size This sets the low speed threshold in bytes per second. If the server is sending data at the same or slower speed than this value for at least timeout option seconds, DNF aborts the connection. The default is 1000. Valid units are 'k', 'M', 'G'.

password

string The password to use for connecting to a repository with basic HTTP authentication. Empty by default.

proxy

string URL of a proxy server to connect through. Set to an empty string in the repository configuration to disable proxy setting inherited from the main section. The expected format of this option is <scheme>://<ip-or-hostname>[:port]. (For backward compatibility, '_none_' can be used instead of the empty string.)

Note: The curl environment variables (such as http_proxy) are effective if this option is unset (or '_none_' is set in the repository configuration). See the curl man page for details.

proxy_username

string The username to use for connecting to the proxy server. Empty by default.

proxy_password

string The password to use for connecting to the proxy server. Empty by default.

proxy_auth_method

string The authentication method used by the proxy server. Valid values are

method

meaning

basic

HTTP Basic authentication

digest

HTTP Digest authentication

negotiate

HTTP Negotiate (SPNEGO) authentication

ntlm

HTTP NTLM authentication

digest_ie

HTTP Digest authentication with an IE flavor

ntlm_wb

NTLM delegating to winbind helper

none

None auth method

any

All suitable methods

Defaults to any

proxy_sslcacert

string Path to the file containing the certificate authorities to verify proxy SSL certificates. Empty by default - uses system default.

proxy_sslverify

boolean When enabled, proxy SSL certificates are verified. If the client can not be authenticated, connecting fails and the repository is not used any further. If False, SSL connections can be used, but certificates are not verified. Default is True.

proxy_sslclientcert

string Path to the SSL client certificate used to connect to proxy server. Empty by default.

proxy_sslclientkey

string Path to the SSL client key used to connect to proxy server. Empty by default.

repo_gpgcheck

boolean Whether to perform GPG signature check on this repository's metadata. The default is False.

retries

integer Set the number of total retries for downloading packages. The number is accumulative, so e.g. for retries=10, dnf will fail after any package download fails for eleventh time. Setting this to 0 makes dnf try forever. Default is 10.

skip_if_unavailable

boolean If enabled, DNF will continue running and disable the repository that couldn't be synchronized for any reason. This option doesn't affect skipping of unavailable packages after dependency resolution. To check inaccessibility of repository use it in combination with refresh command line option. The default is False. Note this option in particular can be set in your configuration file by your distribution.

sslcacert

string Path to the file containing the certificate authorities to verify SSL certificates. Empty by default - uses system default.

sslverify

boolean When enabled, remote SSL certificates are verified. If the client can not be authenticated, connecting fails and the repository is not used any further. If False, SSL connections can be used, but certificates are not verified. Default is True.

sslverifystatus

boolean When enabled, revocation status of the server certificate is verified using the "Certificate Status Request" TLS extension (aka. OCSP stapling). Default is False.

sslclientcert

string Path to the SSL client certificate used to connect to remote sites. Empty by default.

sslclientkey

string Path to the SSL client key used to connect to remote sites. Empty by default.

throttle

storage size Limits the downloading speed. It might be an absolute value or a percentage, relative to the value of the bandwidth option option. 0 means no throttling (the default). The absolute value is in bytes by default but can be specified with a unit of storage. Valid units are 'k', 'M', 'G'.

timeout

time in seconds Number of seconds to wait for a connection before timing out. Used in combination with minrate option option. Defaults to 30 seconds.

username

string The username to use for connecting to repo with basic HTTP authentication. Empty by default.

user_agent

string The User-Agent string to include in HTTP requests sent by DNF. Defaults to

```
libdnf (NAME VERSION_ID; VARIANT_ID; OS.BASEARCH)
```

where NAME, VERSION_ID and VARIANT_ID are OS identifiers read from the os-release(5) file, and OS and BASEARCH are the canonical OS name and base architecture, respectively. Example:

```
libdnf (Fedora 31; server; Linux.x86_64)
```

## TYPES OF OPTIONS
boolean

This is a data type with only two possible values. One of following options can be used: 1, 0, True, False, yes, no

integer

It is a whole number that can be written without a fractional component.

list

It is an option that could represent one or more strings separated by space or comma characters.

string

It is a sequence of symbols or digits without any whitespace character.

color

A string describing color and modifiers separated with a comma, for example "red,bold".

- Colors: black, blue, cyan, green, magenta, red, white, yellow

- Modifiers: bold, blink, dim, normal, reverse, underline

## FILES
Cache Files

/var/cache/dnf

Main Configuration File

/etc/dnf/dnf.conf

Repository

/etc/yum.repos.d/

Variables

Any properly named file in /etc/dnf/vars is turned into a variable named after the filename (or overrides any of the above variables but those set from commandline). Filenames may contain only alphanumeric characters and underscores and be in lowercase. Variables are also read from /etc/yum/vars for YUM compatibility reasons.

## SEE ALSO
•

dnf(8), DNF Command Reference

## AUTHOR
See AUTHORS in DNF source distribution.

## COPYRIGHT
2012-2024, Red Hat, Licensed under GPLv2+


yum.conf

title: yum.conf(5)

text:
# yum.conf(5)

## NAME
yum.conf - redirecting to DNF Configuration Reference

## DESCRIPTION
DNF by default uses the global configuration file at /etc/dnf/dnf.conf and all *.repo files found under /etc/yum.repos.d. The latter is typically used for repository configuration and takes precedence over global configuration.

The configuration file has INI format consisting of section declaration and name=value options below each on separate line. There are two types of sections in the configuration files: main and repository. Main section defines all global configuration options and should be only one.

The repository sections define the configuration for each (remote or local) repository. The section name of the repository in brackets serve as repo ID reference and should be unique across configuration files. The allowed characters of repo ID string are lower and upper case alphabetic letters, digits, -, _, . and :. The minimal repository configuration file should aside from repo ID consists of baseurl, metalink or mirrorlist option definition.

## DISTRIBUTION-SPECIFIC CONFIGURATION
Configuration options, namely best and skip_if_unavailable, can be set in the DNF configuration file by your distribution to override the DNF defaults.

## [MAIN] OPTIONS
allow_vendor_change

boolean If disabled dnf will stick to vendor when upgrading or downgrading rpms. Default is True

WARNING:

This option is currently not supported for downgrade and distro-sync commands

arch

string The architecture used for installing packages. By default this is auto-detected. Often used together with ignorearch option.

assumeno

boolean If enabled dnf will assume No where it would normally prompt for confirmation from user input. Default is False.

assumeyes

boolean If enabled dnf will assume Yes where it would normally prompt for confirmation from user input (see also defaultyes). Default is False.

autocheck_running_kernel

boolean Automatic check whether there is installed newer kernel module with security update than currently running kernel. Default is True.

basearch

string The base architecture used for installing packages. By default this is auto-detected.

best

boolean True instructs the solver to either use a package with the highest available version or fail. On False, do not fail if the latest version cannot be installed and go with the lower version. The default is False. Note this option in particular can be set in your configuration file by your distribution. Also note that the use of the highest available version is only guaranteed for the packages directly requested and not for their dependencies.

cachedir

string Path to a directory used by various DNF subsystems for storing cache data. Has a reasonable root-writable default depending on the distribution. DNF needs to be able to create files and directories at this location.

cacheonly

boolean If set to True DNF will run entirely from system cache, will not update the cache and will use it even in case it is expired. Default is False.

API Notes: Must be set before repository objects are created. Plugins must set this in the pre_config hook. Later changes are ignored.

check_config_file_age

boolean Specifies whether dnf should automatically expire metadata of repos, which are older than their corresponding configuration file (usually the dnf.conf file and the foo.repo file). Default is True (perform the check). Expire of metadata is also affected by metadata age. See also metadata_expire.

clean_requirements_on_remove

boolean Remove dependencies that are no longer used during dnf remove. A package only qualifies for removal via clean_requirements_on_remove if it was installed through DNF but not on explicit user request, i.e. it was pulled in as a dependency. The default is True. (installonlypkgs are never automatically removed.)

config_file_path

string Path to the default main configuration file. Default is /etc/dnf/dnf.conf.

debuglevel

integer Debug messages output level, in the range 0 to 10. The higher the number the more debug output is put to stdout. Default is 2.

debug_solver

boolean Controls whether the libsolv debug files should be created when solving the transaction. The debug files are created in the ./debugdata directory. Default is False.

defaultyes

boolean If enabled the default answer to user confirmation prompts will be Yes. Not to be confused with assumeyes which will not prompt at all. Default is False.

diskspacecheck

boolean Controls whether rpm should check available disk space during the transaction. Default is True.

errorlevel

integer Error messages output level, in the range 0 to 10. The higher the number the more error output is put to stderr. Default is 3. This is deprecated in DNF and overwritten by --verbose commandline option.

exclude_from_weak

list Prevent installing packages as weak dependencies (recommends or supplements). The packages can be specified by a name or a glob and separated by a comma. Defaults to [].

exclude_from_weak_autodetect

boolean If enabled, dnf will autodetect unmet weak dependencies (recommends or supplements) of packages installed on the system. Providers of these weak dependencies will not be installed by dnf as weak dependencies any more (they will still be installed if pulled in as a regular dependency). Defaults to true.

exit_on_lock

boolean Should the dnf client exit immediately when something else has the lock. Default is False.

gpgkey_dns_verification

boolean Should the dnf attempt to automatically verify GPG verification keys using the DNS system. This option requires the unbound python module (python3-unbound) to be installed on the client system. This system has two main features. The first one is to check if any of the already installed keys have been revoked. Automatic removal of the key is not yet available, so it is up to the user, to remove revoked keys from the system. The second feature is automatic verification of new keys when a repository is added to the system. In interactive mode, the result is written to the output as a suggestion to the user. In non-interactive mode (i.e. when -y is used), this system will automatically accept keys that are available in the DNS and are correctly signed using DNSSEC. It will also accept keys that do not exist in the DNS system and their NON-existence is cryptographically proven using DNSSEC. This is mainly to preserve backward compatibility. Default is False.

group_package_types

list List of the following: optional, default, mandatory. Tells dnf which type of packages in groups will be installed when 'groupinstall' is called. Default is: default, mandatory.

ignorearch

boolean If set to True, RPM will allow attempts to install packages incompatible with the CPU's architecture. Defaults to False. Often used together with arch option.

installonlypkgs

list List of provide names of packages that should only ever be installed, never upgraded. Kernels in particular fall into this category. These packages are never removed by dnf autoremove even if they were installed as dependencies (see clean_requirements_on_remove for auto removal details). This option append the list values to the default installonlypkgs list used by DNF. The number of kept package versions is regulated by installonly_limit.

installonly_limit

integer Number of installonly packages allowed to be installed concurrently. Defaults to 3. The minimal number of installonly packages is 2. Value 0 means unlimited number of installonly packages. Value 1 is explicitly not allowed since it complicates kernel upgrades due to protection of the running kernel from removal.

installroot

string The root of the filesystem for all packaging operations. It requires an absolute path. See also --installroot commandline option.

install_weak_deps

boolean When this option is set to True and a new package is about to be installed, all packages linked by weak dependency relation (Recommends or Supplements flags) with this package will be pulled into the transaction. Default is True.

keepcache

boolean Keeps downloaded packages in the cache when set to True. Even if it is set to False and packages have not been installed they will still persist until next successful transaction. The default is False.

logdir

string Directory where the log files will be stored. Default is /var/log.

logfilelevel

integer Log file messages output level, in the range 0 to 10. The higher the number the more debug output is put to logs. Default is 9.

This option controls dnf.log, dnf.librepo.log and hawkey.log. Although dnf.librepo.log and hawkey.log are affected only by setting the logfilelevel to 10.

log_compress

boolean When set to True, log files are compressed when they are rotated. Default is False.

log_rotate

integer Log files are rotated log_rotate times before being removed. If log_rotate is 0, the rotation is not performed. Default is 4.

log_size

storage size Log files are rotated when they grow bigger than log_size bytes. If log_size is 0, the rotation is not performed. The default is 1 MB. Valid units are 'k', 'M', 'G'.

The size applies for individual log files, not the sum of all log files. See also log_rotate.

metadata_timer_sync

time in seconds The minimal period between two consecutive makecache timer runs. The command will stop immediately if it's less than this time period since its last run. Does not affect simple makecache run. Use 0 to completely disable automatic metadata synchronizing. The default corresponds to three hours. The value is rounded to the next commenced hour.

module_obsoletes

boolean This option controls whether dnf should apply modular obsoletes when possible. Default is False.

module_platform_id

string Set this to $name:$stream to override PLATFORM_ID detected from /etc/os-release. It is necessary to perform a system upgrade and switch to a new platform.

module_stream_switch

boolean This option controls whether it's possible to switch enabled streams of a module. Default is False.

multilib_policy

string Controls how multilib packages are treated during install operations. Can either be "best" (the default) for the depsolver to prefer packages which best match the system's architecture, or "all" to install packages for all available architectures.

obsoletes

boolean This option only has affect during an install/update. It enables dnf's obsoletes processing logic, which means it makes dnf check whether any dependencies of given package are no longer required and removes them. Useful when doing distribution level upgrades. Default is 'true'.

Command-line option: --obsoletes

persistdir

string Directory where DNF stores its persistent data between runs. Default is "/var/lib/dnf".

pluginconfpath

list List of directories that are searched for plugin configurations to load. All configuration files found in these directories, that are named same as a plugin, are parsed. The default path is /etc/dnf/plugins.

pluginpath

list List of directories that are searched for plugins to load. Plugins found in any of the directories in this configuration option are used. The default contains a Python version-specific path.

plugins

boolean Controls whether the plugins are enabled. Default is True.

protected_packages

list List of packages that DNF should never completely remove. They are protected via Obsoletes as well as user/plugin removals.

The default is: dnf, glob:/etc/yum/protected.d/*.conf and glob:/etc/dnf/protected.d/*.conf. So any packages which should be protected can do so by including a file in /etc/dnf/protected.d with their package name in it.

DNF will protect also the package corresponding to the running version of the kernel. See also protect_running_kernel option.

protect_running_kernel

boolean Controls whether the package corresponding to the running version of kernel is protected from removal. Default is True.

releasever

string Used for substitution of $releasever in the repository configuration. See also repo variables.

reposdir

list DNF searches for repository configuration files in the paths specified by reposdir. The behavior of reposdir could differ when it is used along with --installroot option.

rpmverbosity

string RPM debug scriptlet output level. One of: critical, emergency, error, warn, info or debug. Default is info.

strict

boolean If disabled, all unavailable packages or packages with broken dependencies given to DNF command will be skipped without raising the error causing the whole operation to fail. Currently works for install command only. The default is True.

tsflags

list List of strings adding extra flags for the RPM transaction.

tsflag value

RPM Transaction Flag

noscripts

RPMTRANS_FLAG_NOSCRIPTS

test

RPMTRANS_FLAG_TEST

notriggers

RPMTRANS_FLAG_NOTRIGGERS

nodocs

RPMTRANS_FLAG_NODOCS

justdb

RPMTRANS_FLAG_JUSTDB

nocontexts

RPMTRANS_FLAG_NOCONTEXTS

nocaps

RPMTRANS_FLAG_NOCAPS

nocrypto

RPMTRANS_FLAG_NOFILEDIGEST

The nocrypto option will also set the _RPMVSF_NOSIGNATURES and _RPMVSF_NODIGESTS VS flags. The test option provides a transaction check without performing the transaction. It includes downloading of packages, gpg keys check (including permanent import of additional keys if necessary), and rpm check to prevent file conflicts. The nocaps is supported with rpm-4.14 or later. When nocaps is used but rpm doesn't support it, DNF only reports it as an invalid tsflag.

upgrade_group_objects_upgrade

boolean Set this to False to disable the automatic running of group upgrade when running the upgrade command. Default is True (perform the operation).

varsdir

list List of directories where variables definition files are looked for. Defaults to "/etc/dnf/vars", "/etc/yum/vars". See variable files in Configuration reference.

zchunk

boolean Enables or disables the use of repository metadata compressed using the zchunk format (if available). Default is True.

## [MAIN] OPTIONS - COLORS
color

string Controls if DNF uses colored output on the command line. Possible values: "auto", "never", "always". Default is "auto".

color_list_available_downgrade

color Color of available packages that are older than installed packages. The option is used during list operations. Default is magenta.

color_list_available_install

color Color of packages that are available for installation and none of their versions in installed. The option is used during list operations. Default is bold,cyan.

color_list_available_reinstall

color Color of available packages that are identical to installed versions and are available for reinstalls. Default is bold,underline,green. The option is used during list operations.

color_list_available_upgrade

color Color of available packages that are newer than installed packages. Default is bold,blue. The option is used during list operations.

color_list_installed_extra

color Color of installed packages that do not have any version among available packages. The option is used during list operations. Default is bold,red.

color_list_installed_newer

color Color of installed packages that are newer than any version among available packages. The option is used during list operations. Default is bold,yellow.

color_list_installed_older

color Color of installed packages that are older than any version among available packages. The option is used during list operations. Default is yellow.

color_list_installed_reinstall

color Color of installed packages that are among available packages and can be reinstalled. The option is used during list operations. Default is cyan.

color_search_match

color Color of patterns matched in search output. Default is bold,magenta.

color_update_installed

color Color of removed packages. Default is red. This option is used during displaying transactions.

color_update_local

color Color of local packages that are installed from the @commandline repository. This option is used during displaying transactions. Default is green.

color_update_remote

color Color of packages that are installed/upgraded/downgraded from remote repositories. This option is used during displaying transactions. Default is bold,green.

## REPO OPTIONS
baseurl

list List of URLs for the repository. Defaults to [].

URLs are tried in the listed order (equivalent to yum's "failovermethod=priority" behaviour).

cost

integer The relative cost of accessing this repository, defaulting to 1000. This value is compared when the priorities of two repositories are the same. The repository with the lowest cost is picked. It is useful to make the library prefer on-disk repositories to remote ones.

enabled

boolean Include this repository as a package source. The default is True.

gpgkey

list of strings URLs of a GPG key files that can be used for signing metadata and packages of this repository, empty by default. If a file can not be verified using the already imported keys, import of keys from this option is attempted and the keys are then used for verification.

metalink

string URL of a metalink for the repository. Defaults to None.

mirrorlist

string URL of a mirrorlist for the repository. Defaults to None.

module_hotfixes

boolean Set this to True to disable module RPM filtering and make all RPMs from the repository available. The default is False. This allows user to create a repository with cherry-picked hotfixes that are included in a package set on a modular system.

name

string A human-readable name of the repository. Defaults to the ID of the repository.

priority

integer The priority value of this repository, default is 99. If there is more than one candidate package for a particular operation, the one from a repo with the lowest priority value is picked, possibly despite being less convenient otherwise (e.g. by being a lower version).

type

string Type of repository metadata. Supported values are: rpm-md. Aliases for rpm-md: rpm, repomd, rpmmd, yum, YUM.

## REPO VARIABLES
Right side of every repo option can be enriched by the following variables:

$arch

Refers to the system’s CPU architecture e.g, aarch64, i586, i686 and x86_64.

$basearch

Refers to the base architecture of the system. For example, i686 and i586 machines both have a base architecture of i386, and AMD64 and Intel64 machines have a base architecture of x86_64.

$releasever

Refers to the release version of operating system which DNF derives from information available in RPMDB.

In addition to these hard coded variables, user-defined ones can also be used. They can be defined either via variable files, or by using special environmental variables. The names of these variables must be prefixed with DNF_VAR_ and they can only consist of alphanumeric characters and underscores:

```
$ DNF_VAR_MY_VARIABLE=value
```

To use such variable in your repository configuration remove the prefix. E.g.:

```
[myrepo]
baseurl=https://example.site/pub/fedora/$MY_VARIABLE/releases/$releasever
```

Note that it is not possible to override the arch and basearch variables using either variable files or environmental variables.

Although users are encouraged to use named variables, the numbered environmental variables DNF0 - DNF9 are still supported:

```
$ DNF1=value
[myrepo]
baseurl=https://example.site/pub/fedora/$DNF1/releases/$releasever
```

## OPTIONS FOR BOTH [MAIN] AND REPO
Some options can be applied in either the main section, per repository, or in a combination. The value provided in the main section is used for all repositories as the default value, which repositories can then override in their configuration.

bandwidth

storage size Total bandwidth available for downloading. Meaningful when used with the throttle option. Storage size is in bytes by default but can be specified with a unit of storage. Valid units are 'k', 'M', 'G'.

countme

boolean Determines whether a special flag should be added to a single, randomly chosen metalink/mirrorlist query each week. This allows the repository owner to estimate the number of systems consuming it, by counting such queries over a week's time, which is much more accurate than just counting unique IP addresses (which is subject to both overcounting and undercounting due to short DHCP leases and NAT, respectively).

The flag is a simple "countme=N" parameter appended to the metalink and mirrorlist URL, where N is an integer representing the "longevity" bucket this system belongs to. The following 4 buckets are defined, based on how many full weeks have passed since the beginning of the week when this system was installed: 1 = first week, 2 = first month (2-4 weeks), 3 = six months (5-24 weeks) and 4 = more than six months (> 24 weeks). This information is meant to help distinguish short-lived installs from long-term ones, and to gather other statistics about system lifecycle.

Default is False.

deltarpm

boolean When enabled, DNF will save bandwidth by downloading much smaller delta RPM files, rebuilding them to RPM locally. However, this is quite CPU and I/O intensive. Default is True.

deltarpm_percentage

integer When the relative size of delta vs pkg is larger than this, delta is not used. Default value is 75 (Deltas must be at least 25% smaller than the pkg). Use 0 to turn off delta rpm processing. Local repositories (with file:// baseurl) have delta rpms turned off by default.

enablegroups

boolean Determines whether DNF will allow the use of package groups for this repository. Default is True (package groups are allowed).

excludepkgs

list Exclude packages of this repository, specified by a name or a glob and separated by a comma, from all operations. Can be disabled using --disableexcludes command line switch. Defaults to [].

fastestmirror

boolean If enabled a metric is used to find the fastest available mirror. This overrides the order provided by the mirrorlist/metalink file itself. This file is often dynamically generated by the server to provide the best download speeds and enabling fastestmirror overrides this. The default is False.

gpgcheck

boolean Whether to perform GPG signature check on packages found in this repository. The default is False.

This option can only be used to strengthen the active RPM security policy set with the %_pkgverify_level macro (see the /usr/lib/rpm/macros file for details). That means, if the macro is set to 'signature' or 'all' and this option is False, it will be overridden to True during DNF runtime, and a warning will be printed. To squelch the warning, make sure this option is True for every enabled repository, and also enable localpkg_gpgcheck.

includepkgs

list Include packages of this repository, specified by a name or a glob and separated by a comma, in all operations. Inverse of excludepkgs, DNF will exclude any package in the repository that doesn't match this list. This works in conjunction with excludepkgs and doesn't override it, so if you 'excludepkgs=*.i386' and 'includepkgs=python*' then only packages starting with python that do not have an i386 arch will be seen by DNF in this repo. Can be disabled using --disableexcludes command line switch. Defaults to [].

ip_resolve

IP address type Determines how DNF resolves host names. Set this to '4'/'IPv4' or '6'/'IPv6' to resolve to IPv4 or IPv6 addresses only. By default, DNF resolves to either addresses.

localpkg_gpgcheck

boolean Whether to perform a GPG signature check on local packages (packages in a file, not in a repository). The default is False. This option is subject to the active RPM security policy (see gpgcheck for more details).

max_parallel_downloads

integer Maximum number of simultaneous package downloads. Defaults to 3. Maximum of 20.

metadata_expire

time in seconds The period after which the remote repository is checked for metadata update and in the positive case the local metadata cache is updated. The default corresponds to 48 hours. Set this to -1 or never to make the repo never considered expired. Expire of metadata can be also triggered by change of timestamp of configuration files (dnf.conf, <repo>.repo). See also check_config_file_age.

minrate

storage size This sets the low speed threshold in bytes per second. If the server is sending data at the same or slower speed than this value for at least timeout option seconds, DNF aborts the connection. The default is 1000. Valid units are 'k', 'M', 'G'.

password

string The password to use for connecting to a repository with basic HTTP authentication. Empty by default.

proxy

string URL of a proxy server to connect through. Set to an empty string in the repository configuration to disable proxy setting inherited from the main section. The expected format of this option is <scheme>://<ip-or-hostname>[:port]. (For backward compatibility, '_none_' can be used instead of the empty string.)

Note: The curl environment variables (such as http_proxy) are effective if this option is unset (or '_none_' is set in the repository configuration). See the curl man page for details.

proxy_username

string The username to use for connecting to the proxy server. Empty by default.

proxy_password

string The password to use for connecting to the proxy server. Empty by default.

proxy_auth_method

string The authentication method used by the proxy server. Valid values are

method

meaning

basic

HTTP Basic authentication

digest

HTTP Digest authentication

negotiate

HTTP Negotiate (SPNEGO) authentication

ntlm

HTTP NTLM authentication

digest_ie

HTTP Digest authentication with an IE flavor

ntlm_wb

NTLM delegating to winbind helper

none

None auth method

any

All suitable methods

Defaults to any

proxy_sslcacert

string Path to the file containing the certificate authorities to verify proxy SSL certificates. Empty by default - uses system default.

proxy_sslverify

boolean When enabled, proxy SSL certificates are verified. If the client can not be authenticated, connecting fails and the repository is not used any further. If False, SSL connections can be used, but certificates are not verified. Default is True.

proxy_sslclientcert

string Path to the SSL client certificate used to connect to proxy server. Empty by default.

proxy_sslclientkey

string Path to the SSL client key used to connect to proxy server. Empty by default.

repo_gpgcheck

boolean Whether to perform GPG signature check on this repository's metadata. The default is False.

retries

integer Set the number of total retries for downloading packages. The number is accumulative, so e.g. for retries=10, dnf will fail after any package download fails for eleventh time. Setting this to 0 makes dnf try forever. Default is 10.

skip_if_unavailable

boolean If enabled, DNF will continue running and disable the repository that couldn't be synchronized for any reason. This option doesn't affect skipping of unavailable packages after dependency resolution. To check inaccessibility of repository use it in combination with refresh command line option. The default is False. Note this option in particular can be set in your configuration file by your distribution.

sslcacert

string Path to the file containing the certificate authorities to verify SSL certificates. Empty by default - uses system default.

sslverify

boolean When enabled, remote SSL certificates are verified. If the client can not be authenticated, connecting fails and the repository is not used any further. If False, SSL connections can be used, but certificates are not verified. Default is True.

sslverifystatus

boolean When enabled, revocation status of the server certificate is verified using the "Certificate Status Request" TLS extension (aka. OCSP stapling). Default is False.

sslclientcert

string Path to the SSL client certificate used to connect to remote sites. Empty by default.

sslclientkey

string Path to the SSL client key used to connect to remote sites. Empty by default.

throttle

storage size Limits the downloading speed. It might be an absolute value or a percentage, relative to the value of the bandwidth option option. 0 means no throttling (the default). The absolute value is in bytes by default but can be specified with a unit of storage. Valid units are 'k', 'M', 'G'.

timeout

time in seconds Number of seconds to wait for a connection before timing out. Used in combination with minrate option option. Defaults to 30 seconds.

username

string The username to use for connecting to repo with basic HTTP authentication. Empty by default.

user_agent

string The User-Agent string to include in HTTP requests sent by DNF. Defaults to

```
libdnf (NAME VERSION_ID; VARIANT_ID; OS.BASEARCH)
```

where NAME, VERSION_ID and VARIANT_ID are OS identifiers read from the os-release(5) file, and OS and BASEARCH are the canonical OS name and base architecture, respectively. Example:

```
libdnf (Fedora 31; server; Linux.x86_64)
```

## TYPES OF OPTIONS
boolean

This is a data type with only two possible values. One of following options can be used: 1, 0, True, False, yes, no

integer

It is a whole number that can be written without a fractional component.

list

It is an option that could represent one or more strings separated by space or comma characters.

string

It is a sequence of symbols or digits without any whitespace character.

color

A string describing color and modifiers separated with a comma, for example "red,bold".

- Colors: black, blue, cyan, green, magenta, red, white, yellow

- Modifiers: bold, blink, dim, normal, reverse, underline

## FILES
Cache Files

/var/cache/dnf

Main Configuration File

/etc/dnf/dnf.conf

Repository

/etc/yum.repos.d/

Variables

Any properly named file in /etc/dnf/vars is turned into a variable named after the filename (or overrides any of the above variables but those set from commandline). Filenames may contain only alphanumeric characters and underscores and be in lowercase. Variables are also read from /etc/yum/vars for YUM compatibility reasons.

## SEE ALSO
•

dnf(8), DNF Command Reference

## AUTHOR
See AUTHORS in DNF source distribution.

## COPYRIGHT
2012-2024, Red Hat, Licensed under GPLv2+


yum-versionlock.conf

package: dnf-plugins-core

title: yum-versionlock.conf(5)

summary: redirecting to DNF versionlock Plugin

text:
# yum-versionlock.conf(5)

## NAME
yum-versionlock.conf - redirecting to DNF versionlock Plugin

## DESCRIPTION
versionlock is a plugin that takes a set of names and versions for packages and excludes all other versions of those packages. This allows you to protect packages from being updated by newer versions. Alternately, it accepts a specific package version to exclude from updates, e.g. for when it's necessary to skip a specific release of a package that has known issues.

The plugin provides a command versionlock which allows you to view and edit the list of locked packages easily.

The plugin will walk each line of the versionlock file, and parse out the name and version of the package. It will then exclude any package by that name that doesn't match one of the versions listed within the file. This is basically the same as using dnf --exclude for the package name itself (as you cannot exclude installed packages), but dnf will still see the versions you have installed/versionlocked as available so that dnf reinstall will still work, etc.

It can also work in the opposite way, like a fast exclude, by prefixing a '!' character to the version recorded in the lock list file. This specifically excludes a package that matches the version exactly.

Note the versionlock plugin does not apply any excludes in non-transactional operations like repoquery, list, info, etc.

## SYNOPSIS
dnf versionlock [options] [add|exclude|list|delete|clear] [<package-name-spec>]

## ARGUMENTS
<package-name-spec>

Package spec to lock or exclude.

## SUBCOMMANDS
dnf versionlock add <package-name-spec>

Add a versionlock for all available packages matching the spec. It means that only versions of packages represented by <package-name-spec> will be available for transaction operations. Each <package-name-spec> is converted to concrete NEVRAs which are used for locking. The NEVRAs to lock to are first searched among installed packages and then (if none is found) in all currently available packages. Examples:

```
Locking a package to the version installed:

    $ dnf repoquery --installed bash

    bash-0:5.0.7-1.fc30.x86_64

    $ dnf repoquery bash

    bash-0:5.0.2-1.fc30.i686

    bash-0:5.0.2-1.fc30.x86_64

    bash-0:5.0.7-1.fc30.i686

    bash-0:5.0.7-1.fc30.x86_64

    $ dnf versionlock add bash

    Adding versionlock on: bash-0:5.0.7-1.fc30.*
Locking not installed package to any of available versions:

    $ dnf repoquery --installed mutt

    $ dnf repoquery mutt

    mutt-5:1.11.4-1.fc30.x86_64

    mutt-5:1.12.1-3.fc30.x86_64

    $ dnf versionlock add mutt

    Adding versionlock on: mutt-5:1.11.4-1.fc30.*

    Adding versionlock on: mutt-5:1.12.1-3.fc30.*
```

NOTE:

Be careful when adding specific versions If you add a package specifying a version with dnf versionlock mutt-5:1.11.4-1.fc30.x86_64 then, if you run dnf versionlock add mutt versionlock will not add mutt-5:1.12.1-3.fc30.x86_64.

dnf versionlock exclude <package-name-spec>

Add an exclude (within versionlock) for the available packages matching the spec. It means that packages represented by <package-name-spec> will be excluded from transaction operations.

dnf versionlock list or dnf versionlock

List the current versionlock entries.

dnf versionlock delete <package-name-spec>

Remove any matching versionlock entries.

dnf versionlock clear

Remove all versionlock entries.

## OPTIONS
All general DNF options are accepted, see Options in dnf(8) for details.

--raw

Do not resolve <package-name-spec> to NEVRAs to find specific version to lock to. Instead <package-name-spec> are used as they are. This enables locking to not yet available versions of the package. For example you may want to keep the bash package on major version 5 and consume any future updates as far as they keep the major version:

```
$ dnf versionlock add --raw 'bash-5.*'
Adding versionlock on: bash-5.*
```

## CONFIGURATION
/etc/dnf/plugins/versionlock.conf

The minimal content of conf file should contain main sections with enabled and locklist parameters.

locklist

This option is a string that points to the file which has the versionlock information in it. Note that the file has to exist (or the versionlock plugin will make dnf exit). However, it can be empty. The file takes entries in the format of <package-name-spec> (optionally prefixed with '!' for excludes). See Specifying packages in dnf(8) for details.

## NOTES
A specified package does not have to exist within the available cache of repository data to be considered valid for locking or exclusion. This is by design, to accommodate use cases such as a presently disabled repository. However, a package must exist in the repository cache when the add or exclude subcommands are invoked for it.

## AUTHOR
See AUTHORS in your Core DNF Plugins distribution

## COPYRIGHT
2022, Red Hat, Licensed under GPLv2+


Dockerfile

package: docker-cli

title: Dockerfile(5)

text:
# Dockerfile(5)

## NAME
Dockerfile - automate the steps of creating a Docker image

## INTRODUCTION
The Dockerfile is a configuration file that automates the steps of creating a Docker image. It is similar to a Makefile. Docker reads instructions from the Dockerfile to automate the steps otherwise performed manually to create an image. To build an image, create a file called Dockerfile.

The Dockerfile describes the steps taken to assemble the image. When the Dockerfile has been created, call the docker build command, using the path of directory that contains Dockerfile as the argument.

## SYNOPSIS
INSTRUCTION arguments

For example:

FROM image

## DESCRIPTION
A Dockerfile is a file that automates the steps of creating a Docker image. A Dockerfile is similar to a Makefile.

## USAGE
docker build .

-- Runs the steps and commits them, building a final image.

The path to the source repository defines where to find the context of the

build. The build is run by the Docker daemon, not the CLI. The whole

context must be transferred to the daemon. The Docker CLI reports

"Sending build context to Docker daemon" when the context is sent to the

daemon.

```
  docker build -t repository/tag .
```

-- specifies a repository and tag at which to save the new image if the build

succeeds. The Docker daemon runs the steps one-by-one, committing the result

to a new image if necessary, before finally outputting the ID of the new

image. The Docker daemon automatically cleans up the context it is given.

Docker reuses intermediate images whenever possible. This significantly

accelerates the docker build process.

## FORMAT
FROM image

FROM image:tag

FROM image@digest

-- The FROM instruction sets the base image for subsequent instructions. A

valid Dockerfile must have FROM as its first instruction. The image can be any

valid image. It is easy to start by pulling an image from the public

repositories.

-- FROM must be the first non-comment instruction in Dockerfile.

-- FROM may appear multiple times within a single Dockerfile in order to create

multiple images. Make a note of the last image ID output by the commit before

each new FROM command.

-- If no tag is given to the FROM instruction, Docker applies the

latest tag. If the used tag does not exist, an error is returned.

-- If no digest is given to the FROM instruction, Docker applies the

latest tag. If the used tag does not exist, an error is returned.

MAINTAINER

-- MAINTAINER sets the Author field for the generated images.

Useful for providing users with an email or url for support.

RUN

-- RUN has two forms:

```
  # the command is run in a shell - /bin/sh -c

  RUN <command>

  # Executable form

  RUN ["executable", "param1", "param2"]
```

-- The RUN instruction executes any commands in a new layer on top of the current

image and commits the results. The committed image is used for the next step in

Dockerfile.

-- Layering RUN instructions and generating commits conforms to the core

concepts of Docker where commits are cheap and containers can be created from

any point in the history of an image. This is similar to source control. The

exec form makes it possible to avoid shell string munging. The exec form makes

it possible to RUN commands using a base image that does not contain /bin/sh.

Note that the exec form is parsed as a JSON array, which means that you must

use double-quotes (") around words not single-quotes (').

CMD

-- CMD has three forms:

```
  # Executable form

  CMD ["executable", "param1", "param2"]`

  # Provide default arguments to ENTRYPOINT

  CMD ["param1", "param2"]`

  # the command is run in a shell - /bin/sh -c

  CMD command param1 param2
```

-- There should be only one CMD in a Dockerfile. If more than one CMD is listed, only

the last CMD takes effect.

The main purpose of a CMD is to provide defaults for an executing container.

These defaults may include an executable, or they can omit the executable. If

they omit the executable, an ENTRYPOINT must be specified.

When used in the shell or exec formats, the CMD instruction sets the command to

be executed when running the image.

If you use the shell form of the CMD, the <command> executes in /bin/sh -c:

Note that the exec form is parsed as a JSON array, which means that you must

use double-quotes (") around words not single-quotes (').

```
  FROM ubuntu

  CMD echo "This is a test." | wc -
```

-- If you run command without a shell, then you must express the command as a

JSON array and give the full path to the executable. This array form is the

preferred form of CMD. All additional parameters must be individually expressed

as strings in the array:

```
  FROM ubuntu

  CMD ["/usr/bin/wc","--help"]
```

-- To make the container run the same executable every time, use ENTRYPOINT in

combination with CMD.

If the user specifies arguments to docker run, the specified commands

override the default in CMD.

Do not confuse RUN with CMD. RUN runs a command and commits the result.

CMD executes nothing at build time, but specifies the intended command for

the image.

LABEL

-- LABEL <key>=<value> [<key>=<value> ...]or

```
  LABEL <key>[ <value>]

  LABEL <key>[ <value>]

  ...
```

The LABEL instruction adds metadata to an image. A LABEL is a

key-value pair. To specify a LABEL without a value, simply use an empty

string. To include spaces within a LABEL value, use quotes and

backslashes as you would in command-line parsing.

```
  LABEL com.example.vendor="ACME Incorporated"

  LABEL com.example.vendor "ACME Incorporated"

  LABEL com.example.vendor.is-beta ""

  LABEL com.example.vendor.is-beta=

  LABEL com.example.vendor.is-beta=""
```

An image can have more than one label. To specify multiple labels, separate

each key-value pair by a space.

Labels are additive including LABELs in FROM images. As the system

encounters and then applies a new label, new keys override any previous

labels with identical keys.

To display an image's labels, use the docker inspect command.

STOPSIGNAL

-- STOPSIGNAL <signal>

The STOPSIGNAL instruction sets the system call signal that will be sent

to the container to exit. This signal can be a signal name in the format

SIG<NAME>, for instance SIGKILL, or an unsigned number that matches a

position in the kernel's syscall table, for instance 9. The default is

SIGTERM if not defined.

The image's default stopsignal can be overridden per container, using the

--stop-signal flag on docker-run(1) and docker-create(1).

EXPOSE

-- EXPOSE <port> [<port>...]

The EXPOSE instruction informs Docker that the container listens on the

specified network ports at runtime. Docker uses this information to

interconnect containers using links and to set up port redirection on the host

system.

ENV

-- ENV <key> <value>

The ENV instruction sets the environment variable <key> to

the value <value>. This value is passed to all future

RUN, ENTRYPOINT, and CMD instructions. This is

functionally equivalent to prefixing the command with <key>=<value>. The

environment variables that are set with ENV persist when a container is run

from the resulting image. Use docker inspect to inspect these values, and

change them using docker run --env <key>=<value>.

Note that setting "ENV DEBIAN_FRONTEND=noninteractive" may cause

unintended consequences, because it will persist when the container is run

interactively, as with the following command: docker run -t -i image bash

ADD

-- ADD has two forms:

```
  ADD <src> <dest>

  # Required for paths with whitespace

  ADD ["<src>",... "<dest>"]
```

The ADD instruction copies new files, directories

or remote file URLs to the filesystem of the container at path <dest>.

Multiple <src> resources may be specified but if they are files or directories

then they must be relative to the source directory that is being built

(the context of the build). The <dest> is the absolute path, or path relative

to WORKDIR, into which the source is copied inside the target container.

If the <src> argument is a local file in a recognized compression format

(tar, gzip, bzip2, etc) then it is unpacked at the specified <dest> in the

container's filesystem. Note that only local compressed files will be unpacked,

i.e., the URL download and archive unpacking features cannot be used together.

All new directories are created with mode 0755 and with the uid and gid of 0.

COPY

-- COPY has two forms:

```
  COPY <src> <dest>

  # Required for paths with whitespace

  COPY ["<src>",... "<dest>"]
```

The COPY instruction copies new files from <src> and

adds them to the filesystem of the container at path <dest>. The <src> must be

the path to a file or directory relative to the source directory that is

being built (the context of the build) or a remote file URL. The <dest> is an

absolute path, or a path relative to WORKDIR, into which the source will

be copied inside the target container. If you COPY an archive file it will

land in the container exactly as it appears in the build context without any

attempt to unpack it. All new files and directories are created with mode 0755

and with the uid and gid of 0.

ENTRYPOINT

-- ENTRYPOINT has two forms:

```
  # executable form

  ENTRYPOINT ["executable", "param1", "param2"]`

  # run command in a shell - /bin/sh -c

  ENTRYPOINT command param1 param2
```

-- An ENTRYPOINT helps you configure a

container that can be run as an executable. When you specify an ENTRYPOINT,

the whole container runs as if it was only that executable. The ENTRYPOINT

instruction adds an entry command that is not overwritten when arguments are

passed to docker run. This is different from the behavior of CMD. This allows

arguments to be passed to the entrypoint, for instance docker run <image> -d

passes the -d argument to the ENTRYPOINT. Specify parameters either in the

ENTRYPOINT JSON array (as in the preferred exec form above), or by using a CMD

statement. Parameters in the ENTRYPOINT are not overwritten by the docker run

arguments. Parameters specified via CMD are overwritten by docker run

arguments. Specify a plain string for the ENTRYPOINT, and it will execute in

/bin/sh -c, like a CMD instruction:

```
  FROM ubuntu

  ENTRYPOINT wc -l -
```

This means that the Dockerfile's image always takes stdin as input (that's

what "-" means), and prints the number of lines (that's what "-l" means). To

make this optional but default, use a CMD:

```
  FROM ubuntu

  CMD ["-l", "-"]

  ENTRYPOINT ["/usr/bin/wc"]
```

VOLUME

-- VOLUME ["/data"]

The VOLUME instruction creates a mount point with the specified name and marks

it as holding externally-mounted volumes from the native host or from other

containers.

USER

-- USER daemon

Sets the username or UID used for running subsequent commands.

The USER instruction can optionally be used to set the group or GID. The

followings examples are all valid:

USER [user | user:group | uid | uid:gid | user:gid | uid:group ]

Until the USER instruction is set, instructions will be run as root. The USER

instruction can be used any number of times in a Dockerfile, and will only affect

subsequent commands.

WORKDIR

-- WORKDIR /path/to/workdir

The WORKDIR instruction sets the working directory for the RUN, CMD,

ENTRYPOINT, COPY and ADD Dockerfile commands that follow it. It can

be used multiple times in a single Dockerfile. Relative paths are defined

relative to the path of the previous WORKDIR instruction. For example:

```
  WORKDIR /a

  WORKDIR b

  WORKDIR c

  RUN pwd
```

In the above example, the output of the pwd command is a/b/c.

ARG

-- ARG <name>[=<default value>]

The ARG instruction defines a variable that users can pass at build-time to

the builder with the docker build command using the --build-arg

<varname>=<value> flag. If a user specifies a build argument that was not

defined in the Dockerfile, the build outputs a warning.

```
  [Warning] One or more build-args [foo] were not consumed
```

The Dockerfile author can define a single variable by specifying ARG once or many

variables by specifying ARG more than once. For example, a valid Dockerfile:

```
  FROM busybox

  ARG user1

  ARG buildno

  ...
```

A Dockerfile author may optionally specify a default value for an ARG instruction:

```
  FROM busybox

  ARG user1=someuser

  ARG buildno=1

  ...
```

If an ARG value has a default and if there is no value passed at build-time, the

builder uses the default.

An ARG variable definition comes into effect from the line on which it is

defined in the Dockerfile not from the argument's use on the command-line or

elsewhere. For example, consider this Dockerfile:

```
  1 FROM busybox

  2 USER ${user:-some_user}

  3 ARG user

  4 USER $user

  ...
```

A user builds this file by calling:

```
  $ docker build --build-arg user=what_user Dockerfile
```

The USER at line 2 evaluates to some_user as the user variable is defined on the

subsequent line 3. The USER at line 4 evaluates to what_user as user is

defined and the what_user value was passed on the command line. Prior to its definition by an

ARG instruction, any use of a variable results in an empty string.

Warning: It is not recommended to use build-time variables for

passing secrets like github keys, user credentials etc. Build-time variable

values are visible to any user of the image with the docker history command.

You can use an ARG or an ENV instruction to specify variables that are

available to the RUN instruction. Environment variables defined using the

ENV instruction always override an ARG instruction of the same name. Consider

this Dockerfile with an ENV and ARG instruction.

```
  1 FROM ubuntu

  2 ARG CONT_IMG_VER

  3 ENV CONT_IMG_VER=v1.0.0

  4 RUN echo $CONT_IMG_VER
```

Then, assume this image is built with this command:

```
  $ docker build --build-arg CONT_IMG_VER=v2.0.1 Dockerfile
```

In this case, the RUN instruction uses v1.0.0 instead of the ARG setting

passed by the user:v2.0.1 This behavior is similar to a shell

script where a locally scoped variable overrides the variables passed as

arguments or inherited from environment, from its point of definition.

Using the example above but a different ENV specification you can create more

useful interactions between ARG and ENV instructions:

```
  1 FROM ubuntu

  2 ARG CONT_IMG_VER

  3 ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}

  4 RUN echo $CONT_IMG_VER
```

Unlike an ARG instruction, ENV values are always persisted in the built

image. Consider a docker build without the --build-arg flag:

```
  $ docker build Dockerfile
```

Using this Dockerfile example, CONT_IMG_VER is still persisted in the image but

its value would be v1.0.0 as it is the default set in line 3 by the ENV instruction.

The variable expansion technique in this example allows you to pass arguments

from the command line and persist them in the final image by leveraging the

ENV instruction. Variable expansion is only supported for a limited set of

Dockerfile instructions. ⟨#environment-replacement⟩

Docker has a set of predefined ARG variables that you can use without a

corresponding ARG instruction in the Dockerfile.

- HTTP_PROXY

- http_proxy

- HTTPS_PROXY

- https_proxy

- FTP_PROXY

- ftp_proxy

- NO_PROXY

- no_proxy

- ALL_PROXY

- all_proxy

To use these, pass them on the command line using --build-arg flag, for

example:

```
  $ docker build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
```

ONBUILD

-- ONBUILD [INSTRUCTION]

The ONBUILD instruction adds a trigger instruction to an image. The

trigger is executed at a later time, when the image is used as the base for

another build. Docker executes the trigger in the context of the downstream

build, as if the trigger existed immediately after the FROM instruction in

the downstream Dockerfile.

You can register any build instruction as a trigger. A trigger is useful if

you are defining an image to use as a base for building other images. For

example, if you are defining an application build environment or a daemon that

is customized with a user-specific configuration.

Consider an image intended as a reusable python application builder. It must

add application source code to a particular directory, and might need a build

script called after that. You can't just call ADD and RUN now, because

you don't yet have access to the application source code, and it is different

for each application build.

-- Providing application developers with a boilerplate Dockerfile to copy-paste

into their application is inefficient, error-prone, and

difficult to update because it mixes with application-specific code.

The solution is to use ONBUILD to register instructions in advance, to

run later, during the next build stage.

## HISTORY
*May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation. *Feb 2015, updated by Brian Goff (cpuguy83@gmail.com) for readability *Sept 2015, updated by Sally O'Malley (somalley@redhat.com) *Oct 2016, updated by Addam Hardy (addam.hardy@gmail.com)


docker-config-json

title: docker-config-json(5)

summary: Default Docker configuration file

text:
# docker-config-json(5)

## NAME
HOME/.docker/config.json - Default Docker configuration file

## INTRODUCTION
By default, the Docker command line stores its configuration files in a directory called .docker within your $HOME directory. Docker manages most of the files in the configuration directory and you should not modify them. However, you can modify the config.json file to control certain aspects of how the docker command behaves.

Currently, you can modify the docker command behavior using environment variables or command-line options. You can also use options within config.json to modify some of the same behavior. When using these mechanisms, you must keep in mind the order of precedence among them. Command line options override environment variables and environment variables override properties you specify in a config.json file.

The config.json file stores a JSON encoding of several properties:

•

The HttpHeaders property specifies a set of headers to include in all messages sent from the Docker client to the daemon. Docker does not try to interpret or understand these header; it simply puts them into the messages. Docker does not allow these headers to change any headers it sets for itself.

•

The psFormat property specifies the default format for docker ps output. When the --format flag is not provided with the docker ps command, Docker's client uses this property. If this property is not set, the client falls back to the default table format. For a list of supported formatting directives, see docker-ps(1).

•

The detachKeys property specifies the default key sequence which detaches the container. When the --detach-keys flag is not provide with the docker attach, docker exec, docker run or docker start, Docker's client uses this property. If this property is not set, the client falls back to the default sequence ctrl-p,ctrl-q.

•

The imagesFormat property specifies the default format for docker images output. When the --format flag is not provided with the docker images command, Docker's client uses this property. If this property is not set, the client falls back to the default table format. For a list of supported formatting directives, see docker-images(1).

You can specify a different location for the configuration files via the DOCKER_CONFIG environment variable or the --config command line option. If both are specified, then the --config option overrides the DOCKER_CONFIG environment variable:

```
docker --config  /testconfigs/ ps
```

This command instructs Docker to use the configuration files in the /testconfigs/ directory when running the ps command.

## Examples
Following is a sample config.json file:

```
{

  "HttpHeaders": {

    "MyHeader": "MyValue"

  },

  "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}",

  "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}",

  "detachKeys": "ctrl-e,e"
}
```

## HISTORY
January 2016, created by Moxiegirl ⟨mary@docker.com⟩


apt-cudf.conf

title: apt-cudf.conf(5)

summary: Configuration file for apt\-cudf

text:
# apt-cudf.conf(5)

## NAME
apt-cudf.conf - Configuration file for apt-cudf

## DESCRIPTION
The configuration file allows one to define default optimization criteria for all solvers known by apt-cudf

## SYNTAX

```
  solver: <solver list> | '*'
```

A comma-separated list of solvers. The character will make the optimization criteria as default for all solvers without a more specific definition.

```
  upgrade: <optimization criteria>
  dist-upgrade: <optimization criteria>
  install: <optimization criteria>
  remove: <optimization criteria>
```

Default optimization criteria associated to apt-get actions. The optimization criteria is solver specific. Specifying a incorrect criteria will result in an error from the underlying cudf solver. Please refere to the solver man page for the correct syntax

```
  trendy: <optimization criteria>
  paranoid: <optimization criteria>
  <keyword>: <optimization criteria>
```

Define a shortcut for an optimization criteria. The shortcut can then be used by apt-get to pass a specific optimization criteria for a cudf solver

```
  apt-get install gnome --solver aspcud -o "APT::Solver::aspcud::Preferences=trendy"
```

## EXAMPLE

```
  solver: mccs-cbc , mccs-lpsolve
  upgrade: -lex[-new,-removed,-notuptodate]
  dist-upgrade: -lex[-notuptodate,-new]
  install: -lex[-removed,-changed]
  remove: -lex[-removed,-changed]
  trendy: -lex[-removed,-notuptodate,-unsat_recommends,-new]
  paranoid: -lex[-removed,-changed]
  solver: *
  upgrade: -new,-removed,-notuptodate
  dist-upgrade: -notuptodate,-new
  install: -removed,-changed
  remove: -removed,-changed
  trendy: -removed,-notuptodate,-unsat_recommends,-new
  paranoid: -removed,-changed
```

## SEE ALSO
apt-cudf(8), apt-get(8), update-cudf-solvers(8), README.cudf-solvers <file:///usr/share/doc/apt-cudf/README.cudf-solvers>, README.Debian <file:///usr/share/doc/apt-cudf/README.Debian>

## AUTHOR
Copyright: (C) 2011 Pietro Abate <pietro.abate@pps.jussieu.fr> Copyright: (C) 2011 Stefano Zacchiroli <zack@debian.org>

License: GNU Lesser General Public License (GPL), version 3 or above


deb

package: dpkg

title: deb(5)

summary: Debian binary package format

text:
# deb(5)

## NAME
deb - Debian binary package format

## SYNOPSIS
filename.deb

## DESCRIPTION
The .deb format is the Debian binary package file format. It is understood since dpkg 0.93.76, and is generated by default since dpkg 1.2.0 and 1.1.1elf (i386/ELF builds).

The format described here is used since Debian 0.93; details of the old format are described in deb-old(5).

## FORMAT
The file is an ar archive with a magic value of !<arch>. Only the common ar archive format is supported, with no long file name extensions, but with file names containing an optional trailing slash, which limits their length to 15 characters (from the 16 allowed). File sizes are limited to 10 ASCII decimal digits, allowing for up to approximately 9536.74 MiB member files.

The tar archives currently allowed are, the old-style (v7) format, the pre-POSIX ustar format, a subset of the GNU format (new style long pathnames and long linknames, supported since dpkg 1.4.1.17; large file metadata since dpkg 1.18.24), and the POSIX ustar format (long names supported since dpkg 1.15.0). Unrecognized tar typeflags are considered an error. Each tar entry size inside a tar archive is limited to 11 ASCII octal digits, allowing for up to 8 GiB tar entries. The GNU large file metadata support permits 95-bit tar entry sizes and negative timestamps, and 63-bit UID, GID and device numbers.

The first member is named debian-binary and contains a series of lines, separated by newlines. Currently only one line is present, the format version number, 2.0 at the time this manual page was written. Programs which read new-format archives should be prepared for the minor number to be increased and new lines to be present, and should ignore these if this is the case.

If the major 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 required member is named control.tar. It is a tar archive containing the package control information, either not compressed (supported since dpkg 1.17.6), or compressed with gzip (with .gz extension) or xz (with .xz extension, supported since 1.17.6), zstd (with .zst extension, supported since dpkg 1.21.18), as a series of plain files, of which the file control is mandatory and contains the core control information, the md5sums, conffiles, triggers, shlibs and symbols files contain optional control information, and the preinst, postinst, prerm and postrm files are optional maintainer scripts. The control tarball may optionally contain an entry for ‘.’, the current directory.

The third, last required member is named data.tar. It contains the filesystem as a tar archive, either not compressed (supported since dpkg 1.10.24), or compressed with gzip (with .gz extension), xz (with .xz extension, supported since dpkg 1.15.6), zstd (with .zst extension, supported since dpkg 1.21.18), bzip2 (with .bz2 extension, supported since dpkg 1.10.24) or lzma (with .lzma extension, supported since dpkg 1.13.25).

These members must occur in this exact order. Current implementations should ignore any additional members after data.tar. Further members may be defined in the future, and (if possible) will be placed after these three. Any additional members that may need to be inserted after debian-binary and before control.tar or data.tar and which should be safely ignored by older programs, will have names starting with an underscore, ‘_’.

Those new members which won't be able to be safely ignored will be inserted before data.tar with names starting with something other than underscores, or will (more likely) cause the major version number to be increased.

## MEDIA TYPE

### Current
application/vnd.debian.binary-package

### Deprecated
application/x-debian-package

application/x-deb

## SEE ALSO
deb-old(5), dpkg-deb(1), deb-control(5), deb-conffiles(5), deb-md5sums(5), deb-triggers(5), deb-shlibs(5), deb-symbols(5), deb-preinst(5), deb-postinst(5), deb-prerm(5), deb-postrm(5).