Purpose of this guide

This guide describes the installation and the configuration of the
NetBSD operating system as well as the setup and administration of some
of its subsystems.
It primarily addresses people coming from other Unix-like operating
systems, and aims to be a useful guide in the face of the many small
problems one encounters when using a new tool.

This guide is not a Unix tutorial: basic knowledge of some
concepts and tools is assumed. You should know, for example, what a
file and a directory are, and how to use an editor. There are plenty
of books explaining basic Unix and operating system concepts, and you
should consult one if you need more background information.
It is better to choose a general book and avoid titles like
“Learning Unix-XYZ, version 1.2.3.4 in 10 days”, but this
is a matter of personal taste.

Much work is still required to finish this introduction to
NetBSD: some chapters are not finished (some are not even started) and
some subjects need more testing.
Corrections and additions are most certainly welcome.

Chapter 1. What is NetBSD?

NetBSD is a free, fast, secure, and highly portable Unix-like Open Source
operating system. It is available for many platforms, from 64-bit x86
servers and PC desktop systems to embedded ARM and MIPS based devices.
Its clean design and advanced features make it excellent in both
production and research environments, and it is user-supported with
complete source. Many applications are easily available through pkgsrc,
the NetBSD Packages Collection.

1.1. The story of NetBSD

The first version of NetBSD (0.8) dates back to 1993 and
springs from the 4.3BSD Lite operating system, a version of
Unix developed at the University of California, Berkeley (BSD
= Berkeley Software Distribution), and from the 386BSD
system, the first BSD port to the Intel 386 CPU. In the
following years, modifications from the 4.4BSD Lite
release (the last release from the Berkeley group) were integrated
into the system. The BSD branch of Unix has had a great importance
and influence on the history of Unix-like operating systems, to which
it has contributed many tools, ideas and improvements which are now
standard: the vi editor, the C shell, job control, the Berkeley
fast file system, reliable signals, support for virtual memory and
TCP/IP, just to name a few. This tradition of research and
development survives today in the BSD systems and, in particular, in
NetBSD.

1.2. NetBSD features

NetBSD operates on a vast range of hardware platforms and is very
portable. The full source to the NetBSD kernel and userland is
available for all the supported platforms; please see the details on
the official site of
the NetBSD Project.

These characteristics bring also indirect advantages.
For example, if you work on just one platform you could think that
you're not interested in portability.
But portability is tied to code quality; without a well written and
well organized code base it would be impossible to support a large
number of platforms.
And code quality is the base of any good and solid software system,
though surprisingly few people seem to understand it.

One of the key characteristics of NetBSD is that its developers
are not satisfied with partial implementations.
Some systems seem to have the philosophy of “If it works, it's
right”.
In that light NetBSD's philosophy could be described as “It
doesn't work unless it's right”.
Think about how many overgrown programs are collapsing
under their own weight and “features” and you'll understand
why NetBSD tries to avoid this situation at all costs.

1.3. Supported platforms

NetBSD supports many platforms, including the popular
PC platform (i386 and amd64), SPARC and UltraSPARC, Alpha,
Amiga, Atari, and m68k and PowerPC based Apple Macintosh machines.
Technical details for all of them can be found on the NetBSD site.

1.4. NetBSD's target users

The NetBSD site states that: “The NetBSD Project provides a
freely available and redistributable system that professionals,
hobbyists, and researchers can use in whatever manner they
wish”.
It is also an ideal system if you want to learn Unix,
mainly because of its adherence to standards (one of the project
goals) and because it works equally well on the latest PC
hardware as well as on hardware which is considered obsolete
by many other operating systems. To learn and use
Unix you don't need to buy expensive hardware; you can use that old
PC or Mac in your attic. It is important to note that although NetBSD
runs on old hardware, modern hardware is well supported and care has
been taken to ensure that supporting old machines does not inhibit
performance on modern hardware.
In addition, if you need a Unix system which runs consistently on a
variety of platforms, NetBSD is probably your best choice.

1.5. Applications for NetBSD

Aside from the standard Unix productivity tools, editors,
formatters, C/C++ compilers and debuggers and so on that are included
with the base system, there is a huge collection of packages
(currently over 8,000) that can be installed both from source and in
pre-compiled form.
All the packages that you expect to find on a well configured system
are available for NetBSD for free. The framework that makes this possible,
pkgsrc, also includes a number of commercial applications.
In addition, NetBSD provides binary emulation for various other *nix
operating systems, allowing you to run non-native applications.
Linux emulation is probably the most relevant example. You can run
the Linux versions of

Firefox

the Adobe Flash player plugin

Acrobat Reader

many other programs

1.6. How to get NetBSD

NetBSD is an Open Source operating system, and as such it is freely
available for download from
ftp.NetBSD.org and
its mirrors.

There is no “official” supplier of
NetBSD CD-ROMs but there are various resellers.
You can find the most up to date list on the relevant
page on
the NetBSD site.

2.1. Preliminary considerations

2.1.1. Dual booting

It is possible to install NetBSD together with other operating
systems on one hard disk.

If there is already an operating system on the hard disk, think
about how you can free some space for NetBSD; if NetBSD will share
the disk with other operating systems you will probably need to
create a new partition (which you will do with
sysinst). Often times this will not be
possible unless you resize an existing partition.

Unfortunately, it is not possible to resize an existing partition
with sysinst, but there are some
commercial products (like
Partition Magic)
and some free tools (GNU Parted,
FIPS, pfdisk)
available for this.

You can also install NetBSD on a separate hard disk.

Advice

Unless you are comfortable with setting up a partitioning
scheme for two or more operating systems, and unless you
understand the risk of data loss if you should make a mistake,
it is recommended that you give NetBSD its own hard disk. This
removes the risk of damage to the existing operating system.

2.1.2. NetBSD on emulation and virtualization

It is possible to install and run NetBSD on top of other
operating systems without having to worry about partitioning.
Emulators or virtualization environments provide a quick and secure
way to try out NetBSD. The host operating system remains unchanged,
and the risk of damaging important data is minimized.

Information about NetBSD as a Xen
host and guest system is available on the
NetBSD/xen web
page.

The
NetBSD on
emulated hardware web page provides detailed information
about various emulators and the supported NetBSD platforms. It
should also be noted that NetBSD runs as a VMware guest.

2.2. Install preparations

2.2.1. The INSTALL document

The first thing to do before installing NetBSD is to read the
release information and installation notes in one of the
INSTALL files: this is the official
description of the installation procedure, with platform-specific
information and important details. It is available in HTML, PostScript,
plain text, and an enhanced text format to be used with
more. These
files can be found in the root
directory of the NetBSD release (on the install CD or on the FTP
server). For example:

ftp://ftp.NetBSD.org/pub/NetBSD/NetBSD-5.0/port/INSTALL.html

2.2.2. Partitions

The terminology used by NetBSD for partitioning is different
from the typical DOS/Windows terminology; in fact, there are two
partitioning schemes involved when running NetBSD on a typical PC.
NetBSD installs in one of the four primary BIOS partitions (the
partitions defined in the hard disk partition table).

Within a BIOS partition (also called slice)
NetBSD defines its BSD partitions using a
disklabel: these partitions can be seen only by
NetBSD and are identified by lowercase letters (starting with
“a”).
For example, wd0a refers to the “a” partition of the first
IDE disk (wd0) and sd0a refers to the “a” partition of the
first SCSI disk. In Figure 2.1, “Partitions” there are two
primary BIOS partitions, one used by DOS and the other by NetBSD.
NetBSD describes the disk layout through the disklabel.

Figure 2.1. Partitions

Note

The meaning of partitions “c” and “d”
is typical of the i386 port.
On most other ports, “c” represents the whole disk.

Note

If NetBSD shares the hard disk with another operating system
(like in the previous example) you will want to install a
boot manager, i.e., a program which lets you
choose which OS to start at boot time.
sysinst can do this for you and
will ask if you want to install one. Unless you have specific
reasons not to, you should let sysinst perform this step.

2.2.3. Hard disk space requirements

The exact amount of space required for a given NetBSD installation
varies depending on the platform being used and which distribution sets
are selected. In general, if you have 1GB of free space on your hard
drive, you will have more than enough space for a full installation
of the base system.

2.2.4. Network settings

If you plan to fetch distribution sets over the network (not
necessary if you downloaded a full-size install ISO) and do not use
DHCP, write down your basic network settings. You will need:

Your IP address (example: 192.168.1.7)

the netmask (example: 255.255.255.0)

the IP address of your default gateway
(example: 192.168.1.1)

the IP address of the DNS server you use
(example: 145.253.2.75)

2.2.5. Backup your data and operating systems!

Before you begin the installation, make sure that you have
a reliable backup of any operating systems and data on the used
hard disk. Mistakes in partitioning your hard disk can lead to data loss.
Existing operating systems may become unbootable.
"Reliable backup" means that the backup and restore procedure is
tested and works flawlessly!

2.2.6. Preparing the installation media

The NetBSD installation system consists of two parts. The first
part is the installation kernel. This kernel contains the NetBSD
install program sysinst and it is booted
from a CD (or DVD), memory card, USB flash drive, or floppy disk.
The sysinst program will
prepare the disk: it separates the disk space into partitions, makes
the disk bootable and creates the necessary file systems.

The second part of the install system is made up of the binary
distribution sets: the files of the NetBSD operating system.
The installer needs to have access to the distribution sets.
sysinst will usually fetch these files
from the CD or DVD you burned, but it can also get them via FTP,
NFS, or local filesystem.

The NetBSD Project provides complete install media for every
supported hardware architecture. This is usually in the form of
bootable CD images (.iso files). For example:

ftp://ftp.NetBSD.org/pub/NetBSD/iso/5.0/

Note

2.2.6.1. Booting the install system from CD

To use a bootable NetBSD install CD
download the iso file for your hardware
architecture and burn it to a CD or DVD. You will need to handle
this step alone, as burning programs vary widely. Ensure that
your computer is set up to boot from CD-ROM before hard drives,
insert the disc, and reboot the computer.

2.2.6.2. Booting the install system from floppy

If you need to create installation floppies, you need to
copy floppy images to a diskette. The floppy images are available
on the NetBSD FTP servers or on a NetBSD install CD.
To perform this operation in DOS you can use the
rawrite program in the
i386/installation/misc directory. For
Windows, there's a version in rawr32.zip.
The image files are
i386/installation/floppy/boot1.fs and
i386/installation/floppy/boot2.fs for
installation of a “normal” PC.
The other floppies that are available are described in more detail
in the INSTALL document.

Note

Before you write the boot images to floppies, you
should always check that the floppies are good: this simple step
is often overlooked, but can save you a lot of trouble!

The procedure to write floppies is:

Format the floppy.

Go to the I386\INSTALLATION\FLOPPY directory
of the CD-ROM.

Run the
..\MISC\RAWRITE
program (or extract ..\MISC\RAWR32.ZIP
if you're on a Windows system, and run the RAWRITE32 program
in that file). Usually the “Source file”s are
BOOT1.FS and
BOOT2.FS and the
“Destination drive” is A:

To create a boot floppy in a Unix environment, the
dd command can be used:
For example:

#cd i386/installation/floppy#dd if=boot.fs of=/dev/fd0a bs=36b

Note

A 1440K floppy contains 1474560 bytes and is made up of 80
cylinders, 2 tracks, 18 sectors and 512 bytes per sector, i.e., 80 *
2 * 18 = 2880 blocks.
Thus bs=36b copies one cylinder (18 * 2 blocks) at
a time and repeats the operation 80 times instead of 2880.

2.3. Checklist

This is the checklist about the things that should be clear
and on-hand now:

Available disk space

Bootable medium with the install system

CD/DVD or server with the distribution sets

Your network information (only if you will be fetching
distribution sets via the network and do not use DHCP)

3.1. Introduction

This chapter will guide you through the installation
process.
The concepts presented here apply to all installation methods. The
only difference is in the way the distribution sets are fetched by
the installer.
Some details of the installation differ depending on
the NetBSD release: The examples from this chapter were created
with NetBSD 5.0.

Note

The following install screens are just examples.
Do not simply copy them, as your hardware and configuration
details may be different!

3.2. The installation process

The installation process is divided logically in two parts.
In the first part you create a partition for NetBSD and write
the disklabel for that partition.
In the second part you decide which distribution sets (subsets of
the operating system) you want to install and then extract
the files into the newly created partition(s).

3.3. Keyboard layout

The NetBSD install program
sysinst allows you to change
the keyboard layout during the installation. If for some
reason this does not work for you, you can use
the map in the following table.

US

IT

DE

FR

-

'

ß

)

/

-

-

!

=

ì

'

-

:

ç

Ö

M

;

ò

ö

m

#

£

§

3

"

°

Ä

%

*

(

(

8

(

)

)

9

)

=

=

0

'

à

ä

ù

`

\

^

@

\

ù

#

`

3.4. Starting the installation

To start the installation of NetBSD, insert your chosen boot media
(CD/DVD, USB drive, floppy, etc.) and reboot the computer.
The kernel on the installation medium will be booted and start
displaying a lot of messages on the screen about hardware being
detected.

Figure 3.1. Selecting the language

When the kernel has booted you will find yourself in the NetBSD
installation program, sysinst, shown in
Figure 3.1, “Selecting the language”.
From here on you should follow the instructions displayed on the
screen, using the INSTALL document as a companion
reference. You will find the INSTALL document in various
formats in the root directory of the NetBSD release.
The sysinst screens all have more or less
the same layout: the upper part of the screen shows a short
description of the current operation or a short help message, and the
rest of the screen is made up of interactive menus and prompts.
To make a choice, use the cursor keys, the
“Ctrl+N” (next) and “Ctrl+P”
(previous) keys, or press one of the letters displayed left of
each choice. Confirm your choice by pressing the Return
key.

Start by selecting the language you prefer to use for the
installation process.

After choosing “Yes” to continue,
sysinst displays a list of one or more
disks and asks which one you want to install NetBSD on.
In the example given in Figure 3.5, “Choosing a hard disk”,
there are two disks, and NetBSD will be installed on
“wd0”, the first IDE disk found. If you use SCSI
or external USB disks, the first will be named “sd0”,
the second “sd1” and so on.

Figure 3.5. Choosing a hard disk

The installer will then ask whether you want to do a full,
minimal or custom installation. NetBSD is broken into a collection
of distributions sets. “Full installation” is the
default and will install all sets; “Minimal installation”
will only install a small core set, the minimum of what is needed for
a working system. If you select “Custom installation”
you can select which sets you would like to have installed. This step
is shown in Figure 3.6, “Full or custom installation”.

Figure 3.6. Full or custom installation

If you choose to do a custom installation,
sysinst will allow you to choose which
distribution sets to install, as shown in Figure 3.7, “Selecting distribution sets”. At a minimum, you must select a kernel
and the “Base” and “System (/etc)” sets.

Figure 3.7. Selecting distribution sets

3.5. MBR partitions

The first important step of the installation has come: the
partitioning of the hard disk.
First, you need to specify whether NetBSD will use a partition
(suggested choice) or the whole disk.
In the former case it is still possible to create a partition that
uses the whole hard disk (Figure 3.8, “Choosing the partitioning scheme”)
so we recommend that you select this option as it keeps the
BIOS partition table in a format which is compatible with other
operating systems.

Figure 3.8. Choosing the partitioning scheme

The next screen shows the
current state of the MBR partition table on
the hard disk before the installation of NetBSD. There are four primary
partitions, and as you can see, this example disk is currently empty.
If you do have other partitions you can leave them around and
install NetBSD on a partition that is currently unused, or you can
overwrite a partition to use it for NetBSD.

Figure 3.9. fdisk

Deleting a partition is simple: after selecting the partition,
a menu with options for that partition will appear
(Figure 3.10, “Partition options”). Change
the partition kind to “Delete partition” to remove the
partition. Of course, if you want to use the partition for
NetBSD you can set the partition kind to “NetBSD”.

You can create a partition for NetBSD by selecting the partition
you want to install NetBSD to. The partition names “a”
to “d” correspond to the four primary partitions
on other operating systems. After selecting a partition, a menu
with options for that partition will appear, as shown in
Figure 3.10, “Partition options”.

Figure 3.10. Partition options

To create a new partition, the following information must be supplied:

the type (kind) of the new partition

the first (start) sector of the new partition

the size of the new partition

Choose the partition type “NetBSD” for the
new partition (using the “type” option). The
installation program will try to guess the “start”
position based on the end of the preceding partition.
Change this value if necessary. The same thing applies to the
“size” option; the installation program will try to
fill in the space that is available until the next partition or the
end of the disk (depending on which comes first). You can change this
value if it is incorrect, or if you do not want NetBSD to use the
suggested amount of space.

After you have chosen the partition type, start position, and
size, it is a good idea to set the name that should be used in the
boot menu. You can do this by selecting the “bootmenu”
option and providing a label, e.g., “NetBSD”. It is a
good idea to repeat this step for other bootable partitions so you
can boot both NetBSD and a Windows system (or other operating
systems) using the NetBSD bootselector. If you are satisfied with
the partition options, confirm your choice by selecting
“Partition OK”.
Choose “Partition table OK” to leave the MBR partition
table editor.

If you have made an error in partitioning (for example you have
created overlapping partitions) sysinst
will display a message and suggest that you go back to the
MBR partition editor (but you are also allowed to continue). If the
data is correct but the NetBSD partition lies outside the range of
sectors which is bootable by the BIOS,
sysinst will warn you and ask if you
want to proceed anyway. Doing so may lead to problems on
older PCs.

Note

This is not a limitation of NetBSD. Some old BIOSes cannot boot a
partition which lies outside the first 1024 cylinders.
To fully understand the problem you should study the different type
of BIOSes and the many addressing schemes that they use
(physical CHS,
logical CHS,
LBA, ...).
These topics are not described in this guide.

On modern computers (those with support for int13
extensions), it is possible to install NetBSD in
partitions that live outside the first 8 GB of the hard disk,
provided that the NetBSD boot selector is installed.

At this point, the BIOS partitions (called
slices on BSD systems) have been created.
They are also called
PC BIOS partitions,
MBR partitions or
fdisk partitions.

Note

Do not confuse the slices or
BIOS partitions with the
BSD partitions, which are different things.

3.6. Disklabel partitions

Some platforms, like PC systems (amd64 and i386), use DOS-style
MBR partitions to separate file systems. The
MBR partition you created earlier in the installation
process is necessary to make sure that other operating systems do
not overwrite the diskspace that you allocated to NetBSD.

NetBSD uses its own partition scheme, called a
disklabel, which is stored at the start of
the MBR partition. In the next few steps you will create a
disklabel(5) and set the sizes of the NetBSD partitions, or
use existing partition sizes, as shown in
Figure 3.12, “Edit partitions?”.

Figure 3.12. Edit partitions?

When you choose to set the sizes of the NetBSD partitions
you can define the partitions you would like to create.
The installation program will generate a disklabel based on these
settings. This installation screen is shown in
Figure 3.13, “Setting partition sizes”.

Figure 3.13. Setting partition sizes

The default partition scheme of just using a big
/ (root) file system (plus swap) works
fine with NetBSD, and there is little need to change this.
Figure 3.13, “Setting partition sizes” shows how to change the
size of the swap partition to 600 MB.
Changing /tmp to reside on a
RAM disk
(mfs(8)) for extra speed may be a good idea. Other partition
schemes may use separate partitions for
/var, /usr and/or
/home, but you should use your own
experience to decide if you need this.

The next step is to create the disklabel and edit its
partitions, if necessary, using the disklabel editor
(Figure 3.14, “The disklabel editor”).
If you predefined the partition sizes in the previous step, the
resulting disklabel will probably fit your wishes. In that case
you can complete the process immediately by selecting
“Partition sizes ok”.

Figure 3.14. The disklabel editor

There are
two reserved partitions, “c”, representing the
NetBSD partition, and “d”, representing the whole
disk. You can edit all other partitions by using
the cursor keys and pressing the return key. You can add a
partition by selecting an unused slot and setting parameters
for that partition. The partition editing screen is shown in
Figure 3.15, “Disklabel partition editing”.

Figure 3.15. Disklabel partition editing

3.7. Setting the disk name

After defining the partitions in the new disklabel, the last item
is to enter a name for the NetBSD disk as shown in
Figure 3.16, “Naming the NetBSD disk”. This can be used later to
distinguish between disklabels of otherwise identical disks.

Figure 3.16. Naming the NetBSD disk

3.8. Last chance!

The installer now has all the data it needs to prepare the disk.
Nothing has been written to the disk at this point but, and now is
your last chance to abort the installation process before actually
writing data to the disk.
Choose “no”
to abort the installation process and return to the main menu,
or continue by selecting “yes”.

Figure 3.17. Last chance to abort

3.9. The disk preparation process

After confirming that sysinst
should prepare the disk, it will run disklabel(8) to create
the NetBSD partition layout and
newfs(8) to create the file systems on the disk.

After preparing the NetBSD partitions and their filesystems,
the next question (shown in Figure 3.18, “Selecting bootblocks”) is which
bootblocks to install. Usually you will
choose the default of BIOS console,
i.e., show boot messages on your computer's display.

If you run a farm of machines without monitor, it may
be more convenient to use a serial console running on one of
the serial ports. The menu also allows changing the serial
port's baud rate from the default of 9600 baud, 8 data bits,
no parity and one stopbit.

Figure 3.18. Selecting bootblocks

3.10. Choosing the installation media

At this point, you have finished the first and most difficult
part of the installation!

The second half of the installation process consists of
populating the file systems by extracting the distribution sets that
you selected earlier (base, compiler tools, games, etc).
Before unpacking the sets, sysinst asks
what information you would like to see during that process, as shown in
Figure 3.19, “Choosing the verbosity of the extraction process”. You can choose between
a progress bar, a display of the name of each extracted file, or
nothing.

Figure 3.19. Choosing the verbosity of the extraction process

Now sysinst needs to find the NetBSD
sets and you must tell it where to find them. The menu offers several
choices, as shown in
Figure 3.20, “Installation media”. The options are explained in
detail in the INSTALL documents.

Figure 3.20. Installation media

3.10.1. Installing from CD-ROM or DVD

When selecting “CD-ROM / DVD”,
sysinst asks the name of the CD-ROM
or DVD device and the directory in which the set files are
stored, see Figure 3.21, “CD-ROM/DVD installation”. The device is usually
cd0 for the first CD-ROM or DVD drive,
regardless of whether it is IDE or SCSI (or even USB or FireWire).

Figure 3.21. CD-ROM/DVD installation

The CD-ROM/DVD device name

If you don't know the name of the CD-ROM/DVD device, you can
find by doing the following:

Press Ctrl-Z to pause sysinst
and go to the shell prompt.

Type the command:

#dmesg

This will show the kernel startup messages, including the
name of the CD-ROM device, for example
cd0.

If the display scrolls too quickly, you can also use
more:

#dmesg | more

Go back to the installation program with the command:

#fg

3.10.2. Installing from an unmounted file system

Figure 3.22, “Mounting a file system” shows the menu to install
NetBSD from an unmounted file system. It is necessary to specify
the device ("Device"), the file system of the device ("File system")
and the path to the install sets ("Set directory"). The setting for
the "Base directory" is optional and can be kept blank.

In the following example the install sets are stored on a
MSDOS file system, on partition "e"
on the device "sd0".

In Figure 3.24, “Accessing a MSDOS file system” the file system type is
specified. It is “msdos” but it could also be the
NetBSD file system “ffs” or “ext2fs”,
a Linux file system.
The “Base directory” item is left blank and the
binary sets are stored under “/sets”. Choosing
“Continue” will start the extraction of the sets.

Figure 3.24. Accessing a MSDOS file system

3.10.3. Installing via FTP

If you choose to install from a local network or the Internet
via FTP, sysinst will configure the
system's network connection, download the selected set files to a
temporary directory, and then extract them.

Note

The exact names of your network interfaces depend on the
hardware you use. Example interfaces are “wm”
for Intel Gigabit interfaces, “ne” for
NE2000 and compatible ethernet cards, and “ath” for
Atheros based wireless cards. This list is by no means complete,
and NetBSD supports many more network devices.

To get a list of network interfaces available on your system,
interrupt the installation process by pressing
“Ctrl+Z”, then enter

To get more information about all the devices found during
system startup, including network devices, type

#dmesg | more

You can return to the NetBSD installation by typing

#fg

Figure 3.25. Which network interface to configure

Next, you have a chance to set your network medium.

Note

It is unlikely that you will need to enter anything other
than the default here. If you experience problems like very slow
transfers or timeouts, you may, for example, force different
duplex settings for ethernet cards. To get a list of
supported media and media options for a given network device
(ne2, for example), escape from
sysinst by pressing
“Ctrl+Z”, then enter:

The various values printed after “media” may be of
interest here, including keywords like
“autoselect” but also including any
“mediaopt” settings.

Return to the installation by typing:

#fg

The next question will be whether you want to perform DHCP
autoconfiguration as shown in Figure 3.26, “Using DHCP for network configuration”.
Answer “Yes” if you have a DHCP
Dynamic Host Configuration Protocol (DHCP)
running somewhere on your network, and
sysinst will fetch a number of
defaults from it. Answer “No” to enter all the
values manually.

We will assume you answered “No”
and go into all the questions asked in detail.

sysinst will now run a few commands
(not displayed in detail here) to configure the network:
flushing the routing table, setting the default route, and
testing if the network connection is operational.

When you are satisfied with your settings (the defaults work most
of the time), choose “Get Distribution” to
continue.

Figure 3.29. Defining the FTP settings

3.10.4. Installing via NFS

If you want to install NetBSD from a server in your local
network, NFS is an alternative to FTP.

Note

Using this installation method requires the ability
to set up an NFS server, a topic which is not discussed here.

As shown in Figure 3.30, “NFS install screen”, you must specify the IP
address of the NFS server with "Host", the "Base directory" that is
exported by the NFS server, and the
"Set directory", which contains the install sets.

Figure 3.30. NFS install screen

Figure 3.31, “NFS example” shows an example:
Host “192.168.1.50 ” is the NFS server that provides
the directory “/home/username/Downloads”
The NetBSD install sets are stored in the directory
“/home/username/Downloads/sets” on the NFS server.
Choose “Continue” to start the installation of the
distribution sets.

Figure 3.31. NFS example

3.11. Extracting sets

After the method for obtaining distribution sets has been
chosen, and (if applicable) after those sets have been transferred,
they will be extracted into the new NetBSD file system.

After extracting all selected sets,
sysinst will create device nodes in
the /dev directory and then display a
message saying that everything went well.

Another message (see Figure 3.32, “Extraction of sets completed”)
will let you know that the set extraction is now completed, and
that you will have an opportunity to configure some essential
things before finishing the NetBSD installation.

Figure 3.32. Extraction of sets completed

3.12. System configuration

The first thing you can configure is your timezone.
It is
Universal Time Coordinated (UTC) by
default, and you can use the two-level menu of
continents/countries and cities shown in
Figure 3.33, “Selecting the system's time zone” to
select your timezone with the Return key. Next,
press “x” followed by Return to exit timezone
selection.

Figure 3.33. Selecting the system's time zone

At this point, you are given the option to choose a password
encryption scheme.
While “DES”
is the standard algorithm used on most Unix systems,
“MD5”, “Blowfish”, and “SHA1”
allow longer passwords than DES, which only uses the first eight
characters of the password that is entered. DES is still useful for
interoperability with other operating systems.

Figure 3.34. Selecting a password encryption scheme

After choosing the password cipher you are asked if you want to
set the root password. It is recommended to set a root password
at this point for security reasons.

Figure 3.35. Set a root password?

When you agree to set a root password, sysinst will run the
passwd(1) utility for you. Please note that the password
is not echoed.

Figure 3.36. Setting root password

The next menu allows you to choose which command line interpreter -
also known as a “shell” - will be used for the
root account. The default is the classic
Bourne shell, sh(1). Other choices are
the Korn shell (ksh(1)) and the
C shell (csh(1)).
If, upon reading this, you don't have some idea of which shell you
prefer, simply use the default, as this is a highly subjective
decision. Should you later change your mind, root's shell can always
be changed.

Figure 3.37. Choosing a shell

3.13. Finishing the installation

At this point the installation is finished.

Figure 3.38. Installation completed

After passing the dialog that
confirms the installation, sysinst
will return to the main menu. Remove any installation media (CD,
floppy, etc.) and choose “Reboot the computer” to boot
your new NetBSD installation.

Chapter 4. Upgrading NetBSD

This chapter describes the binary upgrade of a NetBSD system.
There are a variety of alternatives to perform this procedure, and the
following sections will guide you through them:

4.1. Using sysinst

4.1.1. Overview

To do the upgrade, you must have some form of bootable media
(CD-ROM, USB drive, floppy, etc.) available and at least the base and
kern distribution sets. Since files already installed on the system
are overwritten in place, you only need additional free space for
files which weren't previously installed or to account for growth of
the sets between releases. Usually this is not more than a few
megabytes.

Note

Since upgrading involves replacing the kernel, boot blocks, and
most of the system binaries, it has the potential to cause data loss.
Before beginning, you are strongly advised to back up any important
data on the NetBSD partition or on any other partitions on your disk.

The upgrade procedure is similar to an installation, but without
the hard disk partitioning. sysinst will
attempt to merge the settings stored in your /etc
directory with the new version of NetBSD. Also, file systems are checked
before unpacking the sets. Fetching the binary sets is done in the same
manner as in the installation procedure.

4.1.2. The INSTALL document

Before doing an upgrade it is essential to read the
release information and upgrading notes in one of the
INSTALL files: this is the official
description of the upgrade procedure, with platform specific
information and important details. It can be found in the root
directory of the NetBSD release (on the install CD or on the FTP
server).

It is advisable to print the INSTALL document out. It is
available in four formats: .txt, .ps, .more, and .html.

4.1.3. Performing the upgrade

The following section provides an overview of the
binary upgrade process. Most of the following
sysinst dialogs
are similar to those of the installation process. More
verbose descriptions and explanations of the dialogs are
available in Chapter 3, Example installation.

After selecting the installation language and the keyboard
type, the main menu appears. Choosing option
“b: Upgrade NetBSD on a hard disk” will start the
the upgrade process.

Figure 4.1. Starting the upgrade

The dialog in Figure 4.2, “Continuing the upgrade” will request
permission to continue with the upgrade. At this point nothing
has been changed yet and the upgrade can still be cancelled. This is
a good time to ask yourself whether you have made a backup, and if
you know for certain that you will be able to restore from it.

Figure 4.2. Continuing the upgrade

After choosing to continue with “Yes”, the
next dialog will ask you to specify the hard disk with the NetBSD
system that shall be upgraded.
If more than one disk is available a list of the disks will be
displayed.

Figure 4.3. Choosing the hard drive

The system used for the example has only one hard disk
available: “wd0”.

The following dialog provides a menu to choose the installation
type. The choices are
“Full installation”,
“Minimal installation”, or
“Custom installation”.

Figure 4.4. Choosing the distribution filesets

At this point, sysinst will perform a
check of the file system to ensure its integrity.

Figure 4.5. File system check

The next step is to choose which type of bootblocks to install.

Figure 4.6. Choosing bootblocks

The next dialog will ask how much information should
be displayed during the extraction of the distribution sets.

Figure 4.7. Upgrade process - verbosity level

The following dialog asks for the install method of choice
and provides a list of possible options. The install medium
contains the new NetBSD distribution sets. You will be prompted
for different information depending on which option you choose.
For example, a CD-ROM or DVD install requires you to specify which
device to use and which directory the sets are in, while an FTP install
requires you to configure your network and specify the hostname of an
FTP server. More details can be found in
Section 3.10, “Choosing the installation media”.

Figure 4.8. Install medium

sysinst will now unpack the distribution
sets, replacing your old binaries. After unpacking these sets, it
runs the postinstall(8) script to perform various system cleanup
and configuration update tasks. If
postinstall produces errors, you will have
to manually resolve the issues it brings up. See postinstall's man
page for more information. Even after a successful
postinstall run, it is advisable to use
etcupdate(8) to aid in merging any other configuration changes.
You should also read the remarks in INSTALL about
upgrading, as specific compatibility issues are documented there.

Figure 4.9. Upgrade complete

When you are back at the main menu, remove the boot medium (if
applicable) and reboot. Have fun with your new version of NetBSD!

4.2. Using sysupgrade

The sysupgrade utility (currently
found in pkgsrc/sysutils/sysupgrade) allows you
to upgrade a running system to a newer binary release.

Note

Please be aware that, as of August 2012,
sysupgrade is a farily new tool and is
still undergoing field testing. Use with care. In particular,
upgrades across major binary releases might not work properly
yet because of the lack of a reboot between the kernel installation
and the unpacking of the sets. That said, you may find this tool
very convenient to track NetBSD-current or stable NetBSD
branches.

One of the benefits of sysupgrade is
that it is an integrated and almost-unattended solution: the tool
fetches the new kernel and distribution sets from remote sites if you
desire and performs the upgrade without user intervention until new
changes to the configuration files need to be merged.

Let's assume you are running NetBSD/amd64 6.0 and you wish to
upgrade to NetBSD 6.1. The procedure to do so would be to run the
following command:

#sysupgrade auto ftp://ftp.NetBSD.org/pub/NetBSD/NetBSD-6.1/amd64

And that's all that it takes. This will proceed to download
the kernel and sets appropriate for your machine, unpack them and
assist you in merging new configuration changes. Do not forget to
reboot afterwards.

For more details, please see the included sysupgrade(8) manual
page and the /usr/pkg/etc/sysupgrade.conf
configuration file.

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.

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.

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

Advice

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.

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

Note

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:

5.9. 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, adding
rtclocaltime=YES
to /etc/rc.conf:

Note

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:

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.

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 “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=192.168.1.1”.

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:

nameserver 145.253.2.75

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

IP-addresshostnamehost

For example:

192.168.1.3 vigor3.your.domainvigor3

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:

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.

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

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

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
http://www.NetBSD.org/support/security/.
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.

6.1. Introducing vi

It is not like the vi editor needs introducing to seasoned UNIX
users. The vi editor, originally developed by Bill Joy of Sun
Microsystems, is an endlessly extensible, easy to use
light ASCII editor and the bane of the
newbie existence. This section will introduce the vi editor to
the newbie and perhaps toss in a few ideas for the seasoned user
as well.

The first half of this section will overview editing, saving,
yanking/putting and navigating a file within a vi session. The
second half will be a step by step sample vi session to help
get started.

This is intended as a primer for using
the vi editor, it is not by
any means a thorough guide. It is meant to get the
first time user up and using vi with
enough skills to make changes to and create files.

6.1.1. The vi interface

Using the vi editor really is not much different than any
other terminal based software with one exception, it does not
use a tab type (or curses if you will) style interface, although
many versions of vi do use curses it does
not give the same look and feel of the typical curses based
interface. Instead it works in two modes,
command and edit.
While this may seem strange, it is not much different than
windows based editing if you think about it. Take this as an
example, if you are using say gedit and you take the mouse,
highlight some text, select cut and then paste, the whole time
you are using the mouse you are not editing (even though you
can). In vi, the same action is done by simply deleting the
whole line with dd in command mode, moving
to the line you wish to place it below and hitting
p in command mode. One could almost say
the analogy is “mouse mode vs. command mode”
(although they are not exactly identical, conceptually the
idea is similar).

To start up a vi session, one simply begins the way they might
with any terminal based software:

$vi filename

One important note to remember here is that when a file is
edited, it is loaded into a memory buffer. The rest of the
text will make reference to the buffer and file in their proper
context. A file only changes when the
user has committed changes with one of the write commands.

6.1.2. Switching to Edit Mode

The vi editor sports a range of options one can provide at
start up, for the time being we will just look at the default
startup. When invoked as shown above, the editors default
startup mode is command mode, so in essence you cannot commence
to typing into the buffer. Instead you must switch out out of
command mode to enter text. The following text describes edit
start modes:

a Append after cursor.
A Append to end of line.
C Change the rest of current line.
cw Change the current word.
i Insert before cursor.
I Insert before first non blank line.
o Open a line below for insert
O Open a line above for insert.

6.1.3. Switching Modes & Saving Buffers to Files

Of course knowing the edit commands does not do much good if
you can't switch back to command mode and save a file, to
switch back simply hit the ESC key. To
enter certain commands, the colon must be used. Write commands
are one such set of commands. To do this, simply enter
:.

Hitting the colon then will put the user at the colon (or
command if you will) prompt at the bottom
left corner of the screen. Now let us look at the save commands:

:w Write the buffer to file.
:wq Write the buffer to file and quit.

6.1.4. Yanking and Putting

What good is an editor if you cannot manipulate blocks of
text? Of course vi supports this feature as well and as with
most of the vi commands it somewhat intuitive. To yank a line
but not delete it, simply enter
yy or Y in command mode
and the current line will be copied into a buffer. To put the
line somewhere, navigate to the line above where the line is
to be put and hit the p key for the
“put” command. To move a line, simply delete the
whole line with the dd command, navigate
and put.

