NetBSD Documentation: Other FAQs and HOWTOs

Hardware support

• Lists of supported devices
• Graphical acceleration
• Configuring WiFi
• Virtual machines

User configuration

• Adding a user
• Selecting a shell
• Adding something to your path
• Setting something for all users

Managing third-party software

• Package management on NetBSD
• Installing binary packages with pkgin
• Installing root TLS/SSL certificates
• Advanced: Fetching pkgsrc and building packages from source

System services (daemons)

• Managing services
• Running services on startup
• Running periodic tasks

Editing files under NetBSD

• Available text editors
• Changing /etc/motd

Disks & Filesystems

• Viewing disk device names
• Enabling metadata journaling (WAPBL) on FFS filesystems
• Adding a disk to an existing system
• Moving /usr from root to a different partition
• How to mount a 'read-only' filesystem read/write?
• When is it safe to use fsck?
• Encrypted swap with cgd(4)

Memory/Swap Configuration

• How much swap space?
• Adding more swap to a running system

Rescuing a system

• Single user mode
• How to switch from single-user to multi-user
• Rebuilding /dev

Hardware support

Lists of supported devices

The best way to check that a device is supported is to boot NetBSD and check dmesg(8). For help selecting devices for your NetBSD machine, usb(4) and pci(4) contain lists of supported USB and PCI Express device drivers. The man pages for the individual drivers often contain lists of individual devices. Other man pages also exist for other buses, for example spi(4).

See the laptops wiki page for a list of laptops tested by developers.

For lists of supported ARM boards, try checking the device tree set lists. Note that this list only contains non-UEFI-based ARM boards, UEFI based ARM boards are supported generically.

For more niche hardware platforms, try checking individual port pages.

Graphical acceleration

On x86, NetBSD 9.0 supports Intel integrated graphics up to Kaby Lake, Nvidia graphics up to Maxwell, and AMD graphics up to Graphics Core Next (version 1). Anything newer than this will work, but will use llvmpipe instead of the GPU for OpenGL.

Configuring WiFi

See above for information about supported WiFi cards and USB devices. To see if your WiFi interface is detected and find its name, run ifconfig(8).

For advice on configuring WiFi, see the 802.11 documentation. You can do this in the installer by exiting the installer and dropping to a shell, then entering the installer again with exit.

Virtual machines

NetBSD can run in most standard virtual machines. NetBSD supports paravirtualization in QEMU with virtio(4), Xen with xennet(4) and friends, VMware with vmx(4), Amazon EC2 with ena(4).

When booting in a x86 virtual machine using the standard BIOS graphical console, trying dropping to the bootloader prompt and using vesa 1024x768x16 to select higher console resolutions, followed by boot. You can make these settings permanent by editing /boot.cfg. For more information, see boot(8).

User configuration

Adding a user

You can use the useradd(8) command to add users and usermod(8) to modify them. The passwd(1) command can be used to set and change your own and (if you are root) other users' passwords

Use the -m option to useradd to create and populate their home directory with shell configuration from /etc/skel, including the correct PATH to run X11 programs and programs from packages. Use -g wheel to allow the user to su(1) to root if they have the correct password.

Selecting a shell

A number of shells are available in NetBSD as standard. chsh(1) can be used to change or set your shell, and if you're root, other users' too.

Adding something to your path

For example, to add /usr/local/bin to your path, edit the file .profile in your home directory and add the following:

PATH=/usr/local/bin:$PATH
export PATH

This works for sh(1) and comparable Bourne-compatible shells like ksh(1).

For the C-shell csh(1), add the following to .login:

set path = ( /usr/local/bin $path )

Setting something for all users

You can set something for all users running sh(1) by adding it to the following files:

You can set something for all users running csh(1) or shells/tcsh by adding it to one of the following files:

Managing third-party software

Package management on NetBSD

NetBSD uses the pkgsrc framework for managing installation of third-party software. There are various ways to use pkgsrc, this section will only cover the simplest and most common ways.

