Handbook WG - Part I - Introduction - bsdinstall

[carlavilla]

Summary

Changes:

• Upgrade Part I to indicate that this part of the handbook covers Wayland too.
• In the Introduction chapter:
  • Use https for all the links
  • Minor typos
• In the bsdinstall chapter:
  • Remove references to any FreeBSD versions as much as possible. In this way the document will not look outdated
  • Update the images to reflect the current state of the installer.
  • Add alternative text to all images to improve the accessibility of the chapter
  • Remove references to different architectures and hardware. The user is directed to consult the release notes for each release to find out what architectures and hardware it supports.
  • Remove the links, use text instead of the link.
  • Improve the AsciiDoc after conversion.

Since there are many changes, it will be easier to see it here: https://www.carlavilla.es/freebsd/bsdinstall.html

In the future, when we get to the virtualization chapter, the parts that tell how to install FreeBSD in VirtualBox, etc, will be moved to the bsdinstall chapter. The virtualization chapter will be reserved for bhyve.

We do not make the change now so as not to leave the virtualization chapter empty.

[arrowd]

documentation/content/en/books/handbook/bsdinstall/_index.adoc

170

Maybe mention <<bsdinstall-usb>> in this sentence, as it is the first one that talks about burning to USB?

And in the next sentence write "It should be burned to a USB stick using the instructions above."

421

Why remove "or" word between -bootonly.iso and -mini-memstick.img?

1202

I wonder if this advice makes sense at all. "Try building a custom kernel" is at the same time hardcore and too vague. Even if user figures out how do build and boot a custom kernel, what should he put into the kernel config?

documentation/content/en/books/handbook/introduction/_index.adoc

116–117

I'm afraid, Yandex runs FreeBSD no more.

[karels]

documentation/content/en/books/handbook/bsdinstall/_index.adoc

68

I agree with removing the details by architecture, but I think it is useful to list the different types of media (virtual machine, SD card, install images) and the general installation procedure. Otherwise we may confuse people, as the chapter mostly talks about bsdinstall. I can take a stab at this, cribbing from the old text but simplifying.

450–452

This section seems useful, but the default partitioning uses a single root partition plus swap. Maybe that should be mentioned here?

470–472

I think it is worth mentioning home directories too; here is a proposal.

477

I have also heard that swap should be double the size of RAM up to 4 GB, 8 GB up to 8 GB RAM, and the size of RAM about 8 GB. This apparently was in the handbook and/or bsdinstall. Does anyone know the history or who to ask?

485–486

I think this should be changed, but it's difficult to phrase. There is a limit at which a warning is issued about too much swap space. It is vm.swap_maxpages / 2, and its value depends on the size of the swap memory allocation zone. That makes it hard to figure when installing. Here is an attempt at some wording.

593

Clarify; it seems odd to say there are three, then list four.

595

602–608

Maybe add: Note that /tmp can be added later as a memory-based file system (mfs) on systems with sufficient memory.

1013

The default ntp config uses a remote pool; should this be mentioned, e.g. "or if you wish to use a remote server pool"?

1196–1197

This seems out of position. Shouldn't it be in order for bsdinstall? Now it is after rebooting, so you get a login prompt, not a menu.

1201–1202

This statement is mostly referring to ISA, which is being removed from the system after being long obsolete. I think this sentence and the next one could be removed. But maybe we should mention kernel modules for devices not in the generic kernel? I haven't tried loading modules from the loader prompt when booting from ISO; I can try this if we might want to document it.

documentation/content/en/books/handbook/introduction/_index.adoc

119

SecureOS hasn't been at McAfee for some years; it is now at Forcepoint. But Sidewinder is well past end of sale. I think we should remove this.

[carlavilla]

documentation/content/en/books/handbook/bsdinstall/_index.adoc

68

Yes please, let me know when you have the new text and I'll put there :)

170

Good catch :)

450–452

Sure. Can you please prepare the text?

477

TBH, I heard the same thing, but I don't know where the idea came from. I have also read, although this affects Linux, that it is no longer worth putting swap.

