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