Debian Codegraph @

upstream/debian-unstable/man7/dnf5-caching.7

raw
1 .\" Man page generated from reStructuredText
2 .\" by the Docutils 0.22.4 manpage writer.
3 .
4 .
5 .nr rst2man-indent-level 0
6 .
7 .de1 rstReportMargin
8 \\$1 \\n[an-margin]
9 level \\n[rst2man-indent-level]
10 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
11 -
12 \\n[rst2man-indent0]
13 \\n[rst2man-indent1]
14 \\n[rst2man-indent2]
15 ..
16 .de1 INDENT
17 .\" .rstReportMargin pre:
18 . RS \\$1
19 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
20 . nr rst2man-indent-level +1
21 .\" .rstReportMargin post:
22 ..
23 .de UNINDENT
24 . RE
25 .\" indent \\n[an-margin]
26 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
27 .nr rst2man-indent-level -1
28 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
30 ..
31 .TH "DNF5-CACHING" "7" "May 09, 2026" "" "dnf5"
32 .SH NAME
33 dnf5-caching \- Caching
34 .SH DESCRIPTION
35 .sp
36 This page aims to provide an overview of the various instruments, such as configuration options,
37 command\-line parameters, and commands, available in DNF5 for manipulating cached data and
38 their associated scenarios.
39 .SH CACHED DATA LOCATION
40 .sp
41 Following directory structure illustrates a typical DNF5 cache directory:
42 .INDENT 0.0
43 .INDENT 3.5
44 .sp
45 .EX
46 /var/cache/libdnf5/
47 ├── fedora\-*
48 │\ \ ├── metalink.xml
49 │\ \ ├── repodata
50 │\ \ │\ \ ├── *\-comps\-Everything.x86_64.xml
51 │\ \ │\ \ ├── *\-primary.xml.zck
52 │\ \ │\ \ └── repomd.xml
53 │\ \ └── solv
54 │\ \ ├── fedora\-group.solvx
55 │\ \ └── fedora.solv
56 ├── temporary_files.toml
57 └── updates\-*
58 ├── metalink.xml
59 ├── packages
60 │\ \ └── bash\-5.2.21\-1.fc38.x86_64.rpm
61 ├── repodata
62 │\ \ ├── *\-primary.xml.zck
63 │\ \ ├── *\-updateinfo.xml.zck
64 │\ \ ├── *\-comps\-Everything.x86_64.xml.gz
65 │\ \ └── repomd.xml
66 └── solv
67 ├── updates\-group.solvx
68 ├── updates\-updateinfo.solvx
69 └── updates.solv
70 .EE
71 .UNINDENT
72 .UNINDENT
73 .sp
74 The default root cache directory is \fB/var/cache/libdnf5\fP, but when DNF5 runs as another user,
75 it uses the cache from \fB~/.cache/libdnf5\fP with the same structure. The root cache
76 directory can be redefined using the \fBsystem_cachedir\fP configuration option, and the user
77 cachedir with the \fBcachedir\fP option.
78 .sp
79 Within the cache directory, there are subdirectories corresponding to each configured repository,
80 such as \fBfedora\-*\fP and \fBupdates\-*\fP\&. These contain metadata files in the \fBrepodata\fP directory
81 and solver\-generated cached files in the \fBsolv\fP directory. The solver files, used to enhance
82 performance in resolving package dependencies or running queries, can be enabled or disabled on
83 a repository level through the \fBbuild_cache\fP configuration option. The \fBpackages\fP directory
84 may store downloaded packages from a repository, and a \fBmetalink\fP or \fBmirrorlist\fP file provides
85 information on the remote locations of the repository data.
86 .sp
87 Additionally, the root cache directory contains a \fBtemporary_files.toml\fP file related to
88 temporarily stored packages in the system.
89 .SH METADATA TYPES
90 .sp
91 There are several types of metadata downloaded from remote locations and processed in DNF5.
92 .sp
93 Some metadata is mandatory and always considered. The main repository metadata file, \fBrepomd.xml\fP,
94 contains information about specific metadata type files related to a repository, such as checksums,
95 file sizes, and their locations in the metadata hierarchy. Another mandatory file is the \fBprimary\fP
96 metadata file, providing detailed information about available packages, including package names,
97 versions, dependencies, etc. If DNF5 is compiled with modularity support, \fBmodules\fP metadata is
98 also downloaded and processed.
99 .sp
100 Other metadata types are optional and can be loaded into DNF5 in the following ways:
101 .INDENT 0.0
102 .IP \(bu 2
103 Explicit user request by adding the requested type to the \fBoptional_metadata_types\fP configuration option
104 .IP \(bu 2
105 Automatically during runtime, depending on the CLI command used
106 .IP \(bu 2
107 For \fBfilelists\fP metadata, when the user passes any filepath argument
108 .UNINDENT
109 .sp
110 Here is the list of supported optional metadata types:
111 .INDENT 0.0
112 .IP \(bu 2
113 \fBcomps\fP: Metadata containing package groups and environment descriptions
114 .IP \(bu 2
115 \fBfilelists\fP: Information about all files provided by packages
116 .IP \(bu 2
117 \fBupdateinfo\fP: Security\-related updates and advisories information
118 .IP \(bu 2
119 \fBpresto\fP: Information related to delta RPMs
120 .IP \(bu 2
121 \fBother\fP: Additional metadata, such as changelogs
122 .UNINDENT
123 .sp
124 If the required metadata is not present in the system, it can result in different scenarios,
125 such as returning an empty query, error output for no match for an argument, or an error when
126 resolving a transaction.
127 .SH CACHING PACKAGES
128 .sp
129 By default, DNF5 does not cache downloaded package data, as the \fBkeepcache\fP option is configured
130 to \fBFalse\fP\&. With this setting, every time DNF5 downloads a package from the remote location,
131 it tracks it within the \fBtemporary_files.toml\fP in the repository cache directory. After the next
132 successful transaction run, all the files are removed based on this list. This process occurs only
133 when the transaction contains any inbound action; otherwise, packages are retained, considering
134 potential use cases.
135 .sp
136 When the keepcache option is set to \fBTrue\fP, downloaded files are not tracked, and they could be
137 removed later, either manually or by executing the \fBclean\fP command, for example,
138 \fBdnf5 clean packages\fP\&.
139 .sp
140 Packages are always retained when downloaded using the \fBdownload\fP command.
141 .SH SHARING ROOT CACHE AMONG USERS
142 .sp
143 Typically, DNF5 is run with superuser privileges to make system changes. However, there are
144 scenarios where executing queries without elevated privileges is sufficient. In such cases,
145 we may need to download the entire repository metadata for the user account from the remote,
146 even if there is existing data in the root\(aqs cache.
147 .sp
148 In DNF5, when checking for empty, expired, or invalid repository metadata while running under
149 a non\-root account, we first examine the root\(aqs location. If metadata is present there, it is
150 copied to the user cache location. Note that this cloning of metadata is optimized when
151 copy\-on\-write functionality is present on the filesystem, such as with btrfs.
152 .SH CACHEONLY OPTION VS PARAMETER
153 .sp
154 To instruct DNF5 to operate exclusively with cached data, avoiding downloads from remote locations,
155 two instruments are available. First, using the \fBcacheonly\fP configuration option, we can specify
156 either \fBmetadata\fP to utilize only repository metadata from the cache or \fBall\fP to include
157 the entire cache, disallowing any package downloads. Alternatively, when the \fB\-\-cacheonly\fP
158 parameter is employed, it automatically sets the configuration option to \fBall\fP, resulting
159 in a fully cache\-driven operation.
160 .sp
161 Using the \fBmetadata\fP value for the \fBcacheonly\fP configuration can be advantageous when optional
162 repositories are temporarily unavailable or when we know they are unnecessary for our current
163 use case. It is also useful when cached metadata is not the latest or has expired but is still
164 functional.
165 .SH DELETE, CREATE, UPDATE
166 .sp
167 The following commands are used for manual cache deletion and creation:
168 .INDENT 0.0
169 .INDENT 3.5
170 .nf
171 \fBdnf5\-clean(8)\fP, Clean command \%<#\:clean-command-ref-label>
172 \fBdnf5\-makecache(8)\fP, Makecache command \%<#\:makecache-command-ref-label>
173 .fi
174 .sp
175 .UNINDENT
176 .UNINDENT
177 .sp
178 To force metadata update before executing a command, use the \fB\-\-refresh\fP parameter.
179 .SH Author
180 See AUTHORS.md in dnf5 source distribution.
181 .SH Copyright
182 Contributors to the dnf5 project.
183 .\" End of generated man page.