Chapter 5. The first steps on NetBSD

Table of Contents

5.1. Troubleshooting
5.1.1. Boot problems
5.1.2. Misconfiguration of /etc/rc.conf
5.2. The man command
5.3. Editing configuration files
5.4. Login
5.5. Changing the root password
5.6. Adding users
5.7. Shadow passwords
5.8. Changing the keyboard layout
5.9. System time
5.10. Secure Shell (ssh(1))
5.11. Basic configuration in /etc/rc.conf
5.12. Basic network settings
5.13. Mounting a CD-ROM
5.14. Mounting a floppy
5.15. Installing additional software
5.16. Security alerts
5.17. Stopping and rebooting the system

After installing and rebooting, the computer will boot from the hard disk. If everything went well you'll be looking at the login prompt within a few seconds (or minutes, depending on your hardware). The system is not yet fully configured, but basic configuration is easy. You will see how to quickly configure some important things, and in doing so you will learn some basics about how the system works.

5.1. Troubleshooting

5.1.1. Boot problems

If the system does not boot it could be that the boot manager was not installed correctly or that there is a problem with the MBR (Master Boot Record). Boot the machine from your install medium (CD, DVD, floppy, etc.) and when you see the boot menu, select the option to drop to the boot prompt.

type "?" or "help" for help.
> ?
commands are:
boot [xdNx:][filename] [-12acdqsvxz]
     (ex. "hd0a:netbsd.old -s")
ls [path]
dev xd[N[x]]:
consdev {pc|com[0123]|com[0123]kbd|auto}
modules {enabled|disabled}
load {path_to_module}
multiboot [xdNx:][filename] [<args>]
> boot hd0a:netbsd

The system should now boot from the hard disk. If NetBSD boots correctly from the hard disk, there is probably a Master Boot Record problem. You can install the boot manager or modify its configuration with the fdisk -B command. See Section 22.1, “Installing the boot manager” for a detailed description.

5.1.2. Misconfiguration of /etc/rc.conf

If you or the installation software haven't done any configuration of /etc/rc.conf (sysinst normally will), the system will drop you into single user mode and show the message

/etc/rc.conf is not configured. Multiuser boot aborted

When the system asks you to choose a shell, simply press RETURN to get to a /bin/sh prompt. If you are asked for a terminal type, respond with vt220 (or whatever is appropriate for your terminal type) and press RETURN. You may need to type one of the following commands to get your delete key to work properly, depending on your keyboard:

# stty erase '^h'
# stty erase '^?'

At this point, you need to configure at least one file in the /etc directory. However, the root file system (/) is mounted read-only, so you will first need to make it writable with:

# /sbin/mount -u -w /

Next, take a look at the /etc/rc.conf file. Modify it to your tastes, making sure that you set rc_configured=YES so that you don't end up in this position again. Default values for the various programs can be found in /etc/defaults/rc.conf. More complete documentation can be found in rc.conf(5).

When you have finished, type exit at the prompt to leave the single-user shell and continue with the multi-user boot.

5.2. The man command

If you have never used a Unix(-like) operating system before, your best friend is now the man command, which displays a manual page. The NetBSD manual pages are among the best and most detailed you can find, although they are very technical.

A good manual to read after booting a new NetBSD system is afterboot(8). It contains information about various necessary and useful configuration settings.

man name shows the man page of the name command and man -k name shows a list of man pages dealing with name (you can also use the apropos command).

To learn the basics of the man command, type:

# man man

Manual pages contain not only information about commands but also descriptions of some NetBSD features and structures. For example, take a look at the hier(7) man page, which describes in detail the layout of the filesystem used by NetBSD.

# man hier

Other similar pages are release(7) and pkgsrc(7).

# man 8 intro

Manual pages are divided in several sections, depending on what they document:

  1. general commands (tools and utilities), see intro(1)

  2. system calls and error numbers, see intro(2)

  3. C libraries, see intro(3)

  4. special files and hardware support, see intro(4)

  5. file formats, see intro(5)

  6. games, see intro(6)

  7. miscellaneous information pages, see intro(7)

  8. system maintenance and operation commands, see intro(8)

  9. kernel internals, see intro(9)

A subject may appear in more than one section of the manual; to view a specific page, supply the section number as an argument to the man command. For example, time appears in section 1 (the time user command) and in section 3 (the time function of the C library). To see the man page for the time C function, write:

# man 3 time

To see all the available pages:

# man -w time
# man -a time

5.3. Editing configuration files

Other than a shell, a text editor is the most essential tool for NetBSD system administration.

There are two provided in the base system

  • ed(1), a line orientated text editor. ed is a very simplistic text editor. It has a command mode (active when first started) and an input mode. Its primary advantage is that it will work even without a correct terminal type set. In an emergency, ed is worth knowing, but note that vi(1) is available in /rescue, which brings us to...

  • vi(1), a screen orientated text editor. vi is the only screen editor available in the base install, and requires a valid terminal type to run. Refer to Chapter 6, Editing to learn more about NetBSD's default editor.


Before you continue you should know or learn how to open, edit and save files within vi. Make sure to read Chapter 6, Editing.