1196–1197

No, in principle it is in its place. In "section 2.5.4. Installing from the Network" referenced here. Maybe we could improve it, but the truth is, I don't know how

1202

TBH, I think we can remove the Troubleshooting section, refers to very old issues, such as ACPI or updating the BIOS. Virtually no computer has a BIOS anymore, they all use EFI

documentation/content/en/books/handbook/introduction/_index.adoc

116–117

Benedict proposes to delete this entire section and leave this work to the FreeBSD Foundation. This way we won't have to worry about whether the listed companies continue to use FreeBSD or not. Personally, I like the idea.

[bcr]

A few minor edits to the text: one missing word the others are suggestions only.

documentation/content/en/books/handbook/bsdinstall/_index.adoc

486

s/can be by/can be raised by/

or easier: The limit is raised by ...
or: Raise the limit by ...

606

Shouldn't tmpfs be the preferred choice these days?

1013

... or to use a remote server pool.

[karels]

documentation/content/en/books/handbook/bsdinstall/_index.adoc

68

Here is a first draft, feel free to edit. Hopefully it is not too detailed, but I tried to provide context for those who would recognize what they were looking for.

Depending on the architecture and platform, different images are downloaded from
the https://www.freebsd.org/where/[Download FreeBSD] page and used to install or run. The image types are:

• Virtual Machine disk images, such as "qcow2", "vmdk", "vhd", and raw device images. These are not installation images, but rather the preconfigured ("already installed") instances, ready to run and perform post-installation tasks. Virtual machine images are also commonly used in cloud environments that provide FreeBSD installations.
• SD card images, for embedded systems such as Raspberry Pi. These files must be uncompressed and written as a raw image to an SD card, from which the board will then boot.
• Installation images to boot from an ISO or USB device, and then install FreeBSD on a hard drive for the usual desktop, laptop, or server systems.

The rest of this chapter describes the third case, explaining how to install FreeBSD using the text-based installation program named bsdinstall.
There may be minor differences between the installer and what is shown here, so use this chapter as a general guide rather than as a set of literal instructions.

166–167

196

(Note, *.img also includes the SD card images, which _can_ be copied to the device.)

450–452

Here is an attempt; probably could use more wordsmithing.

477

It is definitely worth having swap on smaller systems; I just put the ability to add swap into the SD image startup scripts because of problems people were running into. It is also useful as a kernel dump device. fwiw, I used 2x RAM up to 4 GB of memory, 8 GB up to 8 GB memory, and 1x RAM above that; Colin used the same for EC2. I think we need a tweak here, but I'm not sure what. We could add "less for larger-memory configurations" in the parenthetical expression after RAM.

948

This is where network setup should be, after the root password is set up; at least, that's where it appears installing 13.1 on amd64 from the disc1 image.

1013

The server pool doesn't care :).

1196–1197

I don't understand how this can be the right place. The previous section ended with the first boot, then shutdown -p. No list of interfaces is shown after a shutdown -p. I walked through an install to verify where this goes, and it is after setting the root password when installing locally on amd64 with 13.1.

1201–1202

Removing the paragraph is best. An aside: most people still refer to the computer firmware as the "BIOS", e.g. vendor instructions refer to updating the BIOS (even though UEFI is what gets used).

[carlavilla]

Fixed everything :)

[karels]

I think this is looking good. Were you planning to update your html version?

[carlavilla]

In D37616#856960, @karels wrote:

I think this is looking good. Were you planning to update your html version?

Just upgraded. I have a problem with the images.
I'm gonna try to paste here the new ones only

[carlavilla]

{F53053992}

{F53054021}

{F53054047}

{F53054066}

{F53054068}

[jrm]

In D37616#856997, @carlavilla wrote:

{F53053992}

{F53054021}

{F53054047}

{F53054066}

{F53054068}

Are we supposed to see images here? I only see the quoted text.

[carlavilla]

In D37616#857034, @jrm wrote:

In D37616#856997, @carlavilla wrote:

{F53053992}

{F53054021}

{F53054047}

{F53054066}

