Skip to main content.

Navigation: ● Home ● Recent changes ● NetBSD blog ● Presentations ● About ● Developers ● Gallery ● Ports ● Packages ● Documentation ● FAQ & HOWTOs ● The Guide ● Manual pages ● Wiki ● Support ● Community ● Mailing lists ● Bug reports ● Security ● Developers ● CVSWeb ● Mercurial ● Cross-reference ● Release engineering ● Projects list

NetBSD Documentation: Other FAQs and HOWTOs

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. On x86, NetBSD 10.0 supports Intel integrated graphics up to Gen12 ("Tiger Lake").

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). There are various special considerations when running NetBSD as a guest OS, especially with regards to IPv6 routes, unclean shutdown, and graphics modes. Please see the notes on using NetBSD as a guest in the official guide.

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 emacsorset -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). shcurrently 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 shit 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-tabcompleteorset -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)orshells/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.

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) edis 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) viretains 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: ○ editors/vilearn - in pkgsrc and highly recommended. ○ VI lovers home page. ○ Purdue University Engineering Computer Network. 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=NOin/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

(一)Halt the system (二)Connect the new drive and reboot (三)Check dmesg(8) output to confirm that the drive is recognized (四)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. (五)For each filesystem added, newfs <filesystem> (where <filesystem> is the partition's raw device, like /dev/rsd1e, /dev/rwd1f, ...) (六)Put the filesystems into /etc/fstab (七) fsck(8) them:

fsck -f <filesystem>

(八) mount(8) them:

mount -va

Moving /usr from root to a different partition

(一)Make sure that the desired new location (e.g. /dev/sd0e) does not overlap any existing partitions. Check the output from disklabel(8). (二)If it does not already contain a filesystem, run

# newfs /dev/sd0e

(三)Mount it and copy across data:

# mount /dev/sd0e /mnt

(四)

# cd /usr

(五)

# pax -rw -pe . /mnt

(六)

# umount /mnt

(七)Edit /etc/fstab and add '/dev/sd0e /usr ffs rw 1 2' (change /dev/sd0e for your situation). (八)Shutdown to single user mode and make new mountpoint:

# shutdown now

(九)

# mv /usr /usr.old

(十)

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

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: (一) Additional virtual memory Less active pages containing modified data can be migrated to swap space allowing virtual memory to be larger than physical memory. (二) 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. (三) 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: (一) Rebuild the system disk, using a larger swap partition. While arguably the cleanest solution, this obviously involves significant disruption. (二) 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'). 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. 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

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

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

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

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

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?

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

Rebuilding `/dev`