/[gentoo]/xml/htdocs/doc/en/handbook/hb-install-system.xml
Gentoo

Contents of /xml/htdocs/doc/en/handbook/hb-install-system.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.146 - (hide annotations) (download) (as text)
Sun Jun 1 13:37:36 2014 UTC (2 months ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.145: +18 -3 lines
File MIME type: application/xml
Fix bug #498968 - Add warning about non-installation media having different /dev/shm structure, as well as an in-document comment for future reference

1 swift 1.26 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3    
4 swift 1.6 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 nightmorph 1.93 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6 swift 1.6
7 swift 1.146 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-system.xml,v 1.145 2014/04/13 11:58:00 swift Exp $ -->
8 swift 1.11
9 swift 1.3 <sections>
10 swift 1.56
11 neysx 1.101 <abstract>
12     After installing and configuring a stage3, the eventual result is that you
13     have a Gentoo base system at your disposal. This chapter describes how
14     to progress to that state.
15     </abstract>
16    
17 swift 1.146 <version>38</version>
18     <date>2014-06-01</date>
19 swift 1.56
20 swift 1.1 <section>
21 swift 1.3 <title>Chrooting</title>
22 swift 1.1 <subsection>
23 swift 1.2 <title>Optional: Selecting Mirrors</title>
24     <body>
25    
26     <p>
27 swift 1.70 In order to download source code quickly it is recommended to select a fast
28     mirror. Portage will look in your <path>make.conf</path> file for the
29     GENTOO_MIRRORS variable and use the mirrors listed therein. You can surf to
30     our <uri link="/main/en/mirrors.xml">mirror list</uri> and search
31     for a mirror (or mirrors) close to you (as those are most frequently the
32     fastest ones), but we provide a nice tool called <c>mirrorselect</c> which
33 jkt 1.119 provides you with a nice interface to select the mirrors you want. Just
34     navigate to the mirrors of choice and press spacebar to select one or more
35     mirrors.
36 swift 1.70 </p>
37    
38     <pre caption="Using mirrorselect for the GENTOO_MIRRORS variable">
39 swift 1.125 # <i>mirrorselect -i -o &gt;&gt; /mnt/gentoo/etc/portage/make.conf</i>
40 swift 1.70 </pre>
41    
42     <p>
43     A second important setting is the SYNC setting in <path>make.conf</path>. This
44     variable contains the rsync server you want to use when updating your Portage
45     tree (the collection of ebuilds, scripts containing all the information Portage
46     needs to download and install software). Although you can manually enter a SYNC
47     server for yourself, <c>mirrorselect</c> can ease that operation for you:
48 swift 1.2 </p>
49    
50 swift 1.70 <pre caption="Selecting an rsync mirror using mirrorselect">
51 swift 1.125 # <i>mirrorselect -i -r -o &gt;&gt; /mnt/gentoo/etc/portage/make.conf</i>
52 swift 1.2 </pre>
53    
54     <p>
55 swift 1.70 After running <c>mirrorselect</c> it is adviseable to double-check the settings
56 swift 1.125 in <path>/mnt/gentoo/etc/portage/make.conf</path> !
57 swift 1.2 </p>
58    
59 nightmorph 1.113 <note>
60     If you want to manually set a SYNC server in <path>make.conf</path>, you should
61     check out the <uri link="/main/en/mirrors-rsync.xml">community mirrors
62     list</uri> for the mirrors closest to you. We recommend choosing a
63     <e>rotation</e>, such as <c>rsync.us.gentoo.org</c>, rather than choosing a
64     single mirror. This helps spread out the load and provides a failsafe in case a
65     specific mirror is offline.
66     </note>
67    
68 swift 1.2 </body>
69 swift 1.3 </subsection>
70     <subsection>
71 swift 1.5 <title>Copy DNS Info</title>
72     <body>
73    
74     <p>
75 swift 1.24 One thing still remains to be done before we enter the new environment and that
76     is copying over the DNS information in <path>/etc/resolv.conf</path>. You need
77 swift 1.5 to do this to ensure that networking still works even after entering the new
78     environment. <path>/etc/resolv.conf</path> contains the nameservers for your
79     network.
80     </p>
81    
82     <pre caption="Copy over DNS information">
83 swift 1.35 <comment>(The "-L" option is needed to make sure we don't copy a symbolic link)</comment>
84 nightmorph 1.107 # <i>cp -L /etc/resolv.conf /mnt/gentoo/etc/</i>
85 swift 1.18 </pre>
86    
87     </body>
88     </subsection>
89 swift 1.131 <subsection>
90 swift 1.124 <title>Mounting the necessary Filesystems</title>
91 swift 1.43 <body>
92    
93     <p>
94 jkt 1.119 In a few moments, we will change the Linux root towards the new location. To
95     make sure that the new environment works properly, we need to make certain file
96     systems available there as well.
97     </p>
98    
99     <p>
100 swift 1.43 Mount the <path>/proc</path> filesystem on <path>/mnt/gentoo/proc</path> to
101 neysx 1.88 allow the installation to use the kernel-provided information within the
102 swift 1.124 chrooted environment, and then mount-bind the <path>/dev</path> and
103     <path>/sys</path> filesystems.
104 swift 1.43 </p>
105    
106 neysx 1.88 <pre caption="Mounting /proc and /dev">
107 swift 1.144 # <i>mount -t proc proc /mnt/gentoo/proc</i>
108 swift 1.124 # <i>mount --rbind /sys /mnt/gentoo/sys</i>
109 nightmorph 1.118 # <i>mount --rbind /dev /mnt/gentoo/dev</i>
110 swift 1.43 </pre>
111    
112 swift 1.146 <!--
113     Only warning for non-Gentoo installation media. The more other installation
114     media diverge from ours, the more difficult it will be to create proper
115     documentation. If this becomes a larger issue, we will need to include a
116     single warning up front, and perhaps have a wiki page where users can put the
117     differences, so that the installation instructions can focus on Gentoo-only
118     media.
119     -->
120     <warn>
121     When using non-Gentoo installation media, this might not be sufficient.
122     Some distributions make <path>/dev/shm</path> a symbolic link to
123     <path>/run/shm</path> which, after the chroot, becomes invalid. Making
124     <path>/dev/shm</path> a proper tmpfs-mount up front can fix this.
125     </warn>
126    
127 swift 1.43 </body>
128     </subsection>
129     <subsection>
130 swift 1.2 <title>Entering the new Environment</title>
131 swift 1.1 <body>
132    
133     <p>
134 swift 1.19 Now that all partitions are initialized and the base environment
135 swift 1.1 installed, it is time to enter our new installation environment by
136 swift 1.9 <e>chrooting</e> into it. This means that we change from the current
137 swift 1.72 installation environment (Installation CD or other installation medium) to your
138 swift 1.19 installation system (namely the initialized partitions).
139 swift 1.1 </p>
140    
141     <p>
142     This chrooting is done in three steps. First we will change the root
143 swift 1.2 from <path>/</path> (on the installation medium) to <path>/mnt/gentoo</path>
144 swift 1.129 (on your partitions) using <c>chroot</c>. Then we will reload some settings, as
145     provided by <path>/etc/profile</path>, in memory using <c>source</c>.
146 swift 1.130 The last step is to redefine the primary prompt to help us remember that we are
147     inside a chroot environment.
148 swift 1.1 </p>
149    
150     <pre caption = "Chrooting into the new environment">
151     # <i>chroot /mnt/gentoo /bin/bash</i>
152     # <i>source /etc/profile</i>
153 rane 1.87 # <i>export PS1="(chroot) $PS1"</i>
154 swift 1.1 </pre>
155    
156     <p>
157     Congratulations! You are now inside your own Gentoo Linux environment.
158 swift 1.10 Of course it is far from finished, which is why the installation still
159 swift 1.1 has some sections left :-)
160     </p>
161    
162 swift 1.123 <p>
163     If you at any time would need another terminal or console to access the chroot
164     environment, all you need to do is to execute the above steps again.
165     </p>
166    
167 swift 1.1 </body>
168 swift 1.3 </subsection>
169 swift 1.85 </section>
170    
171 swift 1.127 <section id="installing_portage">
172 swift 1.85 <title>Configuring Portage</title>
173 swift 1.3 <subsection>
174 swift 1.134 <title>Installing a Portage Snapshot</title>
175 swift 1.127 <body>
176    
177     <p>
178     You now have to install a Portage snapshot, a collection of files that inform
179     Portage what software titles you can install, which profiles are available, etc.
180     </p>
181    
182     <p>
183     We recommend the use of <c>emerge-webrsync</c>. This will fetch the latest
184     portage snapshot (which Gentoo releases on a daily basis) from one of our mirrors
185     and install it onto your system.
186     </p>
187    
188     <pre caption="Running emerge-webrsync to install a Portage snapshot">
189 swift 1.128 # <i>emerge-webrsync</i>
190 swift 1.127 </pre>
191    
192 swift 1.145 <note>
193     During this operation, <c>emerge-webrsync</c> might complain about a missing
194     <path>/usr/portage</path> location. This is to be expected and nothing to
195     worry about - the tool will create the location for us.
196     </note>
197    
198 swift 1.139 <p>
199     From this point onward, Portage might mention that certain updates are
200     recommended to be executed. This is because certain system packages
201     installed through the stage3 file might have newer versions available,
202     and Portage is now aware of this because a new Portage snapshot is installed.
203     You can safely ignore this for now and update after the Gentoo installation
204     has finished.
205     </p>
206    
207 swift 1.127 </body>
208     </subsection>
209     <subsection>
210 swift 1.126 <title>Optional: Updating the Portage tree</title>
211 swift 1.2 <body>
212    
213     <p>
214 swift 1.126 You can now update your Portage tree to the latest version. <c>emerge
215     --sync</c> will use the rsync protocol to update the Portage tree (which
216     you fetched earlier on through <c>emerge-webrsync</c>) to the latest state.
217 swift 1.2 </p>
218    
219 dertobi123 1.40 <pre caption="Updating the Portage tree">
220 cam 1.50 # <i>emerge --sync</i>
221 neysx 1.78 <comment>(If you're using a slow terminal like some framebuffers or a serial
222     console, you can add the --quiet option to speed up this process:)</comment>
223     # <i>emerge --sync --quiet</i>
224 swift 1.13 </pre>
225    
226     <p>
227 swift 1.126 If you are behind a firewall that blocks rsync traffic, you safely ignore this
228     step as you already have a quite up-to-date Portage tree.
229 swift 1.75 </p>
230    
231     <p>
232 swift 1.13 If you are warned that a new Portage version is available and that you should
233 swift 1.132 update Portage, you should do it now using <c>emerge --oneshot portage</c>. You
234     might also be notified that "news items need reading". More on that next.
235     </p>
236    
237     </body>
238     </subsection>
239     <subsection>
240     <title>Reading News Items</title>
241     <body>
242    
243     <p>
244     When a Portage tree is synchronized to your system, Portage might warn you with
245     the following:
246     </p>
247    
248     <pre caption="Portage informing that news items are available">
249     * IMPORTANT: 2 news items need reading for repository 'gentoo'.
250     * Use eselect news to read news items.
251     </pre>
252    
253     <p>
254     Portage news items were created to provide a communication medium to push
255     critical messages to users via the rsync tree. To manage them you will need to
256     use <c>eselect news</c>. With the <c>read</c> subcommand, you can read all news
257     items. With <c>list</c> you can get an overview of the available news items, and
258     with <c>purge</c> you can remove them once you have read them and have no
259     further need for the item(s) anymore.
260     </p>
261    
262     <pre caption="Handling Portage news">
263     # <i>eselect news list</i>
264     # <i>eselect news read</i>
265     </pre>
266    
267     <p>
268     More information about the newsreader is available through its manual page:
269     <c>man news.eselect</c>.
270 swift 1.13 </p>
271 swift 1.8
272     </body>
273     </subsection>
274 swift 1.72 <subsection>
275     <title>Choosing the Right Profile</title>
276     <body>
277    
278     <p>
279     First, a small definition is in place.
280     </p>
281    
282     <p>
283     A profile is a building block for any Gentoo system. Not only does it specify
284 nightmorph 1.112 default values for USE, CFLAGS and other important variables, it also locks
285 swift 1.72 the system to a certain range of package versions. This is all maintained by the
286     Gentoo developers.
287     </p>
288    
289 nightmorph 1.106 <p>
290 nightmorph 1.102 Previously, such a profile was untouched by the users. However, there may be
291     certain situations in which you may decide a profile change is necessary.
292 swift 1.72 </p>
293    
294     <p>
295 neysx 1.79 You can see what profile you are currently using with the following command:
296 swift 1.72 </p>
297    
298 swift 1.136 <note>
299     The output of the command below is just an example and evolves over time.
300     </note>
301    
302 swift 1.72 <pre caption="Verifying system profile">
303 nightmorph 1.112 # <i>eselect profile list</i>
304     Available profile symlink targets:
305     [1] <keyval id="profile"/> *
306     [2] <keyval id="profile"/>/desktop
307 swift 1.136 [3] <keyval id="profile"/>/desktop/gnome
308     [4] <keyval id="profile"/>/desktop/kde
309 swift 1.72 </pre>
310    
311     <p>
312 swift 1.136 As you can see, there are also <c>desktop</c> subprofiles available for some
313 nightmorph 1.112 architectures. Running <c>eselect profile list</c> will show all available
314     profiles.
315 nightmorph 1.99 </p>
316    
317     <p>
318 nightmorph 1.112 After viewing the available profiles for your architecture, you can use a
319     different one if you wish:
320 swift 1.72 </p>
321    
322 nightmorph 1.106 <pre caption="Changing profiles">
323 nightmorph 1.112 # <i>eselect profile set 2</i>
324 swift 1.72 </pre>
325    
326 nightmorph 1.106 <p test="func:keyval('arch')='AMD64'">
327     If you want to have a pure 64-bit environment, with no 32-bit applications or
328     libraries, you should use a non-multilib profile:
329 swift 1.72 </p>
330    
331 nightmorph 1.106 <pre test="func:keyval('arch')='AMD64'" caption="Switching to a non-multilib profile">
332 nightmorph 1.112 # <i>eselect profile list</i>
333     Available profile symlink targets:
334     [1] <keyval id="profile"/> *
335     [2] <keyval id="profile"/>/desktop
336 swift 1.136 [3] <keyval id="profile"/>/desktop/gnome
337     [4] <keyval id="profile"/>/desktop/kde
338     [5] <keyval id="profile"/>/no-multilib
339 nightmorph 1.112 <comment>(Choose the no-multilib profile)</comment>
340 swift 1.136 # <i>eselect profile set 5</i>
341 nightmorph 1.112 <comment>(Verify the change)</comment>
342     # <i>eselect profile list</i>
343     Available profile symlink targets:
344     [1] <keyval id="profile"/>
345     [2] <keyval id="profile"/>/desktop
346 swift 1.136 [3] <keyval id="profile"/>/desktop/gnome
347     [4] <keyval id="profile"/>/desktop/kde
348     [5] <keyval id="profile"/>/no-multilib *
349 swift 1.83 </pre>
350    
351 nightmorph 1.111 <note>
352     The <c>developer</c> subprofile is specifically for Gentoo Linux development
353     tasks. It is <e>not</e> meant to help set up general development environments.
354     </note>
355    
356 swift 1.72 </body>
357     </subsection>
358 swift 1.28 <subsection id="configure_USE">
359 swift 1.21 <title>Configuring the USE variable</title>
360     <body>
361    
362     <p>
363     <c>USE</c> is one of the most powerful variables Gentoo provides to its users.
364     Several programs can be compiled with or without optional support for certain
365     items. For instance, some programs can be compiled with gtk-support, or with
366     qt-support. Others can be compiled with or without SSL support. Some programs
367     can even be compiled with framebuffer support (svgalib) instead of X11 support
368     (X-server).
369     </p>
370    
371     <p>
372     Most distributions compile their packages with support for as much as possible,
373     increasing the size of the programs and startup time, not to mention an enormous
374 swift 1.24 amount of dependencies. With Gentoo you can define what options a package
375 swift 1.21 should be compiled with. This is where <c>USE</c> comes into play.
376     </p>
377    
378     <p>
379     In the <c>USE</c> variable you define keywords which are mapped onto
380     compile-options. For instance, <e>ssl</e> will compile ssl-support in the
381 nightmorph 1.100 programs that support it. <e>-X</e> will remove X-server support (note the
382 nightmorph 1.115 minus sign in front). <e>gnome gtk -kde -qt4</e> will compile your
383 nightmorph 1.100 programs with gnome (and gtk) support, and not with kde (and qt) support,
384     making your system fully tweaked for GNOME.
385 swift 1.21 </p>
386    
387     <p>
388 swift 1.68 The default <c>USE</c> settings are placed in the <path>make.defaults</path>
389     files of your profile. You will find <path>make.defaults</path> files in the
390 swift 1.125 directory which <path>/etc/portage/make.profile</path> points to and all parent
391 swift 1.68 directories as well. The default <c>USE</c> setting is the sum of all <c>USE</c>
392     settings in all <path>make.defaults</path> files. What you place in
393 swift 1.125 <path>/etc/portage/make.conf</path> is calculated against these defaults
394     settings. If you add something to the <c>USE</c> setting, it is added to the
395     default list. If you remove something from the <c>USE</c> setting (by placing
396     a minus sign in front of it) it is removed from the default list (if it was
397     in the default list at all). <e>Never</e> alter anything inside the
398     <path>/etc/portage/make.profile</path> directory; it gets overwritten when
399     you update Portage!
400 swift 1.21 </p>
401    
402     <p>
403     A full description on <c>USE</c> can be found in the second part of the Gentoo
404 neysx 1.52 Handbook, <uri link="?part=2&amp;chap=2">USE flags</uri>. A full description on
405     the available USE flags can be found on your system in
406 swift 1.23 <path>/usr/portage/profiles/use.desc</path>.
407     </p>
408    
409     <pre caption="Viewing available USE flags">
410     # <i>less /usr/portage/profiles/use.desc</i>
411 swift 1.45 <comment>(You can scroll using your arrow keys, exit by pressing 'q')</comment>
412 swift 1.23 </pre>
413    
414     <p>
415     As an example we show a <c>USE</c> setting for a KDE-based system with DVD, ALSA
416     and CD Recording support:
417 swift 1.21 </p>
418    
419 swift 1.125 <pre caption="Opening /etc/portage/make.conf">
420     # <i>nano -w /etc/portage/make.conf</i>
421 swift 1.21 </pre>
422    
423     <pre caption="USE setting">
424 nightmorph 1.115 USE="-gtk -gnome qt4 kde dvd alsa cdr"
425 swift 1.21 </pre>
426    
427 swift 1.69 </body>
428     </subsection>
429 swift 1.28 </section>
430 swift 1.138 <section test="contains('AMD64 arm PPC PPC64 x86', func:keyval('arch'))">
431 swift 1.137 <title>Optional: Using systemd</title>
432     <body>
433    
434     <p>
435     The remainder of the Gentoo Handbook focuses on OpenRC as the default init
436     support system. If you want to use systemd instead, or are planning to use Gnome
437     3.8 and later (which requires systemd), please consult the <uri
438     link="https://wiki.gentoo.org/wiki/Systemd">systemd page</uri> on
439     the Gentoo wiki as it elaborates on the different configuration settings and
440     methods.
441     </p>
442    
443     <p>
444     The Gentoo Handbook can then be followed with that page in mind.
445     </p>
446    
447     </body>
448     </section>
449     <section>
450 swift 1.133 <title>Timezone</title>
451     <body>
452    
453     <p>
454     Finally select your timezone so that your system knows where it is physically
455 swift 1.142 located. Look for your timezone in <path>/usr/share/zoneinfo</path>, then
456     write it in the <path>/etc/timezone</path> file.
457 swift 1.133 </p>
458    
459     <pre caption="Setting the timezone information">
460     # <i>ls /usr/share/zoneinfo</i>
461     <comment>(Suppose you want to use Europe/Brussels)</comment>
462 swift 1.142 # <i>echo "Europe/Brussels" &gt; /etc/timezone</i>
463 swift 1.140 </pre>
464    
465     <p>
466 swift 1.142 Please avoid the <path>/usr/share/zoneinfo/Etc/GMT*</path> timezones as their
467     names do not indicate the expected zones. For instance, <path>GMT-8</path> is
468     in fact GMT+8.
469 swift 1.140 </p>
470    
471 swift 1.142 <p>
472     Next, reconfigure the timezone-data package, which will update the
473     <path>/etc/localtime</path> file for us, based on the <path>/etc/timezone</path>
474     entry. The <path>/etc/localtime</path> file is used by the system C library
475     to know the timezone the system is in.
476     </p>
477    
478     <pre caption="Reconfiguring timezone-data">
479     # <i>emerge --config sys-libs/timezone-data</i>
480 swift 1.133 </pre>
481    
482     </body>
483     </section>
484    
485 swift 1.143 <section>
486     <title>Configure locales</title>
487     <body>
488    
489     <p>
490     You will probably only use one or maybe two locales on your system. You have to
491     specify locales you will need in <path>/etc/locale.gen</path>.
492     </p>
493    
494     <pre caption="Opening /etc/locale.gen">
495     # <i>nano -w /etc/locale.gen</i>
496     </pre>
497    
498     <p>
499     The following locales are an example to get both English (United States) and
500     German (Germany) with the accompanying character formats (like UTF-8).
501     </p>
502    
503     <pre caption="Specify your locales">
504     en_US ISO-8859-1
505     en_US.UTF-8 UTF-8
506     de_DE ISO-8859-1
507     de_DE@euro ISO-8859-15
508     </pre>
509    
510     <note>
511     You can select your desired locales in the list given by running <c>locale -a</c>.
512     </note>
513    
514     <warn>
515     We strongly suggest that you should use at least one UTF-8 locale because some
516     applications may require it.
517     </warn>
518    
519     <p>
520     The next step is to run <c>locale-gen</c>. It will generates all the locales you
521     have specified in the <path>/etc/locale.gen</path> file.
522     </p>
523    
524     <pre caption="Running locale-gen">
525     # <i>locale-gen</i>
526     </pre>
527    
528     <p>
529     You can verify that your selected locales are available by running <c>locale -a</c>.
530     </p>
531    
532     <p>
533     Once done, you now have the possibility to set the system-wide locale settings.
534     With <c>eselect locale list</c>, the available targets are displayed:
535     </p>
536    
537     <pre caption="Displaying the available LANG settings">
538     # <i>eselect locale list</i>
539     Available targets for the LANG variable:
540     [1] C
541     [2] POSIX
542     [3] en_US
543     [4] en_US.iso88591
544     [5] en_US.utf8
545     [6] de_DE
546     [7] de_DE.iso88591
547     [8] de_DE.iso885915
548     [9] de_DE.utf8
549     [ ] (free form)
550     </pre>
551    
552     <p>
553     With <c>eselect locale set &lt;value&gt;</c> the correct locale can be set:
554     </p>
555    
556     <pre caption="Setting the LANG variable">
557     # <i>eselect locale set 9</i>
558     </pre>
559    
560     <p>
561     Manually, this can still be accomplished through the
562     <path>/etc/env.d/02locale</path> file:
563     </p>
564    
565     <pre caption="Setting the default system locale in /etc/env.d/02locale">
566     LANG="de_DE.UTF-8"
567     LC_COLLATE="C"
568     </pre>
569    
570     <p>
571     Make sure a locale is set, as you could otherwise get warnings and errors
572     during kernel builds and other software deployments later in the installation.
573     </p>
574    
575     <p>
576     Don't forget to reload your environment:
577     </p>
578    
579     <pre caption="Reload shell environment">
580     # <i>env-update &amp;&amp; source /etc/profile</i>
581     </pre>
582    
583     <p>
584     We made a full <uri link="https://wiki.gentoo.org/wiki/Localization/HOWTO">Localization
585     Guide</uri> to help you through this process. You can also read the detailed
586     <uri link="https://wiki.gentoo.org/wiki/UTF-8">UTF-8 article</uri> for very specific
587     informations to enable UTF-8 on your system.
588     </p>
589    
590     </body>
591     </section>
592    
593 swift 1.3 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20