Installing binary packages with pkgin

The NetBSD Project provides pre-built binaries for thousands of software packages. Installing binary packages with pkgin should be the quickest and easiest way to get software on to your NetBSD system, and is recommended for most users. By default, third-party software from pkgsrc is installed to the directory /usr/pkg.

If you installed a NetBSD port that uses the sysinst(8) installer, you may have noticed the Enable installation of binary packages option in the post-installation configuration menu. This installs the pkgin binary package manager.

If you didn't do this, it's also possible to install pkgin on a fresh NetBSD system with pkg_add:

# export PKG_PATH=https://cdn.NetBSD.org/pub/pkgsrc/packages/NetBSD/$(uname -p)/$(uname -r | cut -d_ -f1)/All
# pkg_add pkgin

Note that the default /root/.profile contains an example PKG_PATH.

You can then search for software, e.g. with

# pkgin search shell

Install software with:

# pkgin install fluxbox nginx zsh

Perform package upgrades with:

# pkgin upgrade

For more information, consult the pkgin manual page.

pkgin stores its repository information in /usr/pkg/etc/pkgin/repositories.conf. This may need to be edited to the appropriate subdirectory of https://cdn.NetBSD.org/pub/pkgsrc/packages/NetBSD/.

/usr/pkg/lib/ffmpeg4/libavfilter.so.7: Shared object "libfontconfig.so.2" not found

Installing root TLS/SSL certificates

If you are seeing errors related to TLS/SSL certificates on a fresh install, it's likely because your system does not have any of the root SSL certificates used in the "chain of trust" for HTTPS and other protocols.

Currently, NetBSD does not include any root certificates. These are provided by the security/mozilla-rootcerts package in pkgsrc. Since certificates reside in /etc/openssl and pkgsrc cannot modify files in /etc directly as a general rule, mozilla-rootcerts instead comes with a script for installing certificates to the correct location.

Use it as follows:

# pkgin install mozilla-rootcerts
# mozilla-rootcerts install

Advanced: Fetching pkgsrc and building packages from source

Fetch and unpack pkgsrc:

# ftp https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc.tar.xz
# xzcat pkgsrc.tar.xz | tar xvf -

You can build a package by changing to its directory with cd(1) and running make package followed by make install. There are various tools to automate building from pkgsrc, including pkgtools/pkg_chk and pkgtools/pbulk.

For more information, consult the pkgsrc Guide.

System services (daemons)

Managing services

To manage system startup and services, NetBSD uses the rc(8) system designed by Luke Mewburn.

System services are stored inside /etc/rc.d and are controlled through the service(8) command. For example, to restart the dhcpcd(8) service (responsible for configuring network interfaces):

# service dhcpcd restart

Running services on startup

The services that run on system startup and default flags for services are configured by editing /etc/rc.conf. For example, to run the httpd(8) server on startup on port 8080, set in /etc/rc.conf:

httpd=YES
httpd_flags='-I 8080'

/etc/rc.local is a script that is run as the final part of the boot process, after all networking interfaces, daemons, and everything else is already configured. Custom commands can also be added to this file to run them on startup.

Running periodic tasks

The typical way to run periodic tasks on a Unix system is to use cron(8). NetBSD will also automatically periodically run periodic scripts. For example, commands can be added to the /etc/daily.local script to run regularly every night.

Editing files under NetBSD

Available text editors

There are two obvious options in the base system:

There are a large number of editors available under the editors category in pkgsrc, including:

Changing /etc/motd

If you delete the header of /etc/motd, the startup process will overwrite your changes on boot. This can be disabled by setting update_motd=NO in /etc/rc.conf, in which /etc/motd will not be touched at all, and you can change it at will.

Disks & Filesystems

Viewing disk device names

Various commands like gpt(8) and disklabel(8), and system configuration files like /etc/fstab make it important to know the names of disk devices. You can get a short listing of physical drives with sysctl(8):

