Handbook Talk:AMD64/Installation/Media

No "current-iso" directory
The manual says "Select the current-iso/ directory", but there is none; at least not here: http://mirror.csclub.uwaterloo.ca/gentoo-distfiles/releases/amd64/autobuilds/

Unless I'm mistaken, it should be corrected to "current-install-amd64-minimal"? I can't do that myself because I lack edit permissions. ~ Michael Allan (talk) 11:05, 15 March 2015 (UTC)


 * I have fixed this a file ago. Thanks for reporting it! --Maffblaster (talk) 21:11, 18 August 2016 (UTC)

Additional Helpful Edit
The fetching of the keys example presumes a key server has already been set; for someone starting anew, this may not be the case; instead it would be more helpful if the example instruction includes specifying the key server, as well:

pgp --keyserver hkps.pool.sks-keyservers.net --recv-keys 

The previous comment was from: Jlpoole (talk)


 * It would seem that someone took this advice because the example does (now) use the hkps.pool.sks-keyservers.net server pool. Thanks for reporting it! --Maffblaster (talk) 21:15, 18 August 2016 (UTC)

Bad link for 'Gentoo AMD64 project site'
This link (in the 'Hardware requirements' paragraph) leads here: https://www.gentoo.org/proj/en/base/amd64/ and gives 404 error; the link there to the archived version of the page gives 500 error.

The previous comment was from: Mz (talk)

This looks to have been taken care of. --Grknight (talk) 02:01, 22 October 2015 (UTC)

Booting in UEFI mode
"When installing Gentoo with the purpose of using the UEFI interface instead of BIOS, it is recommended to boot with UEFI immediately". Those words are in "Booting the installation CD" It seems as if he had to do with the installation CD, but the CD is not able UEFI. --Quilosaq (talk)


 * I believe it should be mentioned that you need to use different media like SystemRescueCD ( https://www.system-rescue-cd.org/SystemRescueCd_Homepage ) to load in UEFI and that loading in UEFI is requiered to install Gentoo which supports UEFI. - EvgeniyZh (talk)


 * You are both correct. We're working on getting the Release Engineering team to upgrade our Minimal CDs ability. Right now it can only boot in BIOS (MBR) mode. I will return here when the Handbook has been updated. Done! My edit in this section notes the Minimal install CDs inability to boot UEFI mode. It instructs the reader to use the LiveDVD instead. --Maffblaster (talk) 22:50, 20 April 2017 (UTC)

Optional:_Starting_the_SSH_daemon root login
In this section people up ssh daemon, but with latest version sshd it have #PermitRootLogin prohibit-password options by default, which allow only root login with some keys. We can add info about it to be need change sshd_config to PermitRootLogin yes

Or maybe gentoo can do it only for installation cd dvd's when prepare it ? --Cronolio (talk) 23:50, 14 June 2016 (UTC)


 * Did you open a bug for this on Bugzilla.g.o as instructed on IRC? We'll have to work with RelEng to determine the proper solution. Good work spotting this! Don't forget to sign your comments! --Maffblaster (talk) 23:45, 14 June 2016 (UTC)


 * Yes https://bugs.gentoo.org/show_bug.cgi?id=585930 --Cronolio (talk) 23:50, 14 June 2016 (UTC)

Done https://gitweb.gentoo.org/repo/gentoo.git/commit/?id=5f80a533616f8e591963a5f2ae7d7e9a694e0079 Thanks. --Cronolio (talk) 12:26, 19 June 2016 (UTC)

Typo in Burning
In the Burning with Linux section, the command  contains two hyphens in a row in the filename. - dcljr (talk) 03:15, 7 August 2016 (UTC)


 * Fixed! It was our special PHP function that inserts the name of the Arch that was broken. Thanks for reporting it! --Maffblaster (talk) 21:05, 18 August 2016 (UTC)

K3b
I don't have permissions to fix this myself. Package app-cdr/k3b should be replaced with kde-apps/k3b. Thanks. — The preceding unsigned comment was added by Fturco (talk • contribs) 15 April 2017


 * Fixed as of just a moment ago! Thanks, ! --Maffblaster (talk) 22:48, 20 April 2017 (UTC)

'Core 2' as EM64T example feels outdated
Listing Core 2 Duo & Quad processors as primary examples of EM64T CPUs seems not to be up-to-date. Core 2 is a 11 years old architecture by now (2017). Giving a Core iX as the example would fit much better.


 * Updated to Core i3, i5, and i7 for example. Please remember to sign contributions to discussion pages using the button found in the edit toolbox. Thanks! --Maffblaster (talk) 12:24, 24 April 2017 (UTC)

Typo in Note associated with: "Optional: Starting the SSH daemon"
I noticed a very minor typo in the Note associated with the SSH daemon setup.

Where it reads:

Does it not read better:

Perhaps the missing 's' comes from the use of "users" from the beginning and thus:

— The preceding unsigned comment was added by Stardotstar (talk • contribs)


 * Fixed! Thank you!

Things to do when a user account is added, specifically for purposes of installation assistance via ssh.
I have a laptop which will only install with physical ethernet adapter, so I intend to install via ssh from another lappy.

In doing this I noticed a few things that didn't quite follow perfectly in the handbook so I went back over it and think I can make the following observations for consideration.

Edit: I think I have created problems here by commencing the install process in a terminal session on the live CD environment, wherein one is logged in as the user gentoo. When I switch to + I am at a terminal as root, in which case the command will work as described.

Setting a root password seems to be slightly different than depicted. It appears to require sudo passwd.

I think I have this right since, the default user is gentoo and passwd would set their own password. Further, I found: passwd root, returns: passwd: you may not view or modify password information for root.

n.b. This output was copied from trying the passwd root command after I had already successfully changed it with sudo passwd, which I only tried when I couldn't do it with passwd alone (and I note that in the description, the indicated active user is indeed already root (or maybe I have something out of sequence or something - I'm trying to parse all this from the mindset of having to follow the instructions literally with little or no assumed knowledge).)

