diff --git a/dnf5.spec b/dnf5.spec index 3716da7a2e..ea39435f80 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 65cb183ae0..8be3d45df0 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 0c2bfa2bbc..40fff56f46 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 0000000000..deb2635535 --- /dev/null +++ b/doc/dnf5.conf.5.rst @@ -0,0 +1,1467 @@ +.. + 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_options-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_options-label: + +``assumeno`` + :ref:`boolean ` + + If enabled DNF5 will assume ``No`` where it would normally prompt for confirmation from user input + + Default: ``False``. + +.. _assumeyes_options-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_options-label: + +``autocheck_running_kernel`` + :ref:`boolean ` + + Automatic check whether there is installed newer kernel module with security update than currently running kernel. + + Default: ``True``. + + .. NOTE:: + YUM compatibility option + +``basearch`` + TODO documented in dnf4, not dnf5 + +.. _best_options-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_options-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_options-label: + +``cacheonly`` + :ref:`string ` + TODO needs improvement + + Can be ``all``, ``metadata``, ``none``. + + 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: ``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_options-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_options-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_options-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: ``2``. + +.. _debug_solver_options-label: + +``debug_solver`` + :ref:`boolean ` + + If enabled, libsolv debug files will be created when solving the + transaction. The debug files are created in the `./debugdata` directory. + + Default: ``False``. + +.. _defaultyes_options-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.i + + Default: ``False``. + +.. _diskspacecheck_options-label: + +``diskspacecheck`` + :ref:`boolean ` + + If enabled, controls wheather rpm shoud check available disk space during the transaction. + + Default: ``True``. + +.. _errorlevel_options-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: ``3``. + + .. WARNING:: + This is deprecated in DNF and overwritten by \-\ :ref:`-verbose ` commandline option. + + TODO is this true? + +.. _exit_on_lock_options-label: + +``exit_on_lock`` + :ref:`boolean ` + + If enabled, DNF5 will exit immediately when something else has the lock. + + Default: ``False``. + +.. _gpgkey_dns_verification_options-label: + +``gpgkey_dns_verification`` + :ref:`boolean ` + + If enabled, DNF5 will attempt to automatically verify GPG verification keys using the DNS + system. + + TODO is it true? + v + 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: ``False``. + +.. _group_package_types_options-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: ``default,mandatory``. + +.. _ignorearch_options-label: + +``ignorearch`` + :ref:`boolean ` + + If enabled, RPM will allow attempts to install packages incompatible with the CPU's architecture. + + Often used together with :ref:`arch ` option. + + Default: ``False``. + +.. _installonlypkgs_options-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_options-label: + +``installonly_limit`` + :ref:`integer ` + + Number of :ref:`installonly packages ` allowed to be installed + concurrently. + + ``1`` is explicitely not allowed since it complicates kernel upgrades due to protection of + the running kernel from removal. + + Minimum is ``2``. + + ``0`` means unlimited number of installonly packages. + + Default: ``3``. + +.. _installroot_options-label: + +``installroot`` + :ref:`string ` + + The root of the filesystem for all packaging operations. + It requires an absolute path. + See also :ref:`--installroot commandline option `. + + Default: ``/``. + +.. _install_weak_deps_options-label: + +``install_weak_deps`` + :ref:`boolean ` + + If enabled, when 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: ``True``. + +.. _keepcache_options-label: + +``keepcache`` + :ref:`boolean ` + + If enabled, keeps downloaded packages in the cache. If disabled cache will persist + until the next successful transaction even if no packages have been installed. + + Default: ``False``. + +.. _logdir_options-label: + +``logdir`` + :ref:`string ` + + Directory where the log files will be stored. + + Default: ``/var/log``. + +``logfilelevel`` + TODO documented in dnf4, not dnf5 + +``log_compress`` + TODO documented in dnf4, not dnf5 + +.. _log_rotate_options-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: ``4``. + +.. _log_size_options-label: + +``log_size`` + :ref:`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 size applies for individual log files, not the sum of all log files. + See also :ref:`log_rotate `. + + Default: ``1M``. + +.. _metadata_timer_sync_options-label: + +``metadata_timer_sync`` + :ref:`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 value is rounded to the next commenced hour. + + Default: ``60 * 60 * 3``, 3 hours. + +.. _module_obsoletes_options-label: + +``module_obsoletes`` + :ref:`boolean ` + + If enabled, DNF5 tries to apply modular obsoletes when possible. + + Default: ``False``. + +.. _module_platform_id_options-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. + + Default: empty. + +.. _module_stream_switch_options-label: + +``module_stream_switch`` + :ref:`boolean ` + + If enabled, allows switching enabled streams of a module. + + Default: ``False``. + +.. _multilib_policy_options-label: + +``multilib_policy`` + :ref:`string ` + + Controls how multilib packages are treated during install operations. + + Can either be ``best`` for the depsolver to prefer packages which best match the system's + architecture, or ``all`` to install packages for all available architectures. + + Default: ``best``. + +.. _obsoletes_options-label: + +``obsoletes`` + :ref:`boolean ` + + If enabled, DNF5 uses obsoletes processing logic, which means it checks whether + any dependencies of given package are no longer required and removes them. + + Useful when doing distribution level upgrades. + + It has effect during install/upgrade processes. + + Command-line option: :ref:`--obsoletes ` + + Default: ``True``. + +.. _persistdir_options-label: + +``persistdir`` + :ref:`string ` + + Directory where DNF stores its persistent data between runs. + + Default: ``/var/lib/dnf``. + +.. _pluginconfpath_options-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_options-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_options-label: + +``plugins`` + :ref:`boolean ` + + If enabled, DNF5 plugins are enabled. + + Default: ``True``. + +.. _protected_packages_options-label: + +``protected_packages`` + :ref:`list ` + TODO need review + + List of packages that DNF should never completely remove. + + They are protected via Obsoletes as well as user/plugin removals. + + Default: ``dnf5,glob:/etc/dnf/protected.d/*.conf``. + + .. NOTE:: + 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_options-label: + +``protect_running_kernel`` + :ref:`boolean ` + + Controls whether the package corresponding to the running version of kernel is protected from removal. + + Default: ``True``. + + .. NOTE:: + YUM compatibility option + +``releasever`` + TODO documented in dnf4, not dnf5 + +.. _reposdir_options-label: + +``reposdir`` + :ref:`list ` + + Repository configuration files locations. + + The behavior of ``reposdir`` could differ when it is used + along with \-\ :ref:`-installroot ` option. + + Default: TODO add default + +.. _rpmverbosity_options-label: + +``rpmverbosity`` + :ref:`string ` + + RPM debug scriptlet output level. One of: ``critical``, ``emergency``, + ``error``, ``warn``, ``info`` or ``debug``. + + Default: ``info``. + +.. _strict_options-label: + +``strict`` + :ref:`boolean ` + + .. WARNING:: + ``strict`` option is deprecated. + + 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_options-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. + + Default: empty. + +.. _upgrade_group_objects_upgrade_options-label: + +``upgrade_group_objects_upgrade`` + :ref:`boolean ` + + If enabled, performs the automatic running of ``group upgrade`` when running the ``upgrade`` command. + + Default: ``True``. + +.. _varsdir_options-label: + +``varsdir`` + :ref:`list ` + + List of directories where variables definition files are looked for. + + See :ref:`variable files ` in Configuration reference. + + Default: ``/etc/dnf/vars``. + +.. _zchunk_options-label: + +``zchunk`` + :ref:`boolean ` + + If enabled, repository metadata are compressed using the zchunk format (if available). + + Default: ``True``. + +.. _system_state_options-label: + +``system_state`` + TODO documented in dnf5, not dnf4 + +.. _transaction_history_dir_options-label: + +``transaction_history_dir`` + TODO documented in dnf5, not dnf4 + +.. _transformdb_options-label: + +``transformdb`` + TODO documented in dnf5, not dnf4 + +.. _recent_options-label: + +``recent`` + TODO documented in dnf5, not dnf4 + +.. _reset_nice_options-label: + +``reset_nice`` + TODO documented in dnf5, not dnf4 + +.. _system_cachedir_options-label: + +``system_cachedir`` + TODO documented in dnf5, not dnf4 + +.. _debugdir_options-label: + +``debugdir`` + TODO documented in dnf5, not dnf4 + +.. _optional_metadata_types_options-label: + +``optional_metadata_types`` + TODO documented in dnf5, not dnf4 + +.. _use_host_config_options-label: + +``use_host_config`` + TODO documented in dnf5, not dnf4 + +.. _config_file_age_options-label: + +``config_file_age`` + TODO documented in dnf5, not dnf4 + +.. _disable_excludes_options-label: + +``disable_excludes`` + TODO documented in dnf5, not dnf4 + +.. _allow_downgrade_options-label: + +``allow_downgrade`` + TODO documented in dnf5, not dnf4 + +.. _bugtracker_url_options-label: + +``bugtracker_url`` + TODO documented in dnf5, not dnf4 + +.. _history_record_options-label: + +``history_record`` + TODO documented in dnf5, not dnf4 + +.. _history_record_packages_options-label: + +``history_record_packages`` + TODO documented in dnf5, not dnf4 + +.. _skip_broken_options-label: + +``skip_broken`` + TODO documented in dnf5, not dnf4 + +.. _skip_unavailable_options-label: + +``skip_unavailable`` + TODO documented in dnf5, not dnf4 + +.. _history_list_view_options-label: + +``history_list_view`` + TODO documented in dnf5, not dnf4 + +.. _destdir_options-label: + +``destdir`` + TODO documented in dnf5, not dnf4 + +.. _comment_options-label: + +``comment`` + TODO documented in dnf5, not dnf4 + +.. _downloadonly_options-label: + +``downloadonly`` + TODO documented in dnf5, not dnf4 + +.. _build_cache_options-label: + +``build_cache`` + TODO documented in dnf5, not dnf4 + +.. _exclude_from_weak_options-label: + +``exclude_from_weak`` + TODO documented in dnf5, not dnf4 + +.. _exclude_from_weak_autodetect_options-label: + +``exclude_from_weak_autodetect`` + TODO documented in dnf5, not dnf4 + +[main] Options - Colors +======================= + +.. _color_options-label: + +``color`` + :ref:`string ` + + Controls if DNF uses colored output on the command line. + Possible values: ``auto``, ``never``, ``always``. + + Default: ``auto``. + +.. _color_list_installed_older_options-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_options-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_options-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: ``dim,cyan``. + +.. _color_list_installed_extra_options-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_options-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_options-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: ``dim,magenta``. + +.. _color_list_available_reinstall_options-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,green``. + +.. _color_list_available_install_options-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_options-label: + +``color_update_installed`` + :ref:`color ` + + Color of removed packages. + This option is used during displaying transactions. + + Default: ``dim,red``. + +.. _color_update_local_options-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: ``dim,green``. + +.. _color_update_remote_options-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_options-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_options-label: + +``enabled`` + :ref:`boolean ` + + Include this repository as a package source. + + Default: ``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 +============== +TODO this should be reviewed again + +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_options-label: + +``bandwidth`` + :ref:`storage size ` + + Total bandwidth available for downloading. + Meaningful when used with the :ref:`throttle option `. + + Default: ``0``. + +.. _countme_options-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: ``False``. + +.. _deltarpm_options-label: + +``deltarpm`` + :ref:`boolean ` + + If enabled, DNF5 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: ``True``. + +.. _deltarpm_percentage_options-label: + +``deltarpm_percentage`` + :ref:`integer ` + + When the relative size of delta vs pkg is larger than this, delta is not used. + (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. + + Default: ``75`` + +.. _enablegroups_options-label: + +``enablegroups`` + :ref:`boolean ` + + If enabled, DNF5 will allow the use of package groups. + + Default: ``True``. + +.. _excludepkgs_options-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. + TODO add reference + + Default: ``[]``. + +.. _fastestmirror_options-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_options-label: + +``gpgcheck`` + :ref:`boolean ` + + If enabled, DNF5 will performa a GPG signature check on packages found in this repository. + + 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 DNF5's 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 `. + + Default: ``False``. + +.. _includepkgs_options-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 ref:`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 DNF5 in this repo. + + Can be disabled using ``--disableexcludes`` command line switch. + TODO add reference + + Default: ``[]``. + +.. _ip_resolve_options-label: + +``ip_resolve`` + :ref:`ip address ` + + Determines how DNF resolves host names. Set this to ``4``, ``IPv4``, ``6``, ``IPv6`` + to resolve to IPv4 or IPv6 addresses only. + + Default: ``whatever``. + +.. _localpkg_gpgcheck_options-label: + +``localpkg_gpgcheck`` + :ref:`boolean ` + + If enabled, DNF5 will perform a GPG signature check on local packages (packages in a file, not in a repository). + + This option is subject to the active RPM security policy + (see :ref:`gpgcheck ` for more details). + + Default: ``False``. + +.. _max_parallel_downloads_options-label: + +``max_parallel_downloads`` + :ref:`integer ` + + Maximum number of simultaneous package downloads. Max is ``20``. + + Default: ``3``. + +.. _metadata_expire_options-label: + +``metadata_expire`` + :ref:`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. + It can be ``-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 `. + + Default: ``60 * 60 * 48``, 48 hours. + +.. _minrate_options-label: + +``minrate`` + :ref:`storage size ` + + 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, DNF5 aborts the connection. + + Default: ``1000``. + +.. _password_options-label: + +``password`` + :ref:`string ` + + The password used to connect to a repository with basic HTTP authentication. + + Default: empty. + +.. _proxy_options-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.) + + Default: empty. + + .. 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_options-label: + +``proxy_username`` + :ref:`string ` + + The username to use for connecting to the proxy server. + + Default: empty. + +.. _proxy_password_options-label: + +``proxy_password`` + :ref:`string ` + + The password to use for connecting to the proxy server. + + Default: empty. + +.. _proxy_auth_method_options-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_options-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_options-label: + +``proxy_sslverify`` + :ref:`boolean ` + + If 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_options-label: + +``proxy_sslclientcert`` + :ref:`string ` + + Path to the SSL client certificate used to connect to proxy server. + + Default: empty. + +.. _proxy_sslclientkey_options-label: + +``proxy_sslclientkey`` + :ref:`string ` + + Path to the SSL client key used to connect to proxy server. + + Default: empty. + +.. _repo_gpgcheck_options-label: + +``repo_gpgcheck`` + :ref:`boolean ` + + If enabled, DNF5 will perform GPG signature check on this repository's metadata. + + + .. NOTE:: + 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. + + Default: ``False``. + +.. _retries_options-label: + +``retries`` + :ref:`integer ` + + Set the number of total retries for downloading packages. + The number is cumulative, 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_options-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_options-label: + +``sslcacert`` + :ref:`string ` + + Path to the file containing the certificate authorities to verify SSL certificates. + + Default: empty, uses system default. + +.. _sslverify_options-label: + +``sslverify`` + :ref:`boolean ` + + If enabled, remote SSL certificates are verified. If the client can not be authenticated, + connecting fails and the repository is not used any further. + If disabled, SSL connections can be used, but certificates are not verified. + + Default: ``True``. + +``sslverifystatus`` + TODO documented in dnf4, not dnf5 + +.. _sslclientcert_options-label: + +``sslclientcert`` + :ref:`string ` + + Path to the SSL client certificate used to connect to remote sites. + + Default: empty. + +.. _sslclientkey_options-label: + +``sslclientkey`` + :ref:`string ` + + Path to the SSL client key used to connect to remote sites. + + Default: empty. + +.. _throttle_options-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_options-label: + +``timeout`` + :ref:`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_options-label: + +``username`` + :ref:`string ` + + The username to use for connecting to repo with basic HTTP authentication. + + Default: empty. + +.. _user_agent_options-label: + +``user_agent`` + :ref:`string ` + TODO option not fully implemented + + 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 a81ca0557c..6759328629 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