$ sysctl hw.disknames
hw.disknames = wd0 dk0 dk1 dk2 cgd0

The initial sequence of letters refers to the driver (device type), and the number is the device number.

Here, wd0 is a physical SATA drive, dk0 through dk2 are GPT partitions, and cgd0 is an encrypted partition.

You can also find more information about devices connected to your system by checking dmesg.

NetBSD always applies a BSD disklabel to connected drives, whether real or fictitious. For example, /dev/wd0a refers to the first NetBSD partition, and /dev/rwd0d refers to the entire raw disk. "e" is also special, it will be used for FAT32 partitions, e.g. on a USB drive without a real disklabel installed, the partition containing the data is likely /dev/sd0e.

Enabling metadata journaling (WAPBL) on FFS filesystems

Enabling wapbl(4) (metadata journaling) on a standard NetBSD FFS filesystem can avoid a long fsck(8) after an unclean shutdown and provide better general-use performance. Note that metadata journaling does not help with file corruption when a write operation is interrupted by an unclean shutdown, and can in some cases make it worse.

Add the log option to /etc/fstab to turn on metadata journaling at boot time:

NAME=NetBSD	/	ffs	rw,noatime,log	1 1

The noatime option here disables recording file access time, which may be useful on flash-based filesystems, and other situations where you might want to avoid excess disk writes.

You can then remount the filesystem with journaling enabled:

# mount -u -o rw,noatime,log /

Adding a disk to an existing system

Moving /usr from root to a different partition

How to mount a 'read-only' filesystem read/write?

Use mount(8)'s -u (update) switch: 'mount -u /'. More than likely, you booted single-user which mounts the root filesystem read-only by default. This gives you a chance to run fsck by hand before bringing the system up into multi-user. One other way to mount all the filesystems in /etc/fstab as read/write is to use 'mount -a'.

However, the best way to do this is to go into multi-user mode by exiting from your single-user shell. This will mount all of the filesystems in /etc/fstab in whatever mode they are listed.

When is it safe to use fsck?

Only use fsck(8) on an unmounted or read-only filesystem. Running fsck(8) on a r/w filesystem is dangerous and could corrupt the filesystem. If you bring the system up into single-user mode, the system will be mounted read-only. From there you can do an 'fsck -p' to check all filesystems before bringing the system up into multi-user mode. If the filesystem has previously been marked "clean," and you still want to check it, you can use the -f flag to fsck(8).

If you do make any changes to the filesystem using fsck, it is probably best to type 'reboot -n' to reboot the machine immediately without syncing the disks.

Encrypted swap with cgd(4)

Since the topic of swap encryption pops up from time to time, this information could be useful for some people who are interested in encrypting their swap space but are not sure how to set it up.

Currently there is one limitation, cgd devices are created with disklabel containing only one slice marked as 4.2BSD which is not suitable for swapping into. This is the reason why using cgd drive as a swap device is not straightforward. Roland Dowdeswell is looking into this and it should be resolved in the near future.

