NetBSD Documentation: Other FAQs and HOWTOs

Hardware support

User configuration

Managing third-party software

System services (daemons)

Editing files under NetBSD

Disks & Filesystems

Memory/Swap Configuration

Rescuing a system


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.

  • sh(1) - Bourne shell

    This shell is the standard shell for scripting and interactive use in NetBSD.

    It supports emacs-style and vi-style editing modes with set -o emacs or set -o vi. Filename completion by TAB can be enabled by set -o tabcomplete. The default configuration has both features enabled (in /etc/shrc, read from ~/.shrc). sh currently only has tab completion for file paths.

  • csh(1) - C shell

    This was the standard user shell until NetBSD 4.0, it supports filename completion (set filec and use the ESCAPE key) but does not support command line editing.

  • ksh(1) - Korn shell

    This is a public domain version of the Korn Shell, aka pdksh. Like sh it supports command line editing in emacs and vi modes, but also supports command name completion.

    In Emacs mode, filename and command completion by TAB is enabled by default. Use set -o vi-tabcomplete or set -o vi-esccomplete to get Vi mode with completion by TAB or ESC, respectively.

  • Other shells

    The NetBSD packages collection also contains various other command line shells under the shells category.

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:

  • /etc/profile
    This is run every time a new shell is opened, before any .profile in the user's home directory.
  • /etc/shrc
    This is run from .shrc in the user's home directory and contains interactive mode settings.

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

  • /etc/csh.cshrc
    This is run every time a new shell is opened, before any .cshrc in the user's home directory.
  • /etc/csh.login
    This is run when the user logs in, after anything in /etc/csh.cshrc, but before any .login in the user's home directory.
  • /etc/csh.logout
    This is run when the user logs out, before any .logout in the user's home directory.


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/.

Troubleshooting: ABI differences: "Warning: package `X' was built for a platform: ..."

NetBSD binary packages are built for the first release of a branch. This means that packages intended for use on 9.1 are built for 9.0, and so on. Any difference in the version number of the OS and the packages along this line is fine, since the userspaces are compatible, but it may produce a warning due to the different kernel version number.

However, NetBSD HEAD/CURRENT version numbers containing .99, e.g. 9.99.81 indicate a different branch from 9.0 and cannot be expected to be compatible with packages built for 9.0 unless shared libraries are obtained from a 9.x release's sets.

Troubleshooting: No X11 sets: "Shared object 'libX' not found"

NetBSD binary packages are built to use the optional native X11 sets by default, and will fail to install if a dependency requires a library from the X11 sets but the X11 sets aren't installed:

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

