1 |
pappy 08/04/01 11:56:41 |
2 |
|
3 |
Added: devel-chroots-intro.xml |
4 |
Log: |
5 |
adding the devel-chroots-intro docs |
6 |
|
7 |
Revision Changes Path |
8 |
1.1 xml/htdocs/proj/en/extreme-security/solutions/utils/chroots/devel-chroots-intro.xml |
9 |
|
10 |
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/extreme-security/solutions/utils/chroots/devel-chroots-intro.xml?rev=1.1&view=markup |
11 |
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/extreme-security/solutions/utils/chroots/devel-chroots-intro.xml?rev=1.1&content-type=text/plain |
12 |
|
13 |
Index: devel-chroots-intro.xml |
14 |
=================================================================== |
15 |
<?xml version="1.0" encoding="UTF-8"?> |
16 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
17 |
<!-- $Header $ --> |
18 |
|
19 |
<guide link="http://www.gentoo.org/proj/en/hardened/devel-chroots-intro.xml" lang="en"> |
20 |
|
21 |
<title>Developer Chroots Utility Guide</title> |
22 |
|
23 |
<author title="Author"> |
24 |
<mail link="pappy@g.o">Alexander Gabert</mail> |
25 |
</author> |
26 |
|
27 |
<abstract> |
28 |
This guide covers the installation, configuration and set up |
29 |
of chroots using a tool developed for the Gentoo dev machines. |
30 |
</abstract> |
31 |
|
32 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
33 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
34 |
<license/> |
35 |
|
36 |
<version>1.0</version> |
37 |
<date>2006-12-06</date> |
38 |
|
39 |
<chapter> |
40 |
<title>Introduction</title> |
41 |
<section> |
42 |
<title>What is this all about?</title> |
43 |
<body> |
44 |
|
45 |
<p> |
46 |
The normal procedure for a developer setting up a chroot is |
47 |
to fetch a stage, find a directory where to unpack it, unroll the stage, |
48 |
make some modifications to basic files like <c>/etc/resolv.conf</c>, |
49 |
<c>/etc/hosts</c> and others. |
50 |
Then she or he is usually incorporating some kind of custom script |
51 |
to start the chroot again once the machine gets rebooted |
52 |
or she/he needs to reenter it for another reason. |
53 |
More advanced scripts use screen sessions for making the chroot |
54 |
command launching the chroot independent of the |
55 |
currently connected user. |
56 |
</p> |
57 |
|
58 |
<p> |
59 |
However, lots of these scripts exist and people are using more |
60 |
and more chroots on our development servers, |
61 |
which is a very good thing in fact because it's relieving stress |
62 |
off the main system and is making our production systems |
63 |
more stable if development is done inside contained chroots. |
64 |
</p> |
65 |
|
66 |
<p> |
67 |
There has been a previous version of <c>devel-chroots</c>, |
68 |
but the old version only had limited multiuser capabilities and |
69 |
was rather bulky compared to the code in the script and the |
70 |
configuration abilities of the different chroots. |
71 |
</p> |
72 |
|
73 |
<p> |
74 |
For this reason, the new version of <c>devel-chroots</c> has been |
75 |
completely rewritten and is using a three-layered approach |
76 |
of configuration data for setting up chroots and populating |
77 |
the config files in these. |
78 |
</p> |
79 |
|
80 |
<p> |
81 |
Finishing this introduction, this guide is not meant to be exclusive |
82 |
to Gentoo development machines and their maintainers and users, |
83 |
the tool has been developed to be usable on any machine |
84 |
where chroots should be set up in an automatic and configurable fashion. |
85 |
</p> |
86 |
|
87 |
<p> |
88 |
Your input is welcome and there is always room for improving |
89 |
this little program as it aims at easing development and promotes |
90 |
thorough regression and live testing by providing an easy way |
91 |
of setting up a testbed, which a chroot basically is. |
92 |
</p> |
93 |
|
94 |
</body> |
95 |
</section> |
96 |
</chapter> |
97 |
|
98 |
<chapter> |
99 |
<title>Installation</title> |
100 |
<section> |
101 |
<title>Ebuild installation</title> |
102 |
<body> |
103 |
|
104 |
<p> |
105 |
The utility can be emerged with the following shell command: |
106 |
</p> |
107 |
|
108 |
<note> |
109 |
If you want to emerge only the basic tool without the sample configuration, |
110 |
activate the <c>"minimal"</c> USE-flag. |
111 |
</note> |
112 |
|
113 |
<pre caption="Installation of devel-chroots"> |
114 |
# <i>USE="-minimal" emerge -pv devel-chroots</i> |
115 |
|
116 |
These are the packages that would be merged, in order: |
117 |
|
118 |
Calculating dependencies... done! |
119 |
[ebuild R ] dev-util/devel-chroots-2.0.0 USE="-minimal*" 0 kB |
120 |
|
121 |
Total size of downloads: 0 kB |
122 |
|
123 |
# <i>USE="-minimal" emerge -v devel-chroots</i> |
124 |
</pre> |
125 |
|
126 |
<pre caption="Installation of devel-chroots without configuration files"> |
127 |
# <i>USE="minimal" emerge -pv devel-chroots</i> |
128 |
|
129 |
These are the packages that would be merged, in order: |
130 |
|
131 |
Calculating dependencies... done! |
132 |
[ebuild R ] dev-util/devel-chroots-2.0.0 USE="minimal" 0 kB |
133 |
|
134 |
Total size of downloads: 0 kB |
135 |
|
136 |
# <i>USE="minimal" emerge -v devel-chroots</i> |
137 |
</pre> |
138 |
|
139 |
</body> |
140 |
</section> |
141 |
|
142 |
<section> |
143 |
<title>Fetching the source code</title> |
144 |
<body> |
145 |
|
146 |
<p> |
147 |
The source code for the project can be found in the following |
148 |
anonymous <c>cvs</c> or <c>svn</c> location, along with viewcvs: |
149 |
</p> |
150 |
|
151 |
<pre caption="fetching the project source code with anonymous cvs"> |
152 |
/tmp/dc $ <i>cvs -d :pserver:anonymous@××××××××××××××.org/var/cvsroot co gentoo-projects</i> |
153 |
</pre> |
154 |
|
155 |
<pre caption="fetching the project source code with anonymous svn"> |
156 |
/tmp/dc $ <i>svn co http://anonsvn.gentoo.org/repositories/gentoo-projects</i> |
157 |
</pre> |
158 |
|
159 |
<p> |
160 |
Then dive into the |
161 |
<c>gentoo-projects/devel-chroots/devel-chroots-2.0.0/</c> |
162 |
directory to see the source code for the project. |
163 |
</p> |
164 |
|
165 |
<p> |
166 |
As you can see, it's just the same as the scripts |
167 |
that are getting installed by the ebuild. |
168 |
Which positively means that you can theoretically also use |
169 |
these scripts without having an ebuild install them. |
170 |
</p> |
171 |
|
172 |
</body> |
173 |
</section> |
174 |
</chapter> |
175 |
|
176 |
<chapter> |
177 |
<title>Configuration</title> |
178 |
<section> |
179 |
<title>General machine configuration</title> |
180 |
<body> |
181 |
|
182 |
<p> |
183 |
There is no standard location where a <c>stage3</c> |
184 |
file may be located on the mirrors. |
185 |
For this reason, it is highly advised to edit the |
186 |
default configuration file and explicitly set the <c>STAGE_URL</c> variable. |
187 |
</p> |
188 |
|
189 |
<pre caption="STAGE_URL in default configuration"> |
190 |
$ <i>grep STAGE_URL /etc/devel-chroots/default/config</i> |
191 |
STAGE_URL="$(echo ${GENTOO_MIRRORS} | awk '{ print $1; }')/${STAGE_PATH}/${STAGE_NAME}" |
192 |
# STAGE_URL="http://ftp.belnet.be/mirror/rsync.gentoo.org/gentoo/releases/x86/2006.0/stages/stage3-x86-2006.0.tar.bz2" |
193 |
</pre> |
194 |
|
195 |
<p> |
196 |
As you can see, the default mechanism is to pick the first mirror, |
197 |
add the stage path for a typical x86 stage and construct |
198 |
the name for a current profile's stage. |
199 |
However, this doesn't work for sparc for example, |
200 |
because they are differentiating between sparc32 and sparc64. |
201 |
The same holds true for hppa, where it's stages pertaining |
202 |
to the 1.1 ABI and the 2.0 ABI of different types of machines. |
203 |
</p> |
204 |
|
205 |
<p> |
206 |
Also remember that users and specific chroots can always |
207 |
override this variable, so it would be the best thing |
208 |
to make sure it points to a reasonable default stable stage. |
209 |
</p> |
210 |
|
211 |
<p> |
212 |
As said, users wishing to enable a hardened toolchain chroot, |
213 |
a linux32 chroot on an amd64 machine or a new bleeding edge stage |
214 |
from one of their private mirrors can always override |
215 |
this setting in their own <c>config</c>. |
216 |
</p> |
217 |
|
218 |
<p> |
219 |
Another important piece of the configuration is the global <c>make.conf</c>. |
220 |
Basically, every single chroot contains a file |
221 |
<c>/usr/local/chroot/conf.d/make.conf</c> |
222 |
which is constructed from three possible <c>make.conf</c> files |
223 |
residing in the configuration directory of <c>devel-chroots</c>: |
224 |
</p> |
225 |
|
226 |
<p> |
227 |
<c>/etc/devel-chroots/default/make.conf</c> is the main file for chroots. |
228 |
</p> |
229 |
|
230 |
<p> |
231 |
<c>/etc/devel-chroots/pappy/make.conf</c> is holding user specific addons. |
232 |
</p> |
233 |
|
234 |
<p> |
235 |
<c>/etc/devel-chroots/pappy/chroot001/make.conf</c> is a chroot specific file. |
236 |
</p> |
237 |
|
238 |
<p> |
239 |
These three files make up the final |
240 |
<c>/usr/local/chroot/conf.d/make.conf</c> |
241 |
which then can be sourced by the real <c>/etc/make.conf</c> of the chroot. |
242 |
</p> |
243 |
|
244 |
</body> |
245 |
</section> |
246 |
|
247 |
<section> |
248 |
<title>User specific configuration</title> |
249 |
<body> |
250 |
|
251 |
<p> |
252 |
As noted in the previous section, each user can define her or his |
253 |
own versions of <c>config</c> and <c>make.conf</c> in the |
254 |
configuration directory <c>/etc/devel-chroots/username</c>. |
255 |
This enables the highest possible versatility and flexibility. |
256 |
For example, it is possible to allow a user define her or his own |
257 |
debugging settings for |
258 |
<c>FEATURES</c> and <c>USE</c> flags in <c>make.conf</c>. |
259 |
</p> |
260 |
|
261 |
<p> |
262 |
Another example is the custom setting of the screenrc: |
263 |
</p> |
264 |
|
265 |
<pre caption="user specific screenrc for chroot screen sessions"> |
266 |
$ <i>cat /etc/devel-chroots/pappy/screenrc</i> |
267 |
backtick 1 5 0 /home/pappy/bin/mem.sh |
268 |
backtick 2 1 0 /home/pappy/bin/cetclock.sh 'CET' '-0200' '-0100' |
269 |
|
270 |
hardstatus string '%{= kG}[%= %{= kw}%?%-Lw%?%{r}[%{W}%n*%f %t%?{%u}%?%{r}]%{w}%?%+Lw%?%?%= %{g}]%{W} %2`:%s %{g}%{.w}%H%{.c} [%l] %1`MB ram' |
271 |
</pre> |
272 |
|
273 |
<p> |
274 |
This makes it easy for users to include their own scripts |
275 |
in screen sessions of chroots, |
276 |
for example to measure disk usage or load of the system. |
277 |
</p> |
278 |
|
279 |
<pre caption="Example: user specific CET date display on chroot screen"> |
280 |
~ $ cat bin/cetclock.sh |
281 |
#!/bin/bash |
282 |
|
283 |
# check for daylight saving time being currently active at this time |
284 |
if [ "x$(perl -e '@timeData = localtime(time); print ${timeData}[-1];')y" == "x1y" ] |
285 |
then |
286 |
date --utc --date="$(date --utc '+%F %T') $2" "+$1 %H:%M" |
287 |
else |
288 |
date --utc --date="$(date --utc '+%F %T') $3" "+$1 %H:%M" |
289 |
fi |
290 |
|
291 |
</pre> |
292 |
|
293 |
</body> |
294 |
</section> |
295 |
|
296 |
<section> |
297 |
<title>Chroot specific configuration</title> |
298 |
<body> |
299 |
|
300 |
<p> |
301 |
Last but not least, on some arches (notably amd64), |
302 |
there is the possibility to install an x86 chroot using a special emulator |
303 |
command, called <c>linux32</c>. |
304 |
|
305 |
Redefining the respective variables in the chroot-specific |
306 |
<c>/etc/devel-chroots/pappy/chroot001/config</c> enables users to |
307 |
set up those special chroots on amd64 test machines: |
308 |
</p> |
309 |
|
310 |
<pre caption="chroot specific config for linux32 chroot on amd64"> |
311 |
$ <i>cat /etc/devel-chroots/pappy/chroot001/config</i> |
312 |
CHROOT_BINARY="linux32 /usr/bin/chroot" |
313 |
STAGE_URL="http://ftp.belnet.be/mirror/rsync.gentoo.org/gentoo/releases/x86/2006.0/stages/stage3-x86-2006.0.tar.bz2" |
314 |
</pre> |
315 |
|
316 |
<p> |
317 |
These variables are learned by the script and will |
318 |
be used for setting up the chroot. |
319 |
Other chroots are not affected by this setting, however. |
320 |
This makes it very easy for users to set up and maintain |
321 |
different chroots for their needs on the same machine at a time. |
322 |
</p> |
323 |
|
324 |
<p> |
325 |
As you can see, in every case, |
326 |
chroot-specific data is overwriting default and user-specific data. |
327 |
Please do not change system-internal variables like |
328 |
the maximum number of chroots for a user |
329 |
and similar definitions inside a chroot-specific <c>config</c> file. |
330 |
</p> |
331 |
|
332 |
</body> |
333 |
</section> |
334 |
|
335 |
</chapter> |
336 |
|
337 |
<chapter> |
338 |
<title>Startup and maintenance</title> |
339 |
<section> |
340 |
<title>Automatic startup</title> |
341 |
<body> |
342 |
|
343 |
<p> |
344 |
Automatic startup of the developer chroots is attained with an init script |
345 |
that is conforming to the Gentoo standards. |
346 |
</p> |
347 |
|
348 |
<pre caption="starting the devel-chroots init script"> |
349 |
# /etc/init.d/devel-chroots status |
350 |
* status: stopped |
351 |
|
352 |
# /etc/init.d/devel-chroots start |
353 |
* Starting developer chroots for all users ... |
354 |
* pappy: starting chroot001 in (/space/devel-chroots/pappy/chroot001) |
355 |
* pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot001 |
356 |
* pappy: chroot001: creating conf: make.conf |
357 |
* pappy: starting chroot002 in (/space/devel-chroots/pappy/chroot002) |
358 |
* pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot002 |
359 |
* pappy: chroot002: creating conf: make.conf |
360 |
* config file [/etc/devel-chroots/pappy/chroot002/make.conf] not existing, skipping |
361 |
* no /etc/devel-chroots/pappy/chroot003 config dir |
362 |
* no /etc/devel-chroots/pappy/chroot004 config dir |
363 |
* no /etc/devel-chroots/pappy/chroot005 config dir |
364 |
* no /etc/devel-chroots/pappy/chroot006 config dir |
365 |
* no /etc/devel-chroots/pappy/chroot007 config dir |
366 |
* no /etc/devel-chroots/pappy/chroot008 config dir |
367 |
* launching detached screen session for pappy's chroots |
368 |
* remember that you have to source /usr/local/chroot/conf.d/make.conf |
369 |
* in the make.conf of created chroots for user-specific settings |
370 |
* for multiuser mode, you need to set /usr/bin/screen to mode 4755 |
371 |
* and also change the directory /var/run/screen to mode 0755 [ <ident>ok</ident> ] |
372 |
</pre> |
373 |
|
374 |
<pre caption="restarting the chroots init script"> |
375 |
# /etc/init.d/devel-chroots restart |
376 |
* Stopping developer chroots for all users ... |
377 |
* stopping chroot001 of user pappy (/space/devel-chroots/pappy/chroot001) |
378 |
* pappy: terminating the following screen sessions: 8638 |
379 |
* pappy: unmounting chroot filesystems: /space/devel-chroots/pappy/chroot001 |
380 |
* stopping chroot002 of user pappy (/space/devel-chroots/pappy/chroot002) |
381 |
* pappy: unmounting chroot filesystems: /space/devel-chroots/pappy/chroot002 |
382 |
* no /etc/devel-chroots/pappy/chroot003 config dir |
383 |
* no /etc/devel-chroots/pappy/chroot004 config dir |
384 |
* no /etc/devel-chroots/pappy/chroot005 config dir |
385 |
* no /etc/devel-chroots/pappy/chroot006 config dir |
386 |
* no /etc/devel-chroots/pappy/chroot007 config dir |
387 |
* no /etc/devel-chroots/pappy/chroot008 config dir [ <ident>ok</ident> ] |
388 |
* Starting developer chroots for all users ... |
389 |
* pappy: starting chroot001 in (/space/devel-chroots/pappy/chroot001) |
390 |
* pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot001 |
391 |
* pappy: chroot001: creating conf: make.conf |
392 |
* pappy: starting chroot002 in (/space/devel-chroots/pappy/chroot002) |
393 |
* pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot002 |
394 |
* pappy: chroot002: creating conf: make.conf |
395 |
* config file [/etc/devel-chroots/pappy/chroot002/make.conf] not existing, skipping |
396 |
* no /etc/devel-chroots/pappy/chroot003 config dir |
397 |
* no /etc/devel-chroots/pappy/chroot004 config dir |
398 |
* no /etc/devel-chroots/pappy/chroot005 config dir |
399 |
* no /etc/devel-chroots/pappy/chroot006 config dir |
400 |
* no /etc/devel-chroots/pappy/chroot007 config dir |
401 |
* no /etc/devel-chroots/pappy/chroot008 config dir |
402 |
* launching detached screen session for pappy's chroots |
403 |
* remember that you have to source /usr/local/chroot/conf.d/make.conf |
404 |
* in the make.conf of created chroots for user-specific settings |
405 |
* for multiuser mode, you need to set /usr/bin/screen to mode 4755 |
406 |
* and also change the directory /var/run/screen to mode 0755 [ <ident>ok</ident> ] |
407 |
</pre> |
408 |
|
409 |
<p> |
410 |
As you can see, the init script is maybe generating |
411 |
lots of considered unnecessary output, |
412 |
however this is important for being able |
413 |
to judge why a certain chroot has not been set up |
414 |
and adds in easy understanding what is happening and what is not. |
415 |
</p> |
416 |
|
417 |
<p> |
418 |
For example, as you can see, a chroot for a given user is only started |
419 |
if a configuration directory for that chroot could be found. |
420 |
It can be empty, but it has to exist for the given chroot to be started. |
421 |
</p> |
422 |
|
423 |
<p> |
424 |
Please note that the usage of the init script should be left |
425 |
up to the discretion of the system administrator. |
426 |
</p> |
427 |
|
428 |
</body> |
429 |
</section> |
430 |
|
431 |
<section> |
432 |
<title>User management of chroots</title> |
433 |
<body> |
434 |
|
435 |
<p> |
436 |
Users should be issuing the following script for |
437 |
starting and stopping their own chroots: |
438 |
</p> |
439 |
|
440 |
<pre caption="user maintenance of chroots: stopping chroots"> |
441 |
$ sudo /usr/sbin/devel-chroots stop pappy |
442 |
* stopping chroot001 of user pappy (/space/devel-chroots/pappy/chroot001) |
443 |
* pappy: terminating the following screen sessions: 9371 |
444 |
* pappy: unmounting chroot filesystems: /space/devel-chroots/pappy/chroot001 |
445 |
* stopping chroot002 of user pappy (/space/devel-chroots/pappy/chroot002) |
446 |
* pappy: unmounting chroot filesystems: /space/devel-chroots/pappy/chroot002 |
447 |
</pre> |
448 |
|
449 |
<pre caption="user maintenance of chroots: starting chroots"> |
450 |
$ sudo /usr/sbin/devel-chroots start pappy |
451 |
* pappy: starting chroot001 in (/space/devel-chroots/pappy/chroot001) |
452 |
* pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot001 |
453 |
* pappy: chroot001: creating conf: make.conf |
454 |
* pappy: starting chroot002 in (/space/devel-chroots/pappy/chroot002) |
455 |
* pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot002 |
456 |
* pappy: chroot002: creating conf: make.conf |
457 |
* launching detached screen session for pappy's chroots |
458 |
</pre> |
459 |
|
460 |
<p> |
461 |
Please remember there is no restart command: |
462 |
</p> |
463 |
|
464 |
<pre caption="illegal use of restart command for chroot"> |
465 |
$ sudo /usr/sbin/devel-chroots restart pappy |
466 |
* error: unknown mode: restart |
467 |
</pre> |
468 |
|
469 |
</body> |
470 |
</section> |
471 |
|
472 |
<section> |
473 |
<title>Final notes</title> |
474 |
<body> |
475 |
|
476 |
<p> |
477 |
As noted in the init script, for users being able to reattach |
478 |
to root screen sessions as a user and |
479 |
use the <c>acladd</c> command to see who is working with them, |
480 |
it is necessary to change screen and |
481 |
the working directory of the screen session sockets. |
482 |
</p> |
483 |
|
484 |
<p> |
485 |
However, this is a cosmetic advantage, |
486 |
because normally everybody is supposed to be root |
487 |
on a development system and there is no security restrictions. |
488 |
</p> |
489 |
|
490 |
<p> |
491 |
But on the other hand, having a system of voluntarily |
492 |
least priviledges used for reconnecting to screen sessions |
493 |
as an authorized user never hurts, avoids mistakes and problems |
494 |
and opens up room for cutting down the necessary priviledges |
495 |
of scripts and users for having their work done! |
496 |
</p> |
497 |
|
498 |
</body> |
499 |
</section> |
500 |
</chapter> |
501 |
</guide> |
502 |
|
503 |
|
504 |
|
505 |
|
506 |
-- |
507 |
gentoo-commits@l.g.o mailing list |