commit 90fce41a0be6fe44deabfe93b1c4bda15d9c1266
parent ce404b21963043f967e550efdafac16bbf63d68f
Author: Chris Bracken <chris@bracken.jp>
Date: Tue, 22 Mar 2022 10:13:47 -0700
FreeBSD: reformat to 80 columns, plus minor fixes
Diffstat:
| M | freebsd_install.md | | | 237 | +++++++++++++++++++++++++++++++++++++++---------------------------------------- |
1 file changed, 116 insertions(+), 121 deletions(-)
diff --git a/freebsd_install.md b/freebsd_install.md
@@ -8,16 +8,16 @@ First, we'll need to download an install image from
https://www.freebsd.org/where.html. These instructions presume amd64
architecture, so we'll use an amd64-memstick image.
-Once the image is downloaded, write it to a USB stick using `dd`. Using
-the instructions in the FreeBSD Handbook here:
+Once the image is downloaded, write it to a USB stick using `dd`. Using the
+instructions in the FreeBSD Handbook here:
https://www.freebsd.org/doc/handbook/bsdinstall-pre.html.
Install from USB stick
----------------------
-Boot from the USB stick in UEFI mode. The machine should now boot into
-the FreeBSD installer.
+Boot from the USB stick in UEFI mode. The machine should now boot into the
+FreeBSD installer.
1. Keyboard layout: USA (Caps Lock acts as Left Ctrl).
2. Set hostname (should include domain name).
@@ -30,14 +30,14 @@ the FreeBSD installer.
8. Clean `/tmp` on startup.
9. Add user with `wheel` additional group.
-Once these steps are done, select the option to drop into a console
-session to complete a few additional steps.
+Once these steps are done, select the option to drop into a console session to
+complete a few additional steps.
### Set the console keyboard layout
-The console keyboard layout can be temporarily changed using the
-`kbdcontrol` command:
+The console keyboard layout can be temporarily changed using the `kbdcontrol`
+command:
kbdcontrol -l jp.capsctrl
@@ -45,9 +45,9 @@ It can be permanently set by adding a line to `/etc/rc.conf`:
keymap=jp.capsctrl
-For US keyboard layout with Caps Lock as Control, use `us.ctrl` for a
-Japanese keyboard with Caps Lock as Control, use `jp.capsctrl`. You can
-find all layouts in the `/usr/share/vt/keymaps` directory.
+For US keyboard layout with Caps Lock as Control, use `us.ctrl` for a Japanese
+keyboard with Caps Lock as Control, use `jp.capsctrl`. You can find all layouts
+in the `/usr/share/vt/keymaps` directory.
### Configure the hostname
@@ -98,23 +98,22 @@ then ensure that no one but root can read the contents:
chmod go-rwx /etc/wpa_supplicant.conf
-To assign a fixed IP address to always be returned by the router's DHCP
-server, get the WiFi MAC address using `ifconfig wlan0`, then in the
-router, manually assign a fixed IP address.
+To assign a fixed IP address to always be returned by the router's DHCP server,
+get the WiFi MAC address using `ifconfig wlan0`, then in the router, manually
+assign a fixed IP address.
### Configure sendmail
-By default, sendmail operates localhost only. If you disable it, you'll
-need to enable an alternative mail handler since the system assumes mail
-is available. (See note below)
+By default, sendmail operates localhost only. If you disable it, you'll need to
+enable an alternative mail handler since the system assumes mail is available.
+(See note below)
-Given that we generally want to disable root login on all hosts, it's
-useful to forward root's mail to a local user. To do so:
+Given that we generally want to disable root login on all hosts, it's useful to
+forward root's mail to a local user. To do so:
-1. Edit `/etc/mail/aliases`. Forward root's mail to a local user (e.g.
- `chris`) or a domain-qualified email address such as
- `chris@bracken.jp`.
+1. Edit `/etc/mail/aliases`. Forward root's mail to a local user (e.g. `chris`)
+ or a domain-qualified email address such as `chris@bracken.jp`.
2. Run `newaliases` to rebuild the random-access database populated from
`/etc/mail/aliases`. This is exactly the same as `sendmail -bi`.
@@ -134,9 +133,9 @@ More details can be found in the `periodic` man page.
### Set the console font
-To list available fonts, run `vidfont`, an ncurses-based program that
-sets the font to something legible when running. When it exits, it'll
-dump the selected font name.
+To list available fonts, run `vidfont`, an ncurses-based program that sets the
+font to something legible when running. When it exits, it'll dump the selected
+font name.
To set the font from a script, run:
@@ -148,8 +147,8 @@ To permanently set the console font, edit `/etc/rc.conf`:
allscreens_flags="-f FONTNAME"
-I find `terminus-b32` to be the most legible on a small screen. On a
-large screen, `vgarom-8x14` or `vgarom-8x16` might be better.
+I find `terminus-b32` to be the most legible on a small screen. On a large
+screen, `vgarom-8x14` or `vgarom-8x16` might be better.
A couple reference articles relating to framebuffer console fonts:
@@ -227,39 +226,37 @@ Edit `/usr/local/etc/doas.conf` and add the following text:
permit nopass keepenv root as root
-Set up sudo
------------
+Set up sudo (alternative to doas)
+---------------------------------
Prefer installing `doas` as described above, but leaving instructions here for
reference.
-1. Edit `/usr/local/etc/sudoers` and uncomment the following line to
- enable sudo access for members of the `wheel` group:
+1. Edit `/usr/local/etc/sudoers` and uncomment the following line to enable sudo
+ access for members of the `wheel` group:
%wheel ALL=(ALL) ALL
1. Disable direct root login by editing the passwd file using the `vipw`
- command. Find the row starting with `root:` and replace the hashed
- password between the first and second colons on that line with `*`.
- The line should look something like:
+ command. Find the row starting with `root:` and replace the hashed password
+ between the first and second colons on that line with `*`. The line should
+ look something like:
root:*:0:0::0:0:Charlie &:/root:/bin/csh
1. Type `:wq` to save and exit.
-Now that sudo is set up, log in as a user in the `wheel` group on
-another console (Use Ctrl-Alt-F1 through F8 to switch ttys) and run
-`sudo ls /root` to verify everything is configured properly, then exit
-the root shell and continue all further steps as a user in the `wheel`
-group.
+Now that sudo is set up, log in as a user in the `wheel` group on another
+console (Use Ctrl-Alt-F1 through F8 to switch ttys) and run `sudo ls /root` to
+verify everything is configured properly, then exit the root shell and continue
+all further steps as a user in the `wheel` group.
Configure sshd
--------------
-Edit `/etc/ssh/sshd_config` and uncomment or edit each of the following
-lines to disable password-based logins and allow only key-based
-authentication:
+Edit `/etc/ssh/sshd_config` and uncomment or edit each of the following lines to
+disable password-based logins and allow only key-based authentication:
PasswordAuthentication no
ChallengeResponseAuthentication no
@@ -279,8 +276,8 @@ Connect to the host via ssh from another machine:
Copy any existing public key you want to be able to log in into
`~/.ssh/authorized_keys` on the new machine -- e.g. on the new host:
-`cat > ~/.ssh/authorized_keys`. Then paste the public key you want to
-use to log in, and type ctrl-d to save. You can find your public key in
+`cat > ~/.ssh/authorized_keys`. Then paste the public key you want to use to log
+in, and type ctrl-d to save. You can find your public key in
`~/.ssh/id_rsa.pub` on the existing host you want to connect from.
@@ -300,8 +297,8 @@ of the FreeBSD base install.
Set up NVIDIA drivers
---------------------
-For systems with an NVIDIA card, we'll install the drivers, configure
-them to load at boot, and add X11 config.
+For systems with an NVIDIA card, we'll install the drivers, configure them to
+load at boot, and add X11 config.
First install the drivers:
@@ -315,9 +312,8 @@ Then add the following line to `/etc/rc.conf`:
kld_list="nvidia-modeset"
-Next, create the file
-`/usr/local/etc/X11/xorg.conf.d/driver-nvidia.conf` with the following
-contents:
+Next, create the file `/usr/local/etc/X11/xorg.conf.d/driver-nvidia.conf` with
+the following contents:
Section "Device"
Identifier "NVIDIA Card"
@@ -325,8 +321,8 @@ contents:
Driver "nvidia"
EndSection
-Finally, reboot the system or run `kldload nvidia-modeset` to manually
-load the driver.
+Finally, reboot the system or run `kldload nvidia-modeset` to manually load the
+driver.
Change shell to zsh
@@ -406,6 +402,10 @@ Install xdg-utils to get file associations to apps:
Configure XWindows
------------------
+As of 2022, Wayland works pretty well, and `xwayland` does a good job of
+covering anything that still relies on X, but if you prefer an X11 desktop,
+these instructions will cover things.
+
### Install Xorg, WM, and apps
Install XWindows:
@@ -594,8 +594,8 @@ Another decent starter reference: http://srobb.net/pf.html
### Enable pf
-We'll need to populate `/etc/pf.conf`. A minimal config file that blocks
-all incoming connections other than SSH (port 22):
+We'll need to populate `/etc/pf.conf`. A minimal config file that blocks all
+incoming connections other than SSH (port 22):
# Our external-facing network interface.
ext_if="em0"
@@ -621,16 +621,16 @@ To run a check on our config file without yet applying it:
pfctl -nvf /etc/pf.conf
Next, we'll start `pf`, but since many a system administrator has found
-themselves locked out of their own server by applying a bad config, it's
-useful to queue up a command to disable the firewall after two minutes.
-In another terminal, log into the remote machine, get a *root* shell
-using `doas -s`, then run the following:
+themselves locked out of their own server by applying a bad config, it's useful
+to queue up a command to disable the firewall after two minutes. In another
+terminal, log into the remote machine, get a *root* shell using `doas -s`, then
+run the following:
# Sleep 2 minutes, then disable pf.
sleep 120; pfctl -d
-Then, before the two minutes is up, run these commands in another
-root terminal to start the firewall:
+Then, before the two minutes is up, run these commands in another root terminal
+to start the firewall:
# Load the pf kernel module.
kldload pf
@@ -638,13 +638,13 @@ root terminal to start the firewall:
# Enable pf.
pfctl -e
-It's likely your SSH sessions will hang when you enable the packet
-filter. Quickly try connecting via SSH to verify you can connect before
-the two minute timeout above expires. If it worked, re-enable the packet
-filter on the server using `pfctl -e`.
+It's likely your SSH sessions will hang when you enable the packet filter.
+Quickly try connecting via SSH to verify you can connect before the two minute
+timeout above expires. If it worked, re-enable the packet filter on the server
+using `pfctl -e`.
-Once everything checks out, enable the packet filter on startup by
-adding the following lines to `/etc/rc.conf`:
+Once everything checks out, enable the packet filter on startup by adding the
+following lines to `/etc/rc.conf`:
pf_enable="YES"
pflog_enable="YES"
@@ -662,12 +662,12 @@ To read the pf logs, run:
Canonical reference in the FreeBSD Handbook:
https://www.freebsd.org/doc/handbook/firewalls-blacklistd.html
-If you've got an external-facing SSH port, you'll be continuously
-spammed with bogus connection attempts from people attempting to get
-access to badly-configured machines. The less clever of these tend to
-attack your machine repeatedly from the same IP address. FreeBSD
-includes the `blacklistd` service which can be used to temporarily ban
-IP addresses after repeated failed connection attempts.
+If you've got an external-facing SSH port, you'll be continuously spammed with
+bogus connection attempts from people attempting to get access to
+badly-configured machines. The less clever of these tend to attack your machine
+repeatedly from the same IP address. FreeBSD includes the `blacklistd` service
+which can be used to temporarily ban IP addresses after repeated failed
+connection attempts.
First, we'll add a pf anchor for blacklistd blocks in `/etc/pf.conf`:
@@ -686,8 +686,8 @@ Next, as root, start the blacklistd service:
service blacklistd start
-Finally, we'll enable blacklist support in sshd. Edit
-`/etc/ssh/sshd_config` and uncomment the line:
+Finally, we'll enable blacklist support in sshd. Edit `/etc/ssh/sshd_config` and
+uncomment the line:
UseBlacklist yes
@@ -715,23 +715,21 @@ When editing kernel sources in vim, the indentation settings should be:
Using a serial cable
--------------------
-FreeBSD includes built-in support for various UART serial cables
-including the Prolific PL-2303 and FTDI cables. Connecting the cable
-will create three character devices named `ttyUN`, `ttyUN.init`, and
-`ttyUN.lock` in the dev filesystem.
+FreeBSD includes built-in support for various UART serial cables including the
+Prolific PL-2303 and FTDI cables. Connecting the cable will create three
+character devices named `ttyUN`, `ttyUN.init`, and `ttyUN.lock` in the dev
+filesystem.
* `ttyUN` is the serial device.
-* `ttyUN.init` is an initialisation device used to initialise
- communication port parameters each time a port is opened, such as
- `crtscts` for modems which use `RTS/CTS` signalling for flow control.
-* `ttyUN.lock` is used to lock flags on ports to prevent users or
- programs from changing certain parameters. See the man pages for
- `termios`, `sio`, and `stty` for information on terminal settings,
- locking and initialising devices, and setting terminal options,
- respectively.
-
-More info on serial port configuration can be found in the FreeBSD
-Handbook:
+* `ttyUN.init` is an initialisation device used to initialise communication port
+ parameters each time a port is opened, such as `crtscts` for modems which use
+ `RTS/CTS` signalling for flow control.
+* `ttyUN.lock` is used to lock flags on ports to prevent users or programs from
+ changing certain parameters. See the man pages for `termios`, `sio`, and
+ `stty` for information on terminal settings, locking and initialising devices,
+ and setting terminal options, respectively.
+
+More info on serial port configuration can be found in the FreeBSD Handbook:
* [25.2 USB Virtual Serial Ports](https://www.freebsd.org/doc/handbook/usb-device-mode-terminals.html)
* [26.2 Serial Terminology and Hardware](https://www.freebsd.org/doc/handbook/serial.html)
@@ -759,31 +757,31 @@ you likely need to start ssh-agent. You can do this via:
### Segfault on keyboard input in dmenu
-If you have the `XMODIFIERS` variable set but your IME isn't properly
-configured and running, you'll get a crash on keyboard input to dmenu.
+If you have the `XMODIFIERS` variable set but your IME isn't properly configured
+and running, you'll get a crash on keyboard input to dmenu.
### Can't doas or log in as root
-Imagine you delete the root password via `vipw` without actually editing
-the `/usr/local/etc/sudoers` file first, or that you did edit that file
-but that no user is in the `wheel` group. Time to boot to single-user
-mode. Reboot the machine and when prompted at the initial FreeBSD boot
-prompt, quickly select option `2` to boot to single-user mode.
+Imagine you delete the root password via `vipw` without actually editing the
+`/usr/local/etc/sudoers` file first, or that you did edit that file but that no
+user is in the `wheel` group. Time to boot to single-user mode. Reboot the
+machine and when prompted at the initial FreeBSD boot prompt, quickly select
+option `2` to boot to single-user mode.
-The root filesystem is mounted read-only by default, so first we'll need
-to remount the root filesystem as read-write:
+The root filesystem is mounted read-only by default, so first we'll need to
+remount the root filesystem as read-write:
/sbin/mount -o rw /
-Next, edit `/usr/local/etc/sudoers` or make whatever other changes are
+Next, edit `/usr/local/etc/doas.conf` or make whatever other changes are
required to fix your mistakes. Finally, reboot.
### Force renew DHCP lease
-DHCP leases are cached in /var/db/dhclient.leases.em0 (replace `em0`
-with the interface name).
+DHCP leases are cached in `/var/db/dhclient.leases.em0` (replace `em0` with your
+interface name).
To force renewal of DHCP lease, run as root:
@@ -809,11 +807,11 @@ Intel NUC6i3SYK devices give a repeating error on startup:
sdhci_pci0_slot0: Controller timeout
-and dumps registers. It seems like there's an issue with support for the
-NUC's SD card reader. After a couple minutes, eventually it gives up and
-continues. To eliminate the warning on startup, reboot and enter the
-BIOS by holding down F2, then disable the SD card reader in the
-*Devices* section of the *Advanced* options.
+and dump registers. It seems like there's an issue with support for the NUC's SD
+card reader. After a couple minutes, eventually it gives up and continues. To
+eliminate the warning on startup, reboot and enter the BIOS by holding down F2,
+then disable the SD card reader in the *Devices* section of the *Advanced*
+options.
Alternatively, edit `/boot/loader.conf` to contain:
@@ -826,13 +824,13 @@ If that doesn't work, edit `/boot/device.hints` to contain:
#### Bluetooth doesn't work
-Mostly from notes in FreeBSD [Bugzilla issue
-237083](https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=237038).
+Mostly from notes in FreeBSD
+[Bugzilla issue 237083](https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=237038).
-The NUC's Intel 8260 Bluetooth/wireless requires a custom firmware
-download. FreeBSD 12.0 doesn't ship with all the support needed for
-this chipset. Fixes were landed in July 2019, but will take time to get
-released. When it does, installation will be:
+The NUC's Intel 8260 Bluetooth/wireless requires a custom firmware download.
+FreeBSD 12.0 doesn't ship with all the support needed for this chipset. Fixes
+were landed in July 2019, but will take time to get released. When it does,
+installation will be:
pkg install iwmbt-firmware
@@ -843,12 +841,11 @@ In the meantime, the firmware downloader can be found here:
cd iwmbt-firmware
make
-There's no need to install this, since it's a one-off tool to download
-and install the firmware. However, before you run it, you need to
-prevent FreeBSD from trying to auto-attach the device. Edit
-`/etc/devd.conf` and comment out the following lines, then power off and
-power back on the machine (a reboot is insufficient to clear the
-hardware state):
+There's no need to install this, since it's a one-off tool to download and
+install the firmware. However, before you run it, you need to prevent FreeBSD
+from trying to auto-attach the device. Edit `/etc/devd.conf` and comment out the
+following lines, then power off and power back on the machine (a reboot is
+insufficient to clear the hardware state):
attach 100 {
device-name "ubt[0-9]+";
@@ -881,8 +878,6 @@ It should display something like:
Name: btsock_sco Type: btsock_sco ID: 0000000b Num hooks: 0
Name: ngctl1441 Type: socket ID: 00000019 Num hooks: 0
-I notice when I do it, I'm missing the `ubt0hci` and `ubt012cap` entries
-though.
+I notice when I do it, I'm missing the `ubt0hci` and `ubt012cap` entries though.
-Once you're done, uncomment the section of `/dev/devd.conf` above and
-reboot.
+Once you're done, uncomment the section of `/dev/devd.conf` above and reboot.