You can install missing sets by running sysinst as root, or by booting the installer.

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:

  • ed(1) (Line oriented text editor)
    ed is a very simplistic text editor. It has a command mode, (active when first started) and an input mode. Its primary advantages are it is available even in single-user mode with only the '/' filesystem mounted, and will work even without a correct terminal type set. It is worth gaining a basic understanding of ed(1) - enough to fix fstab(5) and rc.conf(5) files in an emergency.
  • vi(1) (Screen oriented text editor)
    vi retains the command and input modes of ex(1), but adds a full screen visual interface. vi is the only screen editor available in the base install, and requires a valid terminal type to run.
    There are a number of online vi tutorials:

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

  • editors/joe
    A small, fast editor capable of emulating WordStar and emacs key bindings (jstar, jmacs). editors/joe will be familiar to people who have used Borland IDEs.
  • editors/nano
    A very simple to use text editor.
  • editors/emacs
    A proverbial 'everything and the kitchen sink' editor, including a complete lisp interpreter.
  • editors/xfce4-mousepad
    A simple GTK3 based GUI editor.

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

  1. Halt the system
  2. Connect the new drive and reboot
  3. Check dmesg(8) output to confirm that the drive is recognized
  4. Write a disklabel(5) including the partitions using disklabel(8)
    (if the disk doesn't have a disklabel yet, you'll probably do something like:
     disklabel -i -I sd1 # ignore any "sd1: no disk label"
    Partition 'c' is reserved for the entire NetBSD portion of a disk, and on some ports (notably i386), 'd' is similarly reserved for the entire disk. The following is a sample session setting the entire disk to be one filesystem 'e':
    	partition> e
    	Filesystem type [?] [unused]: 4.2BSD
    	Start offset [0c, 0s, 0M]:
    	Partition size ('$' for all remaining) [0c, 0s, 0M]: $
     	e: 234375000         0     4.2BSD      0     0     0   # (Cyl.    0 - 232514*)
    	partition> W
    	Label disk [n]? y
    	partition> Q
    Inside disklabel -i you can use '?' for additional help.
  5. For each filesystem added, newfs <filesystem> (where <filesystem> is the partition's raw device, like /dev/rsd1e, /dev/rwd1f, ...)
  6. Put the filesystems into /etc/fstab
  7. fsck(8) them:
    fsck -f <filesystem>
  8. mount(8) them:
    mount -va

Moving /usr from root to a different partition

  1. Make sure that the desired new location (e.g. /dev/sd0e) does not overlap any existing partitions. Check the output from disklabel(8).
  2. If it does not already contain a filesystem, run
    # newfs /dev/sd0e
  3. Mount it and copy across data:
    # mount /dev/sd0e /mnt
  4. # cd /usr
  5. # pax -rw -pe . /mnt
  6. # umount /mnt
  7. Edit /etc/fstab and add '/dev/sd0e /usr ffs rw 1 2' (change /dev/sd0e for your situation).
  8. Shutdown to single user mode and make new mountpoint:
    # shutdown now
  9. # mv /usr /usr.old
  10. # mkdir /usr
  11. Bring system up, test, and when all OK, 'rm -rf /usr.old'.

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:

  1. Additional virtual memory
    Less active pages containing modified data can be migrated to swap space allowing virtual memory to be larger than physical memory.
  2. An area for kernel core dumps
    This is then read by savecore(8), on boot. For this to work the primary swap partition must be slightly larger than the total RAM.
  3. For mfs(8) filesystems
    Classically mounted on /tmp in order to speed up any programs using /tmp, by adding the following to the fstab(5) file:
    	swap  /tmp  mfs  rw,-s=SIZE 0 0
    where SIZE is in 512byte blocks. The space required is taken from the swap space as the filesystem is used.

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:

  1. Rebuild the system disk, using a larger swap partition.
    While arguably the cleanest solution, this obviously involves significant disruption.
  2. Add an additional swap partition.
    When you add a disk it is usually a good idea to include a small 'b' partition for additional swap, and add an entry of the form:
    	/dev/DISKb       none    swap sw 0 0
    to your /etc/fstab file to automatically enable on boot. (Where DISK is the disk name such as 'sd1' or 'wd2').
  3. Create a swap file.

    The quickest and simplest option is to create a file in an existing filesystem, and use it as additional swap space. While accessing this will be slightly slower than dedicated swap partitions (due to fragmentation and filesystem overhead), it is ideal for solving a temporary swap shortage.

    To add 10 MBytes of swap space is as easy as selecting a filesystem with sufficient free space and:

    	# dd if=/dev/zero bs=1m count=10 of=/somefilesystem/swap
    	# chmod 600 /somefilesystem/swap
    	# swapctl -a -p 1 /somefilesystem/swap

    The dd(1) command creates a 10 MByte file `/somefilesystem/swap'. This swap file needs to be chmod(1) 600 so that unprivileged users may not read its contents (swapctl(8) will reject world readable files). Then swapctl(8) command adds /somefilesystem/swap to the system swap space at priority 1. Priority 0 is the (default) highest priority, and since swapping to files is slightly slower we only want the system to use the file when conventional swap has all been used.

    To make swapping to that file permanent and enable it on every reboot, put something like the following into /etc/fstab:

    /somefilesystem/swap none swap sw,priority=1 0 0


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:

  • fsck -p ; mount -va
    Check the filesystems with fsck(8), then make them available with mount(8).
  • set -E
    Enable command line editing.
  • TERM=vt220 ; export TERM
    Set and export the TERM variable, to permit editors such as vi(1) to work. Note: You may need to use a different terminal type from 'vt220', depending on the console type.
  • /etc/rc.d/network start; /etc/rc.d/dhcpcd start
    Bring up the network. If you have any nfs mounted filesystems you may want to do this before the fsck and mount.

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