/[gentoo-projects]/devel-chroots/devel-chroots-2.0.0/doc/en/devel-chroots-intro.xml
Gentoo

Contents of /devel-chroots/devel-chroots-2.0.0/doc/en/devel-chroots-intro.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (hide annotations) (download) (as text)
Thu Dec 14 17:18:52 2006 UTC (7 years, 9 months ago) by pappy
Branch: MAIN
File MIME type: application/xml
adding 2.0.0 files for project

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

  ViewVC Help
Powered by ViewVC 1.1.20