5.4. Login

For the first login you will use the root user, which is the only user defined at the end of the installation. At the password prompt type the password for root that you set during the installation. If you didn't set a password, just press Enter.

NetBSD/i386 (Amnesiac) (ttyE0)
login: root
We recommend creating a non-root account and using su(1) for 
root access.

5.5. Changing the root password

If you did not set a password for root during the installation, you should use the /usr/bin/passwd command to do so now.

# /usr/bin/passwd
Changing local password for root.
New password:
Retype new password:

Passwords are not displayed on the screen while you type.

Choose a password that has numbers, digits, and special characters (not space) as well as from the upper and lower case alphabet. Do not choose any word in any language. It is common for an intruder to use dictionary attacks.

5.6. Adding users

For security reasons, it is bad practice to login as root during regular use and maintenance of the system. Instead, administrators are encouraged to add a regular user, add the user to the wheel group, then use the su(1) command when root privileges are required. NetBSD offers the useradd(8) utility to create user accounts. For example, to create a new user:

# useradd -m joe

The defaults for the useradd command can be changed; see the useradd(8) man page.

User accounts that can su to root are required to be in the "wheel" group. This can be done when the account is created by specifying a secondary group:

# useradd -m -G wheel joe

As an alternative, the usermod(8) command can be used to add a user to an existing group:

# usermod -G wheel joe

In case you just created a user but forgot to set a password, you can still do that later using the passwd(1) command.

# passwd joe


You can edit /etc/group directly to add users to groups, but do not edit the /etc/passwd directly; use vipw(8).

5.7. Shadow passwords

Shadow passwords are enabled by default. What this means is that all the passwords in /etc/passwd are simply *; the encrypted passwords are stored in a file that can only be read by root, /etc/master.passwd. When you start vipw(8) to edit the password file, the program opens a copy of /etc/master.passwd; when you exit, vipw checks the validity of the copy, creates a new /etc/passwd and installs the new /etc/master.passwd file. Finally, vipw launches pwd_mkdb(8), which creates the files /etc/pwd.db and /etc/spwd.db, two databases which are equivalent to /etc/passwd and /etc/master.passwd but faster to process.

It is very important to always use vipw and the other tools for account administration (chfn(1), chsh(1), chpass(1), passwd(1)) and to never directly modify /etc/master.passwd or /etc/passwd.

5.8. Changing the keyboard layout

If you do not have a US layout keyboard, you will probably want to change keymaps. For example, to use an italian keyboard, enter the following command:

# wsconsctl -k -w encoding=it
encoding -> it

To save the keyboard layout permanently, add the following line to the /etc/wscons.conf file:

encoding it

See Section, “Keyboard mappings” for a list of available keymaps.

5.9. System time

NetBSD, like all Unix systems, uses a system clock based on UTC (Coordinated Universal Time) and this is what you should set your system clock to. If you want to keep the system clock set to the local time (because, for example, you have a dual boot system with Windows installed), you must notify NetBSD, adding rtclocaltime=YES to /etc/rc.conf:

# echo rtclocaltime=YES >> /etc/rc.conf
# service rtclocaltime restart


Alternatively, it is possible to configure Windows 7 and beyond to cope with the RTC being UTC. As alluded to in this Microsoft Knowledge Base article, the way to do this is to add a DWORD registry key named RealTimeIsUniversal, with a value of 1, to HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\TimeZoneInformation.

The number of minutes west of GMT is calculated automatically and is set in the kern.rtc_offset sysctl variable.

To display the current setting of the kern.rtc_offset variable:

# sysctl kern.rtc_offset
kern.rtc_offset = -60

This automatic configuration only works if you have set the proper time zone with a symbolic link to /etc/localtime. Normally this is done as part of the install procedure, but if for some reason it wasn't, you can set it by creating a symbolic link from a file in the /usr/share/zoneinfo directory to /etc/localtime.

The following example sets the time zone to Eastern Europe Summer Time:

# ln -fs /usr/share/zoneinfo/Europe/Helsinki /etc/localtime

5.10. Secure Shell (ssh(1))

By default, all services are disabled in a fresh NetBSD installation, and ssh(1) is no exception. You may wish to enable it so you can log in to your system remotely. Set sshd=YES in /etc/rc.conf and then start the server with the command

# service sshd start

The first time the server is started, it will generate a new keypair, which will be stored inside the directory /etc/ssh.

5.11. Basic configuration in /etc/rc.conf

NetBSD uses /etc/rc.conf to determine what will be executed when the system boots. Understanding this file is important. The rc.conf(5) manual page contains a detailed description of all available options.

The /etc/defaults/rc.conf file contains the default values for most settings. To override a default value, the new value must be put into /etc/rc.conf. The definitions there override the ones in /etc/defaults/rc.conf (which you should leave unchanged).

# man rc.conf

The first modifications are:

  • Set rc_configured=YES (this modification should already have been done by the installation software.)

  • Set dhcpcd=YES to configure your system's network using DHCP.

  • Define a hostname for your machine (use a fully qualified hostname, i.e., one including domain). If you have a standalone machine you can use any name (for example, vigor3.your.domain). If your machine is connected to a network, you should supply the correct name.

  • If your machine is connected to a local network or the Internet through a router, set the defaultroute variable to the IP address of your router (sometimes called a default gateway). For example, defaultroute=

