1. Jump to: content
2. Toggle navigation
3. Installing the Gentoo base system
4. Handbook:AMD64 | Installation
5. Other languages:        čeština • ‎Deutsch • ‎English • ‎español • ‎français • ‎italiano • ‎日本語 • ‎한국어 • ‎polski • ‎português do Brasil • ‎русский • ‎українська • ‎中文 • ‎中文（中国大陆）‎
6. AMD64 Handbook
7. Installation
8. About the installation
9. Choosing the media
10. Configuring the network
11. Preparing the disks
12. Installing stage3
13. Installing base system
14. Configuring the kernel
15. Configuring the system
16. Installing tools
17. Configuring the bootloader
18. Finalizing
19. Working with Gentoo
20. Portage introduction
21. USE flags
22. Portage features
23. Initscript system
24. Environment variables
25. Working with Portage
26. Files and directories
27. Variables
28. Mixing software branches
29. Additional tools
30. Custom package repository
31. Advanced features
32. Network configuration
33. Getting started
34. Advanced configuration
35. Modular networking
36. Wireless
37. Adding functionality
38. Dynamic management
39.  
40. Contents
41. 1 Chrooting
42. 1.1 Optional: Selecting mirrors
43. 1.1.1 Distribution files
44. 1.1.2 Gentoo ebuild repository
45. 1.2 Copy DNS info
46. 1.3 Mounting the necessary filesystems
47. 1.4 Entering the new environment
48. 1.5 Mounting the boot partition
49. 2 Configuring Portage
50. 2.1 Installing an ebuild repository snapshot from the web
51. 2.2 Optional: Updating the Gentoo ebuild repository
52. 2.3 Reading news items
53. 2.4 Choosing the right profile
54. 2.4.1 No-multilib
55. 2.4.2 systemd
56. 2.5 Updating the @world set
57. 2.6 Configuring the USE variable
58. 3 Optional: Using systemd as the init system
59. 4 Timezone
60. 5 Configure locales
61. Chrooting
62. Optional: Selecting mirrors
63. Distribution files
64. In order to download source code quickly it is recommended to select a fast mirror. Portage will look in the make.conf file for the GENTOO_MIRRORS variable and use the mirrors listed therein. It is possible to surf to the Gentoo mirror list and search for a mirror (or mirrors) that is close to the system's physical location (as those are most frequently the fastest ones). However, we provide a nice tool called mirrorselect which provides users with a nice interface to select the mirrors needed. Just navigate to the mirrors of choice and press Spacebar to select one or more mirrors.
65.  
66. root #mirrorselect -i -o >> /mnt/gentoo/etc/portage/make.conf
67. Gentoo ebuild repository
68. A second important step in selecting mirrors is to configure the Gentoo ebuild repository via the /etc/portage/repos.conf/gentoo.conf file. This file contains the sync information needed to update the package repository (the collection of ebuilds and related files containing all the information Portage needs to download and install software packages).
69.  
70. Configuring the repository can be done in a few simple steps. First, if it does not exist, create the repos.conf directory:
71.  
72. root #mkdir --parents /mnt/gentoo/etc/portage/repos.conf
73. Next, copy the Gentoo repository configuration file provided by Portage to the (newly created) repos.conf directory:
74.  
75. root #cp /mnt/gentoo/usr/share/portage/config/repos.conf /mnt/gentoo/etc/portage/repos.conf/gentoo.conf
76. Take a peek with a text editor or by using the cat command. The inside of the file should be in .ini format and look like this:
77.  
78. FILE /mnt/gentoo/etc/portage/repos.conf/gentoo.conf
79. [DEFAULT]
80. main-repo = gentoo
81.  
82. [gentoo]
83. location = /usr/portage
84. sync-type = rsync
85. sync-uri = rsync://rsync.gentoo.org/gentoo-portage
86. auto-sync = yes
87. sync-rsync-verify-jobs = 1
88. sync-rsync-verify-metamanifest = yes
89. sync-rsync-verify-max-age = 24
90. sync-openpgp-key-path = /usr/share/openpgp-keys/gentoo-release.asc
91. sync-openpgp-key-refresh-retry-count = 40
92. sync-openpgp-key-refresh-retry-overall-timeout = 1200
93. sync-openpgp-key-refresh-retry-delay-exp-base = 2
94. sync-openpgp-key-refresh-retry-delay-max = 60
95. sync-openpgp-key-refresh-retry-delay-mult = 4
96.  
97. # for daily squashfs snapshots
98. #sync-type = squashdelta
99. #sync-uri = mirror://gentoo/../snapshots/squashfs
100. The default sync-uri variable value listed above will determine a mirror location based on a rotation. This will aid in easing bandwidth stress on Gentoo's infrastructure and will provide a fail-safe in case a specific mirror is offline. It is recommended the default URI is retained unless a local, private Portage mirror will be used.
101.  
102.  Tip
103. For those interested, the official specification for Portage's plug-in sync API can be found in the Portage project's Sync article.
104. Copy DNS info
105. One thing still remains to be done before entering the new environment and that is copying over the DNS information in /etc/resolv.conf. This needs to be done to ensure that networking still works even after entering the new environment. /etc/resolv.conf contains the name servers for the network.
106.  
107. To copy this information, it is recommended to pass the --dereference option to the cp command. This ensures that, if /etc/resolv.conf is a symbolic link, that the link's target file is copied instead of the symbolic link itself. Otherwise in the new environment the symbolic link would point to a non-existing file (as the link's target is most likely not available inside the new environment).
108.  
109. root #cp --dereference /etc/resolv.conf /mnt/gentoo/etc/
110. Mounting the necessary filesystems
111. In a few moments, the Linux root will be changed towards the new location. To make sure that the new environment works properly, certain filesystems need to be made available there as well.
112.  
113. The filesystems that need to be made available are:
114.  
115. /proc/ which is a pseudo-filesystem (it looks like regular files, but is actually generated on-the-fly) from which the Linux kernel exposes information to the environment
116. /sys/ which is a pseudo-filesystem, like /proc/ which it was once meant to replace, and is more structured than /proc/
117. /dev/ is a regular file system, partially managed by the Linux device manager (usually udev), which contains all device files
118. The /proc/ location will be mounted on /mnt/gentoo/proc/ whereas the other two are bind-mounted. The latter means that, for instance, /mnt/gentoo/sys/ will actually be /sys/ (it is just a second entry point to the same filesystem) whereas /mnt/gentoo/proc/ is a new mount (instance so to speak) of the filesystem.
119.  
120. root #mount --types proc /proc /mnt/gentoo/proc
121. root #mount --rbind /sys /mnt/gentoo/sys
122. root #mount --make-rslave /mnt/gentoo/sys
123. root #mount --rbind /dev /mnt/gentoo/dev
124. root #mount --make-rslave /mnt/gentoo/dev
125.  Note
126. The --make-rslave operations are needed for systemd support later in the installation.
127.  Warning
128. When using non-Gentoo installation media, this might not be sufficient. Some distributions make /dev/shm a symbolic link to /run/shm/ which, after the chroot, becomes invalid. Making /dev/shm/ a proper tmpfs mount up front can fix this:
129. root #test -L /dev/shm && rm /dev/shm && mkdir /dev/shm
130. root #mount --types tmpfs --options nosuid,nodev,noexec shm /dev/shm
131. Also ensure that mode 1777 is set:
132.  
133. root # chmod 1777 /dev/shm
134. Entering the new environment
135. Now that all partitions are initialized and the base environment installed, it is time to enter the new installation environment by chrooting into it. This means that the session will change its root (most top-level location that can be accessed) from the current installation environment (installation CD or other installation medium) to the installation system (namely the initialized partitions). Hence the name, change root or chroot.
136.  
137. This chrooting is done in three steps:
138.  
139. The root location is changed from / (on the installation medium) to /mnt/gentoo/ (on the partitions) using chroot
140. Some settings (those in /etc/profile) are reloaded in memory using the source command
141. The primary prompt is changed to help us remember that this session is inside a chroot environment.
142. root #chroot /mnt/gentoo /bin/bash
143. root #source /etc/profile
144. root #export PS1="(chroot) ${PS1}"
145. From this point, all actions performed are immediately on the new Gentoo Linux environment. Of course it is far from finished, which is why the installation still has some sections left!
146.  
147.  Tip
148. If the Gentoo installation is interrupted anywhere after this point, it should be possible to 'resume' the installation at this step. There is no need to repartition the disks again! Simply mount the root partition and run the steps above starting with copying the DNS info to re-enter the working environment. This is also useful for fixing bootloader issues. More information can be found in the chroot article.
149. Mounting the boot partition
150. Now that the new environment has been entered, it is necessary to create and mount the /boot partition. This will be important when it is time to compile the kernel and install the bootloader:
151.  
152. root #mkdir /boot
153. root #mount /dev/sda2 /boot
154. Configuring Portage
155. Installing an ebuild repository snapshot from the web
156. Next step is to install a snapshot of the main ebuild repository. This snapshot contains a collection of files that informs Portage about available software titles (for installation), which profiles the system administrator can select, package or profile specific news items, etc.
157.  
158. The use of emerge-webrsync is recommended for those who are behind restrictive firewalls (because it uses HTTP/FTP protocols for downloading the snapshot) and saves network bandwidth. Readers who have no network or bandwidth restrictions can happily skip down to the next section.
159.  
160. This will fetch the latest snapshot (which is released on a daily basis) from one of Gentoo's mirrors and install it onto the system:
161.  
162. root #emerge-webrsync
163.  Note
164. During this operation, emerge-webrsync might complain about a missing /usr/portage/ location. This is to be expected and nothing to worry about - the tool will create the location.
165. From this point onward, Portage might mention that certain updates are recommended to be executed. This is because system packages installed through the stage file might have newer versions available; Portage is now aware of new packages because of the repository snapshot. Package updates can be safely ignored for now; updates can be delayed after the Gentoo installation has finished.
166.  
167. Optional: Updating the Gentoo ebuild repository
168. It is possible to update the Gentoo ebuild repository to the latest version. The previous emerge-webrsync command will have installed a very recent snapshot (usually recent up to 24h) so this step is definitely optional.
169.  
170. Suppose there is a need for the last package updates (up to 1 hour), then use emerge --sync. This command will use the rsync protocol to update the Gentoo ebuild repository (which was fetched earlier on through emerge-webrsync) to the latest state.
171.  
172. root #emerge --sync
173. On slow terminals, like some framebuffers or serial consoles, it is recommended to use the --quiet option to speed up the process:
174.  
175. root #emerge --sync --quiet
176. Reading news items
177. When the Gentoo ebuild repository is synchronized to the system, Portage may warn the user with messages similar to the following:
178.  
179. * IMPORTANT: 2 news items need reading for repository 'gentoo'.
180. * Use eselect news to read news items.
181. News items were created to provide a communication medium to push critical messages to users via the rsync tree. To manage them, use eselect news. The eselect application is a Gentoo application that allows for a common management interface towards system changes and operations. In this case, eselect is asked to use its news module.
182.  
183. For the news module, three operations are most used:
184.  
185. With list an overview of the available news items is displayed.
186. With read the news items can be read.
187. With purge news items can be removed once they have been read and will not be reread anymore.
188. root #eselect news list
189. root #eselect news read
190. More information about the newsreader is available through its manual page:
191.  
192. root #man news.eselect
193. Choosing the right profile
194.  Warning
195. Do not select any of the the 17.1 profiles until reading the corresponding 17.1 news item. This profile is experimental and requires special migration instructions.
196. A profile is a building block for any Gentoo system. Not only does it specify default values for USE, CFLAGS, and other important variables, it also locks the system to a certain range of package versions. These settings are all maintained by Gentoo's Portage developers.
197.  
198. You can see what profile the system is currently using with eselect, now using the profile module:
199.  
200. root #eselect profile list
201. Available profile symlink targets:
202.   [1]   default/linux/amd64/13.0 *
203.   [2]   default/linux/amd64/13.0/desktop
204.   [3]   default/linux/amd64/13.0/desktop/gnome
205.   [4]   default/linux/amd64/13.0/desktop/kde
206.  Note
207. The output of the command is just an example and evolves over time.
208. As can be seen, there are also desktop subprofiles available for some architectures.
209.  
210.  Warning
211. Profile upgrades are not to be taken lightly. When selecting the initial profile, make sure to use profile corresponding to the same version as the one initially used by stage3 (e.g. 13.0). Each new profile version is announced through a news item containing migration instructions. Make sure to read it and follow them before switching to a newer profile.
212. After viewing the available profiles for the amd64 architecture, users can select a different profile for the system:
213.  
214. root #eselect profile set 2
215.  
216. No-multilib
217. In order to select a pure 64-bit environment, with no 32-bit applications or libraries, use a no-multilib profile:
218.  
219. root #eselect profile list
220. Available profile symlink targets:
221.   [1]   default/linux/amd64/13.0 *
222.   [2]   default/linux/amd64/13.0/desktop
223.   [3]   default/linux/amd64/13.0/desktop/gnome
224.   [4]   default/linux/amd64/13.0/desktop/kde
225.   [5]   default/linux/amd64/13.0/no-multilib
226. Next select the no-multilib profile:
227.  
228. root #eselect profile set 5
229. root #eselect profile list
230. Available profile symlink targets:
231.   [1]   default/linux/amd64/13.0
232.   [2]   default/linux/amd64/13.0/desktop
233.   [3]   default/linux/amd64/13.0/desktop/gnome
234.   [4]   default/linux/amd64/13.0/desktop/kde
235.   [5]   default/linux/amd64/13.0/no-multilib *
236. systemd
237. Those who desire systemd as their init system should select a profile with systemd somewhere in the profile name:
238.  
239. root #eselect profile set default/linux/amd64/13.0/systemd
240. root #eselect profile list
241. Available profile symlink targets:
242.   [10]  default/linux/amd64/13.0/developer
243.   [11]  default/linux/amd64/13.0/no-multilib
244.   [12]  default/linux/amd64/13.0/systemd *
245.   [13]  default/linux/amd64/13.0/x32
246.   [14]  hardened/linux/amd64
247.  Tip
248. As seen above, full profile names can be used instead of the profile's associated numerical value.
249.  
250.  Note
251. The developer subprofile is specifically for Gentoo Linux development and is not meant to be used by casual users.
252. Updating the @world set
253. At this point, it is wise to update the system's @world set so that a base can be established.
254.  
255. This following step is necessary so the system can apply any updates or USE flag changes which have appeared since the stage3 was built and from any profile selection:
256.  
257. root #emerge --ask --verbose --update --deep --newuse @world
258.  Tip
259. If a full scale desktop environment profile has been selected this process could greatly extend the amount of time necessary for the install process. Those in a time crunch can work by this 'rule of thumb': the shorter the profile name, the less specific the system's @world set; the less specific the @world set, the fewer packages the system will require. In other words:
260. selecting default/linux/amd64/13.0 will require very few packages to be updated, whereas
261. selecting default/linux/amd64/13.0/desktop/gnome/systemd will require many packages to be installed since the init system is changing from OpenRC to systemd, and the GNOME desktop environment framework will be installed.
262. Configuring the USE variable
263. USE is one of the most powerful variables Gentoo provides to its users. Several programs can be compiled with or without optional support for certain items. For instance, some programs can be compiled with support for GTK+ or with support for Qt. Others can be compiled with or without SSL support. Some programs can even be compiled with framebuffer support (svgalib) instead of X11 support (X-server).
264.  
265. Most distributions compile their packages with support for as much as possible, increasing the size of the programs and startup time, not to mention an enormous amount of dependencies. With Gentoo users can define what options a package should be compiled with. This is where USE comes into play.
266.  
267. In the USE variable users define keywords which are mapped onto compile-options. For instance, ssl will compile SSL support in the programs that support it. -X will remove X-server support (note the minus sign in front). gnome gtk -kde -qt4 -qt5 will compile programs with GNOME (and GTK+) support, and not with KDE (and Qt) support, making the system fully tweaked for GNOME (if the architecture supports it).
268.  
269. The default USE settings are placed in the make.defaults files of the Gentoo profile used by the system. Gentoo uses a (complex) inheritance system for its profiles, which we will not dive into at this stage. The easiest way to check the currently active USE settings is to run emerge --info and select the line that starts with USE:
270.  
271. root #emerge --info | grep ^USE
272. USE="X acl alsa amd64 berkdb bindist bzip2 cli cracklib crypt cxx dri ..."
273.  Note
274. The above example is truncated, the actual list of USE values is much, much larger.
275. A full description on the available USE flags can be found on the system in /usr/portage/profiles/use.desc.
276.  
277. root #less /usr/portage/profiles/use.desc
278. Inside the less command, scrolling can be done using the ↑ and ↓ keys, and exited by pressing q.
279.  
280. As an example we show a USE setting for a KDE-based system with DVD, ALSA, and CD recording support:
281.  
282. root #nano -w /etc/portage/make.conf
283. FILE /etc/portage/make.confEnabling USE for a KDE-based system with DVD, ALSA and CD recording support
284. USE="-gtk -gnome qt4 qt5 kde dvd alsa cdr"
285. When USE is defined in /etc/portage/make.conf it is added (or removed if the USE flag starts with the - sign) from that default list. Users who want to ignore any default USE settings and manage it completely themselves should start the USE definition in make.conf with -*:
286.  
287. FILE /etc/portage/make.confIgnoring default USE flags
288. USE="-* X acl alsa"
289.  Warning
290. Although possible, setting -* (as seen in the example above) is discouraged as carefully chosen USE flag defaults may be configured in some ebuilds to prevent conflicts and other errors.
291. Optional: Using systemd as the init system
292. The remainder of the Gentoo Handbook focuses on OpenRC (the traditional Gentoo init system) as the default init system. If systemd is desired or if the reader will be installing GNOME 3.8 and later (which requires systemd), please consult the systemd article. It contains instructions equivalent to the instructions in the following sections of this Handbook. Specifically, it will walk the reader through various init system commands (systemctl) and systemd-specific services (such as timedatectl, hostnamectl, etc.) needed to establish a working systemd environment.
293.  
294.  Note
295. Certain applications are heavily dependent on the GNOME software ecosystem and subsequently dependent on systemd. Readers who are unsure if the GNOME desktop environment will be used can migrate to a systemd profile later.
296. Timezone
297. Select the timezone for the system. Look for the available timezones in /usr/share/zoneinfo/, then write it in the /etc/timezone file.
298.  
299. root #ls /usr/share/zoneinfo
300. Suppose the timezone of choice is Europe/Brussels:
301.  
302. root #echo "Europe/Brussels" > /etc/timezone
303. Please avoid the /usr/share/zoneinfo/Etc/GMT* timezones as their names do not indicate the expected zones. For instance, GMT-8 is in fact GMT+8.
304.  
305. Next, reconfigure the sys-libs/timezone-data package, which will update the /etc/localtime file for us, based on the /etc/timezone entry. The /etc/localtime file is used by the system C library to know the timezone the system is in.
306.  
307. root #emerge --config sys-libs/timezone-data
308. Configure locales
309. Most users will want to use only one or two locales on their system.
310.  
311. Locales specify not only the language that the user should use to interact with the system, but also what the rules are for sorting strings, displaying dates and times, etc.
312.  
313. The locales that a system should support should be mentioned in /etc/locale.gen.
314.  
315. root #nano -w /etc/locale.gen
316. The following locales are an example to get both English (United States) and German (Germany) with the accompanying character formats (like UTF-8).
317.  
318. FILE /etc/locale.genEnabling US and DE locales with the appropriate character formats
319. en_US ISO-8859-1
320. en_US.UTF-8 UTF-8
321. de_DE ISO-8859-1
322. de_DE.UTF-8 UTF-8
323.  Warning
324. We strongly suggest to use at least one UTF-8 locale because some applications may require it.
325. The next step is to run locale-gen. It will generate all the locales specified in the /etc/locale.gen file.
326.  
327. root #locale-gen
328. To verify that the selected locales are now available, run locale -a.
329.  
330. Once done, it is now time to set the system-wide locale settings. Again we use eselect for this, now with the locale module.
331.  
332. With eselect locale list, the available targets are displayed:
333.  
334. root #eselect locale list
335. Available targets for the LANG variable:
336.   [1] C
337.   [2] POSIX
338.   [3] en_US
339.   [4] en_US.iso88591
340.   [5] en_US.utf8
341.   [6] de_DE
342.   [7] de_DE.iso88591
343.   [8] de_DE.iso885915
344.   [9] de_DE.utf8
345.   [ ] (free form)
346. With eselect locale set VALUE the correct locale can be set:
347.  
348. root #eselect locale set 9
349. Manually, this can still be accomplished through the /etc/env.d/02locale file:
350.  
351. FILE /etc/env.d/02localeManually setting system locale definitions
352. LANG="de_DE.UTF-8"
353. LC_COLLATE="C"
354. Make sure a locale is set, as the system would otherwise display warnings and errors during kernel builds and other software deployments later in the installation.
355.  
356. Now reload the environment:
357.  
358. root #env-update && source /etc/profile && export PS1="(chroot) $PS1"
359. We made a full Localization guide to help the user guide through this process. Another interesting article is the UTF-8 guide for very specific information to enable UTF-8 on the system.
360.  
361.  
362.  
363. This page was last modified on 2 January 2015, at 00:03.
364. Privacy policyAbout Gentoo WikiDisclaimers
365. © 2001–2018 Gentoo Foundation, Inc.
366. Gentoo is a trademark of the Gentoo Foundation, Inc. The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-3.0 license. The Gentoo Name and Logo Usage Guidelines apply.