A real world example: Our swap device wd0b will be configured as cgd1, using 256 bit aes-cbc key. Step by step instructions follows:

  1) generate a paramsfile for the cgd device.  the default file would be
     /etc/cgd/wd0b but i will use /etc/cgd/swap for better illustration:

     # cgdconfig -g -V none -k randomkey aes-cbc > /etc/cgd/swap

  2) configure the cgd device over wd0b, (make sure wd0b is not used as a
     swap device at this moment):

     # cgdconfig cgd1 /dev/wd0b /etc/cgd/swap

  3) edit disklabel for cgd1, we need to create a valid swap slice.  save
     the disklabel to a file:

     # disklabel -e -I cgd1

     # /dev/rcgd1d:
     type: cgd
     disk: cgd
     label: default label
     flags:
     bytes/sector: 512
     sectors/track: 2048
     tracks/cylinder: 1
     sectors/cylinder: 2048
     cylinders: 128
     total sectors: 263655
     rpm: 3600
     interleave: 1
     trackskew: 0
     cylinderskew: 0
     headswitch: 0           # microseconds
     track-to-track seek: 0  # microseconds
     drivedata: 0

     4 partitions:
     #        size    offset     fstype  [fsize bsize cpg/sgs]
      d:    263655         0     4.2BSD      0     0     0   # (Cyl.    0 - 128*)

     create a swap slice and change label (that's not really necessary, just for
     our information):

     # /dev/rcgd1d:
     type: cgd
     disk: cgd
     label: swap
     flags:
     bytes/sector: 512
     sectors/track: 2048
     tracks/cylinder: 1
     sectors/cylinder: 2048
     cylinders: 128
     total sectors: 263655
     rpm: 3600
     interleave: 1
     trackskew: 0
     cylinderskew: 0
     headswitch: 0           # microseconds
     track-to-track seek: 0  # microseconds
     drivedata: 0

     4 partitions:
     #        size    offset     fstype  [fsize bsize cpg/sgs]
      a:    263655         0       swap                      # (Cyl.    0 - 128*)

     and save it to a file:

     # disklabel cgd1 > /etc/cgd/swap.disklabel

  4) set up the cgd device to be configured automatically at boot.  add the
     following line into your /etc/cgd/cgd.conf:

     cgd1 /dev/wd0b /etc/cgd/swap

  5) now we need to restore our disklabel to the newly created cgd device at
     boot time.  create /etc/rc.conf.d/cgd with this simple function:

     swap_device="cgd1"
     swap_disklabel="/etc/cgd/swap.disklabel"
     start_postcmd="cgd_swap"

     cgd_swap()
     {
             if [ -f $swap_disklabel ]; then
                     disklabel -R -r $swap_device $swap_disklabel
             fi
     }

  6) add the cgd device into /etc/fstab as a swap device:

     /dev/cgd1a none swap sw 0 0

That's all. Now you can activate your swap partition with 'swapctl -a /dev/cgd1a' or just reboot.

What you see above is a setup from my laptop.

   Device      1K-blocks     Used    Avail Capacity  Priority
   /dev/cgd1a     131827     8828   122999     7%    0

Memory/Swap Configuration

How much swap space?

On older Unix systems it was recommended to have twice as much swap space as RAM. This was because active pages in RAM had to have pages allocated in swap, effectively limiting the total virtual memory to the size of the swap space. On NetBSD this is no longer true, so total virtual memory is approximately swap + RAM.

Under NetBSD there are three primary uses for swap space:

Adding more swap to a running system

Systems should be configured with sufficient swap space, as per the How much swap entry.

There are three ways to add swap to a configured system:

Rescuing a system

Single user mode

Single-user mode is when the kernel has booted, but only runs a single shell on the console as the superuser. It may be necessary to boot into single user mode if your system configuration becomes damaged or lost, and ordinary user accounts are inaccessible. If you boot single-user only the root filesystem will be mounted, and it will be mounted read-only. You can enter single-user mode by running 'shutdown now' as root on a running system, or by booting the system with the '-s' flag (the method for doing this varies from port to port).

Once booted single-user you may find some of the following commands useful:

How to switch from single-user to multi-user

Exit the single-user shell with "exit" or ctrl-D.

The system will boot up to multi-user mode, starting all kind of services, etc. Note that disks are not checked when going from single-user to multi-user mode!

Rebuilding /dev

The /dev directory contains the necessary device files for accessing hardware and pseudo devices. If it becomes damaged, much strangeness can ensue. To rebuild the /dev directory, you should first boot single-user (it should be possible to perform while multiuser, but this is not recommended), then:

mkdir /newdev
cd /newdev
cp /dev/MAKEDEV /newdev/MAKEDEV
sh MAKEDEV all
cd /
mv dev olddev; mv newdev dev
rm -r olddev