{F53054068}

Are we supposed to see images here? I only see the quoted text.

Try here:

https://carlavilla.es/freebsd/bsdinstall-hardening.png
https://carlavilla.es/freebsd/bsdinstall-keymap-10.png
https://carlavilla.es/freebsd/bsdinstall-newboot-loader-menu.png
https://carlavilla.es/freebsd/bsdinstall-part-manual-partscheme.png
https://carlavilla.es/freebsd/bsdinstall-zfs-partmenu.png

[karels]

documentation/content/en/books/handbook/bsdinstall/_index.adoc

606

tmpfs is in section 5

[karels]

I have been skimming, and things are looking good, just a couple of minor nits found. I think I am finished with these chapters. I have been hoping that Kirk McKusick would look at the history though; I'll prod him.

documentation/content/en/books/handbook/bsdinstall/_index.adoc

837

This should be a level-3 section; it should be under the level 2 that lists it and other things (2.8).

[carlavilla]

In D37616#857712, @karels wrote:

I have been skimming, and things are looking good, just a couple of minor nits found. I think I am finished with these chapters. I have been hoping that Kirk McKusick would look at the history though; I'll prod him.

I'll fix the tmpfs manual page section on commit.
And thanks for getting Kirk on board to take a look to the history section :) Really good idea.

About the chapter, @jrm wants to make some corrections. Give him a couple of days more.
I'm finishing the next batch of changes.

[mckusick]

Two suggested changes the history section.

documentation/content/en/books/handbook/introduction/_index.adoc

148

A condition of that settlement was U.C. Berkeley's concession that large parts of Net/2 were "encumbered" code and the property of Novell, who had in turn acquired it from AT&T some time previously.

This could more accurately be written:

A condition of that settlement was U.C. Berkeley's concession that three files of Net/2 were "encumbered" code and had to be removed as they were the property of Novell, who had in turn acquired it from AT&T some time previously.

153–154

The "Lite" releases were light in part because Berkeley's CSRG had removed large chunks of code required for actually constructing a bootable running system (due to various legal requirements) and the fact that the Intel port of 4.4 was highly incomplete.

I suggest this replacement:

Although only three files having to do with System V shared memory and semaphores were removed, many other changes and bug fixes had been made to the BSD distribution, so it was a huge task to merge all the FreeBSD developments into 4.4BSD-Lite.

[jrm]

documentation/content/en/books/handbook/bsdinstall/_index.adoc

55

I don't think we support "many others" beyond those listed. Starting with 14, I don't think we support any others.

56

I guess this was meant to be removed?

58

Depending on the architecture and platform, different images can be link:https://www.freebsd.org/where/[downloaded] to install or directly run FreeBSD.

62

• Virtual Machine disk images, such as qcow2, vmdk, vhd, and raw device images. These are not installation images, but images that have FreeBSD preinstalled and ready for post-installation tasks. Virtual machine images are commonly used in cloud environments.

63

64

64

71

159

I prefer the old version with the simple URL. I find it helpful to see these simple URLs like freebsd.org/handbook, bugs.freebsd.org, and freebsd.org/where.

162

167

171

[karels]

documentation/content/en/books/handbook/bsdinstall/_index.adoc

55

If you consider ARM and PowerPC as groups (e.g. arm + aarch64), there aren't many more, but there is at least i386.

[jrm]

documentation/content/en/books/handbook/bsdinstall/_index.adoc

55

Good call. How about this?

FreeBSD supports different architectures including x86_64, ARM(R), RISC-V(R), and PowerPC(R).

Also, should we use amd64 rather than x86_64? In the FreeBSD community, as far as I know, it's always been referred to as amd64. https://www.freebsd.org/platforms/

[karels]

documentation/content/en/books/handbook/bsdinstall/_index.adoc

55

amd64 is probably better.

62

I wouldn't remove "also" from the sentence about the cloud; that would make it seem that they are used primarily in the cloud. They are used with various virtual machine environments, which is the primary reason they are available for download.

[carlavilla]

Just made the commit with all the reviews