/[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.147 - (show annotations) (download) (as text)
Sun Aug 17 17:01:48 2014 UTC (5 days, 7 hours ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.146: +4 -4 lines
File MIME type: application/xml
Fix bug #517580 - URL updates and language improvements, thanks to Francesco Turco

1 <?xml version='1.0' encoding='UTF-8'?>
2 <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6
7 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-system.xml,v 1.146 2014/06/01 13:37:36 swift Exp $ -->
8
9 <sections>
10
11 <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 <version>39</version>
18 <date>2014-08-17</date>
19
20 <section>
21 <title>Chrooting</title>
22 <subsection>
23 <title>Optional: Selecting Mirrors</title>
24 <body>
25
26 <p>
27 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 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 </p>
37
38 <pre caption="Using mirrorselect for the GENTOO_MIRRORS variable">
39 # <i>mirrorselect -i -o &gt;&gt; /mnt/gentoo/etc/portage/make.conf</i>
40 </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 </p>
49
50 <pre caption="Selecting an rsync mirror using mirrorselect">
51 # <i>mirrorselect -i -r -o &gt;&gt; /mnt/gentoo/etc/portage/make.conf</i>
52 </pre>
53
54 <p>
55 After running <c>mirrorselect</c> it is adviseable to double-check the settings
56 in <path>/mnt/gentoo/etc/portage/make.conf</path> !
57 </p>
58
59 <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 </body>
69 </subsection>
70 <subsection>
71 <title>Copy DNS Info</title>
72 <body>
73
74 <p>
75 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 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 <comment>(The "-L" option is needed to make sure we don't copy a symbolic link)</comment>
84 # <i>cp -L /etc/resolv.conf /mnt/gentoo/etc/</i>
85 </pre>
86
87 </body>
88 </subsection>
89 <subsection>
90 <title>Mounting the necessary Filesystems</title>
91 <body>
92
93 <p>
94 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 Mount the <path>/proc</path> filesystem on <path>/mnt/gentoo/proc</path> to
101 allow the installation to use the kernel-provided information within the
102 chrooted environment, and then mount-bind the <path>/dev</path> and
103 <path>/sys</path> filesystems.
104 </p>
105
106 <pre caption="Mounting /proc and /dev">
107 # <i>mount -t proc proc /mnt/gentoo/proc</i>
108 # <i>mount --rbind /sys /mnt/gentoo/sys</i>
109 # <i>mount --rbind /dev /mnt/gentoo/dev</i>
110 </pre>
111
112 <!--
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 </body>
128 </subsection>
129 <subsection>
130 <title>Entering the new Environment</title>
131 <body>
132
133 <p>
134 Now that all partitions are initialized and the base environment
135 installed, it is time to enter our new installation environment by
136 <e>chrooting</e> into it. This means that we change from the current
137 installation environment (Installation CD or other installation medium) to your
138 installation system (namely the initialized partitions).
139 </p>
140
141 <p>
142 This chrooting is done in three steps. First we will change the root
143 from <path>/</path> (on the installation medium) to <path>/mnt/gentoo</path>
144 (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 The last step is to redefine the primary prompt to help us remember that we are
147 inside a chroot environment.
148 </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 # <i>export PS1="(chroot) $PS1"</i>
154 </pre>
155
156 <p>
157 Congratulations! You are now inside your own Gentoo Linux environment.
158 Of course it is far from finished, which is why the installation still
159 has some sections left :-)
160 </p>
161
162 <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 </body>
168 </subsection>
169 </section>
170
171 <section id="installing_portage">
172 <title>Configuring Portage</title>
173 <subsection>
174 <title>Installing a Portage Snapshot</title>
175 <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 # <i>emerge-webrsync</i>
190 </pre>
191
192 <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 <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 </body>
208 </subsection>
209 <subsection>
210 <title>Optional: Updating the Portage tree</title>
211 <body>
212
213 <p>
214 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 </p>
218
219 <pre caption="Updating the Portage tree">
220 # <i>emerge --sync</i>
221 <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 </pre>
225
226 <p>
227 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 </p>
230
231 <p>
232 If you are warned that a new Portage version is available and that you should
233 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 </p>
271
272 </body>
273 </subsection>
274 <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 default values for USE, CFLAGS and other important variables, it also locks
285 the system to a certain range of package versions. This is all maintained by the
286 Gentoo developers.
287 </p>
288
289 <p>
290 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 </p>
293
294 <p>
295 You can see what profile you are currently using with the following command:
296 </p>
297
298 <note>
299 The output of the command below is just an example and evolves over time.
300 </note>
301
302 <pre caption="Verifying system profile">
303 # <i>eselect profile list</i>
304 Available profile symlink targets:
305 [1] <keyval id="profile"/> *
306 [2] <keyval id="profile"/>/desktop
307 [3] <keyval id="profile"/>/desktop/gnome
308 [4] <keyval id="profile"/>/desktop/kde
309 </pre>
310
311 <p>
312 As you can see, there are also <c>desktop</c> subprofiles available for some
313 architectures. Running <c>eselect profile list</c> will show all available
314 profiles.
315 </p>
316
317 <p>
318 After viewing the available profiles for your architecture, you can use a
319 different one if you wish:
320 </p>
321
322 <pre caption="Changing profiles">
323 # <i>eselect profile set 2</i>
324 </pre>
325
326 <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 </p>
330
331 <pre test="func:keyval('arch')='AMD64'" caption="Switching to a non-multilib profile">
332 # <i>eselect profile list</i>
333 Available profile symlink targets:
334 [1] <keyval id="profile"/> *
335 [2] <keyval id="profile"/>/desktop
336 [3] <keyval id="profile"/>/desktop/gnome
337 [4] <keyval id="profile"/>/desktop/kde
338 [5] <keyval id="profile"/>/no-multilib
339 <comment>(Choose the no-multilib profile)</comment>
340 # <i>eselect profile set 5</i>
341 <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 [3] <keyval id="profile"/>/desktop/gnome
347 [4] <keyval id="profile"/>/desktop/kde
348 [5] <keyval id="profile"/>/no-multilib *
349 </pre>
350
351 <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 </body>
357 </subsection>
358 <subsection id="configure_USE">
359 <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 amount of dependencies. With Gentoo you can define what options a package
375 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 programs that support it. <e>-X</e> will remove X-server support (note the
382 minus sign in front). <e>gnome gtk -kde -qt4</e> will compile your
383 programs with gnome (and gtk) support, and not with kde (and qt) support,
384 making your system fully tweaked for GNOME.
385 </p>
386
387 <p>
388 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 directory which <path>/etc/portage/make.profile</path> points to and all parent
391 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 <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 </p>
401
402 <p>
403 A full description on <c>USE</c> can be found in the second part of the Gentoo
404 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 <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 <comment>(You can scroll using your arrow keys, exit by pressing 'q')</comment>
412 </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 </p>
418
419 <pre caption="Opening /etc/portage/make.conf">
420 # <i>nano -w /etc/portage/make.conf</i>
421 </pre>
422
423 <pre caption="USE setting">
424 USE="-gtk -gnome qt4 kde dvd alsa cdr"
425 </pre>
426
427 </body>
428 </subsection>
429 </section>
430 <section test="contains('AMD64 arm PPC PPC64 x86', func:keyval('arch'))">
431 <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 <title>Timezone</title>
451 <body>
452
453 <p>
454 Finally select your timezone so that your system knows where it is physically
455 located. Look for your timezone in <path>/usr/share/zoneinfo</path>, then
456 write it in the <path>/etc/timezone</path> file.
457 </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 # <i>echo "Europe/Brussels" &gt; /etc/timezone</i>
463 </pre>
464
465 <p>
466 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 </p>
470
471 <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 </pre>
481
482 </body>
483 </section>
484
485 <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 generate 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 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20