6.1.4.1. Oops I Did Not Mean to do that!

Undo is pretty simple, u undoes the last
action and U undoes the last line deleted
or changes made on the last line.

6.1.5. Navigation in the Buffer

Most vi primers or tutorials start off with navigation, however,
not unlike most editors in order to navigate a file there must
be something to navigate to and from (hence why this column
sort of went in reverse). Depending on your flavor of vi (or
if it even is vi and not say elvis, nvi
or vim) you can navigate in both edit and command mode.

For the beginner I feel that switching to command mode and
then navigating is a bit safer until one has practiced for
awhile. The navigation keys for terminals that are not recognized
or do not support the use of arrow keys are the following:

k Moves the cursor up one line.
j Moves the cursor down one line.
l Moves the cursor right one character.
h Moves the cursor left one character.

If the terminal is recognized and supports them, the arrow
keys can be used to navigate the buffer in command mode.

In addition to simple “one spot navigation” vi
supports jumping to a line by simply typing in the line number
at the colon prompt. For example, if you wanted to jump to
line 223 the keystrokes from editor mode would look like so:

ESC:223

6.1.6. Searching a File, the Alternate Navigational Aid

The vi editor supports searching using regular expression
syntax, however, it is slightly different to invoke from
command mode. One simply hits the / key in
command mode and enters what they are searching for, as an
example let us say I am searching for the expression
foo:

/foo

That is it, to illustrate a slightly different expression,
let us say I am looking for foo bar:

/foo bar

6.1.6.1. Additional Navigation Commands

Searching and scrolling are not the only ways to navigate
a vi buffer. Following is a list of succinct navigation
commands available for vi:

0 Move to beginning of line.
$ Move to end of line.
b Back up one word.
w Move forward one word.
G Move to the bottom of the buffer.
H Move to the top line on the screen.
L Move to the last line on the screen.
M Move the cursor to the middle of the screen.
N Scan for next search match but opposite direction.
n Scan for next search match in the same direction.

6.1.7. A Sample Session

Now that we have covered the basics, let us run a sample
session using a couple of the items discussed so far. First,
we open an empty file into the buffer from the command line
like so:

#vi foo.txt

Next we switch to edit mode and enter two lines separated by
an empty line, remember our buffer is empty so we hit the
i key to insert before cursor and enter
some text:

This is some text
there we skipped a line
~
~
~
~

Now hit the ESC key to switch back into
command mode.

Now that we are in command mode, let us save the file. First,
hit the : key, the cursor should be sitting
in the lower left corner right after a prompt. At the
: prompt enter w and
hit the ENTER or RETURN
key. The file has just been saved. There should have been a
message to that effect, some vi editors will also tell you
the name, how many lines and the size of the file as well.

It is time to navigate, the cursor should be sitting wherever
it was when the file was saved. Try using the arrow keys to
move around a bit. If they do not work (or you are just plain
curious) try out the hjkl keys to see
how they work.

Finally, let us do two more things, first, navigate up to the
first line and then to the first character. Try out some of
the other command mode navigation keys on that line, hit the
following keys a couple of times:

$0$0

The cursor should hop to the end of line, back to the beginning
and then to the end again.

Next, search for an expression by hitting the
/ key and an expression like so:

/we

The cursor should jump to the first occurrence
of we.

Now save the file and exit using write and quit:

:wq

6.2. Configuring vi

The standard editor supplied with NetBSD is, needless to say,
vi, the most loved and hated editor in
the world.
If you don't use vi, skip this section, otherwise read it before
installing other versions of vi.
NetBSD's vi (nvi) was written by Keith
Bostic of UCB to have a freely redistributable version of this
editor and has many powerful extensions worth learning while
being still very compatible with the original vi.
Nvi has become the standard version of vi for BSD.

Left-right scrolling of lines, enabled with the option
leftright; the number of columns to scroll
is defined by the sidescroll option.

Command line history editing, enabled with the option
cedit.

Filename completion, enabled by the filec option.

Backgrounded screens and displays.

Split screen editing.

6.2.1. Extensions to .exrc

The following example shows a .exrc file
with some extended options enabled.