5.12. Basic network settings

To resolve the names and IP addresses of remote hosts, the system needs access to a (remote or local) DNS nameserver. Tell the system which nameserver(s) to use by adding the IP address of one or more nameservers to the /etc/resolv.conf file, using the following as an example:


To set the names of local hosts that are not available through DNS, edit the /etc/hosts file, which has the form:

IP-address  hostname  host

For example: vigor3.your.domain vigor3

5.13. Mounting a CD-ROM

New users are often surprised by the fact that although the installation program recognized and mounted their CD-ROM perfectly, the installed system seems to have forgotten how to use the CD-ROM. There is no special magic for using a CD-ROM; you can mount it like any other file system. All you need to know is the device name and some options to the mount(8) command. You can find the device name with the aforementioned dmesg(8) command. For example, if dmesg displays:

# dmesg | grep ^cd
cd0 at atapibus0 drive 1: <ASUS CD-S400/A, , V2.1H> type 5 cdrom removable

the device name is cd0, and you can mount the CD-ROM with the following commands:

# mkdir /cdrom
# mount -t cd9660 -o ro /dev/cd0a /cdrom

To make things easier, you can add a line to the /etc/fstab file:

/dev/cd0a /cdrom cd9660 ro,noauto 0 0

Without the need to reboot, you can now mount the CD-ROM with:

# mount /cdrom

When the CD-ROM is mounted you can't eject it manually; you will have to unmount it before you can do that:

# umount /cdrom

There is also a software command which unmounts the CD-ROM and ejects it:

# eject /dev/cd0a

5.14. Mounting a floppy

To mount a floppy you must know the name of the floppy device and the file system type of the floppy. Read the fdc(4) manpage for more information about device naming, as this will differ depending on the exact size and kind of your floppy disk. For example, to read and write a floppy in MS-DOS format you use the following command:

# mount -t msdos /dev/fd0a /mnt

Instead of /mnt, you can use another directory of your choice; you could, for example, create a /floppy directory like you did for the CD-ROM. If you do a lot of work with MS-DOS floppies, you will want to install the mtools package, which enables you to access a MS-DOS floppy (or hard disk partition) without the need to mount it. It is very handy for quickly copying a file to or from a floppy:

# mcopy foo bar a:
# mcopy a:baz.txt baz
# mcopy a:\*.jpg .

5.15. Installing additional software

Using packages from pkgsrc

If you wish to install any of the software freely available for UNIX-like systems you are strongly advised to first check the NetBSD package system, pkgsrc. pkgsrc automatically handles any changes necessary to make the software run on NetBSD. This includes the retrieval and installation of any other packages on which the software may depend.

  • See the list of available packages

  • Precompiled binaries are available on the NetBSD FTP server for most ports. To install them the PKG_PATH variable needs to be adjusted in the following way (under the sh(1) shell):

    # PKG_PATH="$(uname -p)/$(uname -r | cut -d_ -f1)/All"
    # export PKG_PATH

    Applications can now be installed by the superuser root with the pkg_add command:

    # pkg_add -v perl
    # pkg_add -v apache
    # pkg_add -v firefox

    The above commands will install the Perl programming language, Apache web server, and the Firefox web browser as well as all the packages they depend on.

    It is recommended you install and use pkgin for most non-trivial binary package management tasks, and managing upgrades. pkgin can be installed from the post-installation configuration menu in sysinst, or afterwards using pkg_add on a live system:

    # pkg_add -v pkgin

    It maintains a local database of packages that are on the remote server, you can fetch the database with:

    # pkgin update

    Its usage is oriented on the package tools you have with other operating systems. To search the package database for a word `stat`, use

    # pkgin search WORD

    To install a package (in this case `fscd`), just type

    # pkgin install fluxbox

    To upgrade installed packages:

    # pkgin upgrade

    You should read the manpage to know about more actions you can do with pkgin.

    All details about package management can be found in The pkgsrc guide

Storing third-party software

On many UNIX-like systems the directory structure under /usr/local is reserved for applications and files which are independent of the system's software management. This convention is the reason why most software developers expect their software to be installed under /usr/local. NetBSD has no /usr/local directory, but it can be created manually if needed. NetBSD does not care about anything installed under /usr/local, so this task is left to you as the system administrator.

5.16. Security alerts

By the time that you have installed your system, it is quite likely that bugs in the release have been found. All significant and easily fixed problems will be reported at It is recommended that you check this page regularly.

5.17. Stopping and rebooting the system

Use one of the following two shutdown commands to halt or reboot the system:

# shutdown -h now
# shutdown -r now

Two other commands to perform the same tasks are:

# halt
# reboot

halt, reboot and shutdown are not synonyms: the latter is more sophisticated. On a multiuser system you should really use shutdown, which allows you to schedule a shutdown time and notify users. It will also take care to stop processes properly. For more information, see the shutdown(8), halt(8) and reboot(8) manpages.