1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PACUTILS-SYSROOT 7"
.TH PACUTILS-SYSROOT 7 "2021-08-14" "pacutils" "pacutils-sysroot"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
pacutils\-sysroot \- managing a mounted guest system
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Managing Guests with \-\-root"
.IX Subsection "Managing Guests with --root"
When a libalpm-based installation becomes broken to the point that the package
manager itself can no longer be used, it must be fixed by loading a working
environment and mounting the installation in need of repair as a guest.
Typically this is done by setting the installation root to the guest with the
\&\fB\-\-root\fR option. Libalpm only uses the installation root to determine where
to install and remove files during package transactions. It is completely
independent of all other configuration options. This makes using \fB\-\-root\fR
unreliable for managing a mounted guest.
.PP
The first issue is that when changing the installation root, the host system's
configuration is still used. Because the installation root is a configuration
option (\f(CW\*(C`RootDir\*(C'\fR) it cannot be used to load an alternate configuration file.
Even if \fB\-\-config\fR is added to load the guest configuration, any \f(CW\*(C`Include\*(C'\fR'd
paths will still be resolved relative to the host's root. The only way to
actually use the guest's configuration without using \f(CW\*(C`chroot\*(C'\fR is to use
\&\fB\-\-config\fR and manually add the mount path to all \f(CW\*(C`Include\*(C'\fR paths.
.PP
Now the guest configuration files are being used, but all configured paths will
still refer to paths under to the host's root, not the guest's. If an
installation root is explicitly provided, pacman and pacutils will set defaults
for some, but not all, configuration paths to be underneath it. This typically
works, because those paths are rarely explicitly set, so the defaults generally
do the correct thing. If they have been set, however, the configured values
will be used without modification. In order to reliably operate on the guest,
all configuration paths must be set relative to the installation root (except
for the database and log file paths which will default to paths inside the
installation root if unset).
.SS "Introducing the Sysroot"
.IX Subsection "Introducing the Sysroot"
This is a significant amount of work just to run operate on a mounted system.
In order to allow reliable operating on a mounted guest, pacman and pacutils
have added the concept of a \*(L"sysroot\*(R". The sysroot is what is commonly
intended when using the \fB\-\-root\fR option; the program will operate as if the
sysroot were actually the filesystem root. This is similar to using \f(CW\*(C`chroot\*(C'\fR
to enter the mounted system before running the program, but still runs the
host's copy. There are two ways to do this: chroot into the sysroot shortly
after startup prior to reading any configuration or prepend the sysroot to all
paths.
.PP
Using \f(CW\*(C`chroot\*(C'\fR directly can cause problems with libraries that use delayed
loading of configuration files or shared objects. Notably, glibc delays
loading certain objects until their functionality is actually used. This can
cause a mismatch between components loaded prior to the \f(CW\*(C`chroot\*(C'\fR and those
loaded after. To avoid this problem, libalpm should generally be configured to
use paths under the sysroot without actually calling \f(CW\*(C`chroot\*(C'\fR.
.PP
Pacutils provides sysroot-aware versions of its configuration parsing functions
to simplify the process. Note that the sysroot is prepended to all paths
during config resolution. Programs using the sysroot configuration parsing
routines should \fB\s-1NOT\s0\fR prepend the sysroot to configuration paths provided on
the command line.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 3
\& #include <alpm.h>
\& #include <getopt.h>
\& #include <pacutils.h>
\&
\& enum {
\& FLAG_CONFIG = 1,
\& FLAG_SYSROOT,
\& };
\&
\& int main(int argc, char *argv[]) {
\& const char *config_file = "/etc/pacman.conf";
\& const char *sysroot = NULL;
\& alpm_handle_t *handle = NULL;
\& pu_config_t *config = NULL;
\&
\& struct option long_opts[] = {
\& { "config" , required_argument , NULL , FLAG_CONFIG } ,
\& { "sysroot" , required_argument , NULL , FLAG_SYSROOT } ,
\& { 0, 0, 0, 0 },
\& };
\& while((c = getopt_long(argc, argv, short_opts, long_opts, NULL)) != \-1) {
\& switch(c) {
\& case FLAG_CONFIG: config_file = optarg; break;
\& case FLAG_SYSROOT: sysroot = optarg; break;
\& case \*(Aq?\*(Aq: return 1; /* getopt_long already printed an error message */
\& }
\& }
\& if((config = pu_ui_config_load_sysroot(NULL, config_file, sysroot)) == NULL)
\& { return 1; } /* load_sysroot already printed an error message */
\&
\& if(!(handle = pu_initialize_handle_from_config(config))) {
\& fprintf(stderr, "error: failed to initialize alpm.\en");
\& return 1;
\& }
\&
\& puts(alpm_option_get_root(handle));
\&
\& pu_config_free(config);
\& alpm_release(handle);
\&
\& return 0;
\& }
.Ve
|