set showmode ruler
set filec=^[
set cedit=^[

The first line enables the display of the cursor position (row
and column) and of the current mode (Command, Insert, Append) on
the status line.
The second line (where ^[ is the ESC character) enables filename
completion with the ESC character.
The third line enables command line history editing (also with
the ESC character.)
For example, writing “:” and then pressing ESC opens a window
with a list of the previous commands which can be edited and
executed (pressing Enter on a command executes it.)

6.2.2. Documentation

The source tarball
(src.tgz) contains a lot of useful
documentation on (n)vi and ex, in the
/usr/src/usr.bin/vi/docs directory.
For example:

Edit: A tutorial

Ex Reference Manual

Vi man page

An Introduction to Display Editing with Vi by
William Joy and Mark Horton

Ex/Vi Reference Manual by Keith Bostic

Vi Command & Function Reference

Vi tutorial (beginner and advanced)

If you have never used vi, the “Vi tutorial” is a good
starting point. It is meant to be read using vi and it gradually
introduces the reader to all the vi commands, which can be tested
while reading.
An Introduction to Display Editing with Vi by
William Joy and Mark Horton is also a very good starting point.

If you want to learn more about vi and the nvi extensions you
should read the Ex/Vi Reference Manual
by Keith Bostic which documents all the editor's commands
and options.

6.3. Using tags with vi

This topic is not directly related to NetBSD but it can be useful,
for example, for examining the kernel sources.

When you examine a set of sources in a tree of directories and
subdirectories you can simplify your work using the
tag feature of vi.
The method is the following:

Chapter 7. The rc.d System

NetBSD uses individual scripts for controlling services, similar to
what System V and Linux use, but without runlevels. This chapter is
an overview of the rc.d system and its configuration.

7.1. Basics

The system startup files reside in the /etc
directory. They are:

/etc/rc

/etc/rc.conf

/etc/rc.d/*

/etc/rc.lkm

/etc/rc.local

/etc/rc.shutdown

/etc/rc.subr

/etc/defaults/*

/etc/rc.conf.d/*

First, a look at controlling and supporting scripts (also
documented in rc(8)).

After the kernel has initialized all devices at
startup, it starts init(8), which in turn runs
/etc/rc.

/etc/rc sorts the scripts in
/etc/rc.d using rcorder(8) and then
runs them in that order. See the rcorder(8)
man page for details of how the order of rc.d scripts is
determined.

/etc/rc.subr
contains common functions used by /etc/rc
and various rc.d scripts.

When shutting down the system with shutdown(8),
/etc/rc.shutdown is run, which runs the
scripts in /etc/rc.d in reverse
order (as defined by rcorder(8)). Note that if you shut
down the system using the halt(8) command, these scripts
will not be run.

/etc/rc.local is almost the last
script called at boot up. This script can be edited by the
administrator to start local daemons that don't fit the
rc.d model.

rc.d scripts are controlled by a central configuration file,
/etc/rc.conf, which loads its default settings from
/etc/defaults/rc.conf. If you want to change a
default setting, do not edit /etc/defaults/rc.conf;
instead, override the setting in /etc/rc.conf.

It is a good idea to read the rc.conf(5) man page to learn
about the services that are available to you.

The following example shows how to enable the SSH daemon,
which is disabled by default:

Now sshd(8) will be started automatically at system startup.
The next section describes how to start and stop services at any time.

Last but not least, files can be created in the
/etc/rc.conf.d/ directory to override the behavior
of a given rc.d script without editing the script itself.

7.2. The rc.d Scripts

The actual scripts that control services are in
/etc/rc.d. These scripts are automatically
run at boot time, but they can be called manually if necessary.
The following example shows how to start the SSH daemon
that we enabled in the previous section:

#/etc/rc.d/sshd start
Starting sshd.

Later, if you wish to stop the SSH daemon, run the following
command:

#/etc/rc.d/sshd stop
Stopping sshd.
Waiting for PIDS: 123.

The rc.d scripts take one of the following arguments:

start

stop

restart

status

Some scripts may support other arguments (e.g.,
“reload”), but every script will support at least the
above commands.

As an example, after adding a new record to a named(8) database,
the daemon can be told to reload its configuration files with the
following command:

#/etc/rc.d/named reload
Reloading named config files.

Note that all of the commands discussed above will only take action
if the particular service is enabled in
/etc/rc.conf. It is possible to bypass this
requirement by prepending “one” to the command, as in:

#/etc/rc.d/httpd onestart
Starting httpd.

The above command will allow you to start the httpd(8) service
one time. To stop a service that has been started in this manner, pass
“onestop” to the script.

7.3. The Role of rcorder and rc.d Scripts

The startup system of every Unix system determines, in one way
or another, the order in which services are started. On some Unix
systems this is done by numbering the files and/or putting them in
separate run level directories. Solaris relies on wildcards like
/etc/rc[23].d/S* being sorted numerically when
expanded. Some simply put all the commands that should be started
into a single monolithic script (this is the traditional BSD method,
and is what NetBSD did before the rc.d system). On modern NetBSD this
is done by the rc.d scripts and their contents. Please note that NetBSD
does not have multiple runlevels as found in SysV-style systems like
Solaris and Linux.

At the beginning of each rc.d script there is a series of
commented out lines that have one of the following items in them:

REQUIRE

PROVIDE

BEFORE

KEYWORD

These describe the dependencies of that particular script and
allow rcorder to easily work either “up” or
“down” as the situation requires. As an example, here
is the ordering information contained in
/etc/rc.d/nfsd:

...
PROVIDE: nfsd
REQUIRE: rpcbind mountd
...

Here we can see that this script provides the
“nfsd” service and that it requires
“rpcbind” and “mountd” to be running first.
The rcorder(8) utility is used at system startup time to read
through all the rc.d scripts and determine the order in which they
should be run.

7.4. Additional Reading

Luke Mewburn, one of the principal designers of the rc.d system,
gave a presentation on the system at USENIX 2001. It is available in
PDF
format.

Chapter 8. Console drivers

In NetBSD versions before 1.4 the user could choose between two
different drivers for screen and keyboard,
pccons (specific for i386) and
pcvt. In NetBSD 1.4 the new
wscons multiplatform driver appeared, which
has substituted the previous drivers.

8.1. wscons

Wscons is NetBSD's platform-independent workstation console driver.
It handles complete abstraction of keyboards and mice. This means that
you can plug in several keyboards or mice and they will be multiplexed
onto a single terminal, but also that it can multiplex several
virtual terminals onto one physical terminal.

The capabilities of wscons can vary depending on the port.
Starting with NetBSD 4.0, almost all ports have full support for
most capabilities wscons has to offer. If you are using a
non-mainstream architecture, please see the port-specific FAQ if
wscons seems to lack features.

Wscons support is enabled by default on most architectures. This
can be done manually by adding wscons=YES to your
/etc/rc.conf. Then configure the desired number
of virtual consoles as described in Section 8.1.1.1, “Virtual consoles”
and start wscons by entering
sh /etc/rc.d/wscons start followed by
sh /etc/rc.d/ttys restart. You can now switch
virtual consoles by pressing Ctrl+Alt+Fn or
similar, depending on the platform.

wscons comprises three subsystems: wsdisplay, wskbd and wsmouse.
These subsystems handle abstraction for all display, keyboard and mouse
devices respectively. The following sections discuss the configuration
of wscons per subsystem.

8.1.1. wsdisplay

This section will explain how to configure display and
screen-related options.

8.1.1.1. Virtual consoles

The number of pre-allocated virtual console is controlled by the
following option

options WSDISPLAY_DEFAULTSCREENS=4

Other consoles can be added by enabling the relevant lines in the
/etc/wscons.conf file: the comment mark (#) must
be removed from the lines beginning with screen x.
In the following example a fifth console is added to the four
pre-allocated ones:

The rc.wscons script transforms each of the non
commented lines in a call to the wsconscfg command:
the columns become the parameters of the call. The
idx column becomes the index
parameter, the screen column becomes the
-t type parameter (which defines the type of screen:
rows and columns, number of colors, ...) and the
emul column becomes the -e emul
parameter, which defines the emulation. For example:

screen 3 - vt100

becomes a call to:

wsconscfg -e vt100 3

Please note that it is possible to have a (harmless)
conflict between the consoles
pre-allocated by the kernel and the consoles allocated at boot time
through /etc/wscons.conf.
If during boot the system tries to allocate an already allocated
screen, the following message will be displayed:

wsconscfg: WSDISPLAYIO_ADDSCREEN: Device busy

The solution is to comment out the offending lines in
/etc/wscons.conf.

Note that while it is possible to delete a screen and add it with
different settings, it is, technically speaking, not possible to
actually modify the settings of a screen.

screen 0 cannot be deleted if used as system console.
This implies that the setting of screen 0 cannot be
changed in a running system, if used as system console.

The virtual console must also be active in
/etc/ttys, so that NetBSD runs the
getty(8) program to ask for login. For example:

When starting up the X server, it will look for a virtual
console with no getty(8) program running, e.g. one console
should left as "off" in /etc/ttys. The
line

ttyE3 "/usr/libexec/getty Pc" vt220 off secure

of /etc/ttys is used by the X server
for this purpose. To use a screen different from number 4, a
parameter of the form vtn must be passed to
the X server, where n is the number of the
function key used to activate the screen for X.

For example, screen 7 could be enabled in
/etc/wscons.conf and X could be started with
vt8. If you use xdm you must
edit /etc/X11/xdm/Xservers. For
example:

This error message usually occurs when wsconscfg tries
to add a screen which already exists. One time this occurs
is if you have a screen 0 line in your
/etc/wscons.conf file, because the
kernel always allocates a screen 0 as the console device.
The error message is harmless in this case, and you can get
rid of it by deleting (or commenting out) the
screen 0 line.

8.1.1.2. 50 lines text mode with wscons

A text mode with 50 lines can be used starting with version 1.4.1 of
NetBSD. This mode is activated in the
/etc/wscons.conf. The following line must be
uncommented:

This configuration enables eight screens, which can be accessed with
the key combination Ctrl-Alt-Fn (where
n varies from 1 to 8); the corresponding devices
are ttyE0..ttyE7. To enable them and get a login prompt,
/etc/ttys must be modified:

screen 0 as system console can be set to another
screen type at boot time on VGA displays. This
is a kernel configuration option. If a non-80x25 setting
is selected, it must be made sure that a usable font is
compiled into the kernel, which would be an 8x8 one
for 80x50.

There is a problem with many ATI graphics cards which don't
implement the standard VGA font switching logics: These need another
kernel option to make a nonstandard console font work.

8.1.1.3. Enabling framebuffer console

On many architectures, there is only one type of screen mode:
a graphical framebuffer mode. On machines with VGA graphics cards,
there is a second mode: textmode. This is an optimized mode
specially made for displaying text. Hence, this is the default
console mode for GENERIC kernels on architectures where the graphics
card is typically a VGA card (i386, amd64).

However, you can enable a framebuffer on machines with VGA
cards that support the VESA BIOS extension (VBE).

Starting in NetBSD 6.0 vesafb(4) has been replaced with
genfb(4). VESA framebuffer mode is configured during boot(8)
using the vesa command.

To enable support for this mode in NetBSD 4.x and 5.x,
uncomment the following lines in the kernel configuration file:

8.1.1.4. Enabling scrollback on the console

You can enable scrolling back on wscons consoles by compiling
the WSDISPLAY_SCROLLSUPPORT option into your
kernel. Make sure you don't have option
VGA_RASTERCONSOLE enabled at the same time
though! See Chapter 32, Compiling the kernel for instructions on
building a kernel.

When you have a kernel with options
WSDISPLAY_SCROLLSUPPORT running, you can
scroll up on the console by pressing LEFT SHIFT plus PAGE
UP/DOWN. Please note that this may not work on your system
console (ttyE0)!

8.1.1.5. Wscons and colors

8.1.1.5.1. Changing the color of kernel messages

It is possible to change the foreground and background
color of kernel messages by setting the following options in
kernel config files:

Starting from NetBSD 3.0, you can easily customize many
aspects of your display appearance: the colors used to print normal messages, the
colors used to print kernel messages and the color used to
draw a border around the screen.

All of these details can be changed either from kernel
options or through the wsconsctl(8) utility; the later
may be preferable if you don't want to compile your own
kernel, as the default options in GENERIC
are suitable to get this tip working.

border: The color
of the screen border. Its respective kernel
option is WSDISPLAY_BORDER_COLOR.

msg.default.attrs: The attributes
used to print normal console messages. Its respective
kernel options are WS_DEFAULT_COLATTR
and WS_DEFAULT_MONOATTR (the former is used
in color displays, while the later is used in monochrome
displays).

msg.default.bg:
The background color used to print normal console
messages. Its respective kernel option is
WS_DEFAULT_BG.

msg.default.fg:
The foreground color used to print normal console
messages. Its respective kernel option is
WS_DEFAULT_FG.

msg.kernel.attrs:
The attributes used to print kernel messages and warnings.
Its respective kernel options are
WS_KERNEL_COLATTR and
WS_KERNEL_MONOATTR (the
former is used in color displays, while the later is used
in monochrome displays).

msg.kernel.bg:
The background color used to print kernel messages and
warnings. Its respective kernel option is
WS_KERNEL_BG.

msg.kernel.fg:
The foreground color used to print kernel messages and
warnings. Its respective kernel option is
WS_KERNEL_FG.

The values accepted as colors are: black, red, green,
brown, blue, magenta, cyan and white. The attributes are a
comma separated list of one or more flags, which can be:
reverse, hilit, blink and/or underline.

For example, to emulate the look of one of those old
Amstrad machines:

Note that, in older versions of NetBSD, only a subset of
this functionality is available; more specifically, you can
only change the kernel colors by changing kernel options, as
explained above.
Also note that not all drivers support these features, so
you may not get correct results on all architectures.

8.1.1.5.2. Getting applications to use colors on the console

NetBSD uses the termcap database to
tell applications what the current terminal's capabilities are.
For example, some terminals don't support colors, some don't
support underlining (PC VGA terminals don't, for example) etc.
The TERM environment variable tells the termcap
library the type of terminal. It then refers to its database
for the options.

The default setting for TERM can be
inspected by typing echo $TERM
on the terminal of interest. Usually this is something like
vt220. This terminal type doesn't support
colors. On a typical PC console with 25 lines, you can change
this value to wsvt25 instead, to get colors.
This is done in the C shell (csh) by entering:

setenv TERM wsvt25

In a Bourne-compatible shell (sh, ksh), you can enter:

export TERM=wsvt25

If this does not work for you, you can try the
ansi terminal type, which supports
ANSI color codes. However, other functionality may be
missing with this terminal type. You can have a look
at the file /usr/share/misc/termcap
to see if you can find a useful match for your
console type.

8.1.1.6. Loading alternate fonts

There are several fonts in
/usr/share/wscons/fonts
that can be loaded as console fonts. This can be done with the
wsfontload(8) command, for example:
wsfontload -N ibm -h 8 -e ibm /usr/share/wscons/fonts/vt220l.808.
This command loads the IBM-encoded (-e ibm)
font in the file vt2201.808 which has a height
of eight pixels (-h 8). Name it ibm for later
reference (-N ibm).

To actually display the font on the console, use the command
wsconsctl -dw font=ibm.

If you want to edit a font, you can use the old pcvt
utils that are available in the
sysutils/pcvt-utils
package.

8.1.2. wskbd

8.1.2.1. Keyboard mappings

Wscons also allows setting the keymap to map the keys on
various national keyboards to the right characters. E.g. to
set the keymap for an Italian keymap, run:

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

This setting will last until the next reboot.
To make it permanent, add a encoding line to
/etc/wscons.conf: it will be executed
automatically the next time you reboot.

Please be careful and type two > characters.
If you type only one >, you will overwrite
the file instead of adding a line. But that's why we always
make backup files before touching critical files!

A full list of keyboard mappings can be found in
/usr/src/sys/dev/wscons/wsksymdef.h:

be - Belgian

de - German

dk - Danish

es - Spanish

fi - Finnish

fr - French

gr - Greek

hu - Hungarian

it - Italian

jp - Japanese

no - Norwegian

pl - Polish

pt - Portuguese

ru - Russian

sf - Swiss French

sg - Swiss German

sv - Swedish

ua - Ukrainian

uk - UK-English

us - US-English

There are also several "variants" that can be used to
modify a map:

declk

dvorak

iopener

lk401

metaesc

nodead

swapctrlcaps

dvorak uses the Dvorak keyboard
layout. swapctrlcaps switches the functions of the
Caps Lock and Left Control keys. iopener
is for the nonstandard keyboard layout on the Netpliance
i-opener and makes F1 into Escape and F2 through F12 into F1
through F11.
These can be combined with another map by appending a dot
and then the variant name, for example,
us.iopener. Multiple variants can
be combined, such as
us.dvorak.swapctrlcaps. Note that not all
combinations are allowed.

You can change the compiled in kernel default by adding
options PCKBD_LAYOUT=KB_encoding
where encoding is an uppercase entry
from the list above
(eg: PCKBD_LAYOUT=KB_FR). Variants can be
bitwise or'd in
(eg: PCKBD_LAYOUT=KB_US|KB_SWAPCTRLCAPS).

You can test your keymap by using wsconsctl instead
of directly hacking the keymaps into the keyboard mapping file. For example, to
say keycode 51 without any modifiers should map to a comma, with shift it should
map to a question mark, with alt it should map to a semicolon and with both alt
and shift it should map to colon, issue the following
command:

wsconsctl -w "map += keycode 51=comma question semicolon colon"

8.1.2.2. Changing the keyboard repeat speed

Keyboard repeat speed can be tuned using the
wsconsctl(8) utility.
There are two variables of interest:
repeat.del1, which specifies the delay before
character repetition starts, and repeat.deln,
which sets the delay between each character repetition (once
started).

Let's see an example, assuming you want to accelerate keyboard
speed. You could do, from the command line:

wsconsctl -w repeat.del1=300
wsconsctl -w repeat.deln=40

Or, if you want this to happen automatically every time
you boot up the system, you could add the following lines to
/etc/wscons.conf:

setvar repeat.del1=300
setvar repeat.deln=40

8.1.3. wsmouse

8.1.3.1. Serial mouse support

The wsmouse device (part of wscons) does not directly
support serial mice. The moused(8) daemon is provided
to read serial mouse data, convert it into wsmouse events
and inject them in wscons' event queue, so the mouse can be
used through the abstraction layer provided by wsmouse.

A typical use can be: moused -p /dev/tty00.
This will try to determine the type of mouse connected to
the first serial port and start reading its data. The
moused(8) man page contains more examples.

8.1.3.2. Cut&paste on the console with wsmoused

It is possible to use the mouse on the wscons console to mark
(cut) text with one mouse button, and insert (paste) it again
with another button.

To do this, enable "wsmoused" in
/etc/rc.conf, and start it:

#echo wsmoused=yes >>/etc/rc.conf#sh /etc/rc.d/wsmoused start

After that you can use the mouse to mark text with the left
mouse button, and paste it with the right one. To tune the
behaviour of wsmoused(8) see its manpage, which also
describes the format of the wsmoused.conf(5) config file,
an example of which can be found in
/usr/share/examples/wsmoused.

9.1. What is X?

NetBSD uses the X Window System to provide a graphical interface.
In NetBSD 5.0, the amd64, i386, macppc, shark, sgimips, and sparc64
ports use X.Org and the rest use XFree86.

Please note that the X Window System is a rather bare bones
framework. It acts as a base for modern desktop environments like
GNOME or KDE, but they are not part of the X Window System.
NetBSD ships with the X Window System, but it does not include these
desktop environments; they must be added via pkgsrc.

When you start using X you'll find many new terms which you may
find confusing at first. The basic elements are:

Video hardware, i.e., your video
card.

An X server running on top of the
hardware. The X server provides a standard way to display
graphics (including fonts for text display) and get
mouse/keyboard/other input. X is network-transparent, which means
that you can run X clients on one machine, and the X server
(i.e., the display, with video hardware) on another machine.

X clients. These are the programs you
directly interact with. They run on top of the X server. A web
browser like Firefox is an example of an X client.

A window manager running on top of the X
server. The window manager is a special X client that is allowed
to control the placement of windows. It can also
“decorate” windows with standard “widgets”
(usually these provide actions like window motion, resizing,
iconifying, window killing, etc.).

A desktop environment such as GNOME or
KDE. These are suites of integrated software designed to give you
a well-defined range of software and a more or less common interface
to each program. These typically include a window manager, file
manager, web browser, email client, multimedia player, text editor,
address book, help browser, etc. As you may have guessed, a desktop
environment is not needed to use X, but many users will want to
install one.

9.2. Configuration

In some cases, you may be able to start using X without any
configuration at all, and startx will work just
fine. In many cases, however, some configuration of the X
server is required. Depending on the port you use, this configuration
file will be either /etc/X11/xorg.conf or
/etc/X11/XF86Config.
The structure of the configuration file is described formally
in xorg.conf(5) or XF86Config(5).

To generate an initial configuration file for your X server,
run the command

#X -configure

This command should create a configuration file and place it in
your home directory. To test the generated configuration
file, run, e.g.,

#X -config ~/xorg.conf.new

If this succeeds, you should see a crosshatched background and
a cursor in the shape of an X. Try moving the cursor around to
verify that the mouse is functional. To quit, press Ctrl-Alt-Backspace.

If the above test was successful, move the file into place
(as either /etc/X11/xorg.conf or
/etc/X11/XF86Config) and you are ready to go.
The following sections may be of interest or use, but are not required
reading.

9.3. The mouse

PS/2 and USB mice will normally be autodetected, and a configuration
entry like the following will be generated:

In this example. /dev/tty00 is the first
serial port. Use /dev/tty01 for the
second, and so on. Protocol "auto" will try to automatically
detect the protocol of your serial mouse. If this doesn't work,
try values like "Microsoft", "IntelliMouse" or "Logitech". See
mousedrv(4) for more information.

9.4. The keyboard

Even if you have already configured your keyboard for wscons
(See Section 8.1, “wscons”), you need to configure it for
X as well, at least if you want to use a non-US layout.

An easy solution is to use the XKB protocol
to specify the keyboard type and layout.

If you wish to change the repeat rate of your keyboard, you can
set it with the “AutoRepeat” option, which takes two
arguments: delay and rate, respectively. The following example
sets the initial delay to 200 milliseconds and the repeat rate to 30
per second:

Option "AutoRepeat" "200 30"

If X is already running, the keyboard repeat rate can be changed with
the xset(1) command:

9.5. The monitor

If X does not run at the resolution you think it should, first
run xrandr and see if the resolution you want is
listed. If your preferred resolution is listed in that command's
output, you can change resolutions with, e.g.,

$xrandr -s 1680x1050

If your preferred resolution is not listed, or you have issues with
flickering, you may need to manually specify your monitor's horizontal
and vertical frequencies. These can be set with the
“HorizSync” and “VertRefresh” directives in
the “Monitor” section. An example is provided below.

9.6. The video card

Normally, your video card will be automatically detected. In the
event that this autodetection fails, all available drivers can be found
in /usr/X11R7/lib/modules/drivers. (Replace
“X11R7” with “X11R6” if you use a port that
has not yet switched to X.Org.) The driver can be set with the
“Driver” directive in the “Device” section,
as shown below.

Section "Device"
Identifier "Card0"
Driver "intel"
EndSection

9.7. Starting X

You can start X with the following command:

$startx

If your basic X server configuration is correct, you are left in
the X environment with the default window manager
(twm). If you want a more advanced window
manager or desktop environment, many are available in pkgsrc. See
Section 9.9, “Other window managers or desktop environments” for information about
adding and changing window managers.

9.8. Customizing X

One of the first things you will want to do is to change the
programs that run when X is first started. The easiest way to do this
is to copy the default .xinitrc file to your home
directory and modify it, or create a simple new one from scratch.
For example:

$cp /etc/X11/xinit/xinitrc ~/.xinitrc$vi ~/.xinitrc

The following example shows how to start the window manager
(twm) and open an instance of the
xclock and xterm programs.
The screen background color is set to “bisque4”, which is
defined in /usr/X11R7/lib/X11/rgb.txt.

With this type of setup, to quit X you must exit the window
manager, which is usually done by selecting "exit" from its
menu.

The above example is very simple, but illustrates the basics
of controlling the clients that are run when X is started. You can
run any number of commands from your .xinitrc,
including basic X configuration commands like
xset b off to turn off the bell.

9.9. Other window managers or desktop environments

If you don't like twm, which is a very
simple window manager, you can install another window manager or
a desktop environment from pkgsrc.
The following example uses the Openbox window manager, but there are
many others available in pkgsrc/wm.

Openbox can be installed via binary packages or compiled with
pkgsrc. As always, assuming a properly set PKG_PATH, the binary package
method is:

#pkg_add -v openbox

To build it with pkgsrc, run:

#cd /usr/pkgsrc/wm/openbox#make install

Openbox is now installed; to start it you must modify your
.xinitrc file:
substitute the line which calls twm with
a line which calls openbox.
For example:

The startx command will start the X11 session
with Openbox. As configured in the example .xinitrc
file above, choosing “Exit” or similar from the window
manager's menu will quit the window manager and end the X11 session.

Installing a desktop environment is almost as easy. The following
example shows how to use the Xfce desktop environment.

After running the above commands, edit your
.xinitrc as above and change
“openbox” (or “twm”) to
“xfce4-session”. The next time you run
startx the Xfce desktop environment will be
started.

9.10. Graphical login with xdm

If you always use X and the first thing you do after you log in
is run startx, you can set up
a graphical login to do this automatically. It is very easy:

Create the .xsession file in your home
directory. This file is similar to .xinitrc
and can, in fact, be a link to it.

$ln -s .xinitrc ~/.xsession

Modify /etc/rc.conf, adding the following
line:

xdm=YES # x11 display manager

Start xdm (or reboot your system, as this will be done
automatically from now on):

#/etc/rc.d/xdm start

The configuration files for xdm
are in the /etc/X11/xdm
directory. The Xservers file specifies the
virtual console that X is started on. It defaults to
“vt05”, which is the console you reach via
“Ctrl+Alt+F5”. If you want to use a different virtual
console, change vt05 as desired. In order to avoid keyboard contention
between getty and xdm, be sure to start xdm on a virtual terminal
where getty is disabled. For example, if in
Xservers you have:

:0 local /usr/X11R6/bin/X :0 vt04

then in /etc/ttys you should have

ttyE3 "/usr/libexec/getty Pc" vt220 off secure

(Please note that vt04 corresponds to ttyE3; In
/etc/X11/xdm/Xservers, numbering starts at 1,
but in /etc/ttys, numbering starts at 0).

If you want to change the look of your xdm login screen, you can
modify the xdm configuration file.
For example, to change the background color you can add the
following line to the Xsetup_0 file:

The NetBSD port for i386, alpha, mac68k, macppc, and many others
can execute a great number of native
Linux programs, using the Linux emulation layer.
Generally, when you think about emulation you imagine something
slow and inefficient because, often, emulations must reproduce
hardware instructions and even architectures (usually from old machines)
in software.
In the case of the Linux emulation this is radically different:
it is only a thin software layer, mostly for system calls which
are already very similar between the two systems.
The application code itself is processed at the full speed of your
CPU, so you don't get a degraded performance with the Linux
emulation and the feeling is exactly the same as for native NetBSD
applications.

This chapter explains how to configure the Linux emulation with
an example: the installation of the well known
Acrobat Reader version 7 program.

10.1. Emulation setup

The installation of the Linux emulation is described in the
compat_linux(8) man page; using the package system only two steps
are needed.

Configuring the kernel.

Installing the Linux libraries.

Installing Linux applications like Acrobat Reader

10.1.1. Configuring the kernel

If you use a GENERIC kernel you don't need to do anything because
Linux compatibility is already enabled.

If you use a customized kernel, check that the following options
are enabled:

option COMPAT_LINUX
option EXEC_ELF32

or the following options if you are going to use 64-bit ELF
binaries:

option COMPAT_LINUX
option EXEC_ELF64

when you have compiled a kernel with the previous options you can
start installing the necessary software.

10.1.2. Installing the Linux libraries

Usually, applications are linked against shared libraries, and
for Linux applications, Linux shared libraries are needed.
You can get the shared libraries from any Linux distribution,
provided it's not too old, but the suggested method is to use the
package system and install the libraries automatically (which
uses SUSE libraries).
When you install the libraries, the following happens:

A secondary root directory is created
which will be used for Linux programs.
This directory is /emul/linux.
The Linux programs in emulation mode will use this directory
as their root directory and use files there. If a required
file is not found, it will be searched with
/ as root directory.

For example, if a Linux application opens
/etc/ld.so.conf, it will first be
searched in
/emul/linux/etc/ld.so.conf, and if
not found there in /etc/ld.so.conf.

The shared libraries for Linux are installed.
Most applications are linked dynamically and expect to find
the necessary libraries on the system.
For example, for Acrobat Reader,
if you go to the
/usr/pkgsrc/print/acroread7 and give the
make depends command, pkgsrc will fetch
and install all dependencies for Acrobat
Reader.

Both operations will be handled automatically by the package
system, without the need of manual intervention from the user (we
suppose that, by now, you have already begun to love the package
system...). Note that this section describes manual installation
of the Linux libraries.

To install the libraries, a program must be installed that
handles the RPM format: it is
rpm, which will be used to extract the
SUSE libraries. Execute make and
make install in the
/usr/pkgsrc/misc/rpm/ directory to
build and install rpm.

Next the suse100_base package must be
installed.
The SUSE RPM files can be downloaded by the package system or, if
you have a SUSE CD, you can copy them in the
/usr/pkgsrc/distfiles/suse100 directory and
then run make and make install
after going to the
/usr/pkgsrc/emulators/suse100_base
directory.

With the same method install suse100_compat
and suse100_x11.
The final configuration is:

10.1.3. Installing Acrobat Reader

Now everything is ready for the installation of the
Acrobat Reader program (or other Linux
programs).
Change to
/usr/pkgsrc/print/acroread7 and give the
usual commands.

#make#make install

Note

To download and install Acrobat Reader you need to add the line
“ACCEPTABLE_LICENSES+=adobe-acrobat-license” to
/etc/mk.conf to accept the Acrobat Reader
license, simply follow the instructions given after
make.

10.2. Directory structure

If we examine the outcome of the installation of the Linux
libraries and programs we find that
/emul/linux is a symbolic link pointing to
/usr/pkg/emul/linux, where the following
directories have been created:

bin/
dev/
etc/
lib/
opt/
proc/
root/
sbin/
usr/
var/

Note

Please always refer to /emul/linux and not
to /usr/pkg/emul/linux.
The latter is an implementation detail and may change in the
future.

How much space is required for the Linux emulation software?
On one system we got the following figure:

#cd /usr/pkg/emul#du -k /emul/linux/
...
127804 /emul/linux/

Acrobat Reader, the program, has been
installed in the usual directory for package binaries:
/usr/pkg/bin. It can be run just as any
other program:

$acroread netbsd.pdf

10.3. Emulating /proc

Some Linux programs rely on a Linux-like /proc
filesystem. The NetBSD procfs filesystem can emulate a
/proc filesystem that contains Linux-specific
pseudo-files. To accomplish this you can mount the procfs with
the “linux”-option:

#mount_procfs -o linux procfs /emul/linux/proc

In this example a Linux-like proc filesystem will be mounted to
the /emul/linux/proc directory. You can also
let NetBSD mount it automatically during the booting process of
NetBSD, by adding the following line to /etc/fstab:

procfs /emul/linux/proc procfs ro,linux

10.4. Using Linux browser plugins

Linux plugins for Mozilla-based browsers can be used on native
NetBSD Firefox builds through
nspluginwrapper, a wrapper that
translates between the native browser and a foreign plugin.
At the moment, nspluginwrapper only works reliably on Mozilla-based
browsers that link against GTK2+ (GTK1+ is not supported).
nspluginwrapper can be installed through pkgsrc:

# cd /usr/pkgsrc/www/nspluginwrapper
# make install

Plugins can then be installed in two steps: first, the plugin
has to be installed on the system (e.g. through pkgsrc). After
that the plugin should be registered with the
nspluginwrapper by the users who want to
use that plugin.

In this short example we will have a look at installing the
Macromedia Flash plugin. We can
fullfill the first step by installing the Flash plugin through
pkgsrc:

# cd /usr/pkgsrc/multimedia/ns-flash
# make install

After that an unprivileged user can register the Flash plugin:

$ nspluginwrapper -i /usr/pkg/lib/netscape/plugins/libflashplayer.so

The plugin should then be registered correctly. You can check this
by using the -l option of
nspluginwrapper
(nspluginwrapper -l). If the plugin is listed,
you can restart Firefox, and verify that the plugin was installed
by entering about:plugins in the location
bar.

10.5. Further reading

The following articles may be of interest for further
understanding Linux (and other) emulation:

This chapter is a short introduction to the usage of audio
devices on NetBSD (who wants a dumb computer, anyway?)

11.1. Basic hardware elements

In order to make audio work on your system you must know what
audio card is installed. Sadly it is often not enough to know
the brand and model of the card, because many cards use
chipsets manufactured from third parties. Therefore knowing
the chipset installed on the audio card can sometimes be
useful.
The NetBSD kernel can recognize many chipsets and a quick
look at dmesg is enough most of the time.

Therefore, type the following command:

#dmesg | more

and look for the audio card and chipset. If you're lucky you
won't need to do anything because NetBSD automatically
detects and configures many audio cards.

Sometimes audio doesn't work because the card is not
supported or because you need to do some work in order for
the card to be detected by NetBSD.
Many audio cards are nowadays very cheap, and it is worth
considering buying a different card, but before doing this
you can try some simple steps to make the card work with
NetBSD.

11.2. BIOS settings

This section is useful only to the owners of i386 PCs; on
other architectures (e.g. Amiga) there are no such features.
The most important thing to determine in order to use the
audio card with NetBSD is the type of bus supported by the card.

The most common interfaces are ISA and PCI.

ISA Plug and Play cards are usually more tricky to configure
mostly because of the interaction with the BIOS of the computer.

On the newer machines (those produced after 1997) there is a
BIOS option which causes many headaches for the configuration
of ISA Plug and Play audio cards (but not only audio cards):
this option is usually named “PNP OS Installed”
and is commonly found in the “PNP/PCI Configuration”
(the names can be different in your BIOS.) As a general rule it is
usually better to disable (i.e. set it to “NO”) this
option for NetBSD.

Note

On many systems everything works fine even if this option
is enabled. This is highly system dependent.

11.3. Configuring the audio device

During the installation of NetBSD the devices are created in
the /dev directory.
We are primarily interested in:

/dev/audio/dev/sound/dev/mixer

If they are not present they can be created like this:

#cd /dev#./MAKEDEV all

This command creates all the devices, including the audio
devices.

The audio card is now probably ready to be used without
further work.

You can make a quick test and send an audio file to the
device (audio files usually have the .au
extension), but if you don't have an audio file you can just
send a text or binary file (of course you won't hear anything
useful...).
Use /dev/audio or
/dev/sound:

#cat filename > /dev/audio

or

#cat filename > /dev/sound

If you hear something it means that the card is supported by
NetBSD and was recognized and configured by the kernel at
boot; otherwise you must configure the kernel settings for
the audio device installed on the system (assuming the
card/chipset is supported.)

11.4. Configuring the kernel audio devices

NetBSD supports a wide range of audio cards and the GENERIC
kernel already enables and configures most of them.
Sometimes it is necessary to manually set up the IRQ and DMA
for non-PnP ISA cards.

Note

If you still have problems you can try enabling all the
devices, because some audio cards can be made to work only by
emulating another card.

Many chipset make use of the SoundBlaster and OPL
compatibility, but a great number of them work with the WSS
emulation.

OPL is a MIDI synthesizer produced by Yamaha; there are many
OPL variants (e.g. OPL2, OPL3SA, OPL3SA2, etc.).
Many audio cards rely on this component or on a compatible
one. For example, the chips produced by Crystal (and amongst
them the very common CS423x) all have this chipset, and
that's why they work with NetBSD.

WSS is not a microchip; it is the acronym of Windows Sound
System. WSS is the name of the NetBSD kernel driver which
supports the audio system of Microsoft Windows.
Many audio cards work with Windows because they adhere to
this standard (WSS) and the same holds for NetBSD.

Of the many audio cards that I tested with NetBSD, a good
number work only if opl* and
wss* are enabled in the kernel.

You should have no problem to get the Creative SoundBlaster
cards to work with NetBSD: almost all of them are supported,
including the Sound Blaster Live 1024!

When everything works you can disable in the kernel
configuration file the devices that you don't need.

11.5. Advanced commands

NetBSD comes with a number of commands that deal with audio
devices.
They are:

audioctl(1) made its appearance in NetBSD 1.3 and is used to
manually set some variables regarding audio I/O, like the
frequencies for playing and recording.
The available parameters can be displayed with the
following command:

#audioctl -a | more

For example, to listen to CD quality music you can use the
following command.

With this command you can play audio files in simple
formats like ULAW and WAV. For more
sophisticated needs you might want to install one of the
many programs available in the package system which let you
play audio files in different formats (e.g. MP3, etc.)

Chapter 12. Printing

This chapter describes a simple configuration for printing,
using an HP Deskjet 690C printer connected to the first parallel port
and the lpd printing system that comes with NetBSD.
First, the system will be configured to print text documents, and
next the configuration will be extended to print PostScript
documents using the Ghostscript program
(print/ghostscript).
Please note that there are other, alternative printing systems
available from the
packages collection, like LPRng
(print/LPRng) and the
Common Unix Printing System (CUPS)
(print/cups)
which are not covered here.

12.1. Enabling the printer daemon

After installation it is not yet possible to print, because the
lpd printer spooler daemon is not enabled.
To enable lpd, one line in the
/etc/rc.conf file must be changed from:

lpd=NO

to

lpd=YES

The change will come into effect at the next boot, but the daemon
can be started manually now:

#sh /etc/rc.d/lpd start

To check if lpd is active, type the following
command:

#ps ax | grep lpd
179 ?? Is 0:00.01 lpd

If you don't see an entry for lpd in the output of the previous
command, the daemon is not active.

The lpd system is configured via
/etc/printcap. Before configuring
/etc/printcap it is a good idea
to make a printer test, to check if the physical connection
between your computer and the printer is working.
The test sends out some data directly to the printer
device. Assuming you use a printer connected to the parallel
port, this is /dev/lpt0; if you use an USB
printer try /dev/ulpt0. Please check the
manpages of these devices (lpt(4), ulpt(4)) for more
information!

In our example we have a printer attached to the parallel port,
so we run this:

#lptest 70 5 > /dev/lpt0

To see what the output should look like, try the same command
without redirecting the output to the printer:

A frequent problem is that the output on the printer is not correctly
aligned in columns but has a “staircase” configuration.
This usually means that the printer is configured to begin a new
line at the left margin after receiving both a <CR>
(carriage return, ASCII 13) character and a <LF> (line feed,
ASCII 10) character.
NetBSD only sends a <LF> character.
You can fix this problem in two ways:

by changing the configuration of the printer

by using a simple printer filter (described later)

Note

In the previous example the lpd
spooler is not involved because the program output is sent
directly to the printer device (/dev/lpt0)
and is not spooled.

12.2. Configuring /etc/printcap

This section explains how to configure the example printer
to print text documents.

The printer must have an entry in the
/etc/printcap file; the entry contains the
printer id (the name of the printer) and the printer
description. The lp id is the default
used by many programs. Here is an example entry:

The file format and options are described in detail in the
printcap(5) manpage. Please note that an input
filter has been specified (with the
if option) which will take care of
eliminating the staircase problem:

if=/usr/local/libexec/lpfilter

Printer driver and HP printers

Example 12.1, “/etc/printcap” uses the
lpa0 device (polled driver) for the
printer, instead of the lpd0 (interrupt
driven driver). Using interrupts there is a communication
problem with some printers, and the HP Deskjet 690C is one of
them: printing is very slow and one PostScript page can take
hours. The problem is solved using the
lpa driver. It is also possible to
compile a custom kernel where lpt is polled.

The printcap entry for the printer also specifies a spool directory,
which must be created; this directory will be used by the
lpd daemon to accumulate the data to be
printed:

#cd /var/spool/lpd#mkdir lp#chown daemon:daemon lp#chmod 770 lp

The only missing part is the
lpfilter input filter, which must be written.
The only task performed by this filter is to configure the printer for
the elimination of the staircase problem before sending the text to be
printed.
The printer used in this example requires the following initialization
string:
“<ESC>&k2G”.

After saving this script into the name you used in
/etc/printcap, you need to make sure it's
executable:

#chmod 755 /usr/local/libexec/lpfilter*

Note

There is another filter that can be used:

if=/usr/libexec/lpr/lpf:

This filter is much more complex than the one presented before.
It is written to process the output of nroff
and handles underline and overprinting, expands tab characters
and converts LF to CR + LF.
The source to this filter program can be found in
/usr/src/usr.sbin/lpr/filters/lpf.c.

After everything is in place now, the
lptest command can be run again now, this
time using the lpr command, which will first
send the data to the lpd spooler, then runs the filter and sends
the data off to the printer:

#lptest 70 5 | lpr -h

The lpr program prints text using the
spooler to send data to the printer; the -h
option turns off the printing of a banner page (not really
necessary, because of the sh option in
/etc/printcap). Users more familiar with
the System V printing system can also use the lp(1) command
that comes as an alternative to lpr(1).

12.3. Configuring Ghostscript

Now that basic printing works, the functionality for
printing PostScript files can be added. The simple printer used
in this example does not support native printing of PostScript
files; a program must be used which is capable of converting a
PostScript document in a sequence of commands that the printer
understands. The Ghostscript
program, which can be found in packages collection, can be used
to this purpose. This section explains how to configure lpd to use
Ghostscript to print PostScript files
on the HP Deskjet 690C.

A second id for the printer will be created in
/etc/printcap: this new id will use a different
input filter, which will call Ghostscript to perform the actual print
of the PostScript document.
Therefore, text documents will be printed on the
lp printer and PostScript documents on the
ps printer: both entries use the same physical
printer but have different printing filters.

The same result can be achieved using different
configurations. For example, a single entry with only one
filter could be used. For this, the filter should be able to
automatically determine the format of the document being printed,
and use the appropriate printing program. This approach is
simpler but leads to a more complex filter; if you like it you
should consider installing the
magicfilter program from the packages
collection: it does this and many other things
automatically.

Option mx#0 is very important for printing PostScript
files because it eliminates size restrictions on the input file;
PostScript documents tend to be very big.
The if option points to the new filter.
There is also a new spool directory.

The next steps are the creation of the new spool directory
and of the filter program. The procedure for the spool directory
is the same as above:

#cd /var/spool/lpd#mkdir ps#chown daemon:daemon ps#chmod 770 ps

The filter program for PostScript output is more complex than
the text base one: the file to be printed is fed to the
interpreter which converts it into a sequence of
commands in the printer's control language, and then sends that
off to the printer. We have achieved to
transform a cheap color printer in a device suitable for
PostScript output, by virtue of the NetBSD operating system and
some powerful freeware packages. The options used to configure
Ghostscript are described in the
Ghostscript documentation: cdj550 is the
device used to drive the HP printer.

To summarize: two different printer names have been created on the
system, which point to the same physical printer but use different
options, different filters and different spool directories.
Text files and PostScript files can be printed.
To print PostScript files the Ghostscript package must be installed
on the system.

12.4. Printer management commands

This section lists some useful BSD commands for printer and print
jobs administration.
Besides the already mentioned lpr and
lpd commands, we have:

12.5. Remote printing

It is possible to configure the printing system in order to
print on a printer connected to a remote host.
Let's say that, for example, you work on the wotan
host and you want to print on the printer connected to the
loge host.
The /etc/printcap file of loge is the one
of Example 12.3, “/etc/printcap”.
From wotan it will be possible to print Postscript files using
Ghostscript on loge.

The first step is to accept the print jobs submitted
from the wotan host to the loge host.
To accomplish this, a line with the wotan host name must be added
to the /etc/hosts.lpd file on loge:

#hostname
loge
#cat /etc/hosts.lpd
wotan

The format of this file is very simple: each line contains the
name of a host which is permitted to print on the local system.
By default the lpd daemon only listens on UNIX domain sockets
for local connections, it won't accept any network connects.
To ensure the daemon also accepts incoming network traffic, the
following will need to be added to
/etc/rc.conf:

lpd_flags=""

Next, the /etc/printcap file on wotan
must be configured in order to send print jobs to loge.
For example:

13.1. Initializing and using floppy disks

PC-style floppy disks work mostly like other disk devices like
hard disks, except that you need to low-level format them first.
To use an common 1440 KB floppy in the first floppy drive,
first (as root) format it:

Now the floppy disk can be mounted like any other disk.
Or if you already have a floppy disk with an MS-DOS filesystem
on it that you just want to access from NetBSD, you can just
do something like this:

# mount -t msdos /dev/fd0a /mnt

However, rather than using floppies like normal (bigger) disks, it
is often more convenient to bypass the filesystem altogether and
just splat an archive of files directly to the raw device. E.g.:

# tar cvfz /dev/rfd0a file1 file2 ...

A variation of this can also be done with MS-DOS floppies using
the sysutils/mtools package which
has the benefit of not going through the kernel buffer cache
and thus not being exposed to the danger of the floppy being
removed while a filesystem is mounted on it.

13.2. How to use a ZIP disk

Seems it has one, and it's recognized as sd0,
just like any SCSI disk.
The fact that the ZIP here is an ATAPI one doesn't
matter - a SCSI ZIP
will show up here, too. The ZIP is marked as "removable",
which means
you can eject it with:

13.3. Reading data CDs with NetBSD

Data CDs can contain anything from programs, sound files (MP3, wav),
movies (MP3, QuickTime) to source code, text files, etc. Before
accessing these files, a CD must be mounted on a directory, much like
hard disks are. Just as hard disks can use different filesystems (ffs,
lfs, ext2fs, ...), CDs have their own filesystem, "cd9660". The
NetBSD cd9660 filesystem can handle filesystems without and with
Rockridge and Joliet extensions.

If the CD is still accessed
(e.g. some other shell's still "cd"'d
into it), this will not work. If you shut down the system, the CD
will be unmounted automatically for you, there's nothing to worry
about there.

Making an entry in /etc/fstab:

If you don't want to type the full "mount" command
each time, you
can put most of the values into a line in /etc/fstab:

The CD is not mounted at boot time due to the "noauto" mount
option - this is useful as you'll probably not have a CD in the
drive all the time. See mount(8) and
mount_cd9660(8) for some
other useful options.

Eject the CD:

#eject cd0#

If the CD is still mounted, it will be unmounted if possible,
before being ejected.

13.4. Reading multi-session CDs with NetBSD

Use mscdlabel(8) to add all sessions to the CDs
disklabel, and
then use the appropriate device node to mount the session you want.
You might have to create the corresponding device nodes in
/dev manually.
For example:

Note

The mount options nodev and
nosuid are mandatory from NetBSD 4.0 on. They are
not necessary on NetBSD 3.x systems.

Please also see mount(8) and as an alternative the
auto mount daemonamd(8), for which
example config files can be found in
/usr/share/examples/amd.

13.6. Mounting an ISO image

Sometimes, it is interesting to mount an ISO9660 image
file before you burn the CD; this way, you can examine its
contents or even copy files
to the outside. If you are a Linux user, you should know that this is
done with the special loop filesystem.
NetBSD does it another
way, using the vnode pseudo-disk.

We will illustrate how to do this with an example.
Suppose you have an
ISO image in your home directory, called "mycd.iso":

Start by setting up a new vnode, "pointing" to
the ISO file:

#vnconfig -c vnd0 ~/mycd.iso

Now, mount the vnode:

#mount -t cd9660 /dev/vnd0a /mnt

Yeah, image contents appear under /mnt!
Go to that
directory and explore the image.

When you are happy, you have to umount the image:

#umount /mnt

And at last, deconfigure the vnode:

#vnconfig -u vnd0

Note that these steps can also be used for any kind of file that
contains a filesystem, not just ISO images.

This usually works well on both SCSI and IDE (ATAPI)
CDROMs, CDRW and DVD drives.

To read ("rip") audio tracks in binary form
without going through digital->analog conversion and back.
There are several programs available to do this:

For most ATAPI, SCSI and several proprietary
CDROM drives, the
audio/cdparanoia package can be
used. With cdparanoia the data can be saved to a file or
directed to standard output in WAV, AIFF, AIFF-C or raw
format. Currently the -g option is required by the NetBSD
version of cdparanoia. A hypothetical example of how to save
track 2 as a WAV file is as follows:

$cdparanoia -g /dev/rcd0d 2 track-02.wav

If you want to grab all files from a CD,
cdparanoia's batch mode
is useful:

$cdparanoia -g /dev/rcd0d -B

For ATAPI or SCSI CD-ROMs the
audio/cdd package can be
used. To extract track 2 with cdd, type:

#cdd -t 2 `pwd`

This will put a file called
track-02.cda
in the current directory.

For SCSI CD-ROMS the
audio/tosha package can be used.
To extract track 2 with tosha, you should be able to type:

13.10. Using a CD-R writer with data CDs

The process of writing a CD consists of two steps: First,
a "image" of
the data must be generated, which can then be written to CD-R in a
second step.

Reading an pre-existing ISO image

#dd if=/dev/rcd0a of=filename.iso bs=2k#

Alternatively, you can create a new ISO image yourself:

Generating the ISO image

Put all the data you want to put on CD into one directory. Next
you need to generate a disk-like ISO image of your data. The
image stores the data in the same form as they're later put on
CD, using the ISO 9660 format. The basic ISO9660 format only
understands 8+3 filenames (max. eight letters for filename, plus
three more for an extension). As this is not practical for Unix
filenames, a so-called "Rockridge Extension" needs to be employed
to get longer filenames. (A different set of such extension
exists in the Microsoft world, to get their long filenames right;
that's what's known as Joliet filesystem).

The ISO image is created using the mkisofs command,
which is part
of the sysutils/cdrtools
package.

Example: if you have your data in /usr/tmp/data, you can generate
a ISO image file in /usr/tmp/data.iso with the following
command:

Please see the mkisofs(8) man page for other options like noting
publisher and preparer. The
Bootable CD ROM How-To
explains how to
generate a bootable CD.

Writing the ISO image to CD-R

When you have the ISO image file,
you just need to write it on a
CD. This is done with the "cdrecord" command from the
sysutils/cdrtools package.
Insert a blank CD-R, and off we go:

#cdrecord -v dev=/dev/rcd0d data.iso
...
#

After starting the command, 'cdrecord' shows you a lot of
information about your drive, the disk and the image you're about
to write. It then does a 10 seconds countdown, which is your last
chance to stop things - type ^C if you want to abort.
If you don't abort, the process will write the whole image to the
CD and return with a shell prompt.

13.11. Using a CD-R writer to create audio CDs

If you want to make a backup copy of one of your audio CDs,
you can do
so by extracting ("ripping") the audio tracks from the CD, and then
writing them back to a blank CD. Of course this also works fine if you
only extract single tracks from various CDs,
creating your very own mix CD!

13.12. Creating an audio CD from MP3s

If you have converted all your audio CDs to MP3 and now want to make
a mixed CD for your (e.g.) your car, you can do so by first converting
the .mp3 files back to .wav format, then write them as a normal audio
CD.

The steps involved here are:

Create .wav files from your .mp3 files:

$mpg123 -w foo.wav foo.mp3

Do this for all of the MP3 files that you want to have on your
audio CD. The .wav filenames you use don't matter.

13.14. Copying a data CD with two drives

If you have both a CD-R and a CD-ROM drive in your machine,
you can copy a data CD with the following command:

#cdrecord dev=/dev/rcd1d /dev/rcd0d

Here the CD-ROM (cd0) contains the CD you want to copy, and the CD-R
(cd1) contains the blank disk. Note that this only works with computer
disks that contain some sort of data, it does
not work with
audio CDs! In practice you'll also want to add something like
"speed=8" to make things a bit
faster.

13.15. Using CD-RW rewritables

If you want to blank a CD-RW, you can do this with cdrecord's
"blank" option:

#cdrecord dev=/dev/rcd0d blank=fast

There are several other ways to blank the CD-RW,
call cdrecord(8) with
"blank=help" for a list. See the cdrecord(8)
man page for more information.

13.16. DVD support

Currently, NetBSD supports DVD media through the ISO 9660
also used for CD-ROMs. The new UDF filesystem also present on DVDs
has been supported since NetBSD 4.0. Information about mounting ISO 9660
and UDF filesystems can be found in the mount_cd9660(8) and
mount_udf(8) manual pages respectively.
DVDs, DivX and many avi files be played with multimedia/ogle
or multimedia/gmplayer.

The cgd driver provides functionality
which allows you to use disks or partitions for encrypted storage.
After providing the appropriate key, the encrypted partition is
accessible using cgd pseudo-devices.

14.1. Overview

People often store sensitive information on their hard disks and
are concerned about this information falling into the wrong hands.
This is particularly relevant to users of laptops and other
portable devices, or portable media, which might be stolen or
accidentally misplaced.

14.1.1. Why use disk encryption?

File-oriented encryption tools like
GnuPG are great for encrypting
individual files, which can then be sent across untrusted
networks as well as stored encrypted on disk. But sometimes
they can be inconvenient, because the file must be decrypted
each time it is to be used; this is especially cumbersome when
you have a large collection of files to protect. Any time a
security tool is cumbersome to use, there's a chance you'll
forget to use it properly, leaving the files unprotected for
the sake of convenience.

Worse, readable copies of the encrypted contents might still exist
on the hard disk. Even if you overwrite these files (using
rm -P) before unlinking them, your application
software might make temporary copies you don't know about, or have
been paged to swapspace - and even your hard disk might have
silently remapped failing sectors with data still in them.

The solution is to simply never write the information unencrypted
to the hard disk. Rather than taking a file-oriented approach to
encryption, consider a block-oriented approach - a virtual hard
disk, that looks just like a normal hard disk with normal
filesystems, but which encrypts and decrypts each block on the way
to and from the real disk.

14.1.2. Logical Disk Drivers

The cgd device looks and behaves to the rest of
the operating system like any other disk driver. Rather than
driving real hardware directly, it provides a logical function
layered on top of another block device. It has a special
configuration program, cgdconfig, to create and
configure a cgd device and point it at the
underlying disk device that will hold the encrypted data.

NetBSD includes several other similar logical block devices, each
of which provides some other function where cgd
provides encryption. You can stack several of these logical block
devices together:
you can make an encrypted
raid to protect your encrypted data against
hard disk failure as well.

Once you have created a cgd disk, you can
use disklabel to divide it up into
partitions, swapctl to enable swapping to
those partitions or newfs to make
filesystems, then mount and use those
filesystems, just like any other new disk.

14.1.3. Availability

The cgd driver was written by Roland
C. Dowdeswell, and introduced in the NetBSD 2.0 release.

14.2. Components of the Crypto-Graphic Disk system

A number of components and tools work together to make the
cgd system effective.

14.2.1. Kernel driver pseudo-device

To use cgd you need a kernel with support
for the cgd pseudo-device. Make sure the
following line is in the kernel configuration file:

pseudo-device cgd 4 # cryptographic disk driver

The number specifies how many cgd
devices may be configured at the same time. After configuring
the cgd pseudo-device you can recompile
the kernel and boot it to enable cgd
support.

All three ciphers are used in CBC mode. This means each block
is XORed with the previous encrypted block before
encryption. This reduces the risk that a pattern can be found,
which can be used to break the encryption.

14.2.3. Verification Methods

Another aspect of cgd that needs some
attention are the verification methods
cgdconfig provides. These verification
methods are used to verify the passphrase is correct. The
following verification methods are available:

Verification Methods

none

no verification is performed. This can be dangerous,
because the key is not verified at all. When a wrong key
is entered cgdconfig configures the
cgd device as normal, but data
which was available on the volume will be destroyed
(decrypting blocks with a wrong key will result in
random data, which will result in a regeneration of the
disklabel with the current key).

disklabel

cgdconfig scans for a valid
disklabel. If a valid disklabel is found with the key
that is provided authentication will succeed.

ffs

cgdconfig scans for a valid FFS file
system. If a valid FFS file system is found with the key
that is provided authentication will succeed.

14.3. Example: encrypting your disk

This section works through a step-by-step example of converting
an existing system to use cgd,
performing the following actions:

Preparing the disk and partitions

Scrub off all data

Create the cgd

Adjust config-files

Restoring your backed-up files to the encrypted disk

14.3.1. Preparing the disk

First, decide which filesystems you want to move to an encrypted
device. You're going to need to leave at least the small root
(/) filesystem unencrypted, in order to load
the kernel and run init,
cgdconfig and the rc.d
scripts that configure your cgd. In this
example, we'll encrypt everything except the root
(/) filesystem.

We are going to delete and re-make partitions and filesystems,
and will require a backup to restore the data. So make sure
you have a current, reliable backup stored on a different disk
or machine. Do your backup in single-user mode, with the
filesystems unmounted, to ensure you get a clean
dump. Make sure you back up the disklabel
of your hard disk as well, so you have a record of the
partition layout before you started.

With the system at single user, / mounted
read-write and everything else unmounted, use
disklabel to delete all the data partitions
you want to move into cgd.

Then make a single new partition in all the space you just
freed up, say, wd0e. Set the
partition type for this partition to cgd
Though it doesn't really matter what it is, it will help remind
you that it's not a normal filesystem later. When finished,
label the disk to save the new partition table.

14.3.2. Scrubbing the disk

We have removed the partition table information, but the
existing filesystems and data are still on disk. Even after
we make a cgd device, create filesystems,
and restore our data, some of these disk blocks might not yet
be overwritten and still contain our data in plaintext. This
is especially likely if the filesystems are mostly empty. We
want to scrub the disk before we go further.

We could use dd to copy
/dev/zero over the new
wd0e partition, but this will leave
our disk full of zeros, except where we've written encrypted
data later. We might not want to give an attacker any clues
about which blocks contain real data, and which are free
space, so we want to write "noise" into all the disk
blocks. So we'll create a temporary cgd,
configured with a random, unknown key.

First, we configure a cgd to use a random key:

#cgdconfig -s cgd0 /dev/wd0e aes-cbc 128 < /dev/urandom

Now we can write zeros into the raw partition of our
cgd (/dev/rcgd0d on
NetBSD/i386, /dev/rcgd0c on most other
platforms):

#dd if=/dev/zero of=/dev/rcgd0d bs=32k

The encrypted zeros will look like random data on disk. This might
take a while if you have a large disk. Once finished, unconfigure the
random-key cgd:

#cgdconfig -u cgd0

14.3.3. Creating the cgd

The cgdconfig program, which manipulates
cgd devices, uses parameters files to store
such information as the encryption type, key length, and a
random password salt for each cgd. These
files are very important, and need to be kept safe - without
them, you will not be able to decrypt the data!

We'll generate a parameters file and write it into the default
location (make sure the directory
/etc/cgd exists and is mode 700):

#cgdconfig -g -V disklabel -o /etc/cgd/wd0e aes-cbc 256

This creates a parameters file
/etc/cgd/wd0e describing a
cgd using the
aes-cbc cipher method, a key
verification method of disklabel,
and a key length of 256
bits. It will look something like this:

Note

Remember, you'll want to save this file somewhere safe
later.

Tip

When creating the parameters file,
cgdconfig reads from
/dev/random to create the password
salt. This read may block if there is not enough collected
entropy in the random pool. This is unlikely, especially if
you just finished overwriting the disk as in the previous
step, but if it happens you can press keys on the console
and/or move your mouse until the
rnd device gathers enough
entropy.

Now it's time to create our cgd, for which
we'll need a passphrase. This passphrase needs to be entered
every time the cgd is opened, which is
usually at each reboot. The encryption key is derived from this
passphrase and the salt. Make sure you choose something you won't
forget, and others won't guess.

The first time we configure the cgd, there
is no valid disklabel on the logical device, so the validation
mechanism we want to use later won't work. We override it this
one time:

#cgdconfig -V re-enter cgd0 /dev/wd0e

This will prompt twice for a matching passphrase, just in case
you make a typo, which would otherwise leave you with a
cgd encrypted with a passphrase that's
different to what you expected.

Now that we have a new cgd, we need to
partition it and create filesystems. Recreate your previous
partitions with all the same sizes, with the same letter
names.

Tip

Remember to use the disklabel -I
argument, because you're creating an initial label for a new
disk.

Note

Although you want the sizes of your new partitions to be
the same as the old, unencrypted ones, the offsets will be
different because they're starting at the beginning of this
virtual disk.

Then, use newfs to create filesystems on
all the relevant partitions. This time your partitions will
reflect the cgd disk names, for example:

#newfs /dev/rcgd0h

14.3.4. Modifying configuration files

We've moved several filesystems to another (logical) disk, and
we need to update /etc/fstab
accordingly. Each partition will have the same letter (in this
example), but will be on cgd0 rather than
wd0. So you'll have
/etc/fstab entries something like this:

Note

/tmp should be a separate filesystem,
either mfs or ffs,
inside the cgd, so that your temporary
files are not stored in plain text in the
/ filesystem.

Each time you reboot, you're going to need your
cgd configured early, before
fsck runs and filesystems are mounted.

Put the following line in
/etc/cgd/cgd.conf:

cgd0 /dev/wd0e

This will use /etc/cgd/wd0e as config
file for cgd0.

To finally enable cgd on each boot, put the following line
into /etc/rc.conf:

cgd=YES

You should now be prompted for
/dev/cgd0's passphrase whenever
/etc/rc starts.

14.3.5. Restoring data

Next, mount your new filesystems, and
restore your data into them. It often helps
to have /tmp mounted properly first, as
restore can use a fair amount of temporary
space when extracting a large dumpfile.

To test your changes to the boot configuration,
umount the filesystems and unconfigure the
cgd, so when you exit the single-user
shell, rc will run like on a clean boot,
prompting you for the passphrase and mounting your filesystems
correctly. Now you can bring the system up to multi-user, and
make sure everything works as before.

14.4. Example: encrypted CDs/DVDs

14.4.1. Introduction

This section explains how to create and use encrypted CDs/DVDs
with NetBSD (all I say about "CDs" here does also apply to
"DVDs"). I assume that you have basic knowledge of cgd(4), so
I will not explain what cgd is or what's inside it in
detail. The same applies to vnd(4). One can make use of
encrypted CDs after reading this howto, but for more detailed
information about different cgd configuration options, please
read Chapter 14, The cryptographic device driver (CGD) or the manpages.

14.4.2. Creating an encrypted CD/DVD

cgd(4) provides highly secure encryption of whole partitions
or disks. Unfortunately, creating "normal" CDs is not
disklabeling something and running newfs on it. Neither can you
just put a CDR into the drive, configure cgd and assume it to
write encrypted data when syncing. Standard CDs contain at
least an ISO-9660 filesystem created with mkisofs(8) from the
sysutils/cdrtools package.
ISO images may not contain disklabels or
cgd partitions.

But of course CD reader/writer hardware doesn't care about
filesystems at all. You can write raw data to the CD if you
like - or an encrypted FFS filesystem, which is what we'll do
here. But be warned, there is NO way to read this CD with any
OS except NetBSD - not even other BSDs due to the lack of cgd.

The basic steps when creating an encrypted CD are:

Create an (empty) imagefile

Register it as a virtual disk using vnd(4)

Configure cgd inside the vnd disk

Copy content to the cgd

Unconfigure all (flush!)

Write the image on a CD

The first step when creating an encrypted CD is to create a
single image file with dd. The image may not grow, so make it
large enough to allow all CD content to fit into. Note that
the whole image gets written to the CD later, so creating a
700 MB image for 100 MB content will still require a 700 MB
write operation to the CD. Some info on DVDs here: DVDs are
only 4.7 GB in marketing language. 4.7GB = 4.7 x 1024 x 1024 x
1024 = 5046586573 bytes. In fact, a DVD can only
approximately hold 4.7 x 1000 x 1000 x 1000 = 4700000000
bytes, which is about 4482 MB or about 4.37 GB. Keep this in
mind when creating DVD images. Don't worry for CDs, they hold
"real" 700 MB (734003200 Bytes).

In order to use cgd, a so-called parameter file, describing
encryption parameters and a containing "password salt" must be
generated. We'll call it /etc/cgd/image
here. You can use one parameter file for several encrypted
partitions (I use one different file for each host and a
shared file image for all removable
media, but that's up to you).

I'll use AES-CBC with a keylength of 256 bits. Refer to
cgd(4) and cgdconfig(8) for details and alternatives.

The following command will create the parameter file as
/etc/cgd/image. YOU DO NOT WANT
TO INVOKE THE FOLLOWING COMMAND AGAIN after you
burnt any CD, since a recreated parameter file is a lost
parameter file and you'll never access your encrypted CD again
(the "salt" this file contains will differ among each
call). Consider this file being HOLY, BACKUP
IT and BACKUP IT AGAIN! Use
switch -V to specify verification method "disklabel" for the CD
(cgd cannot detect whether you entered a valid password for the
CD later when mounting it otherwise).

#cgdconfig -g -V disklabel aes-cbc 256 > /etc/cgd/image

Now it's time to configure a cgd for our vnd drive. (Replace
slice "d" with "c" for all platforms that use "c" as the whole
disk (where "sysctl kern.rawpartition"
prints "2", not "3"); if you're on i386 or amd64, "d" is OK
for you):

#cgdconfig -V re-enter cgd1 /dev/vnd0d /etc/cgd/image

The "-V re-enter" option is necessary
as long as the
cgd doesn't have a disklabel yet so we can access and
configure
it. This switch asks for a password twice and uses it for
encryption.

Now it's time to create a disklabel inside the cgd. The
defaults of the label are ok, so invoking disklabel with

#disklabel -e -I cgd1

and leaving vi with ":wq"
immediately will do.

Let's create a filesystem on the cgd, and finally mount it
somewhere:

#newfs /dev/rcgd1a#mount /dev/cgd1a /mnt

The cgd is alive! Now fill /mnt with
content. When finished, reverse the configuration process. The
steps are:

Unmounting the cgd1a:

#umount /mnt

Unconfiguring the cgd:

#cgdconfig -u cgd1

Unconfiguring the vnd:

#vnconfig -u vnd0

The following commands are examples to burn the images on CD
or DVD. Please adjust the dev= for
cdrecord or the /dev/rcd0d for
growisofs. Note the
"rcd0d"
is necessary with NetBSD. Growisofs is
available in the sysutils/dvd+rw-tools
package. Again, use "c" instead of
"d" if this is the raw partition on your
platform.

Finally, write the image file to a CD:

#cdrecord dev=/dev/rcd0d -v image.img

...or to a DVD:

#growisofs -dvd-compat -Z /dev/rcd0d=image.img

Congratulations! You've just created a really secure CD!

14.4.3. Using an encrypted CD/DVD

After creating an encrypted CD as described above, we're not
done yet - what about mounting it again? One might guess,
configuring the cgd on /dev/cd0d is
enough - no, it is not.

NetBSD cannot access FFS file systems on media that is not 512
bytes/sector format. It doesn't matter that the cgd on the CD
is, since the CD's disklabel the cgd resides in has 2048
bytes/sector.

But the CD driver cd(4) is smart enough to grant "write"
access to the (emulated) disklabel on the CD. So before
configuring the cgd, let's have a look at the disklabel and
modify it a bit:

If you don't want to do these changes every time by hand, you
can use Florian Stoehr's tool neb-cd512 which is (at time of writing
this) in pkgsrc-wip and will move to
sysutils/neb-cd512 soon.
You can also download the neb-cd512 source from
http://sourceforge.net/projects/neb-stoehr/ (be sure
to use neb-cd512, not neb-wipe!).

It is invoked with the disk name as parameter, by root:

#neb-cd512 cd0

Now as the disklabel is in 512 b/s format, accessing the CD
is as easy as:

#cgdconfig cgd1 /dev/cd0d /etc/cgd/image#mount -o ro /dev/cgd1a /mnt

Note that the cgd MUST be mounted read-only
or you'll get illegal command errors from the cd(4) driver which
can in some cases make even mounting a CD-based cgd impossible!

Now we're done! Enjoy your secure CD!

#ls /mnt

Remember you have to reverse all steps to remove the CD:

#umount /mnt#cgdconfig -u cgd1#eject cd0

14.5. Suggestions and Warnings

You now have your filesystems encrypted within a
cgd. When your machine is shut down, the data
is protected, and can't be decrypted without the passphrase.
However, there are still some dangers you should be aware of,
and more you can do with cgd. This section
documents several further suggestions and warnings that will
help you use cgd effectively.

Use multiple cgd's for different kinds of
data, one mounted all the time and others mounted only when
needed.

Use a cgd configured on top of a
vnd made from a file on a remote network
fileserver (NFS, SMBFS, CODA, etc) to safely store private data
on a shared system. This is similar to the procedure for
using encrypted CDs and DVDs described in Section 14.4, “Example: encrypted CDs/DVDs”.

14.5.1. Using a random-key cgd for swap

You may want to use a dedicated random-key
cgd for swap space, regenerating the key
each reboot. The advantage of this is that once your machine
is rebooted, any sensitive program memory contents that may
have been paged out are permanently unrecoverable, because the
decryption key is never known to you.

We created a temporary cgd with a random
key when scrubbing the disk in the example above, using a
shorthand cgdconfig -s invocation to avoid
creating a parameters file.

The cgdconfig params file includes a
“randomkey” keygen method. This is more
appropriate for "permanent" random-key configurations, and
facilitates the easy automatic configuration of these volumes
at boot time.

For example, if you wanted to convert your existing
/dev/wd0b partition to a dedicated
random-key cgd1, use the following command to generate
/etc/cgd/wd0b:

#cgdconfig -g -o /etc/cgd/wd0b -V none -k randomkey blowfish-cbc

When using the randomkey keygen method, only verification
method "none" can be used, because the contents of the new
cgd are effectively random each time (the
previous data decrypted with a random key). Likewise, the new
disk will not have a valid label or partitions, and
swapctl will complain about configuring
swap devices not marked as such in a disklabel.

In order to automate the process of labeling the disk,
prepare an appropriate disklabel and save it to a file, for
example /etc/cgd/wd0b.disklabel. Please
refer to disklabel(8) for information about
how to use disklabel to set up a swap
partition.

On each reboot, to restore this saved label to the new
cgd, create the
/etc/rc.conf.d/cgd file as below:

The same technique could be extended to encompass using
newfs to re-create an
ffs filesystem for
/tmp if you didn't want to use
mfs.

14.5.2. Warnings

Prevent cryptographic disasters by making sure you can always
recover your passphrase and parameters file. Protect the
parameters file from disclosure, perhaps by storing it on
removable media as above, because the salt it contains helps
protect against dictionary attacks on the passphrase.

Keeping the data encrypted on your disk is all very well, but
what about other copies? You already have at least one other
such copy (the backup we used during this setup), and it's not
encrypted. Piping dump through file-based
encryption tools like gpg can be one way of
addressing this issue, but make sure you have all the keys and
tools you need to decrypt it to restore
after a disaster.

Like any form of software encryption, the
cgd key stays in kernel memory while the
device is configured, and may be accessible to privileged
programs and users, such as /dev/kmem
grovellers. Taking other system security steps, such as
running with elevated securelevel, is highly recommended.

Once the cgd volumes are mounted as normal
filesystems, their contents are accessible like any other
file. Take care of file permissions and ensure your running
system is protected against application and network security
attack.

Avoid using suspend/resume, especially for laptops with a BIOS
suspend-to-disk function. If an attacker can resume your
laptop with the key still in memory, or read it from the
suspend-to-disk memory image on the hard disk later, the whole
point of using cgd is lost.

The CCD driver allows the user to
“concatenate” several physical disks into one pseudo
volume. While RAIDframe (see Chapter 16, NetBSD RAIDframe) also allows
doing this to create RAID level 0 sets, it does not allow you
to do striping across disks of different geometry, which is where
CCD comes in handy. CCD also allows for an
“interleave” to improve disk performance with a
gained space loss. This example will not cover that
feature.

The steps required to setup a CCD are as follows:

Install physical media

Configure kernel support

Disklabel each volume member of the CCD

Configure the CCD conf file

Initialize the CCD device

Create a filesystem on the new CCD device

Mount the CCD filesystem

This example features a CCD setup on NetBSD/sparc 1.5.
The CCD will reside on 4 SCSI disks in a generic external Sun
disk pack chassis connected to the external 50 pin SCSI port.

15.1. Install physical media

This step is at your own discretion, depending on your platform and the
hardware at your disposal.

If your port uses a MBR (Master Boot Record) to partition the disks
so that the NetBSD partitions are only part of the overall disk,
and other OSs like Windows or Linux use other parts, you can void the
MBR and all partitions on disk by using the command:

This will make all data on the entire disk inaccessible. Note
that the entire disk is slice d on i386
(and some other ports), and c elsewhere (e.g. on
sparc). See the “kern.rawpartition” sysctl - "3"
means "d", "2" means "c".

You will need to create one “slice” on the
NetBSD partition of the disk that consumes the entire
partition. The slice must begin at least one cylinder
offset from the beginning of the disk/partition to provide
space for the special CCD disklabel. The offset should be
1x sectors/cylinder (see following note).
Therefore, the “size” value should be
“total sectors” minus 1x
“sectors/cylinder”. Edit your disklabel
accordingly:

#disklabel -e sd0

Note

The offset of a slice of type “ccd” must be a
multiple of the “sectors/cylinder” value.

Note

Be sure to export EDITOR=[path to your favorite
editor] before editing the disklabels.

Note

The slice must be fstype ccd.

Because there will only be one slice on this partition,
you can recycle the c slice (normally
reserved for symbolic uses). Change your disklabel to
the following:

16.1. RAIDframe Introduction

16.1.1. About RAIDframe

NetBSD uses the CMU RAIDframe
software for its RAID subsystem. NetBSD is the primary
platform for RAIDframe development. RAIDframe can also be
found in OpenBSD and older
versions of FreeBSD. NetBSD
also has another in-kernel RAID level 0 system in its
ccd(4) subsystem (see
Chapter 15, Concatenated Disk Device (CCD) configuration). You
should possess some basic knowledge
about RAID concepts and terminology before continuing. You
should also be at least familiar with the different levels of
RAID - Adaptec provides an
excellent reference, and the raid(4) manpage
contains a short overview too.

16.1.2. A warning about Data Integrity, Backups, and High
Availability

RAIDframe is a Software RAID implementation,
as opposed to Hardware RAID. As such, it does not need special disk
controllers supported by NetBSD. System
administrators should give a
great deal of consideration to whether software RAID or
hardware RAID is more appropriate for their
“Mission Critical” applications. For some projects
you might consider the use of many of the hardware RAID devices
supported by
NetBSD. It is truly at your discretion what type of RAID
you use, but it is recommend that you consider factors such as:
manageability, commercial vendor support, load-balancing and
failover, etc.

Depending on the RAID level used, RAIDframe does provide
redundancy in the event of a hardware failure. However, it is
not a replacement for reliable backups!
Software and user-error can still cause data loss. RAIDframe
may be used as a mechanism for facilitating backups in systems
without backup hardware, but this is not an ideal
configuration. Finally, with regard to "high availability",
RAID is only a very small component to ensuring data
availability.

Once more for good measure: Back up your
data!

16.1.3. Getting Help

If you encounter problems using RAIDframe, you have several
options for obtaining help.

Search the mailing list archives. Unfortunately,
there is no NetBSD list dedicated to RAIDframe support.
Depending on the nature of the problem, posts tend to end up in
a variety of lists. At a very minimum, search netbsd-help,
netbsd-users@NetBSD.org,
current-users@NetBSD.org.
Also search the list for the NetBSD platform on which you are
using RAIDframe:
port-${ARCH}@NetBSD.org.

Caution

Because RAIDframe is constantly undergoing
development, some information in mailing list archives has the
potential of being dated and inaccurate.

If your problem persists: Post to the mailing list
most appropriate (judgment call). Collect as much verbosely
detailed information as possible before posting: Include your
dmesg(8) output from
/var/run/dmesg.boot, your kernel config(5) , your
/etc/raid[0-9].conf, any relevant errors on
/dev/console,
/var/log/messages, or to
stdout/stderr of raidctl(8).
The output of raidctl -s (if available)
will be useful as well. Also
include details on the troubleshooting steps you've taken thus
far, exactly when the problem started, and any notes on recent
changes that may have prompted the problem to develop. Remember
to be patient when waiting for a response.

16.2. Setup RAIDframe Support

The use of RAID will require software and hardware
configuration changes.

16.2.1. Kernel Support

The GENERIC kernel already has support for RAIDframe. If you have
built a custom kernel for your environment the kernel
configuration must have the following options:

The RAID support must be detected by the NetBSD kernel, which
can be checked by looking at the output of the dmesg(8)
command.

#dmesg|grep -i raid
Kernelized RAIDframe activated

Historically, the kernel must also contain static mappings between bus
addresses and device nodes in /dev. This
used to
ensure consistency of devices within RAID sets in the event of a
device failure after reboot. Since NetBSD 1.6, however, using
the auto-configuration features of RAIDframe has been
recommended over statically mapping devices. The
auto-configuration features allow drives to move around on the
system, and RAIDframe will automatically determine which
components belong to which RAID sets.

16.2.2. Power Redundancy and Disk Caching

If your system has an Uninterruptible Power Supply (UPS),
and/or if your system has redundant power supplies, you should
consider enabling the read and write caches on your drives. On
systems with redundant power, this will improve drive performance.
On systems without redundant power, the write cache could endanger
the integrity of RAID data in the event of a power loss.

The dkctl(8) utility to can be used for this on
all kinds of disks that support the operation (SCSI, EIDE, SATA,
...):

16.3. Example: RAID-1 Root Disk

This example explains how to setup RAID-1 root disk. With
RAID-1 components are mirrored and therefore the server can be fully
functional in the event of a single component failure. The goal is
to provide a level of redundancy that will allow the system to
encounter a component failure on either component disk in the RAID
and:

Continue normal operations until a maintenance
window can be scheduled.

Or, in the unlikely event that the component
failure causes a system reboot, be able to quickly reconfigure the
system to boot from the remaining component (platform dependent).

Figure 16.1. RAID-1 Disk Logical Layout

Because RAID-1 provides both redundancy and performance
improvements, its most practical application is on critical
"system" partitions such as /,
/usr, /var,
swap, etc., where read operations are more
frequent than write operations. For other file systems, such as
/home or
/var/{application},
other RAID levels might be considered (see the references above).
If one were simply creating a generic RAID-1 volume for a non-root
file system, the cookie-cutter examples from the man page could be
followed, but because the root volume must be bootable, certain
special steps must be taken during initial setup.

Note

This example will outline a process that differs only
slightly between the x86 and sparc64 platforms. In an attempt to
reduce excessive duplication of content, where differences do exist
and are cosmetic in nature, they will be pointed out using a section
such as this. If the process is drastically different, the process
will branch into separate, platform dependent steps.

16.3.1. Pseudo-Process Outline

Although a much more refined process could be developed
using a custom copy of NetBSD installed on custom-developed
removable media, presently the NetBSD install media lacks
RAIDframe tools and support, so the following pseudo process has
become the de facto standard for setting up RAID-1 Root.

Install a stock NetBSD onto Disk0 of your system.

Figure 16.2. Perform generic install onto Disk0/wd0

Use the installed system on Disk0/wd0 to setup
a RAID Set composed of Disk1/wd1 only.

Figure 16.3. Setup RAID Set

Reboot the system off the Disk1/wd1 with the newly
created RAID volume.

Figure 16.4. Reboot using Disk1/wd1 of RAID

Add / re-sync Disk0/wd0 back into the RAID set.

Figure 16.5. Mirror Disk1/wd1 back to Disk0/wd0

16.3.2. Hardware Review

At present, the alpha, amd64, i386, pmax, sparc, sparc64, and
vax NetBSD platforms support booting from RAID-1. Booting is not
supported from any other RAID level. Booting from a RAID set is
accomplished by teaching the 1st stage boot loader to understand
both 4.2BSD/FFS and RAID partitions. The 1st boot block code only
needs to know enough about the disk partitions and file systems to
be able to read the 2nd stage boot blocks. Therefore, at any
time, the system's BIOS / firmware must be able to read a drive
with 1st stage boot blocks installed. On the x86 platform,
configuring this is entirely dependent on the vendor of the
controller card / host bus adapter to which your disks are
connected. On sparc64 this is controlled by the IEEE 1275 Sun
OpenBoot Firmware.

This article assumes two identical
IDE disks (/dev/wd{0,1})
which we are going to mirror (RAID-1). These disks are identified
as:

Note

If you are using SCSI, replace
/dev/{,r}wd{0,1} with
/dev/{,r}sd{0,1}

In this example, both disks are jumpered as Master on
separate channels on the same controller. You would never want to
have both disks on the same bus on the same controller; this
creates a single point of failure. Ideally you would have the
disks on separate channels on separate controllers. Some SCSI
controllers have multiple channels on the same controller,
however, a SCSI bus reset on one channel could adversely affect
the other channel if the ASIC/IC becomes overloaded. The
trade-off with two controllers is that twice the bandwidth is used
on the system bus. For purposes of simplification, this example
shows two disks on different channels on the same
controller.

Note

RAIDframe requires that all components be of the same
size. Actually, it will use the lowest common denominator among
components of dissimilar sizes. For purposes of illustration, the
example uses two disks of identical geometries. Also, consider
the availability of replacement disks if a component suffers a
critical hardware failure.

Tip

Two disks of identical vendor model numbers could have
different geometries if the drive possesses "grown defects". Use
a low-level program to examine the grown defects table of the
disk. These disks are obviously suboptimal candidates for use in
RAID and should be avoided.

16.3.3. Initial Install on Disk0/wd0

Perform a very generic installation onto your Disk0/wd0.
Follow the INSTALL instructions for your platform. Install all
the sets but do not bother customizing anything other than the
kernel as it will be overwritten.

Tip

On x86, during the sysinst install, when prompted if
you want to "use the entire disk for NetBSD", answer
"yes".

16.3.4. Preparing Disk1/wd1

Once you have a stock install of NetBSD on Disk0/wd0, you
are ready to begin. Disk1/wd1 will be visible and unused by the
system. To setup Disk1/wd1, you will use disklabel(8) to
allocate the entire second disk to the RAID-1 set.

Tip

The best way to ensure that Disk1/wd1 is completely
empty is to 'zero' out the first few sectors of the disk with
dd(1) . This will erase the MBR (x86) or Sun disk label
(sparc64), as well as the NetBSD disk label. If you make a mistake
at any point during the RAID setup process, you can always refer
to this process to restore the disk to an empty state.

Now that you are certain the second disk is empty, on x86
you must establish the MBR on the second disk using the values
obtained from Disk0/wd0 above. We must remember to mark the NetBSD
partition active or the system will not boot. You must also create
a NetBSD disklabel on Disk1/wd1 that will enable a RAID volume to
exist upon it. On sparc64, you will need to simply
disklabel(8) the second disk which will write the proper Sun
Disk Label.

Tip

disklabel(8) will use your shell' s environment
variable $EDITOR variable to edit the
disklabel. The default is vi(1)

Note

On x86, the c: and
d: slices are reserved. c:
represents the NetBSD portion of the disk. d:
represents the entire disk. Because we want to allocate the
entire NetBSD MBR partition to RAID, and because
a: resides within the bounds of
c:, the a: and
c: slices have same size and offset values.
The offset must start at a track boundary (an increment of
sectors matching the sectors/track value in the disk label). On
sparc64 however, c: represents the entire
NetBSD partition in the Sun disk label and d:
is not reserved. Also note that sparc64's c:
and a: require no offset from the beginning of
the disk, however if they should need to be, the offset must start
at a cylinder boundary (an increment of sectors matching the
sectors/cylinder value).

16.3.5. Initializing the RAID Device

Next we create the configuration file for the RAID set /
volume. Traditionally, RAIDframe configuration files belong in
/etc and would be read and initialized at
boot time, however, because we are creating a bootable RAID
volume, the configuration data will actually be written into the
RAID volume using the "auto-configure" feature. Therefore, files
are needed only during the initial setup and should not reside in
/etc.

Note that absent means a non-existing disk.
This will allow us to establish the RAID volume with a bogus
component that we will substitute for Disk0/wd0 at a later
time.

Next we configure the RAID device and initialize the serial
number to something unique. In this example we use a
"YYYYMMDDRevision" scheme. The format
you choose is entirely at your discretion, however the scheme you
choose should ensure that no two RAID sets use the same serial
number at the same time.

After that we initialize the RAID set for the first time,
safely ignoring the errors regarding the bogus component.

16.3.6. Setting up Filesystems

Caution

The root filesystem must begin at sector 0 of the RAID
device. Else, the primary boot loader will be unable to find
the secondary boot loader.

The RAID device is now configured and available. The RAID
device is a pseudo disk-device. It will be created with a default
disk label. You must now determine the proper sizes for disklabel
slices for your production environment. For purposes of
simplification in this example, our system will have 8.5 gigabytes
dedicated to / as
/dev/raid0a and the rest allocated to
swap as
/dev/raid0b.

Caution

Note

Note that 1 GB is 2*1024*1024=2097152 blocks (1 block
is 512 bytes, or 0.5 kilobytes). Despite what the
underlying hardware composing a RAID set is, the RAID pseudo disk
will always have 512 bytes/sector.

Note

In our example, the space allocated to the underlying
a: slice composing the RAID set differed
between x86 and sparc64, therefore the total sectors of the RAID
volumes differs:

The NetBSD install now exists on the RAID filesystem. We need
to fix the mount-points in the new copy of
/etc/fstab or the system will not come up
correctly. Replace instances of wd0 with
raid0.

The swap should be unconfigured upon shutdown to avoid
parity errors on the RAID device. This can be done with a simple,
one-line setting in /etc/rc.conf.

#vi /mnt/etc/rc.conf
swapoff=YES

Next the boot loader must be installed on Disk1/wd1.
Failure to install the loader on Disk1/wd1 will render the system
un-bootable if Disk0/wd0 fails making the RAID-1 pointless.

Tip

Because the BIOS/CMOS menus in many x86 based systems
are misleading with regard to device boot order. I highly
recommend utilizing the "-o timeout=X" option supported by the
x86 1st stage boot loader. Setup unique values for each disk as
a point of reference so that you can easily determine from which
disk the system is booting.

Caution

Although it may seem logical to install the 1st stage boot block into
/dev/rwd1{c,d}
with installboot(8) , this is no longer the case since NetBSD 1.6.x.
If you make this mistake, the boot sector will become irrecoverably damaged
and you will need to start the process over again.

Note

As of NetBSD 6.x, the default filesystem type on x86 platforms
is FFSv2 instead of FFSv1. Make sure you use the correct 1st stage boot block file
/usr/mdec/bootxx_ffsv{1,2}
when running the installboot(8) command.

To find out which filesystem type is currently in use, the
command file(1) or dumpfs(8) can be used:

Warning

Always use shutdown(8) when shutting
down. Never simply use reboot(8). reboot(8) will
not properly run shutdown RC scripts and will not safely disable
swap. This will cause dirty parity at every
reboot.

16.3.8. The first boot with RAID

At this point, temporarily configure your system to boot
Disk1/wd1. See notes in
Section 16.3.10, “Testing Boot Blocks”
for details on this process. The system should boot now and
all filesystems should be on the RAID devices. The RAID will be
functional with a single component, however the set is not fully
functional because the bogus drive (wd9) has failed.

16.3.9. Adding Disk0/wd0 to RAID

We will now add Disk0/wd0 as a component of the RAID. This
will destroy the original file system structure. On x86, the MBR
disklabel will be unaffected (remember we copied wd0's label to
wd1 anyway) , therefore there is no need to "zero"
Disk0/wd0. However, we need to relabel Disk0/wd0 to have an
identical NetBSD disklabel layout as Disk1/wd1. Then we add
Disk0/wd0 as "hot-spare" to the RAID set and initiate the parity
reconstruction for all RAID devices, effectively bringing
Disk0/wd0 into the RAID-1 set and "synching up" both disks.

And finally, reboot the machine one last time before
proceeding. This is required to migrate Disk0/wd0 from status
"used_spare" as "Component0" to state "optimal". Refer to notes
in the next section regarding verification of clean parity after
each reboot.

#shutdown -r now

16.3.10. Testing Boot Blocks

At this point, you need to ensure that your system's
hardware can properly boot using the boot blocks on either disk.
On x86, this is a hardware-dependent process that may be done
via your motherboard CMOS/BIOS menu or your controller card's
configuration menu.

On x86, use the menu system on your machine to set the boot
device order / priority to Disk1/wd1 before Disk0/wd0. The
examples here depict a generic Award BIOS.

You can determine that the BIOS is reading Disk1/wd1 because
the timeout of the boot loader is 30 seconds instead of 15. After
the reboot, re-enter the BIOS and configure the drive boot order
back to the default:

NetBSD LVM allows logical volume management on NetBSD systems,
with a well known user interface, which is the same as the Linux
LVM2 tools.

NetBSD LVM is built on Linux lvm2tools and libdevmapper,
together with a BSD-licensed device-mapper kernel driver
specially written for NetBSD.

The LVM driver allows the user to manage
available disk space effectively and efficiently. Disk space from
several disks, and partitions, known as “Physical Volumes”, can
be added to “Volume Groups”, which is the pool of available
disk space for “Logical Partitions”aka Logical Volumes.

Logical Volumes can be grown and shrunk at will using the
LVM utilities.

The basic building block is the Physical Volume. This is a disk,
or a part of a disk, which is used to store data.

Physical Volumes are aggregated together to make Volume Groups, or
VGs. Typically, Volume Groups are used to aggregate
storage for the same functional unit. Typical Volume Groups could thus
be named “Audio”, “Multimedia” or “Documents”.
By segregating storage requirements in this functional way, the same type
of resilience and redundancy is applied to the whole of the functional
unit.

The steps required to setup a LVM are as follows:

Install physical media

Configure kernel support

Configure system, install tools

Optional step

Disklabel each volume member of the LVM

Initialize the LVM disk devices

Create a volume group from initialized disks

Create Logical volume from created Volume group

Create a filesystem on the new LV device

Mount the LV filesystem

This example features a LVM setup on NetBSD/i386.

17.1. Anatomy of NetBSD Logical Volume Manager

Figure 17.1. Anatomy of Logical Volume Management

Volume Group

The Volume Group is a disk space pool from which the user creates Logical Volumes and
to which Physical Volumes can be added. It is the basic administration unit of the NetBSD
LVM implementation.

Physical Volume

A physical volume is the basic unit in a LVM structure. Every PV consists of small
disk space chunks called Physical Extends. Every Volume Group must have at least one PV.
A PV can be created on hard disks or hard disk like devices such as raid, ccd, or cgd device.

Logical Volume

The Logical Volume is a logical partition created from disk space assigned to the Volume Group.
LV can be newfsed and mounted as any other pseudo-disk device. Lvm tools use functionality exported by
the device-mapper driver in the kernel to create the LV.

Physical Extents

Each physical volume is divided chunks of disk space. The default size is 4MB. Every LV
size is rounded by PE size. The LV is created by mapping Logical Extends in the LV to Physical
extends in a Volume group.

Logical Extents

Each logical volume is split into chunks of disk space, known as logical extents. The extent
size is the same for all logical volumes in the volume group.

Physical Extents mapping

Every LV consists of “LEs” mapped to “PEs” mapped by a target mapping.
Currently, the following mappings are defined.

Linear Mapping

will linearly assign range of PEs to LEs.

For example it can map 100 PEs from PV 1 to LV 1 and
another 100 PEs from PV 0.

Stripe Mapping

will interleave the chunks of the logical extents across a number of physical
volumes.

Snapshots

A facility provided by LVM is 'snapshots'. Whilst in standard NetBSD, the “fss”
driver can be used to provide filesystem snapshots at a filesystem level,
the snapshot facility in the LVM allows the administrator to
create a logical block device which presents an exact copy of a logical volume, frozen at some
point in time. This facility does require that the snapshot be made at a time when the data on
the logical volume is in a consistent state.

Warning

Snapshot feature is not fully implemented in LVM in NetBSD and should not be used in
production.

17.2. Install physical media

This step is at your own discretion, depending on your platform and the hardware at your
disposal. LVM can be used with disklabel partitions or even with standard
partitions created with fdisk.

17.3. Configure Kernel Support

The following kernel configuration directive is needed to provide LVM device support. It
is provided as a kernel module, so that no extra modifications need be made to a standard
NetBSD kernel.
The dm driver is provided as a kernel module, it first appeared in
the NetBSD 6.0 release.

If your system doesn't use modules you can enable dm driver in NetBSD by adding
this line to kernel configuration file. This will add device-mapper driver to
kernel and link it as statically linked module.

pseudo-device dm

If you do not want to rebuild your kernel only because of LVM support
you can use dm kernel module. The devmapper kernel module can be loaded on
your system. To get the current status of modules in the kernel, the
modstat is used:

If your port uses a MBR (Master Boot Record) to partition the disks so that the NetBSD
partitions are only part of the overall disk, and other OSs like Windows or Linux use other
parts, you can void the MBR and all partitions on disk by using the command:

This will make all data on the entire disk inaccessible. Note that the entire disk is
slice d on i386 (and some other ports), and c
elsewhere (e.g. on sparc). See the “kern.rawpartition” sysctl - "3" means "d",
"2" means "c".

You will need to create one “slice” on the NetBSD partition of the disk
that consumes the entire partition. The slice must begin at least two sectors after end of
disklabel part of disk. On i386 it is sector “63”. Therefore, the
“size” value should be “total sectors” minus 2x
“sectors”. Edit your disklabel accordingly:

#disklabel -e sd0

Note

The offset of a slice of type “4.2BSD” must be a multiple of the
“sectors” value.

Note

Be sure to export EDITOR=[path to your favorite editor] before
editing the disklabels.

Note

The slice must be fstype 4.2BSD.

Because there will only be one slice on this partition, you can recycle the
d slice (normally reserved for symbolic uses). Change your disklabel to the
following:

Be sure to write the label when you have completed. Disklabel will object to your
disklabel and prompt you to re-edit if it does not pass its sanity checks.

17.6. Create Physical Volumes

Once all disks are properly labeled, you will need to create physical volume on them.
Every partition/disk added to LVM must have physical volume header on start
of it. All informations, like Volume group where Physical volume belongs are stored in this
header.

#lvm pvcreate /dev/rwd1[ad]

Status of physical volume can be viewed with pvdisplay command.

#lvm pvdisplay

17.7. Create Volume Group

Once all disks are properly labeled with physical volume header, volume group must be
created from them. Volume Group is pool of PEs from which administrator can create Logical
Volumes “partitions”.

#lvm vgcreate vg0 /dev/rwd1[ad]

vg0 is name of Volume Group

/dev/rwd1[ad] is Physical Volume

Volume group can be later extended/reduced with vgextend and vgreduce commands. These
commands adds physical volumes to VG.

#lvm vgextend vg0 /dev/rwd1[ad]#lvm vgreduce vg0 /dev/rwd1[ad]

Status of Volume group can be viewed with vgdisplay command.

#lvm vgdisplay vg0

17.8. Create Logical Volume

Once Volume Group was created administrator can create “logical partitions”
volumes.

#lvm lvcreate -L 20M -n lv1 vg0

vg0 is name of Volume Group

-L 20M is size of Logical Volume

-n lv1 is name of Logical Volume

Logical Volume can be later extended/reduced with lvextend and lvreduce commands.

#lvm lvextend -L+20M /dev/vg0/lv1#lvm lvreduce -L-20M /dev/vg0/lv1

Note

To shrink the lv partition, you must first shrink the filesystem
using resize_ffs(8) (which as of NetBSD 6.x does not support shrinking of FFSv2 yet).

Status of Logical Volume can be viewed with lvdisplay command.

#lvm lvdisplay lv0/lv1

After reboot all functional LV's in defined Volume group can be activated with command

#lvm vgchange -a y

17.9. Example: LVM with Volume groups located on raid1

Motivation for using raid 1 disk as physical volume disk for Volume Group is disk reliability.
With PV on raid 1 disk it is possible to use Logical Volumes even after disk failure.

17.9.1. Loading Device-Mapper driver

Before we can start work with the LVM tools. We have to be sure that
NetBSD dm driver was properly compiled into the kernel or loaded as a module.
Easiest way how to find if we have dm driver available is run modstat.
For more information see
Configure Kernel Support chapter.

17.9.2. Preparing raid1 installation

Following example raid configuration defined in
Raid 1 configuration user will set up clean
raid1 disk device. With 2 disks in a mirror mode.

Partitions should be created with offset 65, because sectors <
than 65 sector are marked as readonly and therefore can't be rewritten.

17.9.3. Creating PV, VG on raid disk

Physical volumes can be created on any disk like device and on any
partition on it we can use a or d on sparc64 c partitions. PV will label
selected partition as LVM used and add needed information to it.

PV is created on char disk device entry. As any other disk operation
in the NetBSD.

#lvm pvcreate /dev/rraid0a

For our example purpose I will create vg00 Volume Group. The first
parameter of vgcreate command is Volume Group name and second is PV
created on raid. If you later found that VG size is no sufficient and you
need more space we will can add it with vgextend
command.

#lvm vgcreate vg00 /dev/rraid0a#lvm vgextend vg00 /dev/rraid1a

Warning

If you add non-raid PV to your Volume Group your data are not safe
anymore. Therefore you should add raid based PV to VG if you want to
keep your data safe.

17.9.4. Creating LV's from VG located on raid disk

For our example purpose we will create Logical Volume named lv0. If
you later found that LV size is not sufficient for you can add it with
lvresize command.

Note

You must also resize the filesystem, when you resize LV,
otherwise you will not see any filesystem change when you mount LV.

Warning

Be aware that to shrink LV you must first shrink the filesystem
(and shrinking of FFSv2 filesystems is not supported yet in NetBSD 6.x).

This means that for FFSv2 filesystems, the -L-* option is not available in NetBSD.

#lvm lvcreate -n lv0 -L 2G vg00#lvm lvresize -L+2G vg00/lv0

All lv device nodes are created in the /dev/vg00/
directory. File system can be create on LV with this command. After
filesystem creation LV can be mounted to system.

#newfs -O2 /dev/vg00/rlv0#mount /dev/vg00/lv0 /mnt/

17.9.5. Integration of LV's in to the system

For Proper LVM integration you have to enable lvm rc.d script,
which detect LVs during boot and enables them. You have to add entry
for Logical Volume to the /etc/fstab file.

18.1. About

This article describes the underlying principles and
mechanisms of the Pluggable Authentication Modules (PAM)
library, and explains how to configure PAM, how to integrate
PAM into applications, and how to write PAM modules.

18.2. Introduction

The Pluggable Authentication Modules (PAM) library is a
generalized API for authentication-related services which allows
a system administrator to add new authentication methods simply
by installing new PAM modules, and to modify authentication
policies by editing configuration files.

PAM was defined and developed in 1995 by Vipin Samar and
Charlie Lai of Sun Microsystems, and has not changed much since.
In 1997, the Open Group published the X/Open Single Sign-on
(XSSO) preliminary specification, which standardized the PAM API
and added extensions for single (or rather integrated) sign-on.
At the time of this writing, this specification has not yet been
adopted as a standard.

Although this article focuses primarily on FreeBSD 5.x and
NetBSD 3.x, which both use OpenPAM, it should be equally
applicable to FreeBSD 4.x, which uses Linux-PAM, and other
operating systems such as Linux and Solaris™.

18.3. Terms and conventions

18.3.1. Definitions

The terminology surrounding PAM is rather confused.
Neither Samar and Lai's original paper nor the XSSO
specification made any attempt at formally defining terms for
the various actors and entities involved in PAM, and the terms
that they do use (but do not define) are sometimes misleading
and ambiguous. The first attempt at establishing a consistent
and unambiguous terminology was a whitepaper written by Andrew
G. Morgan (author of Linux-PAM) in 1999. While Morgan's
choice of terminology was a huge leap forward, it is in this
author's opinion by no means perfect. What follows is an
attempt, heavily inspired by Morgan, to define precise and
unambiguous terms for all actors and entities involved in
PAM.

account

The set of credentials the applicant is requesting
from the arbitrator.

applicant

The user or entity requesting authentication.

arbitrator

The user or entity who has the privileges necessary
to verify the applicant's credentials and the authority
to grant or deny the request.

chain

A sequence of modules that will be invoked in
response to a PAM request. The chain includes
information about the order in which to invoke the
modules, what arguments to pass to them, and how to
interpret the results.

client

The application responsible for initiating an
authentication request on behalf of the applicant and
for obtaining the necessary authentication information
from him.

facility

One of the four basic groups of functionality
provided by PAM: authentication, account management,
session management and authentication token
update.

module

A collection of one or more related functions
implementing a particular authentication facility,
gathered into a single (normally dynamically loadable)
binary file and identified by a single name.

policy

The complete set of configuration statements
describing how to handle PAM requests for a particular
service. A policy normally consists of four chains, one
for each facility, though some services do not use all
four facilities.

server

The application acting on behalf of the arbitrator
to converse with the client, retrieve authentication
information, verify the applicant's credentials and
grant or deny requests.

service

A class of servers providing similar or related
functionality and requiring similar authentication. PAM
policies are defined on a per-service basis, so all
servers that claim the same service name will be subject
to the same policy.

session

The context within which service is rendered to the
applicant by the server. One of PAM's four facilities,
session management, is concerned exclusively with
setting up and tearing down this context.

token

A chunk of information associated with the account,
such as a password or passphrase, which the applicant
must provide to prove his identity.

transaction

A sequence of requests from the same applicant to
the same instance of the same server, beginning with
authentication and session set-up and ending with
session tear-down.

18.3.2. Usage examples

This section aims to illustrate the meanings of some of
the terms defined above by way of a handful of simple
examples.

This policy applies to the sshd
service (which is not necessarily restricted to the
sshd(8) server.)

auth, account,
session and
password are facilities.

pam_nologin.so,
pam_unix.so,
pam_login_access.so,
pam_lastlog.so and
pam_permit.so are modules. It is
clear from this example that
pam_unix.so provides at least two
facilities (authentication and account
management.)

There are some differences between FreeBSD and NetBSD PAM
policies:

By default, every configuration is done
under /etc/pam.d.

If configuration is non-existent, you will not have access
to the system, in contrast with FreeBSD that has a default
policy of allowing authentication.

For authentication, NetBSD forces at least one
required, requisite or
binding module to be present.

18.4. PAM Essentials

18.4.1. Facilities and
primitives

The PAM API offers six different authentication primitives
grouped in four facilities, which are described below.

auth

Authentication. This facility
concerns itself with authenticating the applicant and
establishing the account credentials. It provides two
primitives:

pam_authenticate(3) authenticates the
applicant, usually by requesting an authentication
token and comparing it with a value stored in a
database or obtained from an authentication
server.

pam_setcred(3) establishes account
credentials such as user ID, group membership and
resource limits.

account

Account management. This
facility handles non-authentication-related issues of
account availability, such as access restrictions based
on the time of day or the server's work load. It
provides a single primitive:

Password management. This
facility is used to change the authentication token
associated with an account, either because it has
expired or because the user wishes to change it. It
provides a single primitive:

pam_chauthtok(3) changes the authentication
token, optionally verifying that it is sufficiently
hard to guess, has not been used previously,
etc.

18.4.2. Modules

Modules are a very central concept in PAM; after all,
they are the “M” in “PAM”. A PAM
module is a self-contained piece of program code that
implements the primitives in one or more facilities for one
particular mechanism; possible mechanisms for the
authentication facility, for instance, include the UNIX®
password database, NIS, LDAP and Radius.

18.4.2.1. Module Naming

FreeBSD and NetBSD implement each mechanism in a single module,
named
pam_mechanism.so
(for instance, pam_unix.so for the UNIX®
mechanism.) Other implementations sometimes have separate
modules for separate facilities, and include the facility
name as well as the mechanism name in the module name. To
name one example, Solaris™ has a
pam_dial_auth.so.1 module which is
commonly used to authenticate dialup users.
Also, almost every module has a man page with the same name,
i.e.: pam_unix(8) explains how the
pam_unix.so module works.

18.4.2.2. Module Versioning

FreeBSD's original PAM implementation, based on
Linux-PAM, did not use version numbers for PAM modules.
This would commonly cause problems with legacy applications,
which might be linked against older versions of the system
libraries, as there was no way to load a matching version of
the required modules.

OpenPAM, on the other hand, looks for modules that have
the same version number as the PAM library (currently 2 in
FreeBSD and 0 in NetBSD),
and only falls back to an unversioned module if no versioned
module could be loaded. Thus legacy modules can be provided
for legacy applications, while allowing new (or newly built)
applications to take advantage of the most recent
modules.

Although Solaris™ PAM modules commonly have a version
number, they're not truly versioned, because the number is a
part of the module name and must be included in the
configuration.

18.4.2.3. Module Path

There isn't a common directory for storing PAM modules.
Under FreeBSD, they are located at /usr/lib
and, under NetBSD, you can find them in
/usr/lib/security.

18.4.3. Chains and
policies

When a server initiates a PAM transaction, the PAM library
tries to load a policy for the service specified in the
pam_start(3) call. The policy specifies how
authentication requests should be processed, and is defined in
a configuration file. This is the other central concept in
PAM: the possibility for the admin to tune the system security
policy (in the wider sense of the word) simply by editing a
text file.

A policy consists of four chains, one for each of the four
PAM facilities. Each chain is a sequence of configuration
statements, each specifying a module to invoke, some
(optional) parameters to pass to the module, and a control
flag that describes how to interpret the return code from the
module.

Understanding the control flags is essential to
understanding PAM configuration files. There are a number of
different control flags:

binding

If the module succeeds and no earlier module in the
chain has failed, the chain is immediately terminated
and the request is granted. If the module fails, the
rest of the chain is executed, but the request is
ultimately denied.

This control flag was introduced by Sun in Solaris™ 9
(SunOS™ 5.9), and is also supported by OpenPAM.

required

If the module succeeds, the rest of the chain is
executed, and the request is granted unless some other
module fails. If the module fails, the rest of the
chain is also executed, but the request is ultimately
denied.

requisite

If the module succeeds, the rest of the chain is
executed, and the request is granted unless some other
module fails. If the module fails, the chain is
immediately terminated and the request is denied.

sufficient

If the module succeeds and no earlier module in the
chain has failed, the chain is immediately terminated
and the request is granted. If the module fails, the
module is ignored and the rest of the chain is
executed.

As the semantics of this flag may be somewhat
confusing, especially when it is used for the last
module in a chain, it is recommended that the
binding control flag be used instead
if the implementation supports it.

optional

The module is executed, but its result is ignored.
If all modules in a chain are marked
optional, all requests will always be
granted.

When a server invokes one of the six PAM primitives, PAM
retrieves the chain for the facility the primitive belongs to,
and invokes each of the modules listed in the chain, in the
order they are listed, until it reaches the end, or determines
that no further processing is necessary (either because a
binding or
sufficient module succeeded, or because a
requisite module failed.) The request is
granted if and only if at least one module was invoked, and
all non-optional modules succeeded.

Note that it is possible, though not very common, to have
the same module listed several times in the same chain. For
instance, a module that looks up user names and passwords in a
directory server could be invoked multiple times with
different parameters specifying different directory servers to
contact. PAM treat different occurrences of the same module
in the same chain as different, unrelated modules.

18.4.4. Transactions

The lifecycle of a typical PAM transaction is described
below. Note that if any of these steps fails, the server
should report a suitable error message to the client and abort
the transaction.

If necessary, the server obtains arbitrator
credentials through a mechanism independent of
PAM—most commonly by virtue of having been started
by root, or of being setuid
root.

The server calls pam_start(3) to initialize the
PAM library and specify its service name and the target
account, and register a suitable conversation
function.

The server obtains various information relating to the
transaction (such as the applicant's user name and the
name of the host the client runs on) and submits it to PAM
using pam_set_item(3).

The server calls pam_acct_mgmt(3) to verify that the
requested account is available and valid. If the password
is correct but has expired, pam_acct_mgmt(3) will
return PAM_NEW_AUTHTOK_REQD instead of
PAM_SUCCESS.

If the previous step returned
PAM_NEW_AUTHTOK_REQD, the server now
calls pam_chauthtok(3) to force the client to change
the authentication token for the requested account.

Now that the applicant has been properly
authenticated, the server calls pam_setcred(3) to
establish the credentials of the requested account. It is
able to do this because it acts on behalf of the
arbitrator, and holds the arbitrator's credentials.

Once the correct credentials have been established,
the server calls pam_open_session(3) to set up the
session.

The server now performs whatever service the client
requested—for instance, provide the applicant with a
shell.

Finally, the server calls pam_end(3) to notify
the PAM library that it is done and that it can release
whatever resources it has allocated in the course of the
transaction.

18.5. PAM Configuration

18.5.1. PAM policy files

18.5.1.1. The
/etc/pam.conf file

The traditional PAM policy file is
/etc/pam.conf. This file contains all
the PAM policies for your system. Each line of the file
describes one step in a chain, as shown below:

login auth required pam_nologin.so no_warn

The fields are, in order: service name, facility name,
control flag, module name, and module arguments. Any
additional fields are interpreted as additional module
arguments.

A separate chain is constructed for each service /
facility pair, so while the order in which lines for the
same service and facility appear is significant, the order
in which the individual services and facilities are listed
is not. The examples in the original PAM paper grouped
configuration lines by facility, and the Solaris™ stock
pam.conf still does that, but FreeBSD's
stock configuration groups configuration lines by service.
Either way is fine; either way makes equal sense.

18.5.1.2. The
/etc/pam.d directory

OpenPAM and Linux-PAM support an alternate configuration
mechanism, which is the preferred mechanism in FreeBSD and
NetBSD.
In this scheme, each policy is contained in a separate file
bearing the name of the service it applies to. These files
are stored in /etc/pam.d/.

These per-service policy files have only four fields
instead of pam.conf's five: the service
name field is omitted. Thus, instead of the sample
pam.conf line from the previous
section, one would have the following line in
/etc/pam.d/login:

auth required pam_nologin.so no_warn

As a consequence of this simplified syntax, it is
possible to use the same policy for multiple services by
linking each service name to a same policy file. For
instance, to use the same policy for the
su and sudo services,
one could do as follows:

#cd /etc/pam.d#ln -s su sudo

This works because the service name is determined from
the file name rather than specified in the policy file, so
the same file can be used for multiple differently-named
services.

Since each service's policy is stored in a separate
file, the pam.d mechanism also makes it
very easy to install additional policies for third-party
software packages.

18.5.1.3. The policy search
order

As we have seen above, PAM policies can be found in a
number of places. If no configuration file is found for a
particular service, the /etc/pam.d/other
is used instead. If that file does not exist,
/etc/pam.conf is searched for entries
matching he specified service or, failing that, the "other"
service.

It is essential to understand that PAM's configuration
system is centered on chains.

18.5.2. Breakdown of a
configuration line

As explained in the PAM policy files section, each line in
/etc/pam.conf consists of four or more
fields: the service name, the facility name, the control flag,
the module name, and zero or more module arguments.

The service name is generally (though not always) the name
of the application the statement applies to. If you are
unsure, refer to the individual application's documentation to
determine what service name it uses.

Note that if you use /etc/pam.d/
instead of /etc/pam.conf, the service
name is specified by the name of the policy file, and omitted
from the actual configuration lines, which then start with the
facility name.

Likewise, the control flag is one of the four keywords
described in the Chains and
policies section,
describing how to interpret the return code from the module.
Linux-PAM supports an alternate syntax that lets you specify
the action to associate with each possible return code, but
this should be avoided as it is non-standard and closely tied
in with the way Linux-PAM dispatches service calls (which
differs greatly from the way Solaris™ and OpenPAM do it.)
Unsurprisingly, OpenPAM does not support this syntax.

18.5.3. Policies

To configure PAM correctly, it is essential to understand
how policies are interpreted.

When an application calls pam_start(3), the PAM
library loads the policy for the specified service and
constructs four module chains (one for each facility.) If one
or more of these chains are empty, the corresponding chains
from the policy for the other service are
substituted.

When the application later calls one of the six PAM
primitives, the PAM library retrieves the chain for the
corresponding facility and calls the appropriate service
function in each module listed in the chain, in the order in
which they were listed in the configuration. After each call
to a service function, the module type and the error code
returned by the service function are used to determine what
happens next. With a few exceptions, which we discuss below,
the following table applies:

Table 18.1. PAM chain execution summary

PAM_SUCCESS

PAM_IGNORE

other

binding

if (!fail) break;

-

fail = true;

required

-

-

fail = true;

requisite

-

-

fail = true; break;

sufficient

if (!fail) break;

-

-

optional

-

-

-

If fail is true at the end of a chain,
or when a “break” is reached, the dispatcher
returns the error code returned by the first module that
failed. Otherwise, it returns
PAM_SUCCESS.

The first exception of note is that the error code
PAM_NEW_AUTHTOK_REQD is treated like a
success, except that if no module failed, and at least one
module returned PAM_NEW_AUTHTOK_REQD, the
dispatcher will return
PAM_NEW_AUTHTOK_REQD.

The second exception is that pam_setcred(3) treats
binding and
sufficient modules as if they were
required.

The third and final exception is that
pam_chauthtok(3) runs the entire chain twice (once for
preliminary checks and once to actually set the password), and
in the preliminary phase it treats
binding and
sufficient modules as if they were
required.

18.6. PAM modules

18.6.1. Common Modules

The pam_deny(8) module is one of the simplest modules
available; it responds to any request with
PAM_AUTH_ERR. It is useful for quickly
disabling a service (add it to the top of every chain), or for
terminating chains of sufficient
modules.

The pam_echo(8) module simply passes its arguments to
the conversation function as a
PAM_TEXT_INFO message. It is mostly useful
for debugging, but can also serve to display messages such as
“Unauthorized access will be prosecuted” before
starting the authentication procedure.

The pam_exec(8) module takes its first argument to be
the name of a program to execute, and the remaining arguments
are passed to that program as command-line arguments. One
possible application is to use it to run a program at login
time which mounts the user's home directory.

The pam_ftpusers(8) module successes if and only if
the user is listed in /etc/ftpusers.
Currently, in NetBSD, this module doesn't understand the
extended syntax of ftpd(8), but this will be fixed in
the future.

The pam_group(8) module accepts or rejects applicants
on the basis of their membership in a particular file group
(normally wheel for su(1)). It is
primarily intended for maintaining the traditional behaviour
of BSD su(1), but has many other uses, such as excluding
certain groups of users from a particular service.

In NetBSD, there is an argument called
authenticate in which the user is asked to
authenticate using his own password.

The pam_guest(8) module allows guest logins using
fixed login names. Various requirements can be placed on the
password, but the default behaviour is to allow any password
as long as the login name is that of a guest account. The
pam_guest(8) module can easily be used to implement
anonymous FTP logins.

The pam_krb5(8) module provides functions to verify the
identity of a user and to set user specific credentials using
Kerberos 5. It prompts the user for a password and obtains a new
Kerberos TGT for the principal. The TGT is verified by obtaining a
service ticket for the local host. The newly acquired credentials
are stored in a credential cache and the environment variable
KRB5CCNAME is set appropriately. The credentials cache should be
destroyed by the user at logout with kdestroy(1).

The pam_permit(8) module is one of the simplest
modules available; it responds to any request with
PAM_SUCCESS. It is useful as a placeholder
for services where one or more chains would otherwise be
empty.

The pam_rhosts(8) module provides only
authentication services. It reports success if and only if the
target user's ID is not 0 and the remote host and user are
listed in /etc/hosts.equiv or in the
target user's ~/.rhosts.

The pam_rootok(8) module reports success if and only
if the real user id of the process calling it (which is
assumed to be run by the applicant) is 0. This is useful for
non-networked services such as su(1) or passwd(1),
to which the root should have automatic
access.

The pam_self(8) module reports success if and only if
the names of the applicant matches that of the target account.
It is most useful for non-networked services such as
su(1), where the identity of the applicant can be easily
verified.

The pam_ssh(8) module provides both authentication
and session services. The authentication service allows users
who have passphrase-protected SSH secret keys in their
~/.ssh directory to authenticate
themselves by typing their passphrase. The session service
starts ssh-agent(1) and preloads it with the keys that
were decrypted in the authentication phase. This feature is
particularly useful for local logins, whether in X (using
xdm(1) or another PAM-aware X login manager) or at the
console.

This module implements what is fundamentally a password
authentication scheme. Care should be taken to only use this
module over a secure session (secure TTY, encrypted session, etc.),
otherwise the user's SSH passphrase could be compromised.

Additional consideration should be given to the use of
pam_ssh(8). Users often assume that file permissions are
sufficient to protect their SSH keys, and thus use weak or no
passphrases. Since the system administrator has no effective
means of enforcing SSH passphrase quality, this has the potential
to expose the system to security risks.

The pam_unix(8) module implements traditional UNIX®
password authentication, using getpwnam(3) under FreeBSD
or getpwnam_r(3) under NetBSD to obtain the
target account's password and compare it with the one provided
by the applicant. It also provides account management
services (enforcing account and password expiration times) and
password-changing services. This is probably the single most
useful module, as the great majority of admins will want to
maintain historical behaviour for at least some
services.

18.6.2. NetBSD-specific PAM Modules

The pam_skey(8) module implements S/Key One Time
Password (OTP) authentication methods, using the
/etc/skeykeys database.

18.7. PAM Application Programming

This section has not yet been written.

18.8. PAM Module Programming

This section has not yet been written.

18.9. Sample PAM Application

The following is a minimal implementation of su(1)
using PAM. Note that it uses the OpenPAM-specific
openpam_ttyconv(3) conversation function, which is
prototyped in
security/openpam.h.
If you wish
build this application on a system with a different PAM library,
you will have to provide your own conversation function. A
robust conversation function is surprisingly difficult to
implement; the one presented in the
Sample PAM Conversation
Function sub-chapter is a good
starting point, but should not be used in real-world
applications.

18.10. Sample PAM Module

The following is a minimal implementation of
pam_unix(8), offering only authentication services. It
should build and run with most PAM implementations, but takes
advantage of OpenPAM extensions if available: note the use of
pam_get_authtok(3), which enormously simplifies prompting
the user for a password.

18.11. Sample PAM Conversation
Function

The conversation function presented below is a greatly
simplified version of OpenPAM's openpam_ttyconv(3). It is
fully functional, and should give the reader a good idea of how
a conversation function should behave, but it is far too simple
for real-world use. Even if you're not using OpenPAM, feel free
to download the source code and adapt openpam_ttyconv(3) to
your uses; we believe it to be as robust as a tty-oriented
conversation function can reasonably get.

19.1. Introduction

19.1.1. Overview

This section covers a variety of performance tuning topics.
It attempts to span tuning from the perspective of the system
administrator to systems programmer. The art of performance
tuning itself is very old. To tune something means to make
it operate more efficiently, whether one is referring to
a NetBSD based technical server or a vacuum cleaner, the goal
is to improve something, whether that be the way something
is done, how it works or how it is put together.

19.1.1.1. What is Performance Tuning?

A view from 10,000 feet pretty much dictates that
everything we do is task oriented, this pertains to a
NetBSD system as well. When the system boots, it
automatically begins to perform a variety of tasks.
When a user logs in, they usually have a wide variety
of tasks they have to accomplish. In the scope of these
documents, however, performance tuning strictly means to
improve how efficient a NetBSD system performs.

The most common thought that crops into someone's mind when
they think "tuning" is some sort of speed increase or
decreasing the size of the kernel - while those are ways
to improve performance, they are not the only ends an
administrator may have to take for increasing efficiency.
For our purposes, performance tuning means this:
To make a NetBSD system operate in an optimum
state.

Which could mean a variety of things, not necessarily
speed enhancements. A good example of this is filesystem
formatting parameters, on a system that has a lot of small
files (say like a source repository) an administrator may
need to increase the number of inodes by making their
size smaller (say down to 1024k) and then increasing the
amount of inodes. In this case the number of inodes was
increased, however, it keeps the administrator from
getting those nasty out of inodes messages, which
ultimately makes the system more efficient.

Tuning normally revolves around finding and eliminating
bottlenecks. Most of the time, such bottlenecks are
spurious, for example, a release of Mozilla that does
not quite handle java applets too well can cause Mozilla
to start crunching the CPU, especially applets that are not
done well. Occasions when processes seem to spin off into
nowhere and eat CPU are almost always resolved with a kill.
There are instances, however, when resolving bottlenecks
takes a lot longer, for example, say an rsynced server
is just getting larger and larger. Slowly, performance
begins to fade and the administrator may have to take
some sort of action to speed things up, however, the
situation is relative to say an emergency like an
instantly spiked CPU.

19.1.1.2. When does one tune?

Many NetBSD users rarely have to tune a system. The GENERIC
kernel may run just fine and the layout/configuration of
the system may do the job as well. By the same token, as
a pragma it is always good to know how to tune a system.
Most often tuning comes as a result of a sudden bottleneck
issue (which may occur randomly) or a gradual loss of
performance. It does happen in a sense to everyone
at some point, one process that is eating the CPU is a
bottleneck as much as a gradual increase in paging. So,
the question should not be when to tune so much as when
to learn to tune.

One last time to tune is if you can tune in a preventive
manner (and you think you might need to) then do it.
One example of this was on a system that needed to be
able to reboot quickly. Instead of waiting, I did
everything I could to trim the kernel and make sure
there was absolutely nothing running that was not needed,
I even removed drivers that did have devices, but were
never used (lp). The result was reducing reboot time by
nearly two-thirds. In the long run, it was a smart move
to tune it before it became an issue.

19.1.1.3. What these Documents Will Not Cover

Before I wrap up the introduction, I think it is
important to note what these documents will not cover.
This guide will pertain only to the core NetBSD system.
In other words, it will not cover tuning a web server's
configuration to make it run better; however,
it might mention how to tune NetBSD to run better as a web
server. The logic behind this is simple: web servers,
database software, etc. are third party and almost
limitless. I could easily get mired down in details
that do not apply to the NetBSD system. Almost all third
party software have their own documentation about tuning
anyhow.

19.1.1.4. How Examples are Laid Out

Since there is ample man page documentation, only used
options and arguments with examples are discussed. In
some cases, material is truncated for brevity and not
thoroughly discussed because, quite simply, there is
too much. For example, every single device driver
entry in the kernel will not be discussed, however,
an example of determining whether or not a given system
needs one will be. Nothing in this Guide is concrete,
tuning and performance are very subjective, instead, it
is a guide for the reader to learn what some of the tools
available to them can do.

19.2. Tuning Considerations

Tuning a system is not really too difficult when pro-active tuning
is the approach. This document approaches tuning from a
“before it comes up” approach. While tuning in spare
time is considerably easier versus say, a server that is almost
completely bogged down to 0.1% idle time, there are still a few
things that should be mulled over about tuning before actually
doing it, hopefully, before a system is even installed.

19.2.1. General System Configuration

Of course, how the system is setup makes a big difference.
Sometimes small items can be overlooked which may in fact
cause some sort of long term performance problem.

19.2.1.1. Filesystems and Disks

How the filesystem is laid out relative to disk drives is
very important. On hardware RAID systems, it is not such
a big deal, but, many NetBSD users specifically use NetBSD
on older hardware where hardware RAID simply is not an
option. The idea of / being
close to the first drive is a good one, but for example
if there are several drives to choose from that will be
the first one, is the best performing the one that
/ will be on? On a related note,
is it wise to split off /usr? Will
the system see heavy usage say in
/usr/pkgsrc? It might make sense to
slap a fast drive in and mount it under
/usr/pkgsrc, or it might not. Like
all things in performance tuning, this is subjective.

19.2.1.2. Swap Configuration

There are three schools of thought on swap size and about
fifty on using split swap files with prioritizing and how
that should be done. In the swap size arena, the vendor
schools (at least most commercial ones) usually have
their own formulas per OS. As an example, on a particular
version of HP-UX with a particular version of Oracle the
formula was:

2.5 GB * Number_of_processor

Well, that all really depends on what type of usage the
database is having and how large it is, for instance if it
is so large that it must be distributed, that formula
does not fit well.

The next school of thought about swap sizing is sort of
strange but makes some sense, it says, if possible, get
a reference amount of memory used by the system. It goes
something like this:

Startup a machine and estimate total memory needs
by running everything that may ever be
needed at once. Databases, web servers ....
whatever. Total up the amount.

Add a few MB for padding.

Subtract the amount of physical RAM from this total.

If the amount leftover is 3 times the size of physical RAM,
consider getting more RAM. The problem, of course, is
figuring out what is needed and how much space it will take.
There is also another flaw in this method, some programs
do not behave well. A glaring example of misbehaved
software is web browsers.
On certain versions of Netscape, when something went wrong
it had a tendency to runaway and eat swap space. So, the
more spare space available, the more time to kill it.

Last and not least is the tried and true
PHYSICAL_RAM * 2 method. On modern machines and even
older ones (with limited purpose of course) this seems to
work best.

All in all, it is hard to tell when swapping will start.
Even on small 16MB RAM machines (and less) NetBSD has
always worked well for most people until misbehaving
software is running.

19.2.2. System Services

On servers, system services have a large impact. Getting
them to run at their best almost always requires some
sort of network level change or a fundamental speed
increase in the underlying system (which of course is
what this is all about). There are instances when some
simple solutions can improve services. One example,
an ftp server is becoming slower and a new release of
the ftp server that is shipped with the system comes
out that, just happens to run faster. By upgrading the
ftp software, a performance boost is accomplished.

Another good example where services are concerned is the
age old question: “To use inetd or not to
use inetd?” A great service example is pop3.
Pop3 connections can conceivably clog up inetd. While
the pop3 service itself starts to degrade slowly, other
services that are multiplexed through inetd will also
degrade (in some case more than pop3).
Setting up pop3 to run outside of inetd and on its own
may help.

19.2.3. The NetBSD Kernel

The NetBSD kernel obviously plays a key role in how well a
system performs, while rebuilding and tuning the kernel is
covered later in the text, it is worth discussing in the
local context from a high level.

Tuning the NetBSD kernel really involves three main areas:

removing unrequired drivers

configuring options

system settings

19.2.3.1. Removing Unrequired Drivers

Taking drivers out of the kernel that are not needed
achieves several results; first, the system boots faster
since the kernel is smaller, second again since the
kernel is smaller, more memory is free to users and
processes and third, the kernel tends to respond quicker.

19.2.3.2. Configuring Options

Configuring options such as enabling/disabling certain
subsystems, specific hardware and filesystems can also
improve performance pretty much the same way removing
unrequired drivers does. A very simple example of this
is a FTP server that only hosts ftp files - nothing else.
On this particular server there is no need to have
anything but native filesystem support and perhaps a
few options to help speed things along. Why would it
ever need NTFS support for example? Besides, if it
did, support for NTFS could be added at some later
time. In an opposite case, a workstation may need to
support a lot of different filesystem types to share
and access files.

19.2.3.3. System Settings

System wide settings are controlled by the kernel, a few
examples are filesystem settings, network settings and core
kernel settings such as the maximum number of processes.
Almost all system settings can be at least looked at or
modified via the sysctl facility. Examples using the
sysctl facility are given later on.

19.3. Visual Monitoring Tools

NetBSD ships a variety of performance monitoring tools with the
system. Most of these tools are common on all UNIX systems. In
this section some example usage of the tools is given with
interpretation of the output.

19.3.1. The top Process Monitor

The top monitor does exactly what it says: it displays the CPU
hogs on the system. To run the monitor, simply type top at the
prompt. Without any arguments, it should look like:

The top utility is great for finding CPU hogs, runaway
processes or groups of processes that may be causing
problems. The output shown above indicates that this
particular system is in good health. Now, the next display
should show some very different results:

At first, it should seem rather obvious which process is
hogging the system, however, what is interesting in this
case is why. The bonnie program is a disk benchmark tool
which can write large files in a variety of sizes and ways.
What the previous output indicates is only that the bonnie
program is a CPU hog, but not why.

19.3.1.1. Other Neat Things About Top

A careful examination of the manual page top(1)
shows that there is a lot more that can be done with
top, for example, processes can have their priority
changed and killed. Additionally, filters can be set
for looking at processes.

19.3.2. The sysstat utility

As the man page sysstat(1) indicates, the sysstat
utility shows a variety of system statistics using the
curses library. While it is running the screen is shown
in two parts, the upper window shows the current load
average while the lower screen depends on user commands.
The exception to the split window view is when vmstat
display is on which takes up the whole screen. Following
is what sysstat looks like on a fairly idle system with no
arguments given when it was invoked:

Now that is informative. The first poll is accumulative, so
it is possible to see quite a lot of information in the
output when sysstat is invoked. Now, while that may be
interesting, how about a look at the buffer cache with
sysstat bufcache:

Again, a pretty boring system, but great information to have
available. While this is all nice to look at, it is time to
put a false load on the system to see how sysstat can be
used as a performance monitoring tool. As with top,
bonnie++ will be used to put a high load on the I/O
subsystems and a little on the CPU. The bufcache will be
looked at again to see of there are any noticeable differences:

First, notice that the load average shot up, this is to be
expected of course, then, while most of the numbers are close,
notice that utilization is at 99%. Throughout the time that
bonnie++ was running the utilization percentage remained
at 99, this of course makes sense, however, in a real
troubleshooting situation, it could be indicative of a
process doing heavy I/O on one particular file or filesystem.

19.4. Monitoring Tools

In addition to screen oriented monitors and tools, the NetBSD
system also ships with a set of command line oriented tools.
Many of the tools that ship with a NetBSD system can be found
on other UNIX and UNIX-like systems.

19.4.1. fstat

The fstat(1) utility reports the status of open files on
the system, while it is not what many administrators
consider a performance monitor, it can help find out if a
particular user or process is using an inordinate amount
of files, generating large files and similar information.

The fields are pretty self explanatory, again, this tool while
not as performance oriented as others, can come in handy when
trying to find out information about file usage.

19.4.2. iostat

The iostat(8) command does exactly what it sounds like, it
reports the status of the I/O subsystems on the system. When
iostat is employed, the user typically runs it with a certain
number of counts and an interval between them like so:

The above output is from a very quiet ftp server. The fields
represent the various I/O devices, the tty (which, ironically,
is the most active because iostat is running), wd0 which is the
primary IDE disk, cd0, the cdrom drive, fd0, the floppy and the
memory filesystem.

Now, let's see if we can pummel the system with some heavy
usage. First, a large ftp transaction consisting of a tarball
of netbsd-current source along with the bonnie++ disk
benchmark program running at the same time.

As can be expected, notice that wd0 is very active, what is
interesting about this output is how the processor's I/O seems
to rise in proportion to wd0. This makes perfect sense,
however, it is worth noting that only because this ftp
server is hardly being used can that be observed. If, for
example, the cpu I/O subsystem was already under a moderate
load and the disk subsystem was under the same load as it
is now, it could appear that the cpu is bottlenecked when
in fact it would have been the disk. In such a case, we can
observe that "one tool" is rarely enough to completely
analyze a problem. A quick glance at processes probably
would tell us (after watching iostat) which
processes were causing problems.

19.4.3. ps

Using the ps(1) command or process status, a great deal of
information about the system can be discovered. Most of the
time, the ps command is used to isolate a particular process
by name, group, owner etc. Invoked with no options or
arguments, ps simply prints out information about the user
executing it.

Not very exciting. The fields are self explanatory with the
exception of STAT which is actually the state a process is in.
The flags are all documented in the man page, however, in the
above example, I is idle, S is sleeping, R is runnable,
the + means the process is in a foreground state, and the s
means the process is a session leader. This all makes
perfect sense when looking at the flags, for example,
PID 21560 is a shell, it is idle and (as would be expected)
the shell is the process leader.

In most cases, someone is looking for something very specific
in the process listing. As an example, looking at all processes
is specified with -a, to see all processes plus those without
controlling terminals is -ax and to get a much more verbose
listing (basically everything plus information about the
impact processes are having) aux:

Again, most of the fields are self explanatory with the
exception of VSZ and RSS which can be a little confusing.
RSS is the real size of a process in 1024 byte units while
VSZ is the virtual size. This is all great, but again, how
can ps help? Well, for one, take a look at this modified
version of the same output:

Given that on this server, our baseline indicates a relatively
quiet system, the PID 5032 has an unusually large amount of
%CPU. Sometimes this can also cause high TIME numbers. The
ps command can be grepped on for PIDs, username and process
name and hence help track down processes that may be
experiencing problems.

19.4.4. vmstat

Using vmstat(1), information pertaining to virtual
memory can be monitored and measured. Not unlike iostat,
vmstat can be invoked with a count and interval. Following
is some sample output using 5 5 like the iostat example:

Just a little different. Notice, since most of the work
was I/O based, the actual memory used was not very much.
Since this system uses mfs for /tmp,
however, it can certainly get beat up. Have a look at this:

Pretty scary stuff. That was created by running bonnie in
/tmp
on a memory based filesystem. If it continued for too long,
it is possible the system could have started thrashing.
Notice that even though the VM subsystem was taking a beating,
the processors still were not getting too battered.

19.5. Network Tools

Sometimes a performance problem is not a particular machine,
it is the network or some sort of device on the network such as
another host, a router etc. What other machines that provide a
service or some sort of connectivity to a particular NetBSD system
do and how they act can have a very large impact on performance
of the NetBSD system itself, or the perception of performance by
users.
A really great example of this is when a DNS server that a NetBSD
machine is using suddenly disappears. Lookups take long and they
eventually fail. Someone logged into the NetBSD machine who is not
experienced would undoubtedly (provided they had no other evidence)
blame the NetBSD system. One of my personal favorites,
“the Internet is broke” usually means either DNS
service or a router/gateway has dropped offline. Whatever the
case may be, a NetBSD system comes adequately armed to deal with
finding out what network issues may be cropping up whether
the fault of the local system or some other issue.

19.5.1. ping

The classic ping(8) utility can tell us if there is just
plain connectivity, it can also tell if host resolution
(depending on how nsswitch.conf
dictates) is working. Following is some typical ping
output on a local network with a count of 3 specified:

Much smaller because the request never left the machine. Pings
can be used to gather information about how well a network
is performing. It is also good for problem isolation, for
instance, if there are three relatively close in size NetBSD
systems on a network and one of them simply has horrible
ping times, chances are something is wrong on that one
particular machine.

19.5.2. traceroute

The traceroute(8) command is great for making sure a
path is available or detecting problems on a particular
path. As an example, here is a trace between the example
ftp server and ftp.NetBSD.org:

All in all, not bad. The trace went from the host to the local
router, then out onto the provider network and finally out onto
the Internet looking for the final destination. How to
interpret traceroutes, again, are subjective, but
abnormally high times in portions of a path can indicate a
bottleneck on a piece of network equipment. Not unlike ping,
if the host itself is suspect, run traceroute from another
host to the same destination. Now, for the worst case scenario:

In this case, the Microsoft server cannot be found either
because of multiple addresses or somewhere along the line a
system or server cannot reply to the information request.
At that point, one might think to try ping, in the Microsoft
case, a ping does not reply, that is because somewhere on
their network ICMP is most likely disabled.

19.5.3. netstat

Another problem that can crop up on a NetBSD system is routing
table issues. These issues are not always the systems fault.
The route(8) and netstat(1) commands can show
information about routes and network connections (respectively).

The route command can be used to look at and modify routing
tables while netstat can display information about network
connections and routes. First, here is some output from route
show:

The above output is a little more verbose. So, how can this
help? Well, a good example is when routes between networks
get changed while users are connected. I saw this happen
several times when someone was rebooting routers all day
long after each change. Several users called up saying they
were getting kicked out and it was taking very long to log
back in. As it turned out, the clients connecting to the
system were redirected to another router (which took a very
long route) to reconnect. I observed the M flag or Modified
dynamically (by redirect) on their connections. I deleted
the routes, had them reconnect and summarily followed up
with the offending technician.

19.5.4. tcpdump

Last, and definitely not least is tcpdump(8), the network
sniffer that can retrieve a lot of information. In this
discussion, there will be some sample output and an
explanation of some of the more useful options of tcpdump.

Given that the particular server is a mail server, what is
shown makes perfect sense, however, the utility is very
verbose, I prefer to initially run tcpdump with no options
and send the text output into a file for later digestion
like so:

#tcpdump > tcpdump.out
tcpdump: listening on ex0

So, what precisely in the mish mosh are we looking for?
In short, anything that does not seem to fit, for example,
messed up packet lengths (as in a lot of them) will show
up as improper lens or malformed packets (basically garbage).
If, however, we are looking for something specific, tcpdump
may be able to help depending on the problem.

19.5.4.1. Specific tcpdump Usage

These are just examples of a few things one can do with
tcpdump.

Look for duplicate IP addresses:

tcpdump -e host ip-address

For example:

tcpdump -e host 192.168.0.2

Routing Problems:

tcpdump icmp

There are plenty of third party tools available, however,
NetBSD comes shipped with a good tool set for tracking down
network level performance problems.

19.6. Accounting

The NetBSD system comes equipped with a great deal of performance
monitors for active monitoring, but what about long term monitoring?
Well, of course the output of a variety of commands can be sent to
files and re-parsed later with a meaningful shell script or program.
NetBSD does, by default, offer some extraordinarily powerful
low level monitoring tools for the programmer, administrator or
really astute hobbyist.

19.6.1. Accounting

While accounting gives system usage at an almost userland level,
kernel profiling with gprof provides explicit system call usage.

Using the accounting tools can help figure out what possible
performance problems may be laying in wait, such as increased
usage of compilers or network services for example.

Starting accounting is actually fairly simple, as root, use the
accton(8) command. The syntax to start accounting is:
accton filename

Where accounting information is appended to filename, now,
strangely enough, the lastcomm command which reads from an
accounting output file, by default, looks in
/var/account/acct
so I tend to just use the default location, however, lastcomm
can be told to look elsewhere.

19.6.3. How to Put Accounting to Use

Accounting reports, as was mentioned earlier, offer a way to
help predict trends, for example, on a system that has cc and
make being used more and more may indicate that in a few months
some changes will need to be made to keep the system running at
an optimum level. Another good example is web server usage. If
it begins to gradually increase, again, some sort of action may
need to be taken before it becomes a problem. Luckily, with
accounting tools, said actions can be reasonably predicted and
planned for ahead of time.

19.7. Kernel Profiling

Profiling a kernel is normally employed when the goal is to
compare the difference of new changes in the kernel to a previous
one or to track down some sort of low level performance problem.
Two sets of data about profiled code behavior are recorded
independently:
function call frequency and time spent in each function.

19.7.1. Getting Started

First, take a look at both Section 19.9, “Kernel Tuning” and
Chapter 32, Compiling the kernel.
The only difference in procedure for setting up a kernel
with profiling enabled is when you run config add the -p
option. The build area is
../compile/<KERNEL_NAME>.PROF ,
for example, a GENERIC kernel would be
../compile/GENERIC.PROF.

Following is a quick summary of how to compile a kernel
with profiling enabled on the i386 port, the assumptions
are that the appropriate sources are available under
/usr/src and the GENERIC
configuration is being used, of course, that may not
always be the situation:

cd /usr/src/sys/arch/i386/conf

config -p GENERIC

cd ../compile/GENERIC.PROF

make depend && make

cp /netbsd /netbsd.old

cp netbsd /

reboot

Once the new kernel is in place and the system has rebooted,
it is time to turn on the monitoring and start looking at
results.

19.7.1.1. Using kgmon

To start kgmon:

$kgmon -b
kgmon: kernel profiling is running.

Next, send the data into the file
gmon.out:

$kgmon -p

Now, it is time to make the output readable:

$gprof /netbsd > gprof.out

Since gmon is looking for gmon.out,
it should find it in the current working directory.

By just running kgmon alone, you may not get the
information you need, however, if you are comparing
the differences between two different
kernels, then a known good baseline should be used.
Note that it is generally a good idea to stress the
subsystem if you know what it is both in the baseline
and with the newer (or different) kernel.

19.7.2. Interpretation of kgmon Output

Now that kgmon can run, collect and parse information, it is
time to actually look at some of that information. In this
particular instance, a GENERIC kernel is running with
profiling enabled for about an hour with only system
processes and no adverse load, in the fault insertion
section, the example will be large enough that even under
a minimal load detection of the problem should be easy.

19.7.2.1. Flat Profile

The flat profile is a list of functions, the number of
times they were called and how long it took (in seconds).
Following is sample output from the quiet system:

As is obvious, there is a large difference in performance.
Right off the bat the idle time is noticeably less. The main
difference here is that one particular function has a large
time across the board with very few calls. That function is
check_exec. While at first, this may
not seem strange if a lot of commands had been executed,
when compared to the flat profile of the first measurement,
proportionally it does not seem right:

...
0.00 164.14 0.00 37 0.00 62747.49 check_exec
...

The call in the first measurement is made 37 times and has
a better performance. Obviously something in or around that
function is wrong. To eliminate other functions, a look at
the call graph can help, here is the first instance of
check_exec

Now we can see that the problem, most likely, resides in
check_exec. Of course, problems
are not always this simple and in fact, here
is the simpleton code that was inserted right after
check_exec
(the function is in sys/kern/kern_exec.c):

Not exactly glamorous, but enough to register a large change
with profiling.

19.7.4. Summary

Kernel profiling can be enlightening for anyone and provides a
much more refined method of hunting down performance problems
that are not as easy to find using conventional means, it is
also not nearly as hard as most people think, if you can
compile a kernel, you can get profiling to work.

19.8. System Tuning

Now that monitoring and analysis tools have been addressed,
it is time to look into some actual methods. In this section,
tools and methods that can affect how the system performs
that are applied without recompiling the kernel are addressed,
the next section examines kernel tuning by recompiling.

19.8.1. Using sysctl

The sysctl utility can be used to look at and in some cases
alter system parameters. There are so many parameters that
can be viewed and changed they cannot all be shown here,
however, for the first example here is a simple usage of
sysctl to look at the system PATH environment variable:

Fairly simple. Now something that is actually related to
performance. As an example, lets say a system with many users
is having file open issues, by examining and perhaps raising
the kern.maxfiles parameter the problem may be fixed, but
first, a look:

$sysctl kern.maxfiles
kern.maxfiles = 1772

Now, to change it, as root with the -w option specified:

#sysctl -w kern.maxfiles=1972
kern.maxfiles: 1772 -> 1972

Note, when the system is rebooted, the old value will return,
there are two cures for this, first, modify that parameter in
the kernel and recompile, second (and simpler) add this line
to /etc/sysctl.conf:

kern.maxfiles=1972

19.8.2. tmpfs & mfs

NetBSD's "ramdisk" implementations cache all data in the
RAM, and if that is full, the swap space is used as backing
store. NetBSD comes with two implementations, the
traditional BSD memory-based file system "mfs" and the more
modern "tmpfs". While the former can only grow in size, the
latter can also shrink if space is no longer needed.

When to use and not to use a memory based filesystem can
be hard on large multi user systems. In some cases,
however, it makes pretty good sense, for example, on a
development machine used by only one developer at a time,
the obj directory might be a good place, or some of the
tmp directories for builds. In a case like that, it
makes sense on machines that have a fair amount of RAM
on them. On the other side of the coin, if a system
only has 16MB of RAM and /var/tmp
is mfs-based, there could be severe applications
issues that occur.

The GENERIC kernel has both tmpfs and mfs enabled by default. To use
it on a particular directory first determine where the
swap space is that you wish to use, in the example case,
a quick look in /etc/fstab
indicates that /dev/wd0b is the
swap partition:

This system is a mail server so I only want to use
/tmp with tmpfs, also on this
particular system I have linked /tmp
to /var/tmp to save space
(they are on the same drive). All I need to do is add the
following entry:

/dev/wd0b /var/tmp tmpfs rw 0 0

If you want to use "mfs" instead of "tmpfs", put just
that into the above place.

Now, a word of warning: make sure said directories are
empty and nothing is using them when you mount the memory
file system! After changing /etc/fstab, you
can either run mount -a or reboot the
system.

19.8.3. Soft-dependencies

Soft-dependencies (softdeps) is a mechanism that does not write
meta-data to disk immediately, but it is written in an
ordered fashion, which keeps the filesystem consistent in case of a crash.
The main benefit of softdeps is processing speed.
Soft-dependencies have some sharp edges, so beware! Also note that
soft-dependencies will not be present in any releases past 5.x. See
Section 19.8.4, “Journaling” for information about WAPBL,
which is the replacement for soft-dependencies.

Soft-dependencies can be enabled by adding "softdep" to the
filesystem options in /etc/fstab.
Let's look at an example of /etc/fstab:

More information about softdep capabilities can be found on
the author's page.

19.8.4. Journaling

Journaling is a mechanism which puts written data in a so-called
"journal" first, and in a second step the data from the journal is
written to disk. In the event of a system crash, data that was
not written to disk but that is in the journal can be replayed, and
will thus get the disk into a proper state. The main effect of this
is that no file system check (fsck) is needed after a rough
reboot. As of 5.0, NetBSD includes WAPBL, which provides journaling for
FFS.

Journaling can be enabled by adding "log" to the filesystem
options in /etc/fstab.
Here is an example which enables journaling for the root
(/), /var, and
/usr file systems:

Besides tuning those parameters, disabling write-back caching
on wd(4) devices may be beneficial. See the
dkctl(8) man page for details.

More is available in the NetBSD mailing list archives. See
this and
this mail.

19.9. Kernel Tuning

While many system parameters can be changed with sysctl, many
improvements by using enhanced system software, layout of the
system and managing services (moving them in and out of inetd
for example) can be achieved as well. Tuning the kernel however
will provide better performance, even if it appears
to be marginal.

19.9.2. Configuring the Kernel

Configuring a kernel in NetBSD can be daunting. This is because of
multiple line dependencies within the configuration file itself,
however, there is a benefit to this method and that is, all it really
takes is an ASCII editor to get a new kernel configured and some
dmesg output. The kernel configuration file is under
src/sys/arch/ARCH/conf where ARCH is your
architecture (for example,
on a SPARC it would be under
src/sys/arch/sparc/conf).

After you have located your kernel config file, copy it and remove
(comment out) all the entries you don't need. This is where
dmesg(8) becomes your friend. A clean dmesg(8)-output
will show all of the
devices detected by the kernel at boot time. Using dmesg(8)
output, the device options really needed can be determined.

19.9.2.1. Some example Configuration Items

In this example, an ftp server's kernel is being
reconfigured to run
with the bare minimum drivers and options and any other items that
might make it run faster (again, not necessarily smaller, although
it will be). The first thing to do is take a look at some of the
main configuration items. So, in
/usr/src/sys/arch/i386/conf the
GENERIC file is copied to FTP, then the file FTP edited.

At the start of the file there are a bunch of options beginning
with maxusers, which will be left alone, however, on larger
multi-user systems it might be help to crank that value up a bit.
Next is CPU support, looking at the dmesg output this is seen:

cpu0: Intel Pentium II/Celeron (Deschutes) (686-class), 400.93 MHz

Indicating that only the options I686_CPU options
needs to be used.
In the next section, all options are left alone except the
PIC_DELAY which is recommended unless it is an older machine.
In this case it is enabled since the 686 is “relatively new.”

Between the last section all the way down to compat options there
really was no need to change anything on this particular system.
In the compat section, however, there are several options that do
not need to be enabled, again this is because this machine is
strictly a FTP server, all compat options were turned off.

The next section is File systems, and again,
for this server very
few need to be on, the following were left on:

IPFILTER_LOG is a nice one to have around since the server
will be running ipf.

The next section is verbose messages for various subsystems,
since this machine is already running and had no major problems,
all of them are commented out.

19.9.2.2. Some Drivers

The configurable items in the config file are
relatively few and
easy to cover, however, device drivers are a different story.
In the following examples, two drivers are examined and their
associated “areas” in the file trimmed down.
First, a small
example: the cdrom, in dmesg, is the following lines:

Now, it is time to track that section down in the
configuration file.
Notice that the "cd"-drive is on an atapibus and requires
pciide support.
The section that is of interest in this case is the kernel
config's "IDE and related devices" section.
It is worth noting at this point, in and around
the IDE section are
also ISA, PCMCIA etc., on this machine in the dmesg(8)
output there are
no PCMCIA devices, so it stands to reason
that all PCMCIA references
can be removed. But first, the "cd" drive.

At the start of the IDE section is the following:

...
wd* at atabus? drive ? flags 0x0000
...
atapibus* at atapi?
...

Well, it is pretty obvious that those lines
need to be kept. Next is this:

There is the ex device. So all of the rest under the PCI section
can be removed. Additionally, every single line all the way down
to this one:

exphy* at mii? phy ? # 3Com internal PHYs

can be commented out as well as the remaining.

19.9.2.3. Multi Pass

When I tune a kernel, I like to do it remotely
in an X windows session,
in one window the dmesg output, in the other the config file. It
can sometimes take a few passes to rebuild a very trimmed kernel
since it is easy to accidentally remove dependencies.

19.9.3. Building the New Kernel

Now it is time to build the kernel and put it in place.
In the
conf directory on the ftp server, the following command
prepares the build:

$config FTP

When it is done a message reminding me to make
depend will display, next:

$cd ../compile/FTP$make depend && make

When it is done, I backup the old kernel and drop
the new one in place:

#cp /netbsd /netbsd.orig#cp netbsd /

Now reboot. If the kernel cannot boot, stop the boot process
when prompted and type boot netbsd.orig to
boot from the previous kernel.

19.9.4. Shrinking the NetBSD kernel

When building a kernel for embedded systems, it's often
necessary to modify the Kernel binary to reduce space or memory
footprint.

19.9.4.1. Removing ELF sections and debug information

We already know how to remove Kernel support for drivers
and options that you don't need, thus saving memory and
space, but you can save some KiloBytes of space by
removing debugging symbols and two ELF sections
if you don't need them: .comment and
.ident. They are used for storing RCS
strings viewable with ident(1) and a gcc(1)
version string. The following examples assume you have
your TOOLDIR under
/usr/src/tooldir.NetBSD-2.0-i386
and the target architecture is i386.

On the third column we can see the size of the sections
in hexadecimal form. By summing
.comment and .ident
sizes we know how much we're going to save with their
removal: around 120KB (= 52640 + 72164 = 0xcda0 + 0x119e4).
To remove the sections and debugging symbols that may be
present, we're going to use strip(1):

Chapter 20. NetBSD Veriexec subsystem

Veriexec is NetBSD's file integrity subsystem. It's kernel
based, hence can provide some protection even in the case of a root
compromise.

20.1. How it works

Veriexec works by loading a specification file, also called the
signatures file, to the
kernel. This file contains information about files Veriexec
should monitor, as well as their digital fingerprint (along with
the hashing algorithm used to produce this fingerprint), and
various flags that will be discussed later.

At the moment, the following hashing algorithms are
supported by Veriexec:
MD5,
SHA1,
SHA256,
SHA384,
SHA512, and
RMD160.

20.2. Signatures file

An entry in the Veriexec signatures file looks like
this:

/path/to/file algorithm fingerprint flags

Where the first element, the path, must always be an
absolute path. The algorithm is one of the algorithms listed
above, and fingerprint is the ASCII fingerprint.

20.3. Generating fingerprints

You can generate ASCII fingerprints for each
algorithm using the following tools:

Each entry may be associated with zero or more flags.
Currently, these flags indicate how the file the entry is describing
should be accessed.
Note that this access type is enforced only in strict level 2 (IPS
mode) and above.

The access types you can use are “DIRECT”,
“INDIRECT”, and “FILE”.

DIRECT access
means that the file is executed directly, and not invoked
as an interpreter for some script, or opened with an editor.
Usually, most programs you use will be accessed using this
mode:

%ls /tmp%cp ~/foo /tmp/bar%rm ~/foo

INDIRECT
access means that the file is executed indirectly, and is
invoked to interpret a script. This happens usually when
scripts have a #! magic as their first line. For example,
if you have a script with the following as its first
line:

#!/bin/sh

And you run it as:

%./script.sh

Then /bin/sh will be executed
indirectly -- it will be invoked to interpret the
script.

FILE entries
refer to everything which is not (or should not) be
an executable. This includes shared libraries,
configuration files, etc.

Veriexec allows you to specify more than one way to access a
file in an entry. For example, even though
/usr/bin/perl is mostly used as an
interpreter, it may be desired to be able to execute it
directly, too:

/usr/bin/perl MD5 914aa8aa47ebd79ccd7909a09ed61f81 DIRECT, INDIRECT

Shell scripts using #! magic to be “executable”
also require two access types: We need them to be
“DIRECT” so we can execute them, and we need them
to be “FILE” so that the kernel can feed their
contents to the interpreter they define:

/usr/src/build.sh MD5 e80dbb4c047ecc1d84053174c1e9264a DIRECT, FILE

To make it easier to create signature files, and to make the
signature files themselves more readable, Veriexec allows you to use
the following aliases:

Table 20.2. Veriexec access type aliases

Alias

Expansion

PROGRAM

DIRECT

INTERPRETER

INDIRECT

SCRIPT

DIRECT, FILE

LIBRARY

FILE

Sample scripts for generating fingerprints are available in
/usr/share/examples/veriexecctl. After you've
generated a signatures file, you should save it as
/etc/signatures, and enable Veriexec in
rc.conf:

veriexec=YES

20.4. Strict levels

Since different people might want to use Veriexec for
different purposes, we also define four strict levels, ranging
0-3, and named “learning”, “IDS”,
“IPS”, and “lockdown” modes.

In strict level 0, learning
mode, Veriexec will act passively and simply warn about any
anomalies. Combined with verbose level 1, running the system in
this mode can help you fine-tune the signatures file. This is
also the only strict level in which you can load new entries
to the kernel.

Strict level 1, or IDS
mode, will deny access to files with a fingerprint
mismatch. This mode suits mostly to users who simply want to
prevent access to files which might've been maliciously modified
by an attacker.

Strict level 2, IPS mode,
takes a step towards trying to protect the integrity of
monitored files. In addition to preventing access to files with
a fingerprint mismatch, it will also deny write access and
prevent the removal of monitored files, and enforce the way
monitored files are accessed. (as the signatures file
specifies).

Lockdown mode (strict level 3)
can be used in highly critical situations such as custom made
special-purpose machines, or as a last line of defense after an
attacker compromised the system and we want to prevent traces
from being removed, so we can perform post-mortem analysis. It will
prevent the creation of new files, and deny access to files not
monitored by Veriexec.

It's recommended to first run Veriexec in strict level 0 and
verbose level 1 to fine-tune your signatures file, ensuring that
desired applications run correctly, and only then raise the
strict level (and lower the verbosity level). You can use
/etc/sysctl.conf to auto raise the
strict level to the desired level after a reboot:

kern.veriexec.strict=1

20.5. Veriexec and layered file systems

Veriexec can be used on NFS file systems on the client side
and on layered file systems such as the union file system. The
files residing on these file systems need only be specified in the
/etc/signatures file and that the file
systems be mounted prior to the fingerprints being loaded.

If you are going to use layered file systems then you must
ensure that you include the fingerprint for files you want
protected at every layer. If you fail to do this someone could
overwrite a file protected by Veriexec by using a different layer
in a layered file system stack. This limitation may be removed in
later versions of NetBSD.

It's recommended that if you are not going to use layered
file systems nor NFS then these features should be disabled in
they kernel configuration. If you need to use layered file
systems then you must follow the instructions in the previous
paragraph and ensure that the files you want protected have
fingerprints at all layers. Also you should raise securelevel to
2 after all mounts are done:

kern.securelevel=2

To prevent new layers being mounted which could compromise
Veriexec's protection.

20.6. Kernel configuration

To use Veriexec, aside from creating a signatures file, you
should enable (uncomment) it in your kernel's config file: (e.g.
/usr/src/sys/arch/i386/conf/GENERIC):

21.1. Introduction

Bluetooth is a digital radio protocol used for short range
and low power communications. NetBSD includes support
for the Bluetooth protocol stack, and some integration of
service profiles into the NetBSD device framework.

The lower layers of the Bluetooth protocol stack pertaining
to actual radio links between devices are handled inside the
Bluetooth Controller, which communicates with the Host computer
using the “Host Controller Interface” (HCI)
protocol which can be accessed via a raw packet BTPROTO_HCI
socket interface.

Most of the Bluetooth protocols or services layer atop the
“Link Layer Control and Adaptation Protocol”
(L2CAP), which can be accessed via a BTPROTO_L2CAP socket
interface. This provides sequential packet connections to
remote devices, with up to 64k channels. When an L2CAP
channel is opened, the protocol or service that is required
is identified by a “Protocol/Service Multiplexer”
(PSM) value.

Service Discovery in the Bluetooth environment is provided for
by the sdp(3) library functions and the sdpd(8) daemon,
which keeps a database of locally registered services and makes
the information available to remote devices performing queries.
The sdpquery(1) tool can be used to query local and remote
service databases.

Security on Bluetooth links can be enabled by encryption and
authentication options to btconfig(8) which apply to all
baseband links that a controller makes, or encryption and
authentication can be enabled for individual RFCOMM and L2CAP
links as required. When authentication is requested, a PIN is
presented by each side (generally entered by the operator, some
limited input devices have a fixed PIN). The controller uses
this PIN to generate a Link Key and reports this to the Host
which may be asked to produce it to authenticate subsequent
connections. On NetBSD, the bthcid(8) daemon is
responsible for storing link keys and responding to Link Key
Requests, and also provides an interface to allow unprivileged
users to specify a PIN with a PIN client, such as
btpin(1).

21.2. Supported Hardware

Because Bluetooth controllers normally use the standard
HCI protocol as specified in the “Bluetooth 2.0
Core” documentation to communicate with the host,
the NetBSD Bluetooth stack is compatible with most controllers,
only requiring an interface driver, with the following drivers
available in NetBSD 5.0:

bcsp(4) provides a tty(4) line discipline to send
and receive BlueCore Serial Protocol packets over a serial
line as described in the “BlueCore Serial Protocol
(BCSP)” specification.

btuart(4) provides a tty(4) line discipline to
send and receive Bluetooth packets over a serial line as
described in the “Bluetooth Host Controller Interface
[Transport Layer] specification, Vol 4 part A”.

When support is not already compiled in, it can be added to
the kernel configuration file for any platform that supports
USB and/or PCMCIA (see Section 19.9, “Kernel Tuning”),
using the following declarations, as required:

Some older USB Bluetooth dongles based on the Broadcom
BCM2033 chip require firmware to be loaded before they can
function, and these devices will be attached to ugen(4).
Use the “sysutils/bcmfw” package from the NetBSD
Package Collection, to load firmware and enable these.

21.3. System Configuration

To fully enable Bluetooth services on NetBSD, the following
line should be added to the /etc/rc.conf
file.

bluetooth=YES

and either reboot, or execute the following command:

#/etc/rc.d/bluetooth start

Note

Configuration of Bluetooth controllers is done with the
btconfig(8) program, and the above argument enables
only basic functionality, see the manual page for other
useful options.

Important

bthcid(8)must be running in order
to make authenticated connections with remote devices, and
authentication may be requested by either device.

21.4. Human Interface Devices

Support for “Human Interface Devices” (HIDs),
which operate using the USB HID protocol over a pair of L2CAP
channels is provided by the bthidev(4) driver. Currently,
keyboards and mice are catered for, and attach to wscons(4)
as normal.

21.4.1. Mice

First, you must discover the BDADDR of the device. This
may be printed on the box, but the easiest way is to place
the device into discoverable mode and perform a device inquiry
with the appropriate controller:

For ease of use, you may want to add the address to the
/etc/bluetooth/hosts file, so that
you can refer to the mouse by alias:

#echo "00:14:51:c1:b9:2d mouse" >>/etc/bluetooth/hosts

Now, you can query the mouse, which will likely request
authentication before it accepts connections. The fixed
PIN should be listed in the documentation, though
“0000” is often used. Set the PIN first
using the btpin(1) program:

The device capabilities are cached by btdevctl(8), and
to reattach the mouse at system startup, place an entry in
/etc/bluetooth/btdevctl.conf. The
bthidev(4) driver will attempt to connect once, though
mice will usually be sleeping and may require a tap on the
shoulder to awaken, in which case they should initiate the
connection to the host computer.

21.4.2. Keyboards

First, you must discover the BDADDR of the device. This
may be printed on the box, but the easiest way is to place
the device into discoverable mode and perform a device
inquiry with the appropriate controller:

For ease of use, you may want to add the address to the
/etc/bluetooth/hosts file, so that
you can refer to the keyboard by alias:

#echo "00:0a:95:45:a4:a0 keyboard" >>/etc/bluetooth/hosts

Now, you can query the keyboard, which will likely request
authentication before it accepts connections. The PIN will
need to be entered on the keyboard, and we can generate a
random PIN, using the btpin(1) program.

This tells you that the keyboard has responded to an SDP
query, and the device capabilities are shown. Note that
encryption is enabled by default, since encrypted connection
support is mandatory for Bluetooth keyboards. You may now
attach to the system:

The device capabilities are cached by btdevctl(8), and
to reattach the keyboard at system startup, place an entry in
/etc/bluetooth/btdevctl.conf. The
bthidev(4) driver will attempt to connect once when
attached, but if the keyboard is not available at that time,
you may find that pressing a key will cause it to wake up and
initiate a connection to the last paired host.

21.5. Personal Area Networking

Personal Area Networking services over Bluetooth are provided
by the btpand(8) daemon which can assume all roles from
the PAN profile and connects remote devices to the system
through a tap(4) virtual Ethernet interface.

21.5.1. Personal Area Networking User

The "Personal Area Networking User" role is the client that
accesses Network services on another device. For instance,
in order to connect to the Internet via a smart phone with
the NAP profile, make sure that the phone is discoverable,
then:

reveals that the NAP service is available and that it
provides IPv4, ARP and IPv6 protocols.

Most likely, the phone will request authentication before
it allows connections to the NAP service, so before you
make the first connection you may need to provide a PIN,
which can be randomly generated. Then start btpand(8):

Finally, you will need to configure the tap(4) interface,
but the phone should have a DHCP server so dhcpcd(8)
will do that for you.

#dhcpcd tap0

Now you can surf the World Wide Web, but watch your data
usage unless you have a comprehensive data plan.

21.6. Serial Connections

Serial connections over Bluetooth are provided for by the
RFCOMM protocol, which provides up to 30 channels multiplexed
over a single L2CAP channel. This streamed data protocol can be
accessed using the BTPROTO_RFCOMM socket interface, or via the
rfcomm_sppd(1) program.

For instance, you can make a serial connection to the
“Dial Up Networking” (DUN) service of a mobile
phone in order to connect to the Internet with PPP. First you
should discover the BDADDR of the phone, and add this to your
/etc/bluetooth/hosts for ease of use.
Place the phone into Discoverable mode, and perform an inquiry
from the appropriate controller:

Most likely, the phone will request authentication before
it allows connections to the DUN service, so before you
make the first connection you may need to provide a PIN,
which can be randomly generated. You can use
rfcomm_sppd in stdio mode to check that
the connection is working ok, press ^C
to disconnect and return to the shell, for example:

To have pppd(8) connect to the DUN service of your
phone automatically when making outbound connections, add the
following line to the /etc/ppp/options
file in place of the normal tty declaration:

pty "rfcomm_sppd -d ubt0 -a phone -s DUN -m encrypt"

21.7. Audio

Isochronous (SCO) Audio connections may be created on a
baseband radio link using either the BTPROTO_SCO socket
interface, or the btsco(4) audio device driver. While
the specification says that up to three such links can be
made between devices, the current Bluetooth stack can only
handle one with any dignity.

Important

When using SCO Audio with USB Bluetooth controllers,
you will need to enable isochronous data, and calculate
the MTU that the device will use, see ubt(4) and
btconfig(8).

Note

SCO Audio does not work properly with the bt3c(4)
driver, use a USB controller for best results.

Note

SCO Audio will not work with ehci(4) USB controllers,
since support for Isochronous data over EHCI is missing
in NetBSD.

21.7.1. SCO Audio Headsets

Audio connections to Bluetooth Headsets are possible
using the btsco(4) audio driver, and the bthset(1)
program. First, you need to discover the BDADDR of the
headset, and will probably wish to make an alias in your
/etc/bluetooth/hosts file for ease
of use. Place the headset into discoverable mode and
perform an inquiry with the appropriate controller:

You will need to pair with the headset the first time you
connect, the fixed PIN should be listed in the manual (often,
“0000” is used). btdevctl(8) will query the
device and attach the btsco(4) audio driver.

and you should now be able to transfer 8khz samples to
and from /dev/audio1 using any program
that supports audio, such as audioplay(1) or
audiorecord(1). Adjusting the mixer values should work
when playing though you may find that when opening a
connection, the headset will reset the volume to the last
known settings.

The device capabilities are cached by btdevctl(8), and
to reattach the btsco(4) driver at system startup, add
an entry to /etc/bluetooth/btdevctl.conf.

21.7.2. SCO Audio Handsfree

Audio connections to Bluetooth mobile phones using
the Handsfree profile are possible with the
“comms/bthfp” program from the NetBSD Package
Collection.

First, you need to discover the BDADDR of the phone,
and will probably wish to make an alias in your
/etc/bluetooth/hosts file for ease of
use. Place the phone into discoverable mode and perform
an inquiry with the appropriate controller:

and you will be able to use the
bthfp program to access the
Handsfree profile. The first time you connect, you may
need to use a PIN to pair with the phone, which can be
generated randomly by btpin(1):

When the phone rings, just press a
to answer, and audio should be routed through the
/dev/audio device. Note that you will
need a microphone connected in order to speak to the remote
party.

21.8. Object Exchange

NetBSD does not currently have any native OBEX
capability, see the “comms/obexapp” or
“comms/obexftp” packages from the NetBSD
Package Collection.

21.9. Troubleshooting

When nothing seems to be happening, it may be useful to try
the hcidump program from the
“sysutils/netbt-hcidump” package in the NetBSD
Package Collection. This has the capability to dump packets
entering and leaving Bluetooth controllers on NetBSD, which
is greatly helpful in pinpointing problems.

22.1. Installing the boot manager

Sysinst, the NetBSD installation program usually installs the NetBSD
boot manager on the hard disk.
The boot manager can also be installed or reconfigured at a later
time, if needed, with the fdisk command.
For example:

#fdisk -B wd0

If NetBSD doesn't boot from the hard disk, you can boot it from
the installation floppy and start the kernel on the hard disk.
Insert the installation disk and, at the boot prompt, give the
following command:

>boot wd0a:netbsd

This boots the kernel on the hard disk (use the correct device,
for example sd0a for a SCSI disk).

Note

Sometimes fdisk -B doesn't give the expected
result (at least it happened to me), probably if you
install/remove other operating systems like Windows 95 or
Linux with LILO.
In this case, try running fdisk -i (which
is known as fdisk /mbr from DOS) and
then run again fdisk from NetBSD.

22.2. Deleting the disklabel

Though this is not an operation that you need to perform
frequently, it can be useful to know how to do it in case of
need.
Please be sure to know exactly what you are doing before
performing this kind of operation.
For example:

#dd if=/dev/zero of=/dev/rwd0c bs=8k count=1

The previous command deletes the disklabel (not the MBR partition
table).
To completely delete the disk, the whole device rwd0d
must be used.
For example:

#dd if=/dev/zero of=/dev/rwd0d bs=8k

The commands above will only work as expected on the i386 and amd64 ports
of NetBSD. On other ports, the whole device will end in c, not d (e.g.
rwd0c).

22.3. Speaker

I found this tip on a mailing list (I don't remember the author).
To output a sound from the speaker (for example at the end of a
long script) the spkr driver can be used in
the kernel config, which is mapped on
/dev/speaker. For example:

echo 'BPBPBPBPBP' > /dev/speaker

Note

The spkr device is not enabled in the
generic kernel; a customized kernel is needed.

22.4. Forgot root password?

If you forget root's password, not all is lost and you can still
recover the system with the following steps: boot
single user, mount / and change root's password.
In detail:

Boot single user: when the boot prompt appears and the five
seconds countdown starts, give the following command:

If you get the error “Password file is busy”,
please see the section below.

22.5. Password file is busy?

If you try to modify a password and you get the mysterious
message “Password file is busy”, it probably
means that the file /etc/ptmp has not
been deleted from the system. This file is a temporary copy
of the /etc/master.passwd file; check
that you are not losing important information and then
delete it:

#rm /etc/ptmp

Note

If the file /etc/ptmp exists you can
also receive a warning message at system startup. For
example:

root: password file may be incorrect - /etc/ptmp exists

22.6. Adding a new hard disk

This section describes how to add a new hard disk to an
already working NetBSD system. In the following example a
new SCSI controller and a new hard disk, connected to the
controller, will be added. If you don't need to add a new
controller, skip the relevant part and go to the hard disk
configuration. The installation of an IDE hard disk is
identical; only the device name will be different
(wd# instead of
sd#).

As always, before buying new hardware, consult the hardware
compatibility list of NetBSD and make sure that the new device
is supported by the system.

When the SCSI controller has been physically installed in the
system and the new hard disk has been connected, it's time to
restart the computer and check that the device is correctly
detected, using the dmesg command. This
is the sample output for an NCR-875 controller:

In this example the hard disk already contains a DOS
partition, which will be deleted and replaced with a native
NetBSD partition. The command fdisk -u sd0
allows to modify interactively the partitions. The modified
data will be written on the disk only before exiting and fdisk
will request a confirmation before writing, so you can work
relaxedly.

Disk geometries

The geometry of the disk reported by fdisk can appear
confusing. Dmesg reports 4226725 sectors with 8188/3/172
for C/H/S, but 8188*3*172 gives 4225008 and not 4226725.
What happens is that most modern disks don't have a fixed
geometry and the number of sectors per track changes
depending on the cylinder: the only interesting parameter
is the number of sectors. The disk reports the C/H/S
values but it's a fictitious geometry: the value 172 is the
result of the total number of sectors (4226725) divided by
8188 and then by 3.

To make things more confusing, the BIOS uses yet another
“fake” geometry (C/H/S 524/128/63) which gives
a total of 4225536, a value which is a better approximation
to the real one than 425008. To partition the disk we will
use the BIOS geometry, to maintain compatibility with other
operating systems, although we will lose some sectors
(4226725 - 4225536 = 1189 sectors = 594 KB).

To create the BIOS partitions the command fdisk -u
must be used; the result is the following:

Note

When the disklabel has been created it is possible to
optimize it studying the output of the command
newfs -N /dev/rsd0a, which warns about
the existence of unallocated sectors at the end of a
disklabel partition. The values reported by newfs can be
used to adjust the sizes of the partitions with an
iterative process.

The final operation is the creation of the file systems for
the newly defined partitions (a and
e).

#newfs /dev/rsd0a#newfs /dev/rsd0e

The disk is now ready for usage, and the two partitions can
be mounted. For example:

#mount /dev/sd0a /mnt

If this succeeds, you may want to put an entry for the partition
into /etc/fstab.

22.7. How to rebuild the devices in /dev

First shutdown to single user, partitions still mounted
“rw”
(read-write); You can do that by just typing shutdown
now while you are in multi user mode, or reboot with
the -s option and make /
and /dev read-writable by doing.

23.1. Audience

This section explains various aspects of networking. It is
intended to help people with little knowledge about networks
to get started. It is divided into three big parts.
We start by giving a general overview of how networking works
and introduce the basic concepts. Then we go into details for
setting up various types of networking in the second parts,
and the third part of the networking section covers a number
of “advanced” topics that go beyond the
basic operation as introduced in the first two sections.

The reader is assumed to know about basic system
administration tasks: how to become root, edit files, change
permissions, stop processes, etc. See the other chapters of
this NetBSD guide and e.g. [AeleenFrisch] for
further information on this topic. Besides that, you should
know how to handle the utilities we're going to set up here,
i.e. you should know how to use telnet, FTP, ... I will not
explain the basic features of those utilities, please refer to
the appropriate man-pages, the references listed or of course
the other parts of this document instead.

This introduction to TCP/IP Networking was written with the
intention in mind to give starters a basic knowledge. If you
really want to know what it's all about, read [CraigHunt]. This
book does not only cover the basics, but goes on and explains all
the concepts, services and how to set them up in detail. It's
great, I love it! :-)

23.2. Supported Networking Protocols

There are several protocol suites supported by NetBSD, most of
which were inherited from NetBSD's predecessor, 4.4BSD, and
subsequently enhanced and improved.
The first and most important one today is
DARPA's Transmission Control
Protocol/Internet Protocol (TCP/IP).
Other protocol suites available
in NetBSD include the Xerox Network System
(XNS) which was only implemented at
UCB to connect isolated machines to the
net, Apple's AppleTalk protocol suite and the
ISO protocol suite,
CCITT X.25 and ARGO
TP.
They are only used in some special applications these days.

Today, TCP/IP is the most widespread protocol of the ones
mentioned above. It is implemented on almost every hardware and
operating system, and it is also the most-used protocol in
heterogenous environments. So, if you just want to connect your
computer running NetBSD to some other machine at home or you want
to integrate it into your company's or university's network,
TCP/IP is the right choice. Besides the "old" IP version 4,
NetBSD also supports the "new" IP version 6 (IPv6) since NetBSD
1.5, thanks to code contributed by the KAME project.

There are other protocol suites such as DECNET, Novell's
IPX/SPX or Microsoft's NetBIOS, but these are not currently
supported by NetBSD. These protocols differ from TCP/IP in that
they are proprietary, in contrast to the others, which are
well-defined in several RFCs and other open
standards.

23.3.1. Serial Line

If your remote host is only reachable via telephone, you
can use a modem to access it.

Many computers have a serial port, and the
cable needed is rather cheap.

The disadvantage of a serial connection is that it's slower
than other methods. NetBSD can use at most 115200 bit/s, making
it a lot slower than e.g. Ethernet's minimum 10 Mbit/s and
Arcnet's 4 Mbit/s.

There are two possible protocols to connect a host running
NetBSD to another host using a serial line (possibly
over a phone-line):

Serial Line IP (SLIP)

Point to Point Protocol (PPP)

The choice here depends on whether you use a dial-up
connection through a modem or if you use a static connection
(null-modem or leased line). If you dial up for your IP
connection, it's wise to use PPP as it offers some
possibilities to auto-negotiate IP-addresses and routes, which
can be quite painful to do by hand. If you want to connect to
another machine which is directly connected, use SLIP, as this
is supported by about every operating system and more easy to
set up with fixed addresses and routes.

PPP on a direct connection is a bit difficult to setup, as
it's easy to timeout the initial handshake; with SLIP, there's
no such initial handshake, i.e. you start up one side, and
when the other site has its first packet, it will send it over
the line.

23.3.2. Ethernet

Ethernet is the medium commonly used to build local area
networks (LANs) of interconnected
machines within a limited area such as an office, company or
university campus. Ethernet is based on a bus structure to
which many
machines can connect to, and communication always happens
between two nodes at a time. When two or more nodes want to
talk at the same time, both will restart communication after
some timeout. The technical term for this is
CSMA/CD (Carrier Sense w/ Multiple Access
and Collision Detection).

Initially, Ethernet hardware consisted of a thick (yellow)
cable that machines tapped into using special connectors
that poked through the cable's outer shielding. The
successor of this was called 10base5, which used BNC-type
connectors for tapping in special T-connectors and
terminators on both ends of the bus. Today, ethernet is
mostly used with twisted pair lines which are used in a
collapsed bus system that are contained in switches or
hubs. The twisted pair lines give this type of media its
name - 10baseT for 10 Mbit/s networks, and 100baseT for 100
MBit/s ones. In switched environments there's also the
distinction if communication between the node and the switch
can happen in half- or in full duplex mode.

23.4. TCP/IP Address Format

TCP/IP uses 4-byte (32-bit) addresses in the current
implementations (IPv4), also called IP-numbers
(Internet-Protocol numbers), to address hosts.

TCP/IP allows any two machines to communicate directly. To
permit this all hosts on a given network must have a unique
IP address. To assure this, IP addresses are administrated
by one central organisation, the InterNIC. They give
certain ranges of addresses (network-addresses) directly
to sites which want to participate in the internet or to
internet-providers, which give the addresses to their
customers.

If your university or company is connected to the Internet, it
has (at least) one such network-address for its own use,
usually not assigned by the InterNIC directly, but rather
through an Internet Service Provider (ISP).

If you just want to run your private network at home, see below
on how to “build” your own IP addresses. However, if
you want to connect your machine to the (real :-) Internet, you
should get an IP addresses from your local network-administrator or
-provider.

IP addresses are usually written in
“dotted quad”-notation
- the four bytes are written down in decimal (most significant
byte first),
separated by dots. For example, 132.199.15.99 would be a valid
address. Another way to write down IP-addresses would be as
one 32-bit hex-word, e.g. 0x84c70f63. This is not as convenient
as the dotted-quad, but quite useful at times, too. (See
below!)

Figure 23.1. IPv4-addresses are divided into more significant network- and
less significant hostbits

In the above example, the network-address is 132.199.0.0
(host-bits are set to 0 in network-addresses) and the host's
address is 15.99 on that network.

How do you know that the host's address is 16 bit wide? Well,
this is assigned by the provider from which you get your
network-addresses. In the classless inter-domain routing
(CIDR)
used today, host fields are usually between as little as 2 to
16 bits wide, and the number of network-bits is written after
the network address, separated by a “/”, e.g. 132.199.0.0/16
tells that the network in question has 16 network-bits.
When talking about the “size” of a network,
it's usual to only
talk about it as “/16”, “/24”, etc.

Before CIDR was used, there used to be four classes of
networks. Each one starts with a certain bit-pattern
identifying it. Here are the four classes:

Class A starts with “0” as most significant bit. The
next seven bits of a class A address identify the
network, the remaining 24 bit can be used to address
hosts. So, within one class A network there can be
224
hosts. It's not very likely that you (or your
university, or company, or whatever) will get a whole
class A address.

The CIDR notation for a class A network with its eight
network bits is an “/8”.

Class B starts with “10” as most significant
bits. The
next 14 bits are used for the networks address and the
remaining 16 bits can be used to address more than 65000
hosts. Class B addresses are very rarely given out today,
they used to be common for companies and universities
before IPv4 address space went scarce.

The CIDR notation for a class B network with its 16
network bits is an “/16”.

Returning to our above example, you can see that
132.199.15.99 (or 0x84c70f63, which is more appropriate
here!) is on a class B network, as 0x84... =
1000... (base 2).

Therefore, the address 132.199.15.99 can be split into
an network-address of 132.199.0.0 and a host-address of
15.99.

Class C is identified by the MSBs being
“110”, allowing
only 256 (actually: only 254, see below) hosts on each
of the 221 possible class C
networks. Class C addresses
are usually found at (small) companies.

The CIDR notation for a class C network with its 24
network bits is an “/24”.

There are also other addresses, starting with
“111”. Those are used for special purposes
(e. g. multicast-addresses) and are not of interest
here.

Please note that the bits which are used for identifying the
network-class are part of the network-address.

When separating host-addresses from network-addresses, the
“netmask” comes in handy. In this mask, all the network-bits
are set to “1”, the host-bits are “0”. Thus, putting together
IP-address and netmask with a logical AND-function, the
network-address remains.

To continue our example, 255.255.0.0 is a possible netmask for
132.199.15.99. When applying this mask, the network-address
132.199.0.0 remains.

For addresses in CIDR notation, the number of network-bits
given also says how many of the most significant bits of the
address must be set to “1” to get the netmask for the
corresponding network. For classful addressing, every
network-class has a fixed default netmask assigned:

Class A (/8): default-netmask: 255.0.0.0, first byte of address:
1-127

Another thing to mention here is the “broadcast-address”. When
sending to this address, all hosts on the
corresponding network will receive the message sent. The
broadcast address is characterized by having all host-bits set
to “1”.

Taking 132.199.15.99 with its netmask 255.255.0.0 again, the
broadcast-address would result in 132.199.255.255.

You'll ask now: But what if I want a host's address to be all
bits “0” or “1”? Well, this doesn't work, as network- and
broadcast-address must be present! Because of this, a class B
(/16) network can contain at most
216-2 hosts, a class C (/24)
network can hold no more than 28-2
= 254 hosts.

Besides all those categories of addresses, there's the special
IP-address 127.0.0.1 which always refers to the “local” host,
i.e. if you talk to 127.0.0.1 you'll talk to yourself without
starting any network-activity. This is sometimes useful to use
services installed on your own machine or to play around if you
don't have other hosts to put on your network.

Let's put together the things we've introduced in this section:

IP-address

32 bit-address, with network- and host-bits.

Network-address

IP-address with all host bits set to “0”.

Netmask

32-bit mask with “1” for network- and “0” for host-bits.

Broadcast

IP-address with all host bits set “1”.

localhost's address

The local host's IP address is always 127.0.0.1.

23.5. Subnetting and Routing

After talking so much about netmasks, network-, host- and
other addresses, I have to admit that this is not the whole
truth.

Imagine the situation at your university, which usually has a
class B (/16) address, allowing it to have up to
216 ~= 65534
hosts on that net. Maybe it would be a nice thing to have all
those hosts on one single network, but it's simply not
possible due to limitations in the transport media commonly
used today.

For example, when using thinwire ethernet, the maximum length
of the cable is 185 meters. Even with repeaters in between,
which refresh the signals, this is not enough to cover all the
locations where machines are located. Besides that, there is
a maximum number of 1024 hosts on one ethernet wire, and
you'll lose quite a bit of performance if you go to this
limit.

So, are you hosed now? Having an address which allows more
than 60000 hosts, but being bound to media which allows far
less than that limit?

Well, of course not! :-)

The idea is to divide the “big” class B net into several
smaller networks, commonly called sub-networks or simply
subnets. Those subnets are only allowed to have, say, 254
hosts on them (i.e. you divide one big class B network into
several class C networks!).

To do this, you adjust your netmask to have more network- and
less host-bits on it. This is usually done on a byte-boundary,
but you're not forced to do it there. So, commonly your
netmask will not be 255.255.0.0 as supposed by a class B
network, but it will be set to 255.255.255.0.

In CIDR notation, you now write a “/24” instead of the
“/16” to show that 24 bits of the address are
used for identifying the network and subnet, instead of the
16 that were used before.

This gives you one additional network-byte to assign to each
(physical!) network. All the 254 hosts on that subnet can now
talk directly to each other, and you can build 256 such class
C nets. This should fit your needs.

To explain this better, let's continue our above example. Say
our host 132.199.15.99 (I'll call him dusk from now; we'll talk
about assigning hostnames later) has a netmask of
255.255.255.0 and thus is on the subnet 132.199.15.0/24. Let's
furthermore introduce some more hosts so we have something to
play around with, see Figure 23.2, “Our demo-network”.

Figure 23.2. Our demo-network

In the above network, dusk can talk directly to
dawn, as they are
both on the same subnet. (There are other hosts attached to
the 132.199.15.0/24-subnet but they are not of importance for
us now)

But what if dusk
wants to talk to a host on another subnet?

Well, the traffic will then go through one or more gateways
(routers), which are attached to two subnets. Because of this,
a router always has two different addresses, one for each of
the subnets it is on. The router is functionally transparent,
i.e. you don't have to address it to reach hosts on the
“other” side. Instead, you address that host directly and the
packets will be routed to it correctly.

Example. Let's say dusk wants to get some files
from the local ftp-server. As dusk can't reach ftp directly (because it's on
a different subnet), all its packets will be forwarded to its
"defaultrouter" rzi (132.199.15.1), which
knows where to forward the packets.

Dusk knows the
address of its defaultrouter in its network (rzi, 132.199.15.1), and it
will forward any packets to it which are not on the same
subnet, i.e. it will forward all IP-packets in which the third
address-byte isn't 15.

The (default)router then gives the packets to the appropriate
host, as it's also on the FTP-server's network.

In this example, all packets are
forwarded to the
132.199.1.0/24-network, simply because it's the network's
backbone, the most important part of the network, which
carries all the traffic that passes between several subnets.
Almost all other networks besides 132.199.15.0/24 are attached to
the backbone in a similar manner.

When we now want to reach a host which is located in the
132.199.16.0/24-subnet from dusk, it won't work routing it
to rzi, but you'll
have to send it directly to route2
(132.199.15.2). Dusk will have to know to
forward those packets to route2 and send all the others
to rzi.

When configuring dusk, you tell it to forward
all packets for the 132.199.16.0/24-subnet to route2, and all others to
rzi. Instead of
specifying this default as 132.199.1.0/24, 132.199.2.0/24,
etc., 0.0.0.0 can be used to set the default-route.

Returning to Figure 23.2, “Our demo-network”, there's a similar problem when
dawn wants to send
to noon, which is
connected to dusk
via a serial line running. When looking at the IP-addresses,
noon seems to be
attached to the 132.199.15.0-network, but it isn't
really. Instead, dusk is used as gateway, and
dawn will have to
send its packets to dusk, which will forward them
to noon then. The
way dusk is forced
into accepting packets that aren't destined at it but for a
different host (noon) instead is called “proxy
arp”.

The same goes when hosts from other subnets want to send to
noon. They have to
send their packets to dusk
(possibly routed via rzi),

23.6. Name Service Concepts

In the previous sections, when we talked about hosts, we
referred to them by their IP-addresses. This was necessary to
introduce the different kinds of addresses. When talking about
hosts in general, it's more convenient to give them “names”,
as we did when talking about routing.

Most applications don't care whether you give them an
IP address or a hostname. However, they'll use IP addresses
internally, and there are several methods for them to map
hostnames to IP addresses, each one with its own way of
configuration. In this section we'll introduce the idea behind
each method, in the next chapter, we'll talk about the
configuration-part.

The mapping from hostnames (and domainnames) to IP-addresses
is done by a piece of software called the “resolver”.
This is not an extra service, but some library routines which are
linked to every application using networking-calls. The
resolver will then try to resolve (hence the name ;-) the
hostnames you give into IP addresses. See [RFC1034] and [RFC1035] for details on
the resolver.

Hostnames are usually up to 256 characters long, and contain
letters, numbers and dashes (“-”); case is
ignored.

Just as with networks and subnets, it's possible (and
desirable) to group hosts into domains and subdomains. When
getting your network-address, you usually also obtain a
domainname by your provider. As with subnets, it's up to you
to introduce subdomains. Other as with IP-addresses,
(sub)domains are not directly related to (sub)nets; for
example, one domain can contain hosts from several subnets.

Figure 23.2, “Our demo-network” shows this: Both subnets 132.199.1.0/24 and
132.199.15.0/24 (and others) are part of the subdomain
“rz.uni-regensburg.de”. The
domain the University of Regensburg got from its IP-provider
is “uni-regensburg.de”
(“.de” is for
Deutschland, Germany), the subdomain “rz” is for Rechenzentrum,
computing center.

Hostnames, subdomain- and domainnames are separated by dots
(“.”). It's also possible to use more than one stage of
subdomains, although this is not very common. An example would
be fox_in.socs.uts.edu.au.

A hostname which includes the (sub)domain is also called a
fully qualified domain name (FQDN). For
example, the IP-address 132.199.15.99 belongs to the host with
the FQDN dusk.rz.uni-regensburg.de.

Further above I told you that the IP-address 127.0.0.1 always
belongs to the local host, regardless what's the “real”
IP-address of the host. Therefore, 127.0.0.1 is always mapped
to the name “localhost”.

The three different ways to translate hostnames into
IP addresses are: /etc/hosts, the Domain
Name Service (DNS) and the Network
Information Service (NIS).

23.6.1. /etc/hosts

The first and simplest way to translate hostnames into
IP-addresses is by using a table telling which IP address
belongs to which hostname(s). This table is stored in the
file /etc/hosts and has the following format:

IP-address hostname [nickname [...]]

Lines starting with a hash mark (“#”) are
treated as
comments. The other lines contain one IP-address and the
corresponding hostname(s).

It's not possible for a hostname to belong to several
IP addresses, even if I made you think so when talking about
routing. rzi for
example has really two distinct names for each of its two
addresses: rzi
and rzia (but
please don't ask me which name belongs to which address!).

Giving a host several nicknames can be convenient if you want
to specify your favorite host providing a special service
with that name, as is commonly done with FTP-servers. The
first (leftmost) name is usually the real (canonical) name of
the host.

Besides giving nicknames, it's also convenient to give a
host's full name (including domain) as its canonical name, and
using only its hostname (without domain) as a nickname.

Important: There
must be an entry mapping
localhost to 127.0.0.1 in /etc/hosts!

23.6.2. Domain Name Service (DNS)

/etc/hosts bears an inherent problem,
especially in big networks: when one host is added or one
host's address changes, all the
/etc/hosts files on all machines have to be
changed! This is not only time-consuming, it's also very
likely that there will be some errors and inconsistencies,
leading to problems.

Another approach is to hold only one hostnames-table
(-database) for a network, and make all the clients query
that “nameserver”. Updates will be made only on the
nameserver.

This is the basic idea behind the Domain Name Service (DNS).

Usually, there's one nameserver for each domain (hence
DNS), and every host (client) in that domain knows which
domain it is in and which nameserver to query for its domain.

When the DNS gets a query about a host which is not in its
domain, it will forward the query to a DNS which is either
the DNS of the domain in question or knows which DNS to ask
for the specified domain. If the DNS forwarded the query
doesn't know how to handle it, it will forward that query
again to a DNS one step higher. This is not ad infinitum,
there are several “root”-servers, which know about any
domain.

23.6.3. Network Information Service (NIS/YP)

Yellow Pages (YP) was invented by Sun
Microsystems. The name has been changed into Network
Information Service (NIS) because YP was
already a trademark of the British telecom. So, when I'm
talking about NIS you'll know what I mean. ;-)

There are quite some configuration files on a Unix-system,
and often it's desired to maintain only one set of those
files for a couple of hosts. Those hosts are grouped
together in a NIS-domain (which has nothing to do
with the domains built by using DNS!) and are usually
contained in one workstation cluster.

Examples for the config-files shared among those hosts are
/etc/passwd,
/etc/group and - last but not least -
/etc/hosts.

So, you can “abuse” NIS for getting a unique
name-to-address-translation on all hosts throughout one
(NIS-)domain.

There's only one drawback, which prevents NIS from actually
being used for that translation: In contrast to the DNS, NIS
provides no way to resolve hostnames which are not in the
hosts-table. There's no hosts “one level up” which the
NIS-server can query, and so the translation will fail!
Suns NIS+ takes measures against that problem, but
as NIS+ is only available on Solaris-systems, this is of
little use for us now.

23.6.4. Other

The name resolving methods described above are what's used
commonly today to resolve hostnames into IP addresses, but
they aren't the only ones. Basically, every database
mechanism would do, but none is implemented in NetBSD.
Let's have a quick look what you may encounter.

With NIS lacking hierarchy in data structures, NIS+ is
intended to help out in that field. Tables can be setup in a
way so that if a query cannot be answered by a domain's
server, there can be another domain “above” that
might be able to do so. E.g. you could choose to have a domain
that lists all the hosts (users, groups, ...) that are valid in
the whole company, one that defines the same for each
division, etc. NIS+ is not used a lot today, even Sun went
back to ship back NIS by default.

Last century, the X.500 standard was designed to accommodate
both simple databases like /etc/hosts
as well as complex, hierarchical systems as can be found
e.g. in DNS today. X.500 wasn't really a success, mostly due
to the fact that it tried to do too much at the same time.
A cut-down version is available today as the Lightweight
Directory Access Protocol (LDAP), which is
becoming popular in the last years to manage data like users
but also hosts and others in small to medium sized
organisations.

23.7. Next generation Internet protocol - IPv6

23.7.1. The Future of the Internet

According to experts, the Internet as we know it will face a
serious problem in a few years. Due to its rapid growth and
the limitations in its design, there will be a point at
which no more free addresses are available for connecting
new hosts. At that point, no more new web servers can be set
up, no more users can sign up for accounts at ISPs, no more
new machines can be setup to access the web or participate
in online games - some people may call this a serious
problem.

Several approaches have been made to solve the problem. A
very popular one is to not assign a worldwide unique address
to every user's machine, but rather to assign them
“private”
addresses, and hide several machines behind one official,
globally unique address. This approach is called “Network
Address Translation” (NAT, also known as IP
Masquerading). It has problems, as the machines hidden
behind the global address can't be addressed, and as a
result of this, opening connections to them - which is used
in online gaming, peer to peer networking, etc. - is not
possible. For a more in-depth discussion of the drawbacks of
NAT, see [RFC3027].

A different approach to the problem of internet addresses
getting scarce is to abandon the old Internet protocol with
its limited addressing capabilities, and use a new protocol
that does not have these limitations. The protocol - or
actually, a set of protocols - used by machines connected to
form today's Internet is know as the TCP/IP (Transmission
Control Protocol, Internet Protocol) suite, and version 4
currently in use has all the problems described
above. Switching to a different protocol version that does
not have these problems of course requires for a 'better'
version to be available, which actually is. Version 6 of the
Internet Protocol (IPv6) does fulfill any possible future
demands on address space, and also addresses further
features such as privacy, encryption, and better support of
mobile computing.

Assuming a basic understanding of how today's IPv4 works,
this text is intended as an introduction to the IPv6
protocol. The changes in address formats and name resolution
are covered. With the background given here,
Section 24.9, “IPv6 Connectivity & Transition via 6to4” will show how to use IPv6 even if
your ISP doesn't offer it by using a simple yet efficient
transition mechanism called 6to4. The goal is to get
online with IPv6, giving example configuration for NetBSD.

23.7.2. What good is IPv6?

When telling people to migrate from IPv4 to IPv6, the
question you usually hear is “why?”. There are actually a
few good reasons to move to the new version:

Bigger address space

Support for mobile devices

Built-in security

23.7.2.1. Bigger Address Space

The bigger address space that IPv6 offers is the most
obvious enhancement it has over IPv4. While today's
internet architecture is based on 32-bit wide addresses,
the new version has 128 bit available for
addressing. Thanks to the enlarged address space,
work-arounds like NAT don't have to be used any more. This
allows full, unconstrained IP connectivity for today's IP
based machines as well as upcoming mobile devices like
PDAs and cell phones will benefit from full IP access
through GPRS and UMTS.

23.7.2.2. Mobility

When mentioning mobile devices and IP, another important
point to note is that some special protocol is needed to
support mobility, and implementing this protocol - called
“Mobile IP” - is one of the requirements for every
IPv6 stack. Thus, if you have IPv6 going, you have support for
roaming between different networks, with everyone being
updated when you leave one network and enter the other
one. Support for roaming is possible with IPv4 too, but
there are a number of hoops that need to be jumped in
order to get things working. With IPv6, there's no need
for this, as support for mobility was one of the design
requirements for IPv6. See [RFC3024] for
some more information on the issues that need to be
addressed with Mobile IP on IPv4.

23.7.2.3. Security

Besides support for mobility, security was another
requirement for the successor to today's Internet Protocol
version. As a result, IPv6 protocol stacks are required to
include IPsec. IPsec allows authentication, encryption
and compression of any IP traffic. Unlike application
level protocols like SSL or SSH, all IP traffic between
two nodes can be handled, without adjusting any
applications. The benefit of this is that all applications
on a machine can benefit from encryption and
authentication, and that policies can be set on a per-host
(or even per-network) base, not per
application/service. An introduction to IPsec with a
roadmap to the documentation can be found in [RFC2411], the core protocol is described in
[RFC2401].

23.7.3. Changes to IPv4

After giving a brief overview of all the important features
of IPv6, we'll go into the details of the basics of IPv6
here. A brief understanding of how IPv4 works is assumed,
and the changes in IPv6 will be highlighted. Starting with
IPv6 addresses and how they're split up we'll go into the
various types of addresses there are, what became of
broadcasts, then after discussing the IP layer go into
changes for name resolving and what's new in DNS for IPv6.

23.7.3.1. Addressing

An IPv4 address is a 32 bit value, that's usually written
in “dotted quad” representation, where each
“quad” represents a byte value between 0 and 255,
for example:

127.0.0.1

This allows a theoretical number of
232 or ~4 billion
hosts to be connected on the internet today. Due to
grouping, not all addresses are available today.

IPv6 addresses use 128 bit, which results in
2128
theoretically addressable hosts. This allows for a Really
Big number of machines to addressed, and it sure fits all
of today's requirements plus all those nifty PDAs and cell
phones with IP phones in the near future without any
sweat. When writing IPv6 addresses, they are usually
divided into groups of 16 bits written as four hex digits,
and the groups are separated by colons. An example is:

fe80::2a0:d2ff:fea5:e9f5

This shows a special thing - a number of consecutive zeros
can be abbreviated by a single “::” once in the IPv6
address. The above address is thus equivalent to
fe80:0:00:000:2a0:d2ff:fea5:e9f5 - leading zeros within
groups can be omitted, and only one “::” can
be used in an IPv6 address.

Figure 23.4. IPv6-addresses are divided into more significant network- and
less significant hostbits, too

In IPv4, the border is drawn with the aid of the netmask,
which can be used to mask all net/host bits. Typical
examples are 255.255.0.0 that uses 16 bit for addressing
the network, and 16 bit for the machine, or 255.255.255.0
which takes another 8 bit to allow addressing 256 subnets
on e.g. a class B net.

When addressing switched from classful addressing to CIDR
routing, the borders between net and host bits stopped
being on 8 bit boundaries, and as a result the netmasks
started looking ugly and not really manageable. As a
replacement, the number of network bits is used for a
given address, to denote the border, e.g.

10.0.0.0/24

is the same as a netmask of 255.255.255.0 (24 1-bits). The
same scheme is used in IPv6:

2001:638:a01:2::/64

tells us that the address used here has the first
(leftmost) 64 bits used as the network address, and the
last (rightmost) 64 bits are used to identify the machine
on the network. The network bits are commonly referred to
as (network) “prefix”, and the
“prefixlen” here would be
64 bits.

Common addressing schemes found in IPv4 are the (old)
class B and class C nets. With a class C network (/24),
you get 24 bits assigned by your provider, and it leaves 8
bits to be assigned by you. If you want to add any
subnetting to that, you end up with “uneven” netmasks that
are a bit nifty to deal with. Easier for such cases are
class B networks (/16), which only have 16 bits assigned
by the provider, and that allow subnetting, i.e. splitting
of the rightmost bits into two parts. One to address the
on-site subnet, and one to address the hosts on that
subnet. Usually, this is done on byte (8 bit)
boundaries. Using a netmask of 255.255.255.0 (or a /24
prefix) allows flexible management even of bigger networks
here. Of course there is the upper limit of 254 machines
per subnet, and 256 subnets.

With 128 bits available for addressing in IPv6, the scheme
commonly used is the same, only the fields are
wider. Providers usually assign /48 networks, which leaves
16 bits for a subnetting and 64 hostbits.

Figure 23.5. IPv6-addresses have a similar structure to
class B addresses

Now while the space for network and subnets here is pretty
much ok, using 64 bits for addressing hosts seems like a
waste. It's unlikely that you will want to have several
billion hosts on a single subnet, so what is the idea
behind this?

The idea behind fixed width 64 bit wide host
identifiers is that they aren't assigned manually as it's
usually done for IPv4 nowadays. Instead, IPv6 host addresses
are recommended (not mandatory!) to be built from
so-called EUI64 addresses. EUI64 addresses are - as the
name says - 64 bit wide, and derived from MAC addresses of
the underlying network interface. E.g. for ethernet, the 6
byte (48 bit) MAC address is usually filled with the hex
bits “fffe” in the middle and a bit is set to mark
the address as unique (which is true for Ethernet), e.g. the
MAC address

01:23:45:67:89:ab

results in the EUI64 address

03:23:45:ff:fe:67:89:ab

which again gives the host bits for the IPv6 address as

::0323:45ff:fe67:89ab

These host bits can now be used to automatically assign
IPv6 addresses to hosts, which supports autoconfiguration
of IPv6 hosts - all that's needed to get a complete IPv6
address is the first (net/subnet) bits, and IPv6 also
offers a solution to assign them automatically.

When on a network of machines speaking IP, there's usually
one router which acts as the gateway to outside
networks. In IPv6 land, this router will send “router
advertisement” information, which clients are expected to
either receive during operation or to solicit upon
system startup. The router advertisement information includes
data on the router's address, and which address prefix it
routes. With this information and the host-generated EUI64
address, an IPv6-host can calculate its IP address, and there
is no need for manual address assignment. Of course
routers still need some configuration.

The router advertisement information they create are part
of the Neighbor Discovery Protocol (NDP, see [RFC2461]),
which is the successor to IPv4's ARP protocol. In contrast
to ARP, NDP does not only do lookup of IPv6 addresses for
MAC addresses (the neighbor solicitation/advertisement
part), but also does a similar service for routers and the
prefixes they serve, which is used for autoconfiguration
of IPv6 hosts as described in the previous paragraph.

23.7.3.2. Multiple Addresses

In IPv4, a host usually has one IP address per network
interface or even per machine if the IP stack supports
it. Only very rare applications like web servers result in
machines having more than one IP address. In IPv6, this is
different. For each interface, there is not only a
globally unique IP address, but there are two other
addresses that are of interest: The link local address,
and the site local address. The link local address has a
prefix of fe80::/64, and the host bits are built from the
interface's EUI64 address. The link local address is used
for contacting hosts and routers on the same network only,
the addresses are not visible or reachable from different
subnets. If wanted, there's the choice of either using
global addresses (as assigned by a provider), or using
site local addresses. Site local addresses are assigned
the network address fec0::/10, and subnets and hosts can
be addressed just as for provider-assigned networks. The
only difference is, that the addresses will not be visible
to outside machines, as these are on a different network,
and their “site local” addresses are in a different
physical net (if assigned at all). As with the 10/8
network in IPv4, site local addresses can be used, but
don't have to. For IPv6 it's most common to have hosts
assigned a link-local and a global IP address. Site local
addresses are rather uncommon today, and are no substitute
for globally unique addresses if global connectivity is
required.

23.7.3.3. Multicasting

In IP land, there are three ways to talk to a host:
unicast, broadcast and multicast. The most common one is
by talking to it directly, using its unicast address. In
IPv4, the unicast address is the “normal” IP address
assigned to a single host, with all address bits
assigned. The broadcast address used to address all hosts
in the same IP subnet has the network bits set to the
network address, and all host bits set to “1” (which can
be easily done using the netmask and some bit operations).
Multicast addresses are used to reach a number of hosts in
the same multicast group, which can be machines spread
over the whole internet. Machines must join multicast
groups explicitly to participate, and there are special
IPv4 addresses used for multicast addresses, allocated from
the 224/8 subnet. Multicast isn't used very much in IPv4,
and only few applications like the MBone audio and video
broadcast utilities use it.

In IPv6, unicast addresses are used the same as in IPv4,
no surprise there - all the network and host bits are
assigned to identify the target network and
machine. Broadcasts are no longer available in IPv6 in the
way they were in IPv4, this is where multicasting comes
into play. Addresses in the ff::/8 network are reserved
for multicast applications, and there are two special
multicast addresses that supersede the broadcast addresses
from IPv4. One is the “all routers” multicast address, the
others is for “all hosts”. The addresses are specific to
the subnet, i.e. a router connected to two different
subnets can address all hosts/routers on any of the
subnets it's connected to. Addresses here are:

ff0X::1 for all hosts and

ff0X::2 for all routers,

where “X”
is the scope ID of
the link here, identifying the network. Usually this starts
from “1” for the “node local” scope,
“2” for the first
link, etc. Note that it's perfectly ok for two network
interfaces to be attached to one link, thus resulting in
double bandwidth:

Figure 23.6. Several interfaces attached to a link result in only one
scope ID for the link

One use of the “all hosts” multicast
is in the neighbor
solicitation code of NDP, where any machine that wants to
communicate with another machine sends out a request to
the “all hosts” group, and the machine in question is
expected to respond.

23.7.3.4. Name Resolving in IPv6

After talking a lot about addressing in IPv6, anyone still
here will hope that there's a proper way to abstract all
these long & ugly IPv6 addresses with some nice hostnames
as one can do in IPv4, and of course there is.

Hostname to IP address resolving in IPv4 is usually done in
one of three ways: using a simple table in
/etc/hosts, by
using the Network Information Service (NIS, formerly YP)
or via the Domain Name System (DNS).

As of this writing, NIS/NIS+ over IPv6 is currently only
available on Solaris 8, for both database contents and
transport, using a RPC extension.

Having a simple address<->name map like
/etc/hosts is
supported in all IPv6 stacks. With the KAME implementation
used in NetBSD, /etc/hosts contains
IPv6 addresses
as well as IPv4 addresses. A simple example is the
“localhost” entry in the default NetBSD installation:

127.0.0.1 localhost
::1 localhost

For DNS, there are no fundamentally new concepts. IPv6
name resolving is done with AAAA records that - as the
name implies - point to an entity that's four times the
size of an A record. The AAAA record takes a hostname on
the left side, just as A does, and on the right side
there's an IPv6 address, e.g.

noon IN AAAA 3ffe:400:430:2:240:95ff:fe40:4385

For reverse resolving, IPv4 uses the in-addr.arpa zone,
and below that it writes the bytes (in decimal) in
reversed order, i.e. more significant bytes are more
right. For IPv6 this is similar, only that hex digits
representing 4 bits are used instead of decimal numbers,
and the resource records are also under a different
domain, ip6.int.

So to have the reverse resolving for the above host, you
would put into your /etc/named.conf
something like:

and in the zone file db.reverse you put (besides the usual
records like SOA and NS):

5.8.3.4.0.4.e.f.f.f.5.9.0.4.2.0.2.0.0.0 IN PTR noon.ipv6.example.com.

The address is reversed here, and written down one hex
digit after the other, starting with the least significant
(rightmost) one, separating the hex digits with dots, as
usual in zone files.

One thing to note when setting up DNS for IPv6 is to take
care of the DNS software version in use. BIND 8.x does
understand AAAA records, but it does not offer name
resolving via IPv6. You need BIND 9.x for that. Beyond
that, BIND 9.x supports a number of resource records that
are currently being discussed but not officially
introduced yet. The most noticeable one here is the A6
record which allows easier provider/prefix changing.

To sum up, this section talked about the technical
differences between IPv4 and IPv6 for addressing and name
resolving. Some details like IP header options, QoS and
flows were deliberately left out to not make this
document more complex than necessary.

24.1. A walk through the kernel configuration

Before we dive into configuring various aspects of network
setup, we want to walk through the necessary bits that have to
or can be present in the kernel. See Chapter 32, Compiling the kernel for more details on compiling the
kernel, we will concentrate on the configuration of the kernel
here. We will take the i386/GENERIC config file as an example
here. Config files for other platforms should contain similar
information, the comments in the config files give additional
hints. Besides the information given here, each kernel option
is also documented in the options(4) manpage, and there is
usually a manpage for each driver too, e.g. tlp(4).

The first line of each config file shows the version.
It can be used to compare against other
versions via CVS, or when reporting bugs.

options NTP # NTP phase/frequency locked loop

If you want to run the Network Time Protocol
(NTP), this
option can be enabled for maximum precision. If the option is
not present, NTP will still work. See ntpd(8) for more
information.

If you want to setup a router that forwards packets between
networks or network interfaces, setting this option is
needed. It doesn't only switch on packet forwarding, but also
increases some buffers. See options(4) for details.

options INET # IP + ICMP + TCP + UDP

This enables the TCP/IP code in the kernel. Even if you don't
want/use networking, you will still need this for
machine-internal communication of subsystems like the X Window
System. See inet(4) for more details.

Includes support for the IPsec protocol, including key and
policy management, authentication and compression. This option
can be used without the previous option INET6, if you just
want to use IPsec with IPv4, which is possible. See ipsec(4)
for more information.

#options IPSEC_ESP # IP security (encryption part; define w/IPSEC)

This option is needed in addition to IPSEC if encryption is
wanted in IPsec.

#options MROUTING # IP multicast routing

If multicast services like the MBone services should be routed,
this option needs to be included. Note that the routing itself
is controlled by the mrouted(8) daemon.

options ISO,TPIP # OSI
#options EON # OSI tunneling over IP

These options include the OSI protocol
stack, which was said
for a long time to be the future of networking. It's mostly
history these days. :-) See the iso(4) manpage for more
information.

options NETATALK # AppleTalk networking protocols

Include support for the AppleTalk protocol stack. Userland
server programs are needed to make use of that. See
pkgsrc/net/netatalk and pkgsrc/net/netatalk-asun for such
packages. More information on the AppleTalk protocol and
protocol stack are available in the atalk(4) manpage.

This option is only needed if you have machines on the network
that still run 4.2BSD or a network stack derived from it. If
you've got one or more 4.2BSD-systems on your network, you've
to pay attention to set the right broadcast-address, as
4.2BSD has a bug in its networking code, concerning the
broadcast address. This bug forces you to set all host-bits
in the broadcast-address to “0”. The TCP_COMPAT_42
option helps you ensuring this.

options NFS_BOOT_DHCP,NFS_BOOT_BOOTPARAM

These options enable lookup of data via DHCP or the BOOTPARAM
protocol if the kernel is told to use a NFS root file
system. See the diskless(8) manpage for more information.

These lines tell where the kernel looks for its root file
system, and which filesystem type it is expected to have. If
you want to make a kernel that uses a NFS root filesystem via
the tlp0 interface, you can do this with “root on tlp0 type
nfs”. If a ? is used instead of a
device/type, the kernel
tries to figure one out on its own.

If you want to use PPP or SLIP, you will need some serial
(com) interfaces. Others with attachment on USB, PCMCIA or PUC
will do as well.

# Network Interfaces

This rather long list contains all sorts of network
drivers. Please pick the one that matches your hardware,
according to the comments. For most drivers, there's also a
manual page available, e.g. tlp(4), ne(4), etc.

# MII/PHY support

This section lists media independent interfaces for network
cards. Pick one that matches your hardware. If in doubt,
enable them all and see what the kernel picks. See the mii(4)
manpage for more information.

USB-ethernet adapters only have about 2MBit/s bandwidth, but
they are very convenient to use. Of course this needs other
USB related options which we won't cover here, as well as the
necessary hardware. See the corresponding
manpages for more information.

This is the “lo0” software loopback network device
which is used by some programs these days, as well as for routing
things. It should not be omitted. See lo(4) for more details.

pseudo-device ppp 2 # Point-to-Point Protocol

If you want to use PPP either over a serial interface or
ethernet (PPPoE), you will need this option. See ppp(4) for
details on this interface.

pseudo-device sl 2 # Serial Line IP

Serial Line IP is a simple encapsulation for IP over (well :)
serial lines. It does not include negotiation of IP addresses
and other options, which is the reason that it's not in
widespread use today any more. See sl(4).

pseudo-device strip 2 # Starmode Radio IP (Metricom)

If you happen to have one of the old Metricom Ricochet packet
radio wireless network devices, use this pseudo-device to use
it. See the strip(4) manpage for detailed information.

pseudo-device tun 2 # network tunneling over tty

This network device can be used to tunnel network packets to a
device file, /dev/tun*. Packets routed to
the tun0 interface can be read from
/dev/tun0, and data written to
/dev/tun0 will be sent out the tun0
network interface. This can be used to implement e.g. QoS
routing in userland. See tun(4) for details.

pseudo-device gre 2 # generic L3 over IP tunnel

The GRE encapsulation can be used to tunnel arbitrary layer 3
packets over IP, e.g. to implement
VPNs. See gre(4) for more.

pseudo-device gif 4 # IPv[46] over IPv[46] tunnel (RFC 1933)

Using the GIF interface allows to tunnel
e.g. IPv6 over IPv4, which can be used to get IPv6
connectivity if no IPv6-capable uplink (ISP) is
available. Other mixes of operations are possible, too. See
the gif(4) manpage for some examples.

#pseudo-device faith 1 # IPv[46] tcp relay translation i/f

The faith interface captures IPv6 TCP traffic, for
implementing userland IPv6-to-IPv4 TCP relays e.g. for
protocol transitions. See the faith(4) manpage for more
details on this device.

#pseudo-device stf 1 # 6to4 IPv6 over IPv4 encapsulation

This adds a network device that can be used to tunnel IPv6 over
IPv4 without setting up a configured tunnel before. The source
address of outgoing packets contains the IPv4 address, which
allows routing replies back via IPv4. See the stf(4) manpage
and Section 24.9, “IPv6 Connectivity & Transition via 6to4” for more details.

pseudo-device vlan # IEEE 802.1q encapsulation

This interface provides support for IEEE 802.1Q Virtual LANs,
which allows tagging Ethernet frames with a “vlan” ID.
Using properly configured switches (that also have to support VLAN,
of course), this can be used to build virtual LANs where one
set of machines doesn't see traffic from the other (broadcast
and other). The vlan(4) manpage tells more about this.

24.2. Overview of the network configuration files

The following is a list of the files used to configure the
network. The usage of these files, some of which have already
been met the first chapters, will be described in the
following sections.

/etc/hosts

Local hosts database file. Each line contains information
regarding a known host and contains the internet address,
the host's name and the aliases. Small networks can be
configured using only the hosts file, without a
name server.

/etc/resolv.conf

This file specifies how the routines which provide access
to the Internet Domain Name System should operate.
Generally it contains the addresses of the name servers.

/etc/ifconfig.xxx

This file is used for the automatic configuration of the
network card at boot.

/etc/mygate

Contains the IP address of the gateway.

/etc/nsswitch.conf

Name service switch configuration file. It controls how a
process looks up various databases containing information
regarding hosts, users, groups, etc. Specifically, this
file defines the order to look up the databases. For
example, the line:

hosts: files dns

specifies that the hosts database comes from two
sources, files (the local
/etc/hosts file) and
DNS, (the Internet Domain Name
System) and that the local files are searched before
the DNS.

It is usually not necessary to modify this file.

24.3. Connecting to the Internet with a modem

There are many types of Internet connections: this section
explains how to connect to a provider using a modem over a
telephone line using the PPP protocol, a
very common setup.
In order to have a working connection, the following steps must be
done:

Get the necessary information from the provider.

Edit the file /etc/resolv.conf and
check /etc/nsswitch.conf.

Create the directories /etc/ppp
and /etc/ppp/peers if they don't exist.

Create the connection script, the chat file and the
pppd options file.

Created the user-password authentication file.

Judging from the previous list it looks like a complicated
procedure that requires a lot of work.
Actually, the single steps are very easy: it's just a matter of
modifying, creating or simply checking some small text files.
In the following example it will be assumed that the modem is
connected to the second serial port
/dev/tty01 (COM2 in DOS).

A few words on the difference between com,
COM and tty. For
NetBSD, “com” is the name of the serial port driver
(the one that is displayed by dmesg) and
“tty” is the name of the port. Since numbering
starts at 0, com0 is the driver for the first serial port,
named tty00. In the DOS world, instead, COM1 refers to the
first serial port (usually located at 0x3f8), COM2 to the
second, and so on. Therefore COM1 (DOS) corresponds to
/dev/tty00 (NetBSD).

24.3.1. Getting the connection information

The first thing to do is ask the provider the necessary
information for the connection, which means:

The phone number of the nearest POP.

The authentication method to be used.

The username and password for the connection.

The IP addresses of the name servers.

24.3.2. resolv.conf and
nsswitch.conf

The /etc/resolv.conf file must be configured
using the information supplied by the provider, especially the
addresses of the DNS.
In this example the two DNS will be “194.109.123.2” and
“191.200.4.52”.

The defaults of doing hostname lookups via
/etc/hosts followed by the DNS works
fine and there's usually no need to modify this.

24.3.3. Creating the directories for pppd

The directories /etc/ppp and
/etc/ppp/peers will contain the
configuration files for the PPP connection.
After a fresh install of NetBSD they don't exist and must be
created (chmod 700).

#mkdir /etc/ppp#mkdir /etc/ppp/peers

24.3.4. Connection script and chat file

The connection script will be used as a parameter on the
pppd command line; it is located in
/etc/ppp/peers and has usually the name of
the provider.
For example, if the provider's name is BigNet and your
user name for the connection to the provider is alan, an
example connection script could be:

In the previous example, the script specifies a chat
file to be used for the connection.
The options in the script are detailed in the pppd(8)
man page.

Note

If you are experiencing connection problems, add the
following two lines to the connection script

debug
kdebug 4

You will get a log of the operations performed when the system
tries to connect.
See pppd(8), syslog.conf(5).

The connection script calls the chat
application to deal with the physical connection (modem
initialization, dialing, ...)
The parameters to chat can be specified
inline in the connection script, but it is better to put them in a
separate file.
If, for example, the telephone number of the POP to call is 02
99999999, an example chat script could be:

Note

If you have problems with the chat file, you can try connecting
manually to the POP with the cu(1)
program and verify the exact strings that you are receiving.

24.3.5. Authentication

During authentication each of the two systems verifies the
identity of the other system, although in practice you are not
supposed to authenticate the provider, but only to be verified by
him, using one of the following methods:

PAP/CHAP

login

Most providers use a PAP/CHAP authentication.

24.3.5.1. PAP/CHAP authentication

The authentication information (speak: password) is stored
in the /etc/ppp/pap-secrets for PAP
and in /etc/ppp/chap-secrets for
CHAP. The lines have the following format:

user * password

For example:

alan * pZY9o

For security reasons the pap-secrets and
chap-secrets files should be owned by
root and have permissions “600”.

24.3.5.2. Login authentication

This type of authentication is not widely used today; if the provider
uses login authentication, user name and password must be supplied
in the chat file instead of the PAP/CHAP files, because the
chat file simulates an interactive login.
In this case, set up appropriate permissions for the chat file.

24.3.7. Testing the modem

Before activating the link it is a good idea to make a quick
modem test, in order to verify that the physical connection and
the communication with the modem works. For the test the
cu(1) program can be used, as in the
following example.

Create the file /etc/uucp/port
with the following lines:

type modem
port modem
device /dev/tty01
speed 115200

(substitute the correct device in place of
/dev/tty01).

Write the command cu -p modem to start
sending commands to the modem. For example:

#cu -p modem
Connected.
ATZ
OK
~.
Disconnected.
#

In the previous example the reset command (ATZ) was sent to
the modem, which replied with OK: the communication works.
To exit cu(1), write ~
(tilde) followed by . (dot), as in the
example.

If the modem doesn't work, check that it is connected to the
correct port (i.e. you are using the right port with
cu(1). Cables are a frequent cause of trouble, too.

When you start cu(1) and a message saying
“Permission denied” appears, check who is the
owner of the
/dev/tty##
device, it must be "uucp".
For example:

The two scripts take advantage of the fact that when
pppd is active, it creates the file
LCK..tty01 in the
/var/spool/lock directory.
This file contains the process ID (pid)
of the pppd process.

The two scripts must be executable:

#chmod u+x ppp-start ppp-stop

24.3.10. Running commands after dialin

If you find yourself to always run the same set of commands
each time you dial in, you can put them in a script
/etc/ppp/ip-up which will be called by
pppd(8) after successful dial-in. Likewise, before the
connection is closed down,
/etc/ppp/ip-down is executed.
Both scripts are expected to be executable. See pppd(8)
for more details.

24.4. Creating a small home network

Networking is one of the main strengths of Unix and NetBSD is no
exception: networking is both powerful and easy to set up and
inexpensive too, because there is no need to buy additional software to
communicate or to build a server.
Section 24.5, “Setting up an Internet gateway with IPNAT” explains how
to configure a NetBSD machine
to act as a gateway for a network: with IPNAT all
the hosts of the network can reach the Internet with a single
connection to a provider made by the gateway machine.
The only thing to be checked before creating the network is to buy
network cards supported by NetBSD (check the
INSTALL.* files for a list of supported
devices).

If the card is not recognized by the kernel, check that it is
enabled in the kernel configuration file and then that the
card's IRQ matches the one that the kernel expects.
For example, this is the isa NE2000 line in the configuration
file; the kernel expects the card to be at IRQ 9.

...
ne0 at isa? port 0x280 irq 9 # NE[12]000 ethernet cards
...

If the card's configuration is different, it will probably not be
found at boot.
In this case, either change the line in the kernel configuration
file and compile a new kernel or change the card's setup (usually
through a setup disk or, for old cards, a jumper on the card).

The output of ifconfig has now changed: the
IP address is now printed and there are two new flags,
“UP” and “RUNNING”
If the interface isn't “UP”, it will not be used by the
system to send packets.

The host was given the IP address 192.168.1.1, which belongs to
the set of addresses reserved for internal networks which are not
reachable from the Internet.
The configuration is finished and must now be tested; if
there is another active host on the network, a
ping can be tried.
For example, if 192.168.1.2 is the address of the active host:

With the current setup, at the next boot it will be necessary to
repeat the configuration of the network card.
In order to avoid repeating the card's configuration at each
boot, add the following lines to
/etc/rc.conf:

auto_ifconfig=yes
ifconfig_ne0="inet 192.168.1.1 netmask 0xffffff00"

In this example the variable ifconfig_ne0
was set because the network card was recognized as
ne0 by the kernel; if you are using a
different adapter, substitute the appropriate name in place of
ne0.

At the next boot the network card will be configured
automatically.

If you have a router that is connected to the internet, you
can use it as default router, which will handle all your
packets. To do so, set defaultroute to the
router's IP address in /etc/rc.conf:

defaultroute=192.168.0.254

Be sure to use the default router's IP address instead of
name, in case your DNS server is beyond the default router. In
that case, the DNS server couldn't be reached to resolve the
default router's hostname and vice versa, creating a
chicken-and-egg problem.

To reach hosts on your local network, and assuming you really
have very few hosts, adjust /etc/hosts to
contain the addresses of all the hosts belonging to the
internal network. For example:

Example 24.9. /etc/hosts

#
# Host Database
# This file should contain the addresses and aliases
# for local hosts that share this file.
# It is used only for "ifconfig" and other operations
# before the nameserver is started.
#
#
127.0.0.1 localhost
::1 localhost
#
# RFC 1918 specifies that these networks are "internal".
# 10.0.0.0 10.255.255.255
# 172.16.0.0 172.31.255.255
# 192.168.0.0 192.168.255.255
192.168.1.1 ape.insetti.net ape
192.168.1.2 vespa.insetti.net vespa
192.168.1.0 insetti.net

If you are dialed in via an Internet Service Provider, or if
you have a local Domain Name Server (DNS) running, you may
want to use it to resolve hostnames to IP addresses, possibly
in addition to /etc/hosts, which would
only know your own hosts. To configure a machine as DNS
client, you need to edit
/etc/resolv.conf, and enter the DNS
server's address, in addition to an optional domain name that
will be appended to hosts with no domain, in order to create a
FQDN for resolving. Assuming your DNS server's IP address is
192.168.1.2 and it is setup to serve for "home.net", put the
following into /etc/resolv.conf:

Summing up, to configure the network the following must be done:
the network adapters must be installed and physically connected.
Next they must be configured (with ifconfig)
and, finally, the file /etc/rc.conf must
be modified to configure the interface and possibly default
router, and /etc/resolv.conf and
/etc/nsswitch.conf should be adjusted if
DNS should be used.
This type of network management is sufficient for small
networks without sophisticated needs.

24.5. Setting up an Internet gateway with IPNAT

The mysterious acronym IPNAT hides the
Internet Protocol Network Address Translation, which enables the
routing of an internal network (e.g. your home network as
described in Section 24.4, “Creating a small home network ”) on
a real network (Internet). This means that with only one
“real” IP, static or dynamic, belonging to a
gateway running IPNAT, it is possible to create simultaneous
connections to the Internet for all the hosts of the internal
network.

Some usage examples of IPNAT can be found in the subdirectory
/usr/share/examples/ipf: look at the files
BASIC.NAT and
nat-setup.

The setup for the example described in this section is detailed
in Figure 24.1, “Network with gateway”:
host 1 can connect to the Internet calling
a provider with a modem and getting a dynamic IP address.
host 2 and host 3 can't
communicate with the Internet with a normal setup: IPNAT allows
them to do it: host 1 will act as a Internet gateway for hosts
2 and 3. Using host 1 as default router, hosts 2 and 3 will be
able to access the Internet.

Figure 24.1. Network with gateway

24.5.1. Configuring the gateway/firewall

To use IPNAT, the “pseudo-device ipfilter” must
be compiled into the kernel, and IP packet forwarding must be
enabled in the kernel. To check, run:

#sysctl net.inet.ip.forwarding
net.inet.ip.forwarding = 1

If the result is “1” as in the previous example, the
option is enabled, otherwise, if the result is “0”
the option is disabled. You can do two things:

Compile a new kernel, with the GATEWAY option enabled.

Enable the option in the current kernel with the
following command:

#sysctl -w net.inet.ip.forwarding=1

You can add sysctl settings to
/etc/sysctl.conf to have them set
automatically at boot. In this case you would want to add

net.inet.ip.forwarding=1

The rest of this section explains how to create an IPNAT
configuration that is automatically started every time that a
connection to the provider is activated with the PPP link.
With this configuration all the host of a home network (for
example) will be able to connect to the Internet through the
gateway machine, even if they don't use NetBSD.

For the setup, first, create the
/etc/ipnat.conf file containing the
following rules:

192.168.1.0/24 are the network addresses that should be mapped.
The first line of the configuration file is optional: it enables
active FTP to work through the gateway.
The second line is used to handle correctly tcp and udp packets;
the portmapping is necessary because of the many to one
relationship).
The third line is used to enable ICMP, ping, etc.

Next, create the /etc/ppp/ip-up file;
it will be called automatically every time that the PPP link
is activated:

#!/bin/sh
# /etc/ppp/ip-up
/etc/rc.d/ipnat forcestart

Create the file /etc/ppp/ip-down; it will be
called automatically when the PPP link is closed:

#!/bin/sh
# /etc/ppp/ip-down
/etc/rc.d/ipnat forcestop

Both ip-up and
ip-down must be executable:

#chmod u+x ip-up ip-down

The gateway machine is now ready.

24.5.2. Configuring the clients

Create a /etc/resolv.conf file like the one
on the gateway machine, to make the clients access the same
DNS server as the gateway.

Next, make all clients use the gateway as their default
router. Use the following command:

#route add default 192.168.1.1

192.168.1.1 is the address of the gateway machine configured in
the previous section.

Of course you don't want to give this command every time, so it's
better to define the “defaultroute” entry in the
/etc/rc.conf file: the default route will be
set automatically during system initialization, using the
defaultroute option as an argument to the
route add default command.

If the client machine is not using NetBSD, the configuration will
be different.
On Windows PC's you need to set the gateway property of the
TCP/IP protocol to the IP address of the NetBSD gateway.

That's all that needs to be done on the client machines.

24.5.3. Some useful commands

The following commands can be useful for
diagnosing problems:

ping

netstat -r

Displays the routing tables (similar to
route show).

traceroute

On the client it shows the route followed by the packets to
their destination.

tcpdump

Use on the gateway to monitor TCP/IP traffic.

24.6. Setting up a network bridge device

A bridge can be used to combine different physical networks
into one logical network, i.e. connect them at layer 2 of the
ISO-OSI model, not at layer 3, which is what a router would
do. The NetBSD “bridge” driver
provides bridge functionality on NetBSD systems.

24.6.1. Bridge example

In this example two physical networks are going to be combined
in one logical network, 192.168.1.0, using a NetBSD bridge. The
NetBSD machine which is going to act as bridge has two interfaces,
ne0 and ne1, which are each connected to one physical network.

The first step is to make sure support for the “bridge”
is compiled in the running kernel. Support is included in the
GENERIC kernel.

When the system is ready the bridge can be created, this can
be done using the brconfig(8) command. First
of a bridge interface has to be created. With the following
ifconfig command the “bridge0”
interface will be created:

$ifconfig bridge0 create

Please make sure that at this point both the ne0 and ne1
interfaces are up. The next step is to add the ne0 and ne1
interfaces to the bridge.

$brconfig bridge0 add ne0 add ne1 up

This configuration can be automatically set up by creating
an /etc/ifconfig.interface file, in
this case /etc/ifconfig.bridge0,
with the following contents:

create
!brconfig $int add ne0 add ne1 up

After setting up the bridge the bridge configuration can
be displayed using the brconfig -a command.
Remember that if you want to give the bridge machine an IP
address you can only allocate an IP address to one of the
interfaces which are part of the bridge.

24.7. A common LAN setup

The small home network discussed in the previous section
contained many items that were configured manually. In bigger
LANs that are centrally managed, one can expect Internet
connectivity being available via some router, a DNS server
being available, and most important, a DHCP server which hands
out IP addresses to clients on request. To make a NetBSD client
run in such an environment, it's usually enough to set

dhclient=yes

in /etc/rc.conf, and the IP address will
be set automatically, /etc/resolv.conf
will be created and routing setup to the default router.

24.8. Connecting two PCs through a serial line

If you need to transfer files between two PCs which are not networked
there is a simple solution which is particularly handy when
copying the files to a floppy is not practical: the two machines
can be networked with a serial cable (a null modem
cable).
The following sections describe some configurations.

24.8.1. Connecting NetBSD with BSD or Linux

The easiest case is when both machines run NetBSD: making a
connection with the SLIP protocol is very easy.
On the first machine write the following commands:

#slattach /dev/tty00#ifconfig sl0 inet 192.168.1.1 192.168.1.2

On the second machine write the following commands:

#slattach /dev/tty00#ifconfig sl0 inet 192.168.1.2 192.168.1.1

Now you can test the connection with ping; for
example, on the second PC write:

#ping 192.168.1.1

If everything worked there is now an active network connection
between the two machines and ftp,
telnet and other similar commands can
be executed.
The textual aliases of the machines can be written in the
/etc/hosts file.

In the previous example both PC's used the first serial port
(/dev/tty0).
Substitute the appropriate device if you are using another
port.

IP addresses like 192.168.x.x are reserved for
“internal” networks.
The first PC has address 192.168.1.1 and the second
192.168.1.2.

To achieve a faster connection the -sspeed option to slattach
can be specified.

ftp can be used to transfer files only if
inetd is active and the
ftpd server is enabled.

Linux

If one of the two PC's runs Linux, the commands are slightly
different (on the Linux machine only).
If the Linux machine gets the 192.168.1.2 address, the
following commands are needed:

24.8.2. Connecting NetBSD and Windows NT

NetBSD and Windows NT can be (almost) easily networked with a serial
null modem cable.
Basically what needs to be done is to create a “Remote
Access” connection under Windows NT and to start
pppd on NetBSD.

Start pppd as root after having
created a .ppprc in /root.
Use the following example as a template.

The meaning of the first line will be explained later in this
section; 192.168.1.2 is the IP address that will be assigned by
NetBSD to the Windows NT host; tty00 is the
serial port used for the connection (first serial port).

On the NT side a null modem device must be
installed from the Control Panel (Modem icon) and a Remote Access
connection using this modem must be created.
The null modem driver is standard under Windows NT 4 but it's not
a 100% null modem: when the link is activated, NT sends the
string CLIENT and expects to receive the answer CLIENTSERVER.
This is the meaning of the first line of the .ppprc
file: chat must answer to NT when the
connection is activated or the connection will fail.

In the configuration of the Remote Access connection the
following must be specified: use the null modem, telephone number
“1” (it's not used, anyway), PPP server, enable only
TCP/IP protocol, use IP address and nameservers from the server
(NetBSD in this case).
Select the hardware control flow and set the port to 115200 8N1.

Now everything is ready to activate the connection.

Connect the serial ports of the two machines with the null
modem cable.

Launch pppd on NetBSD.
To see the messages of pppd:
tail -f /var/log/messages).

Activate the Remote Access connection on Windows NT.

24.8.3. Connecting NetBSD and Windows 95

The setup for Windows 95 is similar to the one for Windows NT:
Remote Access on Windows 95 and the PPP server on NetBSD will be
used.
Most (if not all) Windows 95 releases don't have the
null modem driver, which makes things a
little more complicated.
The easiest solution is to find one of the available null modem
drivers on the Internet (it's a small .INF
file) and repeat the same steps as for Windows NT.
The only difference is that the first line of the
.ppprc file (the one that calls
chat) can be removed.

If you can't find a real null modem driver for Windows 95 it's
still possible to use a little trick:

In this way the chat program, called when the
connection is activated, emulates what Windows 95 thinks is a
standard modem, returning to Windows 95 the same answers that a
standard modem would return.
Whenever Windows 95 sends a modem command string,
chat returns OK.

24.9. IPv6 Connectivity & Transition via 6to4

This section will concentrate on how to get network
connectivity for IPv6 and - as that is rarely available directly
- talk at length about the alternatives to native
IPv6 connectivity as a transitional method until native IPv6 peers
are available.

Finding an ISP that offers IPv6 natively needs quite some
luck. What you need next is a router that will be able to
handle the traffic. To date, not all router manufacturers
offer IPv6 or hardware accelerated IPv6 features, and
gateway NAT boxes only rarely support IPv6 and also block IPv6 tunnels.
An alternative approach involves configuring
a standard PC running NetBSD to act as a router.
The base NetBSD system contains a complete IPv6 routing solution,
and for special routing needs software like
Zebra can provide additional routing protocols. This solution is
rather common for sites that want IPv6 connectivity
today. The drawbacks are that you need an ISP that supports
IPv6 and that you may need a dedicated uplink only for IPv6.

IPv6 to-the-door may be rare, but you can still get IPv6
connectivity by using tunnels. Instead of talking IPv6 on the
wire, the IPv6 packets are encapsulated in IPv4 packets, as shown
in Figure 24.2, “A frequently used method for transition is tunneling IPv6 in
IPv4 packets”. Using the existing IPv4
infrastructure, the encapsulated packets are sent to a
IPv6-capable uplink that will then remove the encapsulation, and
forward the IPv6 packets.

Figure 24.2. A frequently used method for transition is tunneling IPv6 in
IPv4 packets

When using tunnels, there are two possibilities. One is to use
a so-called “configured” tunnel, the other is called an
“automatic” tunnel. A “configured” tunnel
is one that required preparation from both ends of the tunnel,
usually connected with some kind of registration to exchange setup
information. An example for such a configured tunnel is the
IPv6-over-IPv4 encapsulation described in [RFC1933],
and that's implemented e.g. by the gif(4)
device found in NetBSD.

An “automatic” tunnel consists of a public server
that has some kind of IPv6 connectivity, e.g. via 6Bone. That server
has made its connectivity data public, and also runs a
tunneling protocol that does not require an explicit
registration of the sites using it as uplink. A well-used
example of such a protocol is the 6to4 mechanism described in
[RFC3056], and that is implemented in the
stf(4) device found in NetBSD's. Another mechanism that
does not require registration of IPv6-information is the 6over4
mechanism, which implements transporting of IPv6 over a
multicast-enabled IPv4 network, instead of e.g. ethernet or
FDDI. 6over4 is documented in [RFC2529].
It's main drawback is
that you do need existing multicast infrastructure. If you
don't have that, setting it up is about as much effort as
setting up a configured IPv6 tunnel directly, so it's usually
not worth bothering in that case.

24.9.1. Getting 6to4 IPv6 up & running

6to4 is an easy way to get IPv6 connectivity for hosts that
only have an IPv4 uplink, especially if you have the background
given in Section 23.7, “Next generation Internet protocol - IPv6”. It can be used with
static as well as dynamically assigned IPv4 addresses,
e.g. as found in modem dialup scenarios today. When using
dynamic IPv4 addresses, a change of IP addresses will be a
problem for incoming traffic, i.e. you can't run persistent
servers.

Example configurations given in this section is for NetBSD 1.5.2.

24.9.2. Obtaining IPv6 Address Space for 6to4

The 6to4 IPv6 setup on your side doesn't consist of a
single IPv6 address; Instead, you get a whole /48 network!
The IPv6 addresses are derived from your (single) IPv4
address. The address prefix “2002:” is reserved for
6to4 based addresses (i.e. IPv6 addresses derived from IPv4
addresses). The next 32 bits are your IPv4 address. This
results in a /48 network that you can use for your very own
purpose. It leaves 16 bits space for
216 IPv6 subnets, which can take
up to 264 nodes each.
Figure 24.3, “6to4 derives an IPv6 from an IPv4 address” illustrates the building of your
IPv6 address (range) from your IPv4 address.

Thanks to
the 6to4 prefix and your worldwide unique IPv4 address, this
address block is unique, and it's mapped to your machine
carrying the IPv4 address in question.

Figure 24.3. 6to4 derives an IPv6 from an IPv4 address

24.9.3. How to get connected

In contrast to the configured “IPv6-over-IPv4 tunnel”
setup, you do not have to register at a 6bone-gateway, which would
only then forward your IPv6 traffic encapsulated in IPv4. Instead,
as your IPv6 address is derived from your IPv4 address, inbound
traffic can be sent through the nearest 6to4 relay router.
De-encapsulation of the packet is done via a
6to4-capable network interface, which then forwards the
resulting IPv6 packet according to your routing setup (in
case you have more than one machine connected on your 6to4
assigned network).

Figure 24.4. Request and reply can be routed via different
gateways in 6to4

24.9.4. Security Considerations

In contrast to the “configured tunnel” setup, you
usually can't setup packet filters to block 6to4-packets from
unauthorized sources, as this is exactly how (and why) 6to4
works at all. As such, malicious users can send packets with
invalid/hazardous IPv6 payload. If you don't already filter
on your border gateways anyways, packets with the following
characteristics should not be allowed as valid 6to4 packets,
and some firewalling seems to be justified for them:

The NetBSD stf(4) manual page documents some common
configuration mistakes intercepted by default by the KAME
stack as well as some further advice on filtering, but keep
in mind that because of the requirement of these filters,
6to4 is not perfectly secure. Still, if forged 6to4 packets
become a problem, you can use IPsec authentication to ensure
the IPv6 packets are not modified.

24.9.5. Data Needed for 6to4 Setup

In order to setup and configure IPv6 over 6to4, a few bits
of configuration data must be known in advance. These are:

Your local IPv4 address. It can be determined using
either the 'ifconfig -a' or
'netstat -i' commands on
most Unix systems. If you use a NATing gateway or
something, be sure to use the official, outside-visible
address, not your private (10/8 or 192.168/16) one.

The 6to4 IPv6 relay anycast address.
which is 2002:c058:6301::, or
the IPv6 address of a specific 6to4 relay router you want
to use. The IPv6 address will do, as it also contains the
IPv4 address in the usual 6to4 translation.

24.9.6. Kernel Preparation

To process 6to4 packets, the operating system kernel needs
to know about them. For that a driver has to be compiled in
that knows about 6to4, and how to handle it. In NetBSD 4.0 and newer,
the driver is already present in GENERIC kernel configurations,
so the procedure below is usually unnecessary.

For a NetBSD kernel, put the following into your
kernel config file to prepare it for using IPv6 and 6to4,
e.g. on NetBSD use:

Note that the stf(4) device is not enabled by
default on NetBSD releases older than 4.0. Rebuild your kernel,
then reboot your system to use the new kernel. Please consult
Chapter 32, Compiling the kernel for further information on
configuring, building and installing a new kernel!

24.9.7. 6to4 Setup

This section describes the commands to setup 6to4. In short,
the steps performed here are:

Configure interface

Set default route

Setup Router Advertisement, if wanted

The first step in setting up 6to4 is creating the 6to4 interface
and assigning an IPv6 address to it. This is achieved with the
ifconfig(8) command. Assuming the example configuration
above, the commands for NetBSD are:

After configuring the 6to4 device with these commands,
routing needs to be setup, to forward all tunneled IPv6 traffic to
the 6to4 relay router. The best way to do this is by
setting a default route, the command to do so is, for NetBSD:

#route add -inet6 default 2002:c058:6301::

Note that NetBSD's stf(4) device determines the
IPv4 address of the 6to4 uplink from the routing table. Using
this feature, it is easy to setup your own 6to4 (uplink)
gateway if you have an IPv6 uplink, e.g. via 6Bone.

After these commands, you are connected to the IPv6-enabled
world - Congratulations! Assuming name resolution is still
done via IPv4, you can now ping an IPv6-site like www.kame.net
or www6.NetBSD.org:

#/sbin/ping6 www.kame.net

As a final step in setting up IPv6 via 6to4, you will want
to setup Router Advertisement if you have several hosts on
your network. While it is possible to setup 6to4 on each
node, doing so will result in very expensive routing from
one node to the other - packets will be sent to the remote
6to4 gateway, which will then route the packets back to the
neighbor node. Instead, setting up 6to4 on one machine and
talking native IPv6 on-wire is the preferred method of
handling things.

The first step to do so is to assign an IPv6-address to your
ethernet. In the following example we will assume subnet
“2”
of the IPv6-net is used for the local ethernet and the MAC
address of the ethernet interface is 12:34:56:78:9a:bc,
i.e. your local gateway's ethernet interface's IP address
will be 2002:3ee0:3972:2:1234:56ff:fe78:9abc. Assign this
address to your ethernet interface, e.g.

#ifconfig ne0 inet6 alias 2002:3ee0:3972:2:1234:56ff:fe78:9abc

Here, “ne0” is an example for your ethernet card
interface. This will most likely be different for your
setup, depending on what kind of card is used.

Next thing that needs to be ensured for setting up the
router is that it will actually forward packets from the
local 6to4 device to the ethernet device and back. To enable
IPv6 packet forwarding, set “ip6mode=router” in NetBSD's
/etc/rc.conf, which will result in the
“net.inet6.ip6.forwarding” sysctl being set to “1”:

#sysctl -w net.inet6.ip6.forwarding=1

Figure 24.5. Enabling packet forwarding is needed for a 6to4 router

To setup router advertisement on BSD, the file
/etc/rtadvd.conf needs to be checked. It allows
configuration of many things, but usually the default config
of not containing any data is ok. With that default, IPv6
addresses found on all of the router's network interfaces
will be advertised.

After checking the router advertisement configuration is
correct and IPv6 forwarding is turned on, the daemon
handling it can be started. Under NetBSD, it is called
'rtadvd'. Start it up either manually
(for testing it the first time) or via the system's startup
scripts, and see all your local nodes automagically
configure the advertised subnet address in addition to their
already-existing link local address.

#rtadvd

24.9.8. Quickstart using pkgsrc/net/hf6to4

So far, we have described how 6to4 works and how to set it
up manually. For an automated way to make everything happen
e.g. when going online, the 'hf6to4' package is convenient. It
will determine your IPv6 address from the IPv4 address you
got assigned by your provider, then set things up that you
are connected.

Steps to setup the pkgsrc/net/hf6to4 package are:

Install the package either by compiling it from pkgsrc,
or by pkg_add'ing the 6to4-1.2
package.

#cd /usr/pkgsrc/net/hf6to4#make install

Make sure you have the stf(4) pseudo-device in your
kernel, see above.

Configure the 'hf6to4' package. First, copy
/usr/pkg/share/examples/hf6to4/hf6to4.conf to
/usr/pkg/etc/hf6to4.conf, then adjust
the variables. Note that the file is in /bin/sh syntax.

Please see the hf6to4(8) manpage for an explanation of all
the variables you can set in
hf6to4.conf. If you have dialup IP
via PPP, and don't want to run Router Advertizing for
other IPv6 machines on your home or office network, you
don't need to configure anything. If you want to setup
Router Advertising, you need to set the
in_if to the internal (ethernet)
interface, e.g.

$in_if="rtk0"; # Inside (ethernet) interface

Now dial up, then start the 6to4 command manually:

#/usr/pkg/sbin/hf6to4 start

After that, you should be connected, use
ping6(8): to see if everything works:

24.9.9. Known 6to4 Relay Routers

It is normally not necessary to pick a specific 6to4 relay
router, but if necessary, you may find a list of known working routers
at http://www.kfu.com/~nsayer/6to4/.
In tests, only 6to4.kfu.com and 6to4.ipv6.microsoft.com were
found working. Cisco has one that requires registration,
see http://www.cisco.com/ipv6/.

There's also an experimental 6to4 server located in Germany,
6to4.ipv6.fh-regensburg.de. This server runs under NetBSD
1.6 and was setup using the configuration steps described
above. The whole configuration of the machine can be seen at
http://www.feyrer.de/IPv6/netstart.local.

24.9.10. Tunneling 6to4 through an IPFilter firewall

The 6to4 protocol encapsulates IPv6 packets in IPv4, and gives
them their own IP type, which most firewalls block as unknown,
as their payload type is directly "TCP", "UDP" or
"ICMP". Usually, you want to setup your 6to4
gateway on the same machine that is directly connected to the
(IPv4) internet, and which usually runs the firewall. For the
case that you want to run your 6to4 gateway behind a firewall,
you need to drill a hole into the firewall, to let 6to4
packets through. Here is how to do this!

The example assumes that you use the "ppp0" interface on your
firewall to connect to the Internet.

Put the following lines into
/etc/ipf.conf to allow your IPFilter
firewall let all 6to4 packets pass (lines broken with \ due to
space restrictions; please put them lines continued that way
all in one line):

# Handle traffic by different rulesets
block in quick on ppp0 all head 1
block out quick on ppp0 all head 2
### Incoming packets:
# allow some IPv4:
pass in log quick on ppp0 proto tcp from any to any \
port = www flags S keep state keep frags group 1
pass in quick on ppp0 proto tcp from any to any \
port = ssh keep state group 1
pass in quick on ppp0 proto tcp from any to any \
port = mail keep state group 1
pass in log quick on ppp0 proto tcp from any to any \
port = ftp keep state group 1
pass in log quick on ppp0 proto tcp from any to any \
port = ftp-data keep state group 1
pass in log quick on ppp0 proto icmp from any to any group 1
# allow all IPv6:
pass in quick on ppp0 proto ipv6 from any to any group 1
pass in log quick on ppp0 proto ipv6-route from any to any group 1
pass in log quick on ppp0 proto ipv6-frag from any to any group 1
pass in log quick on ppp0 proto ipv6-icmp from any to any group 1
pass in log quick on ppp0 proto ipv6-nonxt from any to any group 1
pass in log quick on ppp0 proto ipv6-opts from any to any group 1
# block rest:
blockin log quick on ppp0 all group 1
### Outgoing packets:
# allow usual stuff:
pass out quick on ppp0 proto tcp from any to any flags S \
keep state keep frags group 2
pass out quick on ppp0 proto udp from any to any \
keep state keep frags group 2
pass out quick on ppp0 proto icmp from any to any \
keep state group 2
# allow all IPv6:
pass out quick on ppp0 proto ipv6 from any to any group 2
pass out log quick on ppp0 proto ipv6-route from any to any group 2
pass out log quick on ppp0 proto ipv6-frag from any to any group 2
pass out log quick on ppp0 proto ipv6-icmp from any to any group 2
pass out log quick on ppp0 proto ipv6-nonxt from any to any group 2
pass out log quick on ppp0 proto ipv6-opts from any to any group 2
# block rest:
block out log quick on ppp0 all group 2

Now any host on your network can send (the "out" rules) and
receive (the "in" rules) v4-encapsulated IPv6 packets,
allowing setup of any of them as a 6to4 gateway. Of course you
only want to do this on one host and use native IPv6 between
your hosts, and you may also want to enforce this with more
restrictive rulesets, please see ipf.conf(5) for more
information on IPFilter rules.

After your firewall lets pass encapsulated IPv6 packets, you
may want to set up your 6to4 gateway to monitor the IPv6
traffic, or even restrict it. To do so, you need to setup
IPFilter on your 6to4 gateway as well. For basic monitoring,
enable "ipfilter=yes" in /etc/rc.conf
and put the following into
/etc/ipf6.conf:

pass in log quick on stf0 from any to any
pass out log quick on stf0 from any to any

This logs all (IPv6) traffic going in and out of your "stf0"
tunneling interface. You can add filter rules as well if
needed.

If you are more interested in traffic stats than a general
overview of your network traffic, using MRTG in conjunction
with the "net-snmp" package is recommended instead of
analyzing IPFilter log files.

24.9.11. Conclusion & Further Reading

Compared to where IPv4 is today, IPv6 is still in its early
steps. It is working, there are all sort of services and
clients available, only the userbase is missing. It is hoped
the information provided here helps people better understand
what IPv6 is, and to start playing with it.

A few links should be mentioned here for interested parties:

An example script to setup 6to4 on BSD based machines is
available at
http://www.NetBSD.org/packages/net/hf6to4/.
The script determines your IPv6 address and sets up 6to4
and (if wanted) router advertising. It was designed to
work in dialup setups with changing IPv4 addresses.

The "internet super server", or inetd(8), is available on all
Unix(like) systems, providing many of the basic network services
available. This chapter describes the relationship between the
daemon and several of the config files in the
/etc/ directory.

25.1. Overview

In this document we will look at a simple definition of
inetd(8),
how several files that relate to inetd(8) work (not that these
files are not related to other software), how to add a service
to inetd(8) and some considerations both to use inetd(8) for a
particular service and times when a service might be better
off running outside of inetd(8).

25.2. What is inetd?

In traditional Unix scenarios, one server (daemon) process
watches for connections on a particular port, and handles
incoming requests. Now if a machine offers many services, many
daemon processes would be needed, mostly running idle but still
wasting resources like memory. The internet super server,
inetd, is an approach to this problem. It listens on a number of
ports, and when it receives a request it then determines which
program to run to handle the request and starts an instance of
that program.

In the above diagram you can see the general idea. The
inetd(8) process receives a request and then starts the
appropriate server process. What inetd(8) is doing is
software multiplexing. An important note here, regarding
security: On many other UNIX-like systems, a package called
tcpwrappers is used as a security enhancement for
inetd(8). On NetBSD the tcpwrapper functionality is built
into inetd(8) using libwrap.

25.3. Configuring inetd - /etc/inetd.conf

The operation of inetd(8) is controlled by its own config
file, surprisingly named /etc/inetd.conf,
see inetd.conf(5).
The inetd.conf file basically provides
enabling and mapping of services the systems administrator
would like to have multiplexed through inetd(8), indicating
which program should be started for incoming requests on which
port.

inetd.conf(5) is an ascii file containing one service per
line, and several fields per line. The basic field layout is:

The service name indicates the port inetd(8) should
listen on. It is either a decimal number, or a name
matching a service name given in
/etc/services.

socket-type:

The communications socket type, the different types are
"stream" for a TCP stream, "dgram" for an UDP service,
"raw" for a raw socket, "rdm" for reliably delivered
message and "seqpacket" for a sequenced packet socket. The
most common socket types are "stream" and "dgram".

protocol

The protocol used, mostly "tcp", "tcp6", "udp" and "udp6"
for stream-oriented services via the Transmission Control
Protocol, or datagram-oriented services via the User
Datagram Protocol. It is worth noting that "tcp" and
"udp" mean they use the default (currently IPv4), "tcp4"
specifically means communication via IPv4 only, and "tcp6"
and "udp6" are IPv6-only. In addition to those, protocols
based on Remote Procedure Calls (RPC)
can be specified as either "rpc/tcp" or "rpc/udp".

wait/nowait

This field tells inetd(8) if it should wait for a server
program to return or to continue processing new connections
immediately. Many connections to server processes require
answers after data transfers are complete, where other types
can keep transmitting on a connection continuously, the
latter is a "nowait" and the former "wait". In most cases,
this entry corresponds to the socket-type, for example
a streaming connection would (most of the time) have a
"nowait" value in this field.

user[:group]

This field gives the user name and optionally a group name
that the server process which inetd(8) starts up runs
as.

server-program

This field is the full path of the program that gets started.

program-arguments

This field contains the argument vector argv[] of the
program started, including the program name and additional
arguments the systems administrator may need to specify
for the server program that is started.

That is all a lot to digest and there are other things the
systems administrator can do with some of the fields. Here is a
sample line from an inetd.conf file:

ftp stream tcp nowait root /usr/libexec/ftpd ftpd -ll

From the left, the service-name is "ftp", socket-type is "stream",
protocol is "tcp", inetd(8) won't wait for the server
process to terminate ("nowait"), the process runs as user "root",
path is /usr/libexec/ftpd and program name
and arguments are "ftpd -ll".
Notice in the last field, the program name is different
from the service-name.

25.4. Services - /etc/services

The next file to consider is the service name data base that can
be found in /etc/services. This file
basically contains information mapping a service name to a port
number. The format of the /etc/services
file is:

service-name port-number/protocol-name [aliases]

"service-name" is the name of the service, "port-number" is the
port number assigned to the service, "protocol-name" is either
"tcp" or "udp", and if alias names for a port are needed, they
can be added as "aliases", separated by white spaces. Comments
may be added after a hash mark (#).

Let's take a look at the "ssh" entries as an example:

ssh 22/tcp # Secure Shell
ssh 22/udp

As we can see, from the left, the service name is "ssh",
the port number is "22", the protocols are both "tcp" and "udp".
Notice that there is a separate entry for every protocol a
service can use (even on the same port).

25.5. Protocols - /etc/protocols

Another file read by inetd(8) is
/etc/protocols. This file has the information
pertaining to DARPA Internet protocols.
The format of the protocols name data base is:

protocol-name number [aliases]

where "protocol-name" describes the payload of an IP packet,
e.g. "tcp" or "udp". "number" is the official protocol number
assigned by IANA, and optional alias name