From b3c880e5fd9c1effe3bc312c3bca5cecea4c9ee2 Mon Sep 17 00:00:00 2001 From: Nicola Sella Date: Thu, 20 Jul 2023 17:37:08 +0200 Subject: [PATCH] Add dnf5.conf man page --- dnf5.spec | 1 + doc/CMakeLists.txt | 1 + doc/conf.py.in | 1 + doc/dnf5.conf.5.rst | 1338 +++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + 5 files changed, 1342 insertions(+) create mode 100644 doc/dnf5.conf.5.rst diff --git a/dnf5.spec b/dnf5.spec index 3716da7a2..ea39435f8 100644 --- a/dnf5.spec +++ b/dnf5.spec @@ -274,6 +274,7 @@ It supports RPM packages, modulemd modules, and comps groups & environments. # TODO(jkolarik): modularity is not ready yet # %%{_mandir}/man7/dnf5-modularity.7.* %{_mandir}/man7/dnf5-specs.7.* +%{_mandir}/man5/dnf5.conf.5.* # ========== libdnf5 ========== %package -n libdnf5 diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 65cb183ae..8be3d45df 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -87,6 +87,7 @@ if(WITH_MAN) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/dnf5-builddep.8 DESTINATION share/man/man8) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/dnf5-copr.8 DESTINATION share/man/man8) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/dnf5-repoclosure.8 DESTINATION share/man/man8) + install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/dnf5.conf.5 DESTINATION share/man/man5) endif() endif() diff --git a/doc/conf.py.in b/doc/conf.py.in index 0c2bfa2bb..40fff56f4 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -139,6 +139,7 @@ man_pages = [ ('dnf_daemon/dnf5daemon_client.8', 'dnf5daemon-client', 'Command-line interface for Dnf5daemon', AUTHORS, 8), ('dnf_daemon/dnf5daemon_server.8', 'dnf5daemon-server', 'Package management service with a DBus interface', AUTHORS, 8), ('dnf_daemon/dnf5daemon_dbus_api.8', 'dnf5daemon-dbus-api', 'DBus API Reference for Dnf5daemon', AUTHORS, 8), + ('dnf5.conf.5', 'dnf5.conf', 'DNF5 Configuration Reference', AUTHORS, 5), ] rst_prolog = """ diff --git a/doc/dnf5.conf.5.rst b/doc/dnf5.conf.5.rst new file mode 100644 index 000000000..7febd9561 --- /dev/null +++ b/doc/dnf5.conf.5.rst @@ -0,0 +1,1338 @@ +.. + Copyright Contributors to the libdnf project. + + This file is part of libdnf: https://github.com/rpm-software-management/libdnf/ + + Libdnf is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 2 of the License, or + (at your option) any later version. + + Libdnf is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with libdnf. If not, see . + +######################################### + DNF5.conf - DNF5 Configuration Reference +######################################### + +Description +=========== + +`DNF5` by default uses the global configuration file at /etc/dnf/dnf.conf. + +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. + +.. _conf_main_options-label: + +[main] Options +============== + +.. _allow_vendor_change-label: + +``allow_vendor_change`` + :ref:`boolean ` + + If disabled DNF5 will stick to vendor when upgrading or downgrading rpms. + + Default: ``True``. + + .. WARNING:: This option is currently not supported for `downgrade` and `distro-sync` commands + TODO is this true? + +``arch`` + TODO documented in dnf4, not dnf5 + +.. _assumeno-label: + +``assumeno`` + :ref:`boolean ` + + If enabled DNF5 will assume ``No`` where it would normally prompt for confirmation from user input + + Default: ``False``. + +.. _assumeyes-label: + +``assumeyes`` + :ref:`boolean ` + + If enabled DNF5 will assume ``Yes`` where it would normally prompt for confirmation from user input + (see also :ref:`defaultyes `). + + Default: ``False``. + +.. _autocheck_running_kernel-label: + +``autocheck_running_kernel`` + :ref:`boolean ` + + Automatic check whether there is installed newer kernel module with security update than currently running kernel. + + Default is ``True``. + + .. NOTE:: + YUM compatibility option + +``basearch`` + TODO documented in dnf4, not dnf5 + +.. _best-label: + +``best`` + :ref:`boolean ` + + If ``True``, instructs the solver to either use a package with the highest available + version or fail. If ``False``, do not fail if the latest version cannot be installed and go + with the lower version. + + Default: ``True``. + + .. NOTE:: + This option in particular :ref:`can be set in your configuration file by + your distribution `. + +.. _cachedir-label: + +``cachedir`` + :ref:`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. + + Default: ``/var/cache/libdnf5``. + +.. _cacheonly-label: + +``cacheonly`` + :ref:`string ` + TODO needs improvement + + If set to ``all`` DNF will run entirely from system cache will not update + the cache and will use it even in case it is expired. + + If set to ``metadata`` DNF will cache metadata. + + Default is ``none``. + + .. NOTE:: + 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-label: + +``check_config_file_age`` + :ref:`boolean ` + + If enabled DNF5 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: ``True``. + + .. NOTE:: + Expire of metadata is also affected by metadata age. See also + + :ref:`metadata_expire `. + +.. _clean_requirements_on_remove-label: + +``clean_requirements_on_remove`` + :ref:`boolean ` + + If enabled, 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. + + :ref:`installonlypkgs ` are never automatically removed. + + Default: ``True``. + +.. _debuglevel-label: + +``debuglevel`` + :ref:`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-label: + +``debug_solver`` + :ref:`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-label: + +``defaultyes`` + :ref:`boolean ` + + If enabled the default answer to user confirmation prompts will be ``Yes``. Not + to be confused with :ref:`assumeyes ` which will not prompt at all. Default is ``False``. + +.. _diskspacecheck-label: + +``diskspacecheck`` + :ref:`boolean ` + + Controls wheather rpm shoud check available disk space during the transaction. + Default is ``True``. + +.. _errorlevel-label: + +``errorlevel`` + :ref:`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 \-\ :ref:`-verbose ` commandline + option. + +.. _exit_on_lock-label: + +``exit_on_lock`` + :ref:`boolean ` + + Should the DNF5 client exit immediately when something else has the lock. Default is ``False``. + +.. _gpgkey_dns_verification-label: + +``gpgkey_dns_verification`` + :ref:`boolean ` + + Should the DNF5 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-label: + +``group_package_types`` + :ref:`list ` + + List of the following: optional, default, mandatory. Tells DNF5 which type of packages in groups will + be installed when 'groupinstall' is called. Default is: ``default, mandatory``. + +.. _ignorearch-label: + +``ignorearch`` + :ref:`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 + :ref:`arch ` option. + +.. _installonlypkgs-label: + +``installonlypkgs`` + :ref:`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 + :ref:`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 :ref:`installonly_limit `. + +.. _installonly_limit-label: + +``installonly_limit`` + :ref:`integer ` + + Number of :ref:`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 explicitely not allowed since it + complicates kernel upgrades due to protection of the running kernel from removal. + +.. _installroot-label: + +``installroot`` + :ref:`string ` + + The root of the filesystem for all packaging operations. It requires an absolute path. See also :ref:`--installroot commandline option `. + +.. _install_weak_deps-label: + +``install_weak_deps`` + :ref:`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-label: + +``keepcache`` + :ref:`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-label: + +``logdir`` + :ref:`string ` + + Directory where the log files will be stored. Default is ``/var/log``. + +``logfilelevel`` + TODO documented in dnf4, not dnf5 + +``log_compress`` + TODO documented in dnf4, not dnf5 + +.. _log_rotate-label: + +``log_rotate`` + :ref:`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-label: + +``log_size`` + :ref:`integer ` + + 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 :ref:`log_rotate `. + +.. _metadata_timer_sync-label: + +``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-label: + +``module_obsoletes`` + :ref:`boolean ` + + This option controls whether DNF5 should apply modular obsoletes when possible. + +.. _module_platform_id-label: + +``module_platform_id`` + :ref:`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-label: + +``module_stream_switch`` + :ref:`boolean ` + + This option controls whether it's possible to switch enabled streams of a module. + +.. _multilib_policy-label: + +``multilib_policy`` + :ref:`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-label: + +``obsoletes`` + :ref:`boolean ` + + This option only has affect during an install/update. It enables + DNF5's obsoletes processing logic, which means it makes DNF5 check whether + any dependencies of given package are no longer required and removes them. + Useful when doing distribution level upgrades. + + Default: ``True``. + + Command-line option: :ref:`--obsoletes ` + +.. _persistdir-label: + +``persistdir`` + :ref:`string ` + + Directory where DNF stores its persistent data between runs. + + Default: ``"/var/lib/dnf"``. + +.. _pluginconfpath-label: + +``pluginconfpath`` + :ref:`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. + + Default: ``/etc/dnf/plugins``. + +.. _pluginpath-label: + +``pluginpath`` + :ref:`list ` + + List of directories that are searched for plugins to load. Plugins found in *any of the directories* in this + configuration option are used. + + Default: a Python version-specific path. + +.. _plugins-label: + +``plugins`` + :ref:`boolean ` + + Controls whether the plugins are enabled. + + Default: ``True``. + +.. _protected_packages-label: + +``protected_packages`` + :ref:`list ` + + List of packages that DNF should never completely remove. They are protected via Obsoletes as well as user/plugin + removals. + + Default: ``dnf``, ``glob:/etc/yum/protected.d/*.conf`` and ``glob:/etc/dnf/protected.d/*.conf``. + + .. NOTE:: + 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 + :ref:`protect_running_kernel ` option. + +.. _protect_running_kernel-label: + +``protect_running_kernel`` + :ref:`boolean ` + + Controls whether the package corresponding to the running version of kernel is protected from removal. + + Default: ``True``. + +``releasever`` + TODO documented in dnf4, not dnf5 + +.. _reposdir-label: + +``reposdir`` + :ref:`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 \-\ :ref:`-installroot ` option. + +.. _rpmverbosity-label: + +``rpmverbosity`` + :ref:`string ` + + RPM debug scriptlet output level. One of: ``critical``, ``emergency``, + ``error``, ``warn``, ``info`` or ``debug``. + + Default: ``info``. + +.. _strict-label: + +``strict`` + :ref:`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. + + Default: ``True``. + +.. _tsflags-label: + +``tsflags`` + :ref:`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-label: + +``upgrade_group_objects_upgrade`` + :ref:`boolean ` + + Set this to False to disable the automatic running of ``group upgrade`` when running the ``upgrade`` command. + + Default: ``True`` (perform the operation). + +.. _varsdir-label: + +``varsdir`` + :ref:`list ` + + List of directories where variables definition files are looked for. Defaults to + ``"/etc/dnf/vars", "/etc/yum/vars"``. See :ref:`variable files ` + in Configuration reference. + +.. _zchunk-label: + +``zchunk`` + :ref:`boolean ` + + Enables or disables the use of repository metadata compressed using the zchunk format (if available). + + Default: ``True``. + +.. _system_state-label: + +``system_state`` + TODO documented in dnf5, not dnf4 + +.. _transaction_history_dir-label: + +``transaction_history_dir`` + TODO documented in dnf5, not dnf4 + +.. _transformdb-label: + +``transformdb`` + TODO documented in dnf5, not dnf4 + +.. _recent-label: + +``recent`` + TODO documented in dnf5, not dnf4 + +.. _reset_nice-label: + +``reset_nice`` + TODO documented in dnf5, not dnf4 + +.. _system_cachedir-label: + +``system_cachedir`` + TODO documented in dnf5, not dnf4 + +.. _debugdir-label: + +``debugdir`` + TODO documented in dnf5, not dnf4 + +.. _optional_metadata_types-label: + +``optional_metadata_types`` + TODO documented in dnf5, not dnf4 + +.. _use_host_config-label: + +``use_host_config`` + TODO documented in dnf5, not dnf4 + +.. _config_file_age-label: + +``config_file_age`` + TODO documented in dnf5, not dnf4 + +.. _disable_excludes-label: + +``disable_excludes`` + TODO documented in dnf5, not dnf4 + +.. _allow_downgrade-label: + +``allow_downgrade`` + TODO documented in dnf5, not dnf4 + +.. _bugtracker_url-label: + +``bugtracker_url`` + TODO documented in dnf5, not dnf4 + +.. _history_record-label: + +``history_record`` + TODO documented in dnf5, not dnf4 + +.. _history_record_packages-label: + +``history_record_packages`` + TODO documented in dnf5, not dnf4 + +.. _skip_broken-label: + +``skip_broken`` + TODO documented in dnf5, not dnf4 + +.. _skip_unavailable-label: + +``skip_unavailable`` + TODO documented in dnf5, not dnf4 + +.. _history_list_view-label: + +``history_list_view`` + TODO documented in dnf5, not dnf4 + +.. _destdir-label: + +``destdir`` + TODO documented in dnf5, not dnf4 + +.. _comment-label: + +``comment`` + TODO documented in dnf5, not dnf4 + +.. _downloadonly-label: + +``downloadonly`` + TODO documented in dnf5, not dnf4 + +.. _build_cache-label: + +``build_cache`` + TODO documented in dnf5, not dnf4 + +.. _exclude_from_weak-label: + +``exclude_from_weak`` + TODO documented in dnf5, not dnf4 + +.. _exclude_from_weak_autodetect-label: + +``exclude_from_weak_autodetect`` + TODO documented in dnf5, not dnf4 + +[main] Options - Colors +======================= + +.. _color_list_installed_older-label: + +``color_list_installed_older`` + :ref:`color ` + + Color of installed packages that are older than any version among available packages. + The option is used during list operations. + + Default: ``yellow``. + +.. _color_list_installed_newer-label: + +``color_list_installed_newer`` + :ref:`color ` + + Color of installed packages that are newer than any version among available packages. + The option is used during list operations. + + Default: ``bold,yellow``. + +.. _color_list_installed_reinstall-label: + +``color_list_installed_reinstall`` + :ref:`color ` + + Color of installed packages that are among available packages and can be reinstalled. + The option is used during list operations. + + Default: ``cyan``. + +.. _color_list_installed_extra-label: + +``color_list_installed_extra`` + :ref:`color ` + + Color of installed packages that do not have any version among available packages. + The option is used during list operations. + + Default: ``bold,red``. + +.. _color_list_available_upgrade-label: + +``color_list_available_upgrade`` + :ref:`color ` + + Color of available packages that are newer than installed packages. + The option is used during list operations. + + Default: ``bold,blue``. + +.. _color_list_available_downgrade-label: + +``color_list_available_downgrade`` + :ref:`color ` + + Color of available packages that are older than installed packages. + The option is used during list operations. + + Default: ``magenta``. + +.. _color_list_available_reinstall-label: + +``color_list_available_reinstall`` + :ref:`color ` + + Color of available packages that are identical to installed versions and are available for reinstalls. + The option is used during list operations. + + Default: ``bold,underline,green``. + +.. _color_list_available_install-label: + +``color_list_available_install`` + :ref:`color ` + + Color of packages that are available for installation and none of their versions in installed. + The option is used during list operations. + + Default: ``bold,cyan``. + +.. _color_update_installed-label: + +``color_update_installed`` + :ref:`color ` + + Color of removed packages. Default is red. + This option is used during displaying transactions. + +.. _color_update_local-label: + +``color_update_label`` + :ref:`color ` + + Color of local packages that are installed from the @commandline repository. + This option is used during displaying transactions. + + Default: ``green``. + +.. _color_update_remote-label: + +``color_update_remote`` + :ref:`color ` + + Color of packages that are installed/upgraded/downgraded from remote repositories. + This option is used during displaying transactions. + + Default: ``bold,green``. + +.. _color_search_match-label: + +``color_search_match`` + :ref:`color ` + + Color of patterns matched in search output. + + Default: ``bold,magenta``. + + +Repo Options +============ + +``baseurl`` + TODO documented in dnf4, not dnf5 + +``cost`` + TODO documented in dnf4, not dnf5 + +.. _enabled-label: + +``enabled`` + :ref:`boolean ` + + Include this repository as a package source. The default is True. + +``gpgkey`` + TODO documented in dnf4, not dnf5 + +``metalink`` + TODO documented in dnf4, not dnf5 + +``mirrorlist`` + TODO documented in dnf4, not dnf5 + +``module_hotfixes`` + TODO documented in dnf4, not dnf5 + +``name`` + TODO documented in dnf4, not dnf5 + +``priority`` + TODO documented in dnf4, not dnf5 + +``type`` + TODO documented in dnf4, not dnf5 + + +Repo Variables +============== + +Right side of every repo option can be enriched by the following variables: TODO is it true? + +``$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 :ref:`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-label: + +``bandwidth`` + :ref:`storage size ` + + Total bandwidth available for downloading. Meaningful when used with the :ref:`throttle option `. + +.. _countme-label: + +``countme`` + :ref:`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-label: + +``deltarpm`` + :ref:`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-label: + +``deltarpm_percentage`` + :ref:`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-label: + +``enablegroups`` + :ref:`boolean ` + + Determines whether DNF will allow the use of package groups for this repository. + + Default: ``True`` (package groups are allowed). + +.. _excludepkgs-label: + +``excludepkgs`` + :ref:`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. + + Default: ``[]``. + +.. _fastestmirror-label: + +``fastestmirror`` + :ref:`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. + + Default: ``False``. + +.. _gpgcheck-label: + +``gpgcheck`` + :ref:`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 + :ref:`localpkg_gpgcheck `. + +.. _includepkgs-label: + +``includepkgs`` + :ref:`list ` + + Include packages of this repository, specified by a name or a glob and separated by a comma, in all operations. + Inverse of :ref:`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. + + Default: ``[]``. + +.. _ip_resolve-label: + +``ip_resolve`` + :ref:`ip address ` + + 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-label: + +``localpkg_gpgcheck`` + :ref:`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 :ref:`gpgcheck ` for more details). + +.. _max_parallel_downloads-label: + +``max_parallel_downloads`` + :ref:`integer ` + + Maximum number of simultaneous package downloads. + Default: 3. Maximum of 20. + +.. _metadata_expire-label: + +``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``). See + also :ref:`check_config_file_age `. + +.. _minrate-label: + +``minrate`` + :ref:`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 + :ref:`timeout option ` seconds, DNF aborts the connection. + + Default: 1000. + +.. _password-label: + +``password`` + :ref:`string ` + + The password to use for connecting to a repository with basic HTTP authentication. + + Default: empty. + +.. _proxy-label: + +``proxy`` + :ref:`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 + ``://[: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-label: + +``proxy_username`` + :ref:`string ` + + The username to use for connecting to the proxy server. + + Default: empty. + +.. _proxy_password-label: + +``proxy_password`` + :ref:`string ` + + The password to use for connecting to the proxy server. + + Default: empty. + +.. _proxy_auth_method-label: + +``proxy_auth_method`` + :ref:`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 + ========== ========================================================== + + Default: ``any``. + +.. _proxy_sslcacert-label: + +``proxy_sslcacert`` + :ref:`string ` + + Path to the file containing the certificate authorities to verify proxy SSL certificates. + + Default: empty. Uses system default. + +.. _proxy_sslverify-label: + +``proxy_sslverify`` + :ref:`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: ``True``. + +.. _proxy_sslclientcert-label: + +``proxy_sslclientcert`` + :ref:`string ` + + Path to the SSL client certificate used to connect to proxy server. + + Default: empty. + +.. _proxy_sslclientkey-label: + +``proxy_sslclientkey`` + :ref:`string ` + + Path to the SSL client key used to connect to proxy server. + + Default: empty. + +.. _repo_gpgcheck-label: + +``repo_gpgcheck`` + :ref:`boolean ` + + Whether to perform GPG signature check on this repository's metadata. The default is False. + Note that GPG keys for this check are stored separately from GPG keys used in package signature + verification. Furthermore, they are also stored separately for each repository. + + This means that DNF5 may ask to import the same key multiple times. For example, when a key was + already imported for package signature verification and this option is turned on, it may be needed + to import it again for the repository. + +.. _retries-label: + +``retries`` + :ref:`integer ` + + Set the number of total retries for downloading packages. The number is + accumulative, so e.g. for `retries=10`, DNF5 will fail after any package + download fails for eleventh time. Setting this to `0` makes DNF5 try + forever. + + Default: `10`. + +.. _skip_if_unavailable-label: + +``skip_if_unavailable`` + :ref:`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 + :ref:`refresh command line option `. + + Default: ``False``. + + .. NOTE:: + this option in particular :ref:`can be set in your configuration file + by your distribution `. + +.. _sslcacert-label: + +``sslcacert`` + :ref:`string ` + + Path to the file containing the certificate authorities to verify SSL certificates. + + Default: empty. Uses system default. + +.. _sslverify-label: + +``sslverify`` + :ref:`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: ``True``. + +``sslverifystatus`` + TODO documented in dnf4, not dnf5 + +.. _sslclientcert-label: + +``sslclientcert`` + :ref:`string ` + + Path to the SSL client certificate used to connect to remote sites. + + Default: empty. + +.. _sslclientkey-label: + +``sslclientkey`` + :ref:`string ` + + Path to the SSL client key used to connect to remote sites. + + Default: empty. + +.. _throttle-label: + +``throttle`` + :ref:`storage size ` + + Limits the downloading speed. It might be an absolute value or a percentage, relative to the value of the + :ref:`bandwidth option ` option. ``0`` means no throttling. + + Default: `0`. + +.. _timeout-label: + +``timeout`` + time in seconds + + Number of seconds to wait for a connection before timing out. Used in combination with + :ref:`minrate option ` option. + + Default: `30`. + +.. _username-label: + +``username`` + :ref:`string ` + + The username to use for connecting to repo with basic HTTP authentication. + + Default: empty. + +.. _user_agent-label: + +``user_agent`` + :ref:`string ` + + The User-Agent string to include in HTTP requests sent by DNF. + + Default: :: + + libdnf (NAME VERSION_ID; VARIANT_ID; OS.BASEARCH) + + .. NOTE:: + ``NAME``, ``VERSION_ID`` and ``VARIANT_ID`` are OS identifiers read from the + :manpage:`os-release(5)` file, and ``OS`` and ``BASEARCH`` are the canonical OS + name and base architecture, respectively. + Example: :: + + libdnf (Fedora 39; server; Linux.x86_64) + + +Types of Options +================ + +.. _boolean-label: + +``boolean`` + Data type with only two possible values. + + One of following options can be used: ``1``, ``0``, ``True``, ``False``, ``yes``, ``no``. + +.. _color-label: + +``color`` + 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``. + +.. _integer-label: + +``integer`` + Whole number that can be written without a fractional component. + +.. _ip_address_type-label: + +``ip address type`` + String describing ip addresss types. + + One of the following options can be used: ``4``, ``IPv4``, ``6``, ``IPv6``. + +.. _list-label: + +``list`` + String representing one or more strings separated by space or comma characters. + +.. _storage_size-label: + +``storage size`` + String representing storage sizes formed by an integer and a unit. + + Valid units are ``k``, ``M``, ``G``. + +.. _string-label: + +``string`` + It is a sequence of symbols or digits without any whitespace character. + +.. _time_in_seconds-label: + +``time in seconds`` + String representing time units in seconds. Can be set to ``-1`` or ``never``. + + +Files +===== + +``Cache Files`` + /var/cache/dnf + +``Main Configuration File`` + /etc/dnf/dnf.conf + +``Repository`` + /etc/yum.repos.d/ + +.. _varfiles-label: + +``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 +========= + +TODO man page name? +* :manpage:`dnf(8)`, :ref:`DNF Command Reference ` diff --git a/doc/index.rst b/doc/index.rst index a81ca0557..675932862 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,6 +13,7 @@ Welcome to DNF5's documentation! commands/index dnf5_plugins/index dnf5.8 + dnf5.conf.5 dnf_daemon/index misc/index best_practices/index