rev |
line source |
al@21165
|
1 --- a/doc/proot/man.1
|
al@21165
|
2 +++ b/doc/proot/man.1
|
al@21165
|
3 @@ -1,48 +1,19 @@
|
al@21165
|
4 -.\" Man page generated from reStructuredText.
|
al@21165
|
5 -.
|
al@21165
|
6 .TH PROOT 1 "2014-12-12" "5.1.0" ""
|
al@21165
|
7 .SH NAME
|
al@21165
|
8 -PRoot \- chroot, mount --bind, and binfmt_misc without privilege/setup
|
al@21165
|
9 -.
|
al@21165
|
10 -.nr rst2man-indent-level 0
|
al@21165
|
11 -.
|
al@21165
|
12 -.de1 rstReportMargin
|
al@21165
|
13 -\\$1 \\n[an-margin]
|
al@21165
|
14 -level \\n[rst2man-indent-level]
|
al@21165
|
15 -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
al@21165
|
16 --
|
al@21165
|
17 -\\n[rst2man-indent0]
|
al@21165
|
18 -\\n[rst2man-indent1]
|
al@21165
|
19 -\\n[rst2man-indent2]
|
al@21165
|
20 -..
|
al@21165
|
21 -.de1 INDENT
|
al@21165
|
22 -.\" .rstReportMargin pre:
|
al@21165
|
23 -. RS \\$1
|
al@21165
|
24 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
al@21165
|
25 -. nr rst2man-indent-level +1
|
al@21165
|
26 -.\" .rstReportMargin post:
|
al@21165
|
27 -..
|
al@21165
|
28 -.de UNINDENT
|
al@21165
|
29 -. RE
|
al@21165
|
30 -.\" indent \\n[an-margin]
|
al@21165
|
31 -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
al@21165
|
32 -.nr rst2man-indent-level -1
|
al@21165
|
33 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
al@21165
|
34 -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
al@21165
|
35 -..
|
al@21165
|
36 +PRoot \- chroot, mount \-\-bind, and binfmt_misc without privilege/setup
|
al@21165
|
37 .SH SYNOPSIS
|
al@21165
|
38 .sp
|
al@21165
|
39 \fBproot\fP [\fIoption\fP] ... [\fIcommand\fP]
|
al@21165
|
40 .SH DESCRIPTION
|
al@21165
|
41 .sp
|
al@21165
|
42 PRoot is a user\-space implementation of \fBchroot\fP, \fBmount \-\-bind\fP,
|
al@21165
|
43 -and \fBbinfmt_misc\fP\&. This means that users don\(aqt need any privileges
|
al@21165
|
44 +and \fBbinfmt_misc\fP\&. This means that users don't need any privileges
|
al@21165
|
45 or setup to do things like using an arbitrary directory as the new
|
al@21165
|
46 root filesystem, making files accessible somewhere else in the
|
al@21165
|
47 filesystem hierarchy, or executing programs built for another CPU
|
al@21165
|
48 architecture transparently through QEMU user\-mode. Also, developers
|
al@21165
|
49 can use PRoot as a generic Linux process instrumentation engine thanks
|
al@21165
|
50 -to its extension mechanism, see \fI\%CARE\fP for an example. Technically
|
al@21165
|
51 +to its extension mechanism, see \fICARE\fP for an example. Technically
|
al@21165
|
52 PRoot relies on \fBptrace\fP, an unprivileged system\-call available in
|
al@21165
|
53 every Linux kernel.
|
al@21165
|
54 .sp
|
al@21165
|
55 @@ -55,9 +26,9 @@
|
al@21165
|
56 .sp
|
al@21165
|
57 When the guest Linux distribution is made for a CPU architecture
|
al@21165
|
58 incompatible with the host one, PRoot uses the CPU emulator QEMU
|
al@21165
|
59 -user\-mode to execute transparently guest programs. It\(aqs a convenient
|
al@21165
|
60 +user\-mode to execute transparently guest programs. It's a convenient
|
al@21165
|
61 way to develop, to build, and to validate any guest Linux packages
|
al@21165
|
62 -seamlessly on users\(aq computer, just as if they were in a \fInative\fP
|
al@21165
|
63 +seamlessly on users' computer, just as if they were in a \fInative\fP
|
al@21165
|
64 guest environment. That way all of the cross\-compilation issues are
|
al@21165
|
65 avoided.
|
al@21165
|
66 .sp
|
al@21165
|
67 @@ -75,12 +46,11 @@
|
al@21165
|
68 if they were "normal" host programs.
|
al@21165
|
69 .SH OPTIONS
|
al@21165
|
70 .sp
|
al@21165
|
71 -The command\-line interface is composed of two parts: first PRoot\(aqs
|
al@21165
|
72 +The command\-line interface is composed of two parts: first PRoot's
|
al@21165
|
73 options (optional), then the command to launch (\fB/bin/sh\fP if not
|
al@21165
|
74 specified). This section describes the options supported by PRoot,
|
al@21165
|
75 that is, the first part of its command\-line interface.
|
al@21165
|
76 .SS Regular options
|
al@21165
|
77 -.INDENT 0.0
|
al@21165
|
78 .TP
|
al@21165
|
79 .BI \-r \ path\fP,\fB \ \-\-rootfs\fB= path
|
al@21165
|
80 Use \fIpath\fP as the new guest root file\-system, default is \fB/\fP\&.
|
al@21165
|
81 @@ -104,7 +74,7 @@
|
al@21165
|
82 guest location is a symbolic link, it is dereferenced to ensure
|
al@21165
|
83 the new content is accessible through all the symbolic links that
|
al@21165
|
84 point to the overlaid content. In most cases this default
|
al@21165
|
85 -behavior shouldn\(aqt be a problem, although it is possible to
|
al@21165
|
86 +behavior shouldn't be a problem, although it is possible to
|
al@21165
|
87 explicitly not dereference the guest location by appending it the
|
al@21165
|
88 \fB!\fP character: \fB\-b *host_path*:*guest_location!*\fP\&.
|
al@21165
|
89 .TP
|
al@21165
|
90 @@ -137,14 +107,12 @@
|
al@21165
|
91 .TP
|
al@21165
|
92 .B \-h\fP,\fB \-\-help\fP,\fB \-\-usage
|
al@21165
|
93 Print the version and the command\-line usage, then exit.
|
al@21165
|
94 -.UNINDENT
|
al@21165
|
95 .SS Extension options
|
al@21165
|
96 .sp
|
al@21165
|
97 The following options enable built\-in extensions. Technically
|
al@21165
|
98 developers can add their own features to PRoot or use it as a Linux
|
al@21165
|
99 process instrumentation engine thanks to its extension mechanism, see
|
al@21165
|
100 the sources for further details.
|
al@21165
|
101 -.INDENT 0.0
|
al@21165
|
102 .TP
|
al@21165
|
103 .BI \-k \ string\fP,\fB \ \-\-kernel\-release\fB= string
|
al@21165
|
104 Make current kernel appear as kernel release \fIstring\fP\&.
|
al@21165
|
105 @@ -174,11 +142,9 @@
|
al@21165
|
106 \fIgid\fP\&. Likewise, files actually owned by the current user and
|
al@21165
|
107 group appear as if they were owned by \fIuid\fP and \fIgid\fP instead.
|
al@21165
|
108 Note that the \fB\-0\fP option is the same as \fB\-i 0:0\fP\&.
|
al@21165
|
109 -.UNINDENT
|
al@21165
|
110 .SS Alias options
|
al@21165
|
111 .sp
|
al@21165
|
112 The following options are aliases for handy sets of options.
|
al@21165
|
113 -.INDENT 0.0
|
al@21165
|
114 .TP
|
al@21165
|
115 .BI \-R \ path
|
al@21165
|
116 Alias: \fB\-r *path*\fP + a couple of recommended \fB\-b\fP\&.
|
al@21165
|
117 @@ -187,10 +153,9 @@
|
al@21165
|
118 access information about the host system, as it is illustrated in
|
al@21165
|
119 the \fBExamples\fP section of the manual. These host information
|
al@21165
|
120 are typically: user/group definition, network setup, run\-time
|
al@21165
|
121 -information, users\(aq files, ... On all Linux distributions, they
|
al@21165
|
122 +information, users' files, ... On all Linux distributions, they
|
al@21165
|
123 all lie in a couple of host files and directories that are
|
al@21165
|
124 automatically bound by this option:
|
al@21165
|
125 -.INDENT 7.0
|
al@21165
|
126 .IP \(bu 2
|
al@21165
|
127 /etc/host.conf
|
al@21165
|
128 .IP \(bu 2
|
al@21165
|
129 @@ -229,7 +194,6 @@
|
al@21165
|
130 $HOME
|
al@21165
|
131 .IP \(bu 2
|
al@21165
|
132 \fIpath\fP
|
al@21165
|
133 -.UNINDENT
|
al@21165
|
134 .TP
|
al@21165
|
135 .BI \-S \ path
|
al@21165
|
136 Alias: \fB\-0 \-r *path*\fP + a couple of recommended \fB\-b\fP\&.
|
al@21165
|
137 @@ -238,7 +202,6 @@
|
al@21165
|
138 the guest rootfs. It is similar to the \fB\-R\fP option expect it
|
al@21165
|
139 enables the \fB\-0\fP option and binds only the following minimal set
|
al@21165
|
140 of paths to avoid unexpected changes on host files:
|
al@21165
|
141 -.INDENT 7.0
|
al@21165
|
142 .IP \(bu 2
|
al@21165
|
143 /etc/host.conf
|
al@21165
|
144 .IP \(bu 2
|
al@21165
|
145 @@ -261,8 +224,6 @@
|
al@21165
|
146 $HOME
|
al@21165
|
147 .IP \(bu 2
|
al@21165
|
148 \fIpath\fP
|
al@21165
|
149 -.UNINDENT
|
al@21165
|
150 -.UNINDENT
|
al@21165
|
151 .SH EXIT STATUS
|
al@21165
|
152 .sp
|
al@21165
|
153 If an internal error occurs, \fBproot\fP returns a non\-zero exit status,
|
al@21165
|
154 @@ -285,8 +246,6 @@
|
al@21165
|
155 \fBproot\fP the path to the guest rootfs followed by the desired
|
al@21165
|
156 command. The example below executes the program \fBcat\fP to print the
|
al@21165
|
157 content of a file:
|
al@21165
|
158 -.INDENT 0.0
|
al@21165
|
159 -.INDENT 3.5
|
al@21165
|
160 .sp
|
al@21165
|
161 .nf
|
al@21165
|
162 .ft C
|
al@21165
|
163 @@ -295,14 +254,10 @@
|
al@21165
|
164 Welcome to Slackware Linux 8.0
|
al@21165
|
165 .ft P
|
al@21165
|
166 .fi
|
al@21165
|
167 -.UNINDENT
|
al@21165
|
168 -.UNINDENT
|
al@21165
|
169 .sp
|
al@21165
|
170 The default command is \fB/bin/sh\fP when none is specified. Thus the
|
al@21165
|
171 shortest way to confine an interactive shell and all its sub\-programs
|
al@21165
|
172 is:
|
al@21165
|
173 -.INDENT 0.0
|
al@21165
|
174 -.INDENT 3.5
|
al@21165
|
175 .sp
|
al@21165
|
176 .nf
|
al@21165
|
177 .ft C
|
al@21165
|
178 @@ -312,15 +267,11 @@
|
al@21165
|
179 Welcome to Slackware Linux 8.0
|
al@21165
|
180 .ft P
|
al@21165
|
181 .fi
|
al@21165
|
182 -.UNINDENT
|
al@21165
|
183 -.UNINDENT
|
al@21165
|
184 .SS \fBmount \-\-bind\fP equivalent
|
al@21165
|
185 .sp
|
al@21165
|
186 The bind mechanism enables one to relocate files and directories. This is
|
al@21165
|
187 typically useful to trick programs that perform access to hard\-coded
|
al@21165
|
188 locations, like some installation scripts:
|
al@21165
|
189 -.INDENT 0.0
|
al@21165
|
190 -.INDENT 3.5
|
al@21165
|
191 .sp
|
al@21165
|
192 .nf
|
al@21165
|
193 .ft C
|
al@21165
|
194 @@ -333,14 +284,10 @@
|
al@21165
|
195 [...] # prog is installed in "/tmp/alternate_opt/bin" actually
|
al@21165
|
196 .ft P
|
al@21165
|
197 .fi
|
al@21165
|
198 -.UNINDENT
|
al@21165
|
199 -.UNINDENT
|
al@21165
|
200 .sp
|
al@21165
|
201 As shown in this example, it is possible to bind over files not even
|
al@21165
|
202 owned by the user. This can be used to \fIoverlay\fP system configuration
|
al@21165
|
203 files, for instance the DNS setting:
|
al@21165
|
204 -.INDENT 0.0
|
al@21165
|
205 -.INDENT 3.5
|
al@21165
|
206 .sp
|
al@21165
|
207 .nf
|
al@21165
|
208 .ft C
|
al@21165
|
209 @@ -348,25 +295,19 @@
|
al@21165
|
210 \-rw\-r\-\-r\-\- 1 root root 675 Mar 4 2011 /etc/hosts
|
al@21165
|
211 .ft P
|
al@21165
|
212 .fi
|
al@21165
|
213 -.UNINDENT
|
al@21165
|
214 -.UNINDENT
|
al@21165
|
215 -.INDENT 0.0
|
al@21165
|
216 -.INDENT 3.5
|
al@21165
|
217 .sp
|
al@21165
|
218 .nf
|
al@21165
|
219 .ft C
|
al@21165
|
220 proot \-b ~/alternate_hosts:/etc/hosts
|
al@21165
|
221
|
al@21165
|
222 -$ echo \(aq1.2.3.4 google.com\(aq > /etc/hosts
|
al@21165
|
223 +$ echo '1.2.3.4 google.com' > /etc/hosts
|
al@21165
|
224 $ resolveip google.com
|
al@21165
|
225 IP address of google.com is 1.2.3.4
|
al@21165
|
226 -$ echo \(aq5.6.7.8 google.com\(aq > /etc/hosts
|
al@21165
|
227 +$ echo '5.6.7.8 google.com' > /etc/hosts
|
al@21165
|
228 $ resolveip google.com
|
al@21165
|
229 IP address of google.com is 5.6.7.8
|
al@21165
|
230 .ft P
|
al@21165
|
231 .fi
|
al@21165
|
232 -.UNINDENT
|
al@21165
|
233 -.UNINDENT
|
al@21165
|
234 .sp
|
al@21165
|
235 Another example: on most Linux distributions \fB/bin/sh\fP is a symbolic
|
al@21165
|
236 link to \fB/bin/bash\fP, whereas it points to \fB/bin/dash\fP on Debian
|
al@21165
|
237 @@ -374,21 +315,15 @@
|
al@21165
|
238 might not work with Dash. In this case, the binding mechanism of
|
al@21165
|
239 PRoot can be used to set non\-disruptively \fB/bin/bash\fP as the default
|
al@21165
|
240 \fB/bin/sh\fP on these two Linux distributions:
|
al@21165
|
241 -.INDENT 0.0
|
al@21165
|
242 -.INDENT 3.5
|
al@21165
|
243 .sp
|
al@21165
|
244 .nf
|
al@21165
|
245 .ft C
|
al@21165
|
246 proot \-b /bin/bash:/bin/sh [...]
|
al@21165
|
247 .ft P
|
al@21165
|
248 .fi
|
al@21165
|
249 -.UNINDENT
|
al@21165
|
250 -.UNINDENT
|
al@21165
|
251 .sp
|
al@21165
|
252 Because \fB/bin/sh\fP is initially a symbolic link to \fB/bin/dash\fP, the
|
al@21165
|
253 content of \fB/bin/bash\fP is actually bound over this latter:
|
al@21165
|
254 -.INDENT 0.0
|
al@21165
|
255 -.INDENT 3.5
|
al@21165
|
256 .sp
|
al@21165
|
257 .nf
|
al@21165
|
258 .ft C
|
al@21165
|
259 @@ -402,18 +337,14 @@
|
al@21165
|
260 089ed56cd74e63f461bef0fdfc2d159a /bin/dash
|
al@21165
|
261 .ft P
|
al@21165
|
262 .fi
|
al@21165
|
263 -.UNINDENT
|
al@21165
|
264 -.UNINDENT
|
al@21165
|
265 .sp
|
al@21165
|
266 -In most cases this shouldn\(aqt be a problem, but it is still possible to
|
al@21165
|
267 +In most cases this shouldn't be a problem, but it is still possible to
|
al@21165
|
268 strictly bind \fB/bin/bash\fP over \fB/bin/sh\fP \-\- without dereferencing
|
al@21165
|
269 it \-\- by specifying the \fB!\fP character at the end:
|
al@21165
|
270 -.INDENT 0.0
|
al@21165
|
271 -.INDENT 3.5
|
al@21165
|
272 .sp
|
al@21165
|
273 .nf
|
al@21165
|
274 .ft C
|
al@21165
|
275 -proot \-b \(aq/bin/bash:/bin/sh!\(aq
|
al@21165
|
276 +proot \-b '/bin/bash:/bin/sh!'
|
al@21165
|
277
|
al@21165
|
278 $ md5sum /bin/sh
|
al@21165
|
279 089ed56cd74e63f461bef0fdfc2d159a /bin/sh
|
al@21165
|
280 @@ -423,16 +354,12 @@
|
al@21165
|
281 c229085928dc19e8d9bd29fe88268504 /bin/dash
|
al@21165
|
282 .ft P
|
al@21165
|
283 .fi
|
al@21165
|
284 -.UNINDENT
|
al@21165
|
285 -.UNINDENT
|
al@21165
|
286 .SS \fBchroot\fP + \fBmount \-\-bind\fP equivalent
|
al@21165
|
287 .sp
|
al@21165
|
288 The two features above can be combined to make any file from the host
|
al@21165
|
289 rootfs accessible in the confined environment just as if it were
|
al@21165
|
290 initially part of the guest rootfs. It is sometimes required to run
|
al@21165
|
291 programs that rely on some specific files:
|
al@21165
|
292 -.INDENT 0.0
|
al@21165
|
293 -.INDENT 3.5
|
al@21165
|
294 .sp
|
al@21165
|
295 .nf
|
al@21165
|
296 .ft C
|
al@21165
|
297 @@ -442,12 +369,8 @@
|
al@21165
|
298 Error, do this: mount \-t proc none /proc
|
al@21165
|
299 .ft P
|
al@21165
|
300 .fi
|
al@21165
|
301 -.UNINDENT
|
al@21165
|
302 -.UNINDENT
|
al@21165
|
303 .sp
|
al@21165
|
304 works better with:
|
al@21165
|
305 -.INDENT 0.0
|
al@21165
|
306 -.INDENT 3.5
|
al@21165
|
307 .sp
|
al@21165
|
308 .nf
|
al@21165
|
309 .ft C
|
al@21165
|
310 @@ -461,14 +384,10 @@
|
al@21165
|
311 ? ps \-o tty,command
|
al@21165
|
312 .ft P
|
al@21165
|
313 .fi
|
al@21165
|
314 -.UNINDENT
|
al@21165
|
315 -.UNINDENT
|
al@21165
|
316 .sp
|
al@21165
|
317 -Actually there\(aqs a bunch of such specific files, that\(aqs why PRoot
|
al@21165
|
318 +Actually there's a bunch of such specific files, that's why PRoot
|
al@21165
|
319 provides the option \fB\-R\fP to bind automatically a pre\-defined list of
|
al@21165
|
320 recommended paths:
|
al@21165
|
321 -.INDENT 0.0
|
al@21165
|
322 -.INDENT 3.5
|
al@21165
|
323 .sp
|
al@21165
|
324 .nf
|
al@21165
|
325 .ft C
|
al@21165
|
326 @@ -482,16 +401,12 @@
|
al@21165
|
327 pts/6 ps \-o tty,command
|
al@21165
|
328 .ft P
|
al@21165
|
329 .fi
|
al@21165
|
330 -.UNINDENT
|
al@21165
|
331 -.UNINDENT
|
al@21165
|
332 .SS \fBchroot\fP + \fBmount \-\-bind\fP + \fBsu\fP equivalent
|
al@21165
|
333 .sp
|
al@21165
|
334 Some programs will not work correctly if they are not run by the
|
al@21165
|
335 "root" user, this is typically the case with package managers. PRoot
|
al@21165
|
336 can fake the root identity and its privileges when the \fB\-0\fP (zero)
|
al@21165
|
337 option is specified:
|
al@21165
|
338 -.INDENT 0.0
|
al@21165
|
339 -.INDENT 3.5
|
al@21165
|
340 .sp
|
al@21165
|
341 .nf
|
al@21165
|
342 .ft C
|
al@21165
|
343 @@ -502,13 +417,11 @@
|
al@21165
|
344
|
al@21165
|
345 # mkdir /tmp/foo
|
al@21165
|
346 # chmod a\-rwx /tmp/foo
|
al@21165
|
347 -# echo \(aqI bypass file\-system permissions.\(aq > /tmp/foo/bar
|
al@21165
|
348 +# echo 'I bypass file\-system permissions.' > /tmp/foo/bar
|
al@21165
|
349 # cat /tmp/foo/bar
|
al@21165
|
350 I bypass file\-system permissions.
|
al@21165
|
351 .ft P
|
al@21165
|
352 .fi
|
al@21165
|
353 -.UNINDENT
|
al@21165
|
354 -.UNINDENT
|
al@21165
|
355 .sp
|
al@21165
|
356 This option is typically required to create or install packages into
|
al@21165
|
357 the guest rootfs. Note it is \fInot\fP recommended to use the \fB\-R\fP
|
al@21165
|
358 @@ -516,8 +429,6 @@
|
al@21165
|
359 system files, like \fB/etc/group\fP\&. Instead, it is recommended to use
|
al@21165
|
360 the \fB\-S\fP option. This latter enables the \fB\-0\fP option and binds
|
al@21165
|
361 only paths that are known to not be updated by packages:
|
al@21165
|
362 -.INDENT 0.0
|
al@21165
|
363 -.INDENT 3.5
|
al@21165
|
364 .sp
|
al@21165
|
365 .nf
|
al@21165
|
366 .ft C
|
al@21165
|
367 @@ -527,18 +438,14 @@
|
al@21165
|
368 Installing package perl...
|
al@21165
|
369 .ft P
|
al@21165
|
370 .fi
|
al@21165
|
371 -.UNINDENT
|
al@21165
|
372 -.UNINDENT
|
al@21165
|
373 .SS \fBchroot\fP + \fBmount \-\-bind\fP + \fBbinfmt_misc\fP equivalent
|
al@21165
|
374 .sp
|
al@21165
|
375 PRoot uses QEMU user\-mode to execute programs built for a CPU
|
al@21165
|
376 -architecture incompatible with the host one. From users\(aq
|
al@21165
|
377 +architecture incompatible with the host one. From users'
|
al@21165
|
378 point\-of\-view, guest programs handled by QEMU user\-mode are executed
|
al@21165
|
379 transparently, that is, just like host programs. To enable this
|
al@21165
|
380 feature users just have to specify which instance of QEMU user\-mode
|
al@21165
|
381 they want to use with the option \fB\-q\fP:
|
al@21165
|
382 -.INDENT 0.0
|
al@21165
|
383 -.INDENT 3.5
|
al@21165
|
384 .sp
|
al@21165
|
385 .nf
|
al@21165
|
386 .ft C
|
al@21165
|
387 @@ -548,31 +455,23 @@
|
al@21165
|
388 Welcome to ARMedSlack Linux 12.2
|
al@21165
|
389 .ft P
|
al@21165
|
390 .fi
|
al@21165
|
391 -.UNINDENT
|
al@21165
|
392 -.UNINDENT
|
al@21165
|
393 .sp
|
al@21165
|
394 The parameter of the \fB\-q\fP option is actually a whole QEMU user\-mode
|
al@21165
|
395 command, for instance to enable its GDB server on port 1234:
|
al@21165
|
396 -.INDENT 0.0
|
al@21165
|
397 -.INDENT 3.5
|
al@21165
|
398 .sp
|
al@21165
|
399 .nf
|
al@21165
|
400 .ft C
|
al@21165
|
401 proot \-R /mnt/armslack\-12.2/ \-q "qemu\-arm \-g 1234" emacs
|
al@21165
|
402 .ft P
|
al@21165
|
403 .fi
|
al@21165
|
404 -.UNINDENT
|
al@21165
|
405 -.UNINDENT
|
al@21165
|
406 .sp
|
al@21165
|
407 PRoot allows one to mix transparently the emulated execution of guest
|
al@21165
|
408 programs and the native execution of host programs in the same
|
al@21165
|
409 -file\-system namespace. It\(aqs typically useful to extend the list of
|
al@21165
|
410 +file\-system namespace. It's typically useful to extend the list of
|
al@21165
|
411 available programs and to speed up build\-time significantly. This
|
al@21165
|
412 mixed\-execution feature is enabled by default when using QEMU
|
al@21165
|
413 user\-mode, and the content of the host rootfs is made accessible
|
al@21165
|
414 through \fB/host\-rootfs\fP:
|
al@21165
|
415 -.INDENT 0.0
|
al@21165
|
416 -.INDENT 3.5
|
al@21165
|
417 .sp
|
al@21165
|
418 .nf
|
al@21165
|
419 .ft C
|
al@21165
|
420 @@ -580,24 +479,20 @@
|
al@21165
|
421
|
al@21165
|
422 $ file /bin/echo
|
al@21165
|
423 [...] ELF 32\-bit LSB executable, ARM [...]
|
al@21165
|
424 -$ /bin/echo \(aqHello world!\(aq
|
al@21165
|
425 +$ /bin/echo 'Hello world!'
|
al@21165
|
426 Hello world!
|
al@21165
|
427
|
al@21165
|
428 $ file /host\-rootfs/bin/echo
|
al@21165
|
429 [...] ELF 64\-bit LSB executable, x86\-64 [...]
|
al@21165
|
430 -$ /host\-rootfs/bin/echo \(aqHello mixed world!\(aq
|
al@21165
|
431 +$ /host\-rootfs/bin/echo 'Hello mixed world!'
|
al@21165
|
432 Hello mixed world!
|
al@21165
|
433 .ft P
|
al@21165
|
434 .fi
|
al@21165
|
435 -.UNINDENT
|
al@21165
|
436 -.UNINDENT
|
al@21165
|
437 .sp
|
al@21165
|
438 Since both host and guest programs use the guest rootfs as \fB/\fP,
|
al@21165
|
439 users may want to deactivate explicitly cross\-filesystem support found
|
al@21165
|
440 in most GNU cross\-compilation tools. For example with GCC configured
|
al@21165
|
441 to cross\-compile to the ARM target:
|
al@21165
|
442 -.INDENT 0.0
|
al@21165
|
443 -.INDENT 3.5
|
al@21165
|
444 .sp
|
al@21165
|
445 .nf
|
al@21165
|
446 .ft C
|
al@21165
|
447 @@ -608,14 +503,10 @@
|
al@21165
|
448 $ ./configure; make
|
al@21165
|
449 .ft P
|
al@21165
|
450 .fi
|
al@21165
|
451 -.UNINDENT
|
al@21165
|
452 -.UNINDENT
|
al@21165
|
453 .sp
|
al@21165
|
454 As with regular files, a host instance of a program can be bound over
|
al@21165
|
455 its guest instance. Here is an example where the guest binary of
|
al@21165
|
456 \fBmake\fP is overlaid by the host one:
|
al@21165
|
457 -.INDENT 0.0
|
al@21165
|
458 -.INDENT 3.5
|
al@21165
|
459 .sp
|
al@21165
|
460 .nf
|
al@21165
|
461 .ft C
|
al@21165
|
462 @@ -628,31 +519,24 @@
|
al@21165
|
463 Built for x86_64\-slackware\-linux\-gnu
|
al@21165
|
464 .ft P
|
al@21165
|
465 .fi
|
al@21165
|
466 -.UNINDENT
|
al@21165
|
467 -.UNINDENT
|
al@21165
|
468 .sp
|
al@21165
|
469 -It\(aqs worth mentioning that even when mixing the native execution of
|
al@21165
|
470 +It's worth mentioning that even when mixing the native execution of
|
al@21165
|
471 host programs and the emulated execution of guest programs, they still
|
al@21165
|
472 believe they are running in a native guest environment. As a
|
al@21165
|
473 demonstration, here is a partial output of a typical \fB\&./configure\fP
|
al@21165
|
474 script:
|
al@21165
|
475 -.INDENT 0.0
|
al@21165
|
476 -.INDENT 3.5
|
al@21165
|
477 .sp
|
al@21165
|
478 .nf
|
al@21165
|
479 .ft C
|
al@21165
|
480 checking whether the C compiler is a cross\-compiler... no
|
al@21165
|
481 .ft P
|
al@21165
|
482 .fi
|
al@21165
|
483 -.UNINDENT
|
al@21165
|
484 -.UNINDENT
|
al@21165
|
485 .SH DOWNLOADS
|
al@21165
|
486 .SS PRoot
|
al@21165
|
487 .sp
|
al@21165
|
488 The latest release of PRoot is packaged on \fI\%http://packages.proot.me\fP
|
al@21165
|
489 and sources are hosted on \fI\%http://github.proot.me\fP\&. It is also
|
al@21165
|
490 available as highly compatible static binaries:
|
al@21165
|
491 -.INDENT 0.0
|
al@21165
|
492 .IP \(bu 2
|
al@21165
|
493 for x86_64: \fI\%http://static.proot.me/proot\-x86_64\fP
|
al@21165
|
494 .IP \(bu 2
|
al@21165
|
495 @@ -661,14 +545,12 @@
|
al@21165
|
496 for ARM: \fI\%http://static.proot.me/proot\-arm\fP
|
al@21165
|
497 .IP \(bu 2
|
al@21165
|
498 other architectures: on demand.
|
al@21165
|
499 -.UNINDENT
|
al@21165
|
500 .SS Rootfs
|
al@21165
|
501 .sp
|
al@21165
|
502 Here follows a couple of URLs where some rootfs archives can be freely
|
al@21165
|
503 downloaded. Note that \fBmknod\fP errors reported by \fBtar\fP when
|
al@21165
|
504 extracting these archives can be safely ignored since special files
|
al@21165
|
505 are typically bound (see \fB\-R\fP option for details).
|
al@21165
|
506 -.INDENT 0.0
|
al@21165
|
507 .IP \(bu 2
|
al@21165
|
508 \fI\%http://download.openvz.org/template/precreated/\fP
|
al@21165
|
509 .IP \(bu 2
|
al@21165
|
510 @@ -679,20 +561,15 @@
|
al@21165
|
511 \fI\%http://cdimage.ubuntu.com/ubuntu\-core/releases/\fP
|
al@21165
|
512 .IP \(bu 2
|
al@21165
|
513 \fI\%http://archlinuxarm.org/developers/downloads\fP
|
al@21165
|
514 -.UNINDENT
|
al@21165
|
515 .sp
|
al@21165
|
516 Technically such rootfs archive can be created by running the
|
al@21165
|
517 following command on the expected Linux distribution:
|
al@21165
|
518 -.INDENT 0.0
|
al@21165
|
519 -.INDENT 3.5
|
al@21165
|
520 .sp
|
al@21165
|
521 .nf
|
al@21165
|
522 .ft C
|
al@21165
|
523 tar \-\-one\-file\-system \-\-create \-\-gzip \-\-file my_rootfs.tar.gz /
|
al@21165
|
524 .ft P
|
al@21165
|
525 .fi
|
al@21165
|
526 -.UNINDENT
|
al@21165
|
527 -.UNINDENT
|
al@21165
|
528 .SS QEMU user\-mode
|
al@21165
|
529 .sp
|
al@21165
|
530 QEMU user\-mode is required only if the guest rootfs was made for a CPU
|
al@21165
|
531 @@ -710,8 +587,6 @@
|
al@21165
|
532 .sp
|
al@21165
|
533 Visit \fI\%http://proot.me\fP for help, bug reports, suggestions, patches, ...
|
al@21165
|
534 Copyright (C) 2014 STMicroelectronics, licensed under GPL v2 or later.
|
al@21165
|
535 -.INDENT 0.0
|
al@21165
|
536 -.INDENT 3.5
|
al@21165
|
537 .sp
|
al@21165
|
538 .nf
|
al@21165
|
539 .ft C
|
al@21165
|
540 @@ -721,7 +596,4 @@
|
al@21165
|
541 |__| |__|__\e_____/\e_____/\e____|
|
al@21165
|
542 .ft P
|
al@21165
|
543 .fi
|
al@21165
|
544 -.UNINDENT
|
al@21165
|
545 -.UNINDENT
|
al@21165
|
546 -.\" Generated by docutils manpage writer.
|
al@21165
|
547 .
|