File:  [NetBSD Developer Wiki] / wikisrc / guide / boot.mdwn
Revision 1.4: download - view: text, annotated - select for diffs
Tue Mar 5 23:33:53 2013 UTC (5 years, 3 months ago) by jdf
Branches: MAIN
CVS tags: HEAD
Cosmetics (mainly removing trailing whitespaces).

# The first steps on NetBSD

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.

## Troubleshooting

### 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 does not boot 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 [[Installing the boot manager|guide/misc#bootmanager]] for a
detailed description.

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

    # 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

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

## The man command

If you have never used a Unix(-like) operating system before, your best friend
is now the
[man(1)]( 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
It contains information about various necessary and useful configuration

`man name` shows the man page of the `name` command and `man -k name` shows a
list of man pages dealing with `name`. The tool
[apropos(1)]( does
a full-text search on the manpages installed on your system, sorted by

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

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

 1. general commands (tools and utilities), see
 2. system calls and error numbers, see
 3. C libraries, see
 4. special files and hardware support, see
 5. file formats, see
 6. games, see
 7. miscellaneous information pages, see
 8. system maintenance and operation commands, see
 9. kernel internals, see

You can read the introduction to each of the sections by reading the `intro`
page of the specific section (in this case, 8):

    # man 8 intro

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

## Editing configuration files

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

Though there is the line-editor
[ed(1)](, you might
want to use the other editor provided with the NetBSD base system, named
[vi(1)]( There is a
[separate chapter](guide/edit) about using vi. You should read this first, as
editing config files is essentially for using NetBSD.

Though vi(1) is *the* standard on Unix systems, you maybe want to get a bit used
to ed(1). vi is an descendant of ed, and the commands used in ed are applicable
for vi as well.

## 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`. Note that the password isn't echoed when you type it!

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

## Changing the root password

If you did not set a password for `root` during the installation, you should use
the [passwd(1)](
command to do so now:

    # 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.
Nonetheless, you should choose a password you can type independent of the
keyboard layout. When using some special characters, you might have problems
typing it with your local keymap later on.

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

    # passwd joe

### Note

You can edit `/etc/group` directly to add users to groups, but do *not* edit the
`/etc/passwd` directly; use

## Shadow passwords

Shadow passwords are enabled by default. This means is that all passwords in
`/etc/passwd` are set to `\*`; 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
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
and to *never* directly modify `/etc/master.passwd` or `/etc/passwd`.

## Changing the keyboard layout

If you do not have a US layout keyboard, you 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 [[Keyboard mappings|guide/cons#keyboard_mappings]] for a list of
available keymaps.

## System time

NetBSD, like all Unix systems, uses a system clock based on Greenwich time (GMT)
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 by adding
`rtclocaltime=YES` to `/etc/rc.conf`:

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

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 by
a symbolic link `/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 `/etc/localtime` to a file in the `/usr/share/zoneinfo`

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

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

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

    # /etc/rc.d/sshd start

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

Note that you can enable sshd also by using the configuration menu of `sysinst`.
If you did this, you don't have to do it by hand (and sshd should already have
started at boot time).

## 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
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 `dhclient=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 are 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=`.

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


There are public name servers available, but your Internet Service Provider
should always provide some to you anyway.

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

## 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
command. You can find the device name with the aforementioned
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

    # 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

## 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
[sysutils/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 .

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

pkgsrc might have been installed already by `sysinst`, so you don't have to
install it manually.

 * See the [list of available

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

       # export PKG_PATH="<PORT>/<RELEASE-NUMBER>/All"
       # export PKG_PATH

   Where `<RELEASE-NUMBER>` needs to be replaced by the release number of an
   existing NetBSD release (for example, 6.1). `<PORT>` needs to be replaced by
   the Port name for the used architecture (for example, amd64)

   Applications can now be installed by `root` with the pkg\_add command:

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

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

   Installed applications can be updated in the following way:

       # pkg_add -uv firefox

   The following command will force an update of firefox and all of its

       # pkg_add -fuuv firefox

   All details about package management can be found in [*The pkgsrc

 * Maybe you already installed
   [pkgtools/pkgin]( `sysinst` provides an
   option to install pkgin (if not, you can install it like any other software).
   `pkgin` is a binary package manager, but more sophisticated than `pkg_add`.
   It maintains a database of packages on the server you can fetch 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 fscd

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

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

### Security alerts

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

## 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
[halt(8)]( and

CVSweb for NetBSD wikisrc <> software: FreeBSD-CVSweb