At any rate, since one needs sudo command and root user authority to perform the installation via ssh in many installation scenarios (and, if I'm not mistaken in the use case I have, where I need to conduct as much of the install as possible from my other laptop via ssh), then allowing the added user to sudo may need to be described appropriately.

Would it be enough to simply add the new user to the wheel group when creating the user for this purpose?

I have tested this from scratch - booting into the live environment switching to the + root terminal session, setting, adding a new user: and then starting  and I was able to ssh into the installation environment and execute  commands.

I used sudo vi /etc/group to add my new user to all the groups that gentoo was a member of (presumably only needs wheel) and then logged out and back in via ssh (I think the group can be updated on the fly but I didn't look up how?).

I was then able to reproduce the same experience so far using the gentoo user on the local machine with my newly added account via ssh.

I do hope I'm not wasting anyone's time with this long winded query about these aspects, as it is entirely possible I've missed something in trying to be both in the mindset of a newcomer as well as being only just knowledgeable with Gentoo to be a danger to myself and all the machines around me ;) Trying to contribute and help nonetheless. --Stardotstar (talk) 05:17, 1 July 2017 (UTC) — The preceding unsigned comment was added by Stardotstar (talk • contribs)


 * Hi, this is not the place to receive support. We only talk about improving documentation for the Handbook here. Please try getting support on the Forums, email lists, or IRC. If divulge on a different installation path than is outlined in the Handbook then you are left to your own devices and our user support. Kind regards, --Maffblaster (talk) 23:46, 25 July 2017 (UTC)

Rephrasing request
at https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Media : The occasional Gentoo LiveDVD Occasionally, a special DVD is crafted by the Gentoo Ten project which can be used to install Gentoo. The instructions further down this chapter target the Minimal Installation CD so might be a bit different. However, the LiveDVD (or any other bootable Linux environment) supports getting a root prompt by just invoking sudo su - or sudo -i in a terminal.

You should want to say: "... a special DVD is crafted by the Gento Team project ... " not the Gentoo Ten ... — The preceding unsigned comment was added by Aurelien (talk • contribs)


 * I think we should link to the Release Engineering Project page instead. What do you think? Fturco (talk) 17:13, 22 November 2018 (UTC)


 * I moved this discussion here. Fturco (talk) 16:45, 14 April 2020 (UTC)

Better css style for 'Path' and 'c' templates
The templates and  make inline strings monospaced font. But the white spaces in that inline elements (spans) are more long than ordinary white spaces. Just an example: select to choose your iso. "open file" is a one voice, but his long space seems to join "select open" and "file to". Graphically speaking is ugly.

And this string actually presents on document: ... or  in a terminal. It's muddling: where starts or ends what?

I've looked for nice solution. The template generates span element with inline style "font-family: monospace; font-size: 95%". The template generates span element with class "tripleclick-separator" and the same style as just before. The next css code to append on head section may be a nice solution:

.tripleclick-separator,

span[style="font-family: monospace; font-size: 95%"] {

margin:0 2px;

padding:0 5px;

background:rgba(0,0,0,0.03);

border-left:1px solid #c0c0c0;

border-right:1px solid #c0c0c0;

}

The class "tripleclick-separator" is theoretically not necessary on that css code, but `span[style="font-family: monospace; font-size: 95%"]` doesn't work for ... However the method for applying style is secondary.

The long white space is 8px and I put this lenght to the left and to the right of span elements. There is a margin of 2px because near to punctuation is better. The border makes lenght, so 2 + 5 + 1 = 8px.

You can choose another solution, but now it's not good... Best regards! --Suricata (talk) 23:11, 8 September 2017 (UTC)

Shorter verification instructions
Downloaded files checksum verification instructions listed on Release media signatures are both more concise and clearer than the ones used on this page. Also approach does not require checking hashsum match manually making it more secure. Might be a good idea to use the same approach here.

Raindev (talk) 20:00, 3 December 2017 (UTC)

Gentoo Infrastructure
This article contains a reference to the Gentoo Infrastructure team, but no link is provided. We should use Project:Infrastructure. Fturco (talk) 17:22, 22 November 2018 (UTC)


 * I moved this discussion here. Fturco (talk) 16:48, 14 April 2020 (UTC)

Gpg4win
The Gpg4win homepage now uses HTTPS. Fturco (talk) 17:26, 22 November 2018 (UTC)
 * I just moved this discussion here. Fturco (talk) 16:38, 14 April 2020 (UTC)

GNU Screen
The GNU Screen link now redirects to Screen. Fturco (talk) 17:45, 22 November 2018 (UTC)
 * This problem has been fixed. Fturco (talk) 16:40, 14 April 2020 (UTC)

Downloading Keys, Missing Keys, and Signatures not Checked
Currently, when obtaining the keys used to verify the installation image, gpg complains that 11 signatures have not been checked due to missing keys and there is 1 bad signature. From my understanding, there is no cause for concern from this but it may be wise to update the Linux verification portion of the handbook to show this message as opposed to the older output that does not show the missing keys/bad signature. --Perfectedinterest (talk) 01:41, 1 February 2019 (UTC)

GnuPG has built-in WKD support
Newer versions of GnuPG can use WKD via

Even if we want to account for people having old GnuPG versions, it seems counter-intuitive to provide the manual method only. Michał Górny (talk) 19:58, 19 April 2019 (UTC)

WKD section doesn't appear in translation tool
I try to update the German translation of this page.

The sentence and the code block after 'Alternatively you can use instead the WKD to download the key:' do NOT appear in the translation tool. Intention? Missing tags?

--Mike155 (talk) 20:24, 2 November 2019 (UTC)

Incomprehensible sentence: '... will check for no* options before do* options ... in the exact order ...'
I don't understand the sentence: 'The bootable media will check for no* options before do* options, so that options can be overridden in the exact order specified.'

What does it mean? Is the order of options important? Or will do* options override no* options in any case? When and why would I want to override options? Maybe an example would help.

--Mike155 (talk) 20:32, 2 November 2019 (UTC)

Please add instruction for creating bootable USB sticks for installation.
The entire section on installation media assumes the use of a DVD-ROM. Increasingly, laptops and similar devices are supplied without any kind of optical drive. Most can, however, boot from a USB stick or similar, and USB sticks can be turned into the equivalent of a bootable CD. A recent attempt to do this demonstrated quite clearly that this is far from trivial (there seem to be any number of tools for this, but none seem to work as advertised, and many are barely maintained). Adding a section describing how to create a bootable USB stick for installation, from a few obvious environments including another Gentoo machine, would be very welcome. --Robvr (talk) 09:57, 24 April 2020 (UTC)


 * Usually I use dd to write ISO to USB flash (or isohybrid + dd). Please take a look at Category:Bootable media. --Vazhnov (talk) 10:59, 24 April 2020 (UTC)


 * I've been very pleased with the "Balena Etcher" program. You can download it for free from this web site. It's very easy to use: just put the program in the same directory as your .iso file, select it with your file manager (I use "Dolphin"), then select the image to burn and choose the stick to be used. Say start. A minute later you'll have a bootable USB stick. --Davidbryant (talk) 18:38, 29 June 2020 (UTC)

The "TTYs" Section Introduces Unnecessary Complexity
The section about "TTYs" (4.4.1) makes the installation job unnecessarily complicated. It says: "To view the Gentoo handbook during the installation, first create a user account as described above. Then press Alt+F2 to go to a new terminal."

There is no need to create a new user account at this early stage of the proceedings. I have constructed three Gentoo systems using "links" and TTY2 -- where I logged in as root -- without significant difficulty. In short, Linux doesn't care if "root" is logged in from multiple virtual terminals. --Davidbryant (talk) 22:14, 29 June 2020 (UTC)


 * You are correct in that all this is unnecessary. That's why the section is labeled OPTIONAL.  The user account in the live environment is simply for basic security. --Grknight (talk) 13:53, 30 June 2020 (UTC)


 * The bit about a "live" environment is just a red herring, right? The introduction to this chapter (chapter 2) of the "Handbook" says "The instructions further down this chapter target the Minimal Installation CD."


 * I suppose that a very experienced Gentoo user might be able to install a new system without consulting this "Handbook". But for the novice user, that label "optional" is just a joke. I would not have had a clue what to do next if I had not been able to switch back and forth between the "Handbook" on TTY2 and the root prompt on TTY1. And I couldn't get the "live" .iso image to work ... if it had worked, reading the Handbook would have been much easier. On top of which, y'all don't get around to explaining how to add another user besides "root" until chapter 11 of this "Handbook". I know I'm supposed to RTFM, but skipping ahead nine chapters is just not gonna happen. --Davidbryant (talk) 14:35, 1 July 2020 (UTC)

Suggested Improvements
Here are some more suggestions. Quoted material is from "Choosing the right installation medium".

- "Before we start, we first list what hardware requirements are needed to successfully install Gentoo on a amd64 box."

Bad grammar, not idiomatic, a misspelled word ("an", not "a") -- and it breaks the "no first-person" rule, to boot. I suggest:

Here is a list of the hardware needed to install Gentoo on an AMD64 box.

(About style: abbreviations like "AMD64" can be presented either with or without capital letters. It is generally considered good writing style to choose one version of such abbreviations, and then stick with it consistently. Since it's "AMD64" in the title of the "Handbook", it really ought to be "AMD64" everywhere.)

- "The Gentoo minimal installation CD is a bootable image which contains a self-sustained Gentoo environment."

What on Earth does sustenance have to do with it? We're talking about software, not victuals. I suggest this:

The Gentoo minimal installation CD is a bootable image: a self-contained Gentoo environment.

(The rest of this paragraph is really very good.)

- "The instructions further down this chapter target the Minimal Installation CD so might be a bit different."

Clumsy, and not even idiomatic. How about this?

The instructions in this chapter target the Minimal Installation CD, so things might be a bit different when booting from the LiveDVD.

- "To first verify the cryptographic signature, tools such as GPG4Win can be used. After installation, the public keys of the Gentoo Release Engineering team need to be imported. The list of keys is available on the signatures page. Once imported, the user can then verify the signature of the  file."

Several things are unclear in this paragraph. After installation? Which installation? The Gentoo installation? Or the GPG4Win installation? This may seem obvious to y'all, but it's not necessarily obvious to members of the target audience. They're just babes in the woods, and it would behoove you to keep that fact clearly in mind when writing something like this "Handbook".

Here's a stab at a rewrite.

A tool like GPG4Win can be used to verify the cryptographic signature inside the  file. First, download and install the GPG4Win program. Then, import the public key for the Gentoo Release Engineering team from the signatures page. Finally, use this key and the GPG4Win program to verify the signature inside the  file.

- Running out of steam for today. More tomorrow. --Davidbryant (talk) 17:25, 17 July 2020 (UTC)


 * Took the middle 2 suggestions for now. The first one is not possible as written due to the shared structure of the Handbook across every architecture.  didn't want to dive into the final one just yet. --Grknight (talk) 19:05, 17 July 2020 (UTC)


 * I just waded through the process of verifying the cryptographic signature and the SHA512SUM using Windows 10. Here's what I had to do.


 * 1. Downloading and installing the GPG4Win package was pretty straightforward -- just download a self-extracting archive from the web site, and run it. That much should be familiar ground for most Windows users. The one problem I ran into is that the documentation (provided as a .pdf file called ) is pretty far out of date. The only GUI interface for Windows is now provided via KDE's "Kleopatra" package. Fortunately, I've used Kleopatra from time to time, so I was able to get things to work.


 * 2. When I tried to download the DIGESTS.asc file from https://www.gentoo.org/downloads/, Firefox opened it as a text document. So I had to copy it into a Notepad window, then save it as a text file on my local hard disk. The same thing happens when I choose one of the mirrors.


 * 3. Try as I might, I could not obtain the Gentoo Engineering keys from the signature page -- that's where the existing instructions in the Handbook say to look for them. What I finally did was visit https://gentoo.org/.well-known/openpgpkey/hu/wtktzo4gyuhzu8a4z5fdj3fgmr1u6tob?l=releng, then save the "octet stream" file on my local hard disk. I tried to use "File Explorer" to find Kleopatra ... that didn't work, So I told Kleopatra to import keys (File --> Import), then said "any file" (there's a builtin filter ... .asc, .cer, .gpg, etc.) and selected the downloaded octet stream. Kleopatra imported a pair of keys from the Gentoo Engineering Team. So then I selected File --> Decrypt/Verify, and pointed Kleo to the DIGESTS.asc file. The message it displayed was not very useful, but "Show Audit Log" opened another window where I could view the gpg output, including the fingerprint of the signing key.


 * 4. At long last I was ready to check the .iso file to make sure it was OK. I had to run "Windows Power Shell (X86)" ... the CertUtil program was apparently written in 32-bit assembler, and hasn't yet been updated to run from the 64-bit DOS prompt. "Windows Power Shell (x86)" is available on the Start menu. It starts in the user's home directory. So I keyed in three commands:


 * Well, that's enough for today, I guess. I posted this from Windows 10, which I really don't use very often. I don't suppose a whole lot of Win 10 users are likely to jump straight into Gentoo Linux. They're much more likely to try something like MX Linux, or Ubuntu, or Linux Mint ... easier to install, and much quicker to get up and running, especially the first time around. Still, you never know. --Davidbryant (talk) 21:31, 19 July 2020 (UTC)

More Suggestions
I'm picking up where I left off. More about Windows later ... I'll cook up a proposed revision in a day or two. As always, quoted material is from the associated Wiki page.

- From 3.2.2, Linux based verification:

"Alternatively you can use instead the WKD to download the key: "

What the heck is "the WKD"? I tried looking it up with DuckDuckGo, and mainly got a bunch of stuff about some sort of vodka-based soda pop concoction that's marketed in the U.K. Just curious, I guess.

This section is very well done. I do have one suggestion, though. The "Guidelines" page says, in reference to the &#123;&#123;Cmd&#125;&#125; template:

If the command output is verbose (more than 5 lines) use the collapse-output=true parameter to create an 'Expand' link.

This seems like good advice. For instance ...

Alternatively, you can use the  command:

That certainly looks cleaner than the existing wiki page, to me.

- Section 3.3: Burning a disk

I don't have any particular objection to any of the language here. But I am curious why there's no mention of USB sticks. It's generally much faster and easier to "burn" the .iso file to a USB stick than it is to use a CD-ROM or a DVD. If I cook up some language describing how to create a bootable USB stick (Linux, and Windows), would somebody be willing to add it to the article?

- console=X -- "This sets up serial console access for the CD. The first option is the device, usually ttyS0 on x86, ..."

I find this a mite confusing. This is the AMD64 handbook -- "x86" generally refers to a 32-bit machine. Not a big deal, I guess.

- nodetect -- "... This is useful for doing debugging of a failing CD or driver."

nohotplug -- "... This is useful for doing debugging of a failing CD or driver."

Redundant. Or should I say pleonastic? Better would be ... This is useful for debugging a failing CD or driver.

- This is just a general observation. When I went through this wiki page for the first time, I was a little confused by the plethora of boot options. After studying the list for a while, I concluded that the USB stick I had prepared would probably work just fine without worrying about any of the optional parameters. A word or two of guidance for the novice user right in front of Kernel choices might be helpful. For instance:

In all likelihood, you can boot the default gentoo kernel without specifying any of the optional parameters, and it will work just fine. If you run into problems, or if you're already a Linux expert, you may find the following options of interest. Otherwise, you can skip ahead to Viewing documentation while installing.

- On to the next chapter! --Davidbryant (talk) 16:40, 20 July 2020 (UTC)

Proposed Revision to 3.2.1 Microsoft Windows based verification
Herre are the promised revisions to the Microsoft Windows based verification section.

--- Microsoft Windows has provided hash function support (DOS command ) since the introduction of Windows 7 in 2009. Windows does not support GPG cryptography. Cryptographic software must be installed to verify the Gentoo Engineering Team's signature on the   file that contains hash sums for validating the   installation file. (This step is optional.)

To verify the hash sums cryptographically, download and install the GPG4Win program. This is easy -- download the self-extracting archive from the GPG4Win web site, then run the downloaded .exe file. This will add a program named  to the Windows start menu.

Next, download a copy of the Gentoo Engineering Team's signing key by pointing a web browser to https://gentoo.org/.well-known/openpg/hu/wtktzo4gyuhzu8a4z5fdj3fgmr1u6tob?l=releng, and saving the "octet-stream" file to your hard disk somewhere. Use any desired filename, but be sure to specify the  filename extension. Then, add the downloaded Gentoo keys to your key ring using. Fire up  from the Windows start menu. Choose "Import" from  "File" menu, then select the downloaded octet-stream file.

The cryptographic signature on the  file downloaded in the preceding step can now be verified. Select "Decrypt/Verify" from  "File" menu, then open the   file downloaded previously. Click "Show Audit Log", and compare the fingerprint in the audit log to the fingerprint for Gentoo Engineering shown on the signatures page. They should match.

Even if the optional cryptographic validation step is omitted, the SHA512 checksum total for the Gentoo  file should be verified before burning a bootable CD-ROM or etching a USB stick. This can be done with the  program, which is, most likely, already installed in your copy of Windows. Start up a 32-bit DOS prompt (either Windows System --> Command Prompt, or Windows PowerShell --> Windows PowerShell (x86), from the "Start" menu) and navigate to the folder where you downloaded the Gentoo  file. The following example assumes the file is in your "Downloads" folder.

Once the  file has been located, tell Windows to compute a hash total (SHA512SUM) for that file.

Finally, open the  file with the Notepad editor. The SHA512 hash total shown there should match the hash total computed by. If the totals do not match, either the Gentoo installation file or the  file -- or possibly both of them -- was/were not downloaded correctly.

- The original copy of this suggestion is on my user page. --Davidbryant (talk) 16:48, 22 July 2020 (UTC)

Admin CD and other advanced media choices
On the gentoo.org downloads page there is an "admin CD" about which I can find virtually no information, save a few forum posts from people asking what it is, and a bug from when it was apparently first created: bugs.gentoo.org/352152.

It would seem that this would be the right place to explain a little about what this CD is for, and the differences with the minimal CD.

Also, this seems to be the place for a very brief indication of the differences between the openrc, systemd, no multilib, x32, ulibc, and hardened stage3 tarballs.

I'm sorry that I can't provide copy about the admin CD, but I really don't know anything about it and I can't estimate the reliability of the little information there is on #352152, if nobody here has much further information, I could look into it though... I'd be happy to write up something on the different stage tarballs, if anybody thinks it is a good idea to have that.

All the best.

Kyoreln (talk) 15:16, 20 June 2021 (UTC)