Handbook Talk:AMD64/Installation/Stage/Archive

From Gentoo Wiki
Jump to:navigation Jump to:search

This page is an archive for holding previously resolved discussions/talks from the Handbook Talk:AMD64/Installation/Stage base page.

Removing stage3 after invoking tar xpf?

Talk status
This discussion is done as of October 10, 2018.

This is bloatware police, you ware caught leaving thrash behind, please fix your unemergefull behavior. •`_´•

Remove stage-3 after `tar xpf`is invoked and remove it from the finalizing.

--Kreyren (talk) 16:39, 15 September 2018 (UTC)

Read the handbook.... All the way through: Handbook:AMD64/Installation/Finalizing#Removing_tarballs. :P --Maffblaster (talk) 16:01, 10 October 2018 (UTC)


Talk status
This discussion is done.

Maybe a pointer to use ntpdate (a la `ntpdate -s time.nist.gov`) should show up instead of just date? Not everybody has an accurate clock handy :) Hlzr (talk) 05:05, 7 August 2016 (UTC)

Valid point, although this presumes the system as a connection to the internet, which I guess we're presuming in the first place since readers are instructed to download the stage 3 file. I'll consider adding an alternative here. Thanks for the input! --Maffblaster (talk) 19:39, 3 October 2016 (UTC)

Extended attributes while untarring

Talk status
This discussion is done.

The --xattr option when untarring the stage3 tarball is ignored when using the minimal install iso for amd64 built on 20150709.--Bamapookie (talk) 21:57, 26 July 2015 (UTC)

Grab a newer version of the ISO containing a newer version of tar. Should be fine at this point. --Maffblaster (talk) 19:36, 3 October 2016 (UTC)

Choosing a stage tarball

Talk status
This discussion is done.

No-multilib (pure 64-bit)

 Selecting a no-multilib tarball to be base of the new system will provides a complete 64-bit operating system environment.This effectively renders the ability able to switch to multilib profiles improbable (although it is not impossible). 

A better (from grammar and context perspective) sentence would be :

 Selecting a no-multilib tarball as base of the new system will provide only a complete 64-bit operating system environment.  This effecti-vely renders the ability to switch to multilib profiles improbable ...

(Georgios Doumas)

Georgios, I'll take a look and try to make some grammatical improvements. You can sign your messages on here by clicking the "Signature and timestamp" button in the format box above. :) --Maffblaster (talk) 20:34, 10 March 2016 (UTC)
What about having a short mention in this section about the overview on the download page?--Charles17 (talk) 06:58, 11 March 2016 (UTC)
Hi Gentoo wiki admins, I would like my account renamed to vaukai. open a bug on Bugzilla if you'd like. Main www is outside wiki scope. :) Kind regards, --Maffblaster (talk) 19:36, 3 October 2016 (UTC)

Ping-back to 'Verifying the install ISO' when 'installing stage3'

Talk status
This discussion is done as of 2022-11-27.

I thought it might be handy to have a link in the Para. that starts "Just like with the ISO file..." back to the Installation/Media stage Handbook:AMD64/Installation/Media#Verifying_the_downloaded_files for people like myself, who don't always download a fresh ISO image every install (we likely have one lying around!) but will always download an up-to-date clean stage3, and may not remember the GPG commands to download the Gentoo RelEng keys, and verify. There is a infobox for the verify command, alternatively we could repeat the 'downloading gentoo key' box into this para. if that was deemed appropriate instead.

-- veremit (talk) 21:43, 20 February 2017 (UTC)

I think if a reader wanted to go back and verify the ISO, then they should revisit the step about verifying the ISO... this presumes they still have the extra files necessary to verify the old ISO Handbook:AMD64/Installation/Media#Linux_based_verification. That said, looks like someone implemented the suggestion in the "Verifying and validating" section: "Just like with the ISO file, it is also possible to verify the cryptographic signature of the .DIGESTS.asc file using gpg to make sure the checksums have not been tampered with:" --Maffblaster (talk) 12:00, 27 November 2022 (UTC)


Talk status
This discussion is done as of 2017-04-16.

Please replace http://gcc.gnu.org/onlinedocs/ with https. Fturco (talk) 15:22, 16 April 2017 (UTC)

This was completed some time ago. Perhaps I didn't see or forgot to close this discussion. Thanks, Francesco Turco (Fturco) . --Maffblaster (talk) 18:16, 29 December 2017 (UTC)


Talk status
This discussion is done as of May 15, 2017.

In the NOTE of section CFLAGS and CXXFLAGS, please add a link to Safe CFLAGS.

The GCC optimization guide has more information on how the various compilation options can affect a system.

Thanks. Luttztfz (talk) 12:43, 14 May 2017 (UTC)

I still think it is good to also link to the GCC optimization guide, but I will add the additional reference to the Safe CFLAGs article and perhaps mention that Safe CFLAGs may be a more practical place for beginners to start. Thank you! --Maffblaster (talk) 17:06, 15 May 2017 (UTC)

Tarballs compressed via xz now

Talk status
This discussion is done as of 2018-11-07.

Starting this week, at least amd64 stage3's are now compressed via xz, not bz2. I'd adjust the tarball wildcard to stage3-*.tar.* or similar

Iamben (talk) 15:53, 29 December 2017 (UTC)

Thanks, Ben! I have applyed a change that should work. Let me know if I missed something. --Maffblaster (talk) 20:55, 29 December 2017 (UTC)
The command uses a wrong parameter because of the brace expansion (see "tar not work porperly"). --Feng (talk) 13:36, 31 December 2017 (UTC)
I can second Feng's comment. Brace expansion and pathname expansion are two different things entirely. One should not use the former where the latter is intended. The present usage of brace expansion in the handbook constitutes a dangerous anti-pattern, as well as setting a bad example for users unfamiliar with shell mechanics. Consider the following code:
# mkdir empty && cd empty && touch foo.bz2 foo.bz2.DIGESTS
# printf '<%s>' foo.{bz2,xz}  # this is not a glob and cares not for existing pathnames
# printf '<%s>' foo.*         # this is a glob
# shopt -s extglob
# printf '<%s>' foo.@(bz2|xz) # this is a glob (of the extended variety)
# printf '<%s>' foo.+([^.])   # and so is this
In short, have the user enable the extglob shell option in order to exploit a relatively safe generic approach e.g. tar xpf stage3-*.tar.@(bz2|xz). At present, the handbook contains no valid example of a command where the characteristics of brace expansion are appropriate. Also, the commands are not consistently generic. For example, the tar command exploits * as a globbing character, whereas the user is expected to fill in <release> manually in other commands. EDIT: I just realised that Feng made a similar suggestion in Maffblaster's page. Indeed, his suggestion of using stage3-*.tar.?(bz2|xz) is superior, as it virtually guarantees that one pathname, at most, is matched in the common case. --kerframil (talk) 04:23, 21 July 2018 (UTC)
This has been added. Thanks. --Grknight (talk) 14:29, 7 November 2018 (UTC)

The commands in the "Verifying and validating" chapter could be further improved IMHO. First, if extended globbing is to be used then a command `shopt -s extglob' should be added.

Second, the use of '<' and '>' causes problems if the command is just copypasted to a console window without editing. Why not replace <release> with a single asterisk, as already used for the `tar xvpf' command?

Finally, the `gpg --verify' command did not work for me. I got the complaint "gpg: not a detached signature" and the command exited with status 2 (the sha512 and whirlpool digests were OK though).

--Rafo (talk) 21:50, 1 January 2019 (UTC)

Properly preserve all xattrs like filecaps

Talk status
This discussion is done as of 2017-12-29.

For filecaps to be preserved on unpack (like for USE=filecaps on iputils so ping isn't setuid), --xattrs isnt quite enough, that won't preserve all xattr namespaces. --xattrs-include="*.*" should be enough, this will catch the user.* stuff for filecaps, security.* stuff for pax markings, and more.

Releng is currently disabling filecaps on affected pkgs for stage3 but would like to turn this caps on eventually. We need to get the handbook adjusted before that can (safely) happen.

Iamben (talk) 15:53, 29 December 2017 (UTC)

Nice catch! Thank you for this information. I'll make the change now. --Maffblaster (talk) 20:57, 29 December 2017 (UTC)

Easy verify checksums via rhash

Talk status
This discussion is done as of November 5, 2021.

I propose add another way to check integrity of downloaded files. There is tool app-crypt/rhash which can automatically detect hash method from comments in DIGESTS files, so verifying downloaded files with SHA512 and WHIRLPOOL is simple as:

user $rhash -c stage3-*.tar.xz.DIGESTS

I found this as the most simple and universal method.

--Thaaxaco (talk) 20:07, 23 June 2018 (UTC)

It's good to mention the tool, however it is important to note we can only support tools available in the official live environment, which does not include rhash. On another note, we try to avoiding mentioning alternative tools to the verification and extraction process since the handbook provides instructions using the official minimal live environment. You're welcome to add rhash to another area of the wiki (perhaps the Complete Handbook), but we will not be adding it here. Thank you! --Maffblaster (talk) 20:39, 5 November 2021 (UTC)

Change command for stage3 to actual compression method

Talk status
This discussion is done.

Currently, the command shown to extract the stage3 use the tar.bz2, but the stage3 is actually a tar.xz, so the instructions is outdated. — The preceding unsigned comment was added by Noamcore (talkcontribs) 19:08, 4 October 2018‎

Commands have been updated. --Grknight (talk) 14:27, 7 November 2018 (UTC)

It is 7DEC2019 and the commands in the handbook for AMD64 still show bz2 commands instead of -xvJpf for .tar.xz files.

RFC: Add big red beep about systemd stages

Talk status
This discussion is done as of Nov 5, 2021.

During years people keep asking "why do we have blocks installing Gentoo with systemd???"

If you dig up you will find they are using "standard" openrc stages installing systemd-based systems. While eudev vs udev and openrc vs systemd blocks can be solved manually it looks miss-informative for new users and they get confused. So I would like we add a note about systemd stages existence as well as this allows us to reduce amount of further questions. — The preceding unsigned comment was added by Zlogene (talkcontribs) 13:38, December 16, 2018‎

We have added sections regarding systemd and that the relevant stage tarballs should be used. See this edit Special:Diff/1028319/1028325. Thanks to the work of Andreas K. Hüttel (dilfridge) , the www.g.o/downloads page also clearly delineates between the two with very nice 'tags'. This should really aid our users in downloading the correct stages for the init system target. Thank you for reporting! --Maffblaster (talk) 21:27, 5 November 2021 (UTC)

Missed format update for stage3 unpacking

Talk status
This discussion is done as of Nov 5, 2021.

All commands dealing with the stage 3 now correctly end in ?(bz2|xz) , except the actual extraction. As the up-to-date amd64 images at least are now all .xz this causes issues for people. Ideally add ?(bz2|xz) instead of bz2, or replace bz2 with xz.

Chymæra (talk) 02:10, 18 December 2018 (UTC)

As of now stage archives are zipped using .xz. This issue has been corrected in the handbook a while ago. Thank you for reporting. --Maffblaster (talk) 21:04, 5 November 2021 (UTC)

Incomprehensible sentence: 'Depending on the installation medium, the only tool ...'

Talk status
This discussion is done as of 2021-11-05.

The following sentence doesn't make sense: 'Depending on the installation medium, the only tool necessary to download a stage tarball is a web browser.'

What does this sentence mean? Maybe something like: 'In order to download a stage tarball, you will need a web browser.'?

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

This sentence has been removed for better clarity. Thank you for reporting. See Special:Diff/1028328/1028331. --Maffblaster (talk) 21:21, 5 November 2021 (UTC)

Suggestions for Improvement

Talk status
This discussion is done as of 2022-11-27.

Quoted material is from "Installing the Gentoo installation files".

"Official Gentoo installation media includes the ntpd command ..."

Ungrammatical. A plural subject demands a plural verb.

Official Gentoo installation media include the ntpd command ...

See Special:Diff/1028331/1028361.

"Official media includes a configuration file ..."

The same error. Media are plural.

Official media include a configuration file ...

See Special:Diff/1028331/1028361.

"The date command can also be used to perform a manual set on the system clock."

Very clumsy style. I suggest

The date command can also be used to set the system clock.

See Special:Diff/1028361/1028364.

"Depending on the installation medium, the only tool necessary to download a stage tarball is a web browser."

This is a non sequitur. I suggest either

Irrespective of the installation medium, the only tool necessary to download a stage tarball is a web browser.

or (and this is even better)

The only tool necessary to download a stage tarball is a web browser.

This sentence has been removed. See Special:Diff/1028328/1028331.

"To optimize Gentoo, it is possible to set a couple of variables which impacts the behavior of Portage ..."

Once again, a subject does not agree with its verb ("couple" is the implicit subject of the subordinate clause beginning "which ...").

... set a couple of variables which impact the behavior of Portage ...

Fixed. See Special:Diff/1028364/1028367.

"...too much optimization can make programs behave bad ..."

Adjectives are never verb modifiers, in the English language.

... too much optimization can make programs behave bad[ly] ...

Or, better yet,

... too much optimization can make programs misbehave ...

Fixed as suggested. See Special:Diff/1028367/1028370.

"The MAKEOPTS variable defines how many parallel compilations should occur when installing a package. A good choice is the number of CPUs (or CPU cores) in the system plus one, but this guideline isn't always perfect."

Linus Torvalds recommends setting this variable equal to twice the number of processors in the system. That way there is always one more compile job waiting to run when the previous one in that thread wraps up. It sort of makes sense, since Linux starts a separate thread running for each CPU core it finds fairly early during bootup.

user $ps ux | grep cpuhp
root        13  0.0  0.0      0     0 ?        S    08:59   0:00 [cpuhp/0]
root        14  0.0  0.0      0     0 ?        S    08:59   0:00 [cpuhp/1]
root        19  0.0  0.0      0     0 ?        S    08:59   0:00 [cpuhp/2]
root        24  0.0  0.0      0     0 ?        S    08:59   0:00 [cpuhp/3]
root        29  0.0  0.0      0     0 ?        S    08:59   0:00 [cpuhp/4]
root        34  0.0  0.0      0     0 ?        S    08:59   0:00 [cpuhp/5]
root        39  0.0  0.0      0     0 ?        S    08:59   0:00 [cpuhp/6]
root        44  0.0  0.0      0     0 ?        S    08:59   0:00 [cpuhp/7]
This was adjusted per Sam James (Sam) . See Special:Diff/949773/996115. It now includes factoring in system memory as well. This is likely a better route, since many 8C/16T workstations only have about 8 GBs of memory. OOM can still commonly occur with 16 GiB. --Maffblaster (talk) 23:10, 5 November 2021 (UTC)

"Update the /mnt/gentoo/etc/portage/make.conf file to match personal preference and save (nano users would hit Ctrl+x)."

Users -- especially novice users -- probably ought to say Ctrl+o before they exit the program. Yes, I know that nano will prompt me to save the changes. But a guy can make mistakes that way. It's always safer to explicitly save your changes, then say "exit". I've learned that the hard way. --Davidbryant (talk) 16:48, 24 July 2020 (UTC)

Hi David Bryant (Davidbryant) , I replied inline. I believe the necessary adjustments have been made in order to enhance the reading experience. --Maffblaster (talk) 23:10, 5 November 2021 (UTC)
It looks good. Thank you. Oh, yeah. When I first wrote this I had not yet encountered the Out of Memory error. Since then, I have learned to dial back the -jx parameter when compiling qtwebengine. So far, that's the only package my machine (16GB) can't handle easily at full throttle. Davidbryant (talk) 00:17, 6 November 2021 (UTC)
It seems the only remaining fix before closing this discussion (as all other requested fixes were provided) is to replace "Update the /mnt/gentoo/etc/portage/make.conf file to match personal preference and save (nano users would hit Ctrl+x)." with "Update the /mnt/gentoo/etc/portage/make.conf file to match personal preference and save (nano users would hit Ctrl+O to save, and Ctrl+X to quit)." ? --Blacki (talk) 09:03, 14 July 2022 (UTC)
Implemented here: [[Special:Diff/1127596/1169745}}. --Maffblaster (talk) 11:40, 27 November 2022 (UTC)

Default download directory for stage3 tarball

Talk status
This discussion is done as of Nov 5, 2021.

The default location for downloading stage3 is /var/tmp/catalyst/builds/default it is written on page Catalyst I propose to mention this location on page and give link to the catalyst page and tool. Einstok Fair (talk) 03:17, 13 September 2020 (UTC)

Most users are not going to use Catalyst particularly on their first install. Instead they will often download it from the gentoo.org website. --Grknight (talk) 13:13, 14 September 2020 (UTC)
I agree with Brian Evans (Grknight) , catalyst is still a bit of a mystery many, including myself! We will not be linking to catalyst in the handbook at this time. --Maffblaster (talk) 21:29, 5 November 2021 (UTC)

Proposition to split stage3 into rstage3 and bstage3

Talk status
This discussion is done.

For some systems only runtime dependencies are necessary. And for other systems full toolchains are necessary https://bugs.gentoo.org/742251 Einstok Fair (talk) 03:19, 13 September 2020 (UTC)

This has nothing to do with improving the Handbook so not the correct place to discuss such sweeping changes. --Grknight (talk) 13:16, 14 September 2020 (UTC)

links browser

Talk status
This discussion is done as of Nov 5, 2021.

With the new admincd, using the browser "links" to view https://gentoo.org/wiki/Handbook:AMD64/Installation/Stage#Introduction

suggests: "Verify the current date and time by running the date command: root #date"

Rjc (talk) 00:16, 19 October 2020 (UTC)

Not sure what you are saying here... Are you saying links is not included in the admin live environment? You can see it is included in the .spec file. Since I'm very confused I will close this discussion for now. Please feel free to reopen if you want to discuss more in the future. --Maffblaster (talk) 21:42, 5 November 2021 (UTC)


Talk status
This discussion is done as of 2022-11-27.

If -jN is not set in MAKEOPTS, it now defaults to nproc. Should this be mentioned in the section at the bottom of this page? Or perhaps that section could just be removed? Matthews (talk) 15:22, 7 August 2021 (UTC)

Matthew Smith (Matthews) , can you cite your source for this information? I was unable to find this info via man make.conf Thanks! --Maffblaster (talk) 23:17, 9 March 2022 (UTC)
Looks like Sam James (Sam) found it in Portage sources. We should probably get that documented in man make.conf ... --Maffblaster (talk) 00:08, 10 March 2022 (UTC)
That's it :) - I can't find any documentation on it either, will try and get it added to man make.conf. --Matthews (talk) 08:37, 10 March 2022 (UTC)
Will be mentioned in man 5 make.conf in the next Portage release. I'm not sure if we should add a note on this page of the handbook, or drop mention of MAKEOPTS completely? --Matthews (talk) 18:21, 25 April 2022 (UTC)
Added a note to the Handbook. I think it's good to still mention MAKEOPTS here as a setting that is tunable. See Special:Diff/1169745/1170169. Discussion can be closed. --Maffblaster (talk) 13:38, 27 November 2022 (UTC)

Getting back to root # prompt

Talk status
This discussion is done as of 2022-03-09.

Preparing to download the stage tarball, one goes to the Gentoo mount point (most likely /mnt/gentoo):

root # cd /mnt/gentoo

After that, and for the rest of the installation, the prompt is no longer root #, although the Handbook continues to show root # prompts.

/mnt/gentoo # wget <PASTED_STAGE_URL>

As a novice gentoo user, I do not know how to return to the earlier directory that would let my screen match the remaining chapters of the Handbook. I wonder if you would consider adding that command. VetusDonatus (talk) 00:50, 9 March 2022 (UTC)

Please go to http://forums.gentoo.org and ask questions about the installation there. We can much better help you there :-)
The handbook shows '<username> #' as prompt, whereas your machine shows '<directory> #' as prompt. Don't worry about the difference - you can continue even if your prompt is different from the prompt shown in the handbook. It's important that you are logged in as root - and not as a regular user. The letter '#' shows that you are logged in as root. If you were logged in as a regular user, you would see a '$'.
If your really want the "root #" prompt, then enter PS1='\u \$ ' to get exactly that prompt (although without colors).
Mike155 (talk) 14:27, 9 March 2022 (UTC)
Thanks you, Mike155, for the reassurances. I was hoping that my discussion here would inspire a change to the Handbook, along the lines of mentioning that the minimal gentoo downloaded, burned to CD, and booted, as described in an early chapter, is not the exact system used in the Handbook's examples.
When I get more experience, I hope to suggest how this might be worded.
Best regards,
VetusDonatus (talk) 20:55, 9 March 2022 (UTC)
As Mike155 has stated, it's the # that's important, which indicates to the reader that root permissions are needed, not the path specified in the PS1 variable. Hope this helps! --Maffblaster (talk) 23:02, 9 March 2022 (UTC)