Gentoo Archives: gentoo-commits

From: "Alexander Gabert (pappy)" <pappy@g.o>
To: gentoo-commits@l.g.o
Subject: [gentoo-commits] gentoo commit in xml/htdocs/proj/en/extreme-security/solutions/utils/chroots: devel-chroots-intro.xml
Date: Tue, 01 Apr 2008 11:56:45
Message-Id: E1Jgf6X-0007ik-AP@stork.gentoo.org
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