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, the modifications from the 4.4BSD Lite release (the last release of the Berkeley group) have been integrated in the system. The BSD branch of Unix has had a great importance and influence in the history of this operating system, to which it has contributed many tools, ideas and improvements (the vi editor, the C shell, job control, the Berkeley fast file system, reliable signals, support for virtual memory, TCP/IP implementation, just to name a few) which are now standard in all Unix environments. This tradition of research and development survives today in the BSD systems (free and commercial) and, in particular, in NetBSD.

1.2 NetBSD features

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

A detailed list of NetBSD features can be found at: http://www.NetBSD.org/Misc/features.html.

The basic features of NetBSD are:

• Portability (more than 50 platforms are supported)

• Code quality and correctness

• Adherence to the standards

• Research and innovation

The aforementioned 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 that many platforms. And code quality is the base of any good and solid software systems, though surprisingly few people seem to understand it. The attention to architectural and quality issues is rewarded with the great potentiality of NetBSD's code and the quality of it's drivers.

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

1.3 Supported platforms

NetBSD supports over 50 platforms, including the popular i386, sparc, sparc64, alpha, mac68k and macppc platforms. 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". I would add that NetBSD is an ideal system if you want to learn Unix, mainly because of its adherence to standards (one of the project goals) and because it can run on hardware which is considered obsolete by most other operating systems; we could say "to learn and use Unix you don't need to buy expensive hardware: you can reuse the old PC or Mac that you have in your attic". Also, if you need a Unix system which runs consitently on a variety of platforms, NetBSD is probably your best (only) choice.

1.5 Applications for NetBSD

When you install NetBSD you have a rich set of programs and applications that you can install on your system. Besides having all the standard Unix productivity tools, editors, formatters, C/C++ compilers and debuggers and so on, there is a huge (and constantly growing, I think it is now over 1000) number of packages 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 and there is also a number of commercial applications. You can also make use of one of the available emulation to run binaries from other *nix operating systems. Linux emulation is probably the most relevant example, lots of efforts have gone into it and it is used by almost all NetBSD users; you can run the Linux version of

• Netscape

• Acrobat Reader

• Doom, Quake

• Adobe FrameMaker

• many other programs

NetBSD is also capable of emulating FreeBSD, BSDI and other systems.

1.6 The philosophy of NetBSD

Differently from many contemporary operating systems, the NetBSD installation, though feature rich is not huge in size, because it strives to produce a stable and complete base system without being redundant. After the installation you get a fully working system which still lacks a number of applications like, for example, a web browser (NetBSD, contrary to other OS, does not consider the browser as part of the base system): you have the freedom to decide which programs to install on your machine and the installation of new programs is very easy with the packages collection.

Another advantage of this approach is that the base system will work without these additional packages; if you decide to upgrade your version of Perl you need'nt be afraid to break some parts of your system. When you install NetBSD you don't find huge pre-packaged collections of applications: you may now see this as a disadvantage but when you start understanding the philosophy behind this you will find that it gives you freedom. When you install these software collections (which someone else has decided for you) you fill your hard disk with tons of programs, most of which will stay unused (and unknown) and only waste space (and possibly make the system less stable): this is something which the typical BSD user doesn't want to do.

Even when you start knowing NetBSD, there is always something that will continue to amaze you, the extreme consistency and logic of the system and the attention to the details: nothing appears the result of chance and everything is well thought out. Yes, that's what quality is about and, in my opinion, this is the most distinguishing feature of NetBSD.

We could spend days arguing on the relative merits of operating systems (and some people like to do it) but if you don't try something seriously you can't really judge. I am convinced, because I saw it many times in the mailing lists, that if you try NetBSD you'll be conquered by the perfect balance between complexity and effectiveness; all problems have more than one solution: NetBSD is not happy with a solution but always tries to find the easiest and most elegant one. NetBSD is a tool that enables you to do your work without getting in your way. In this light it is an optimal tool; it's like using a pen: you work hard to learn how to use it but once you've learned you can write or draw and completely forget about the pen.

1.7 How to get NetBSD

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. Of course you can also download NetBSD from the Internet from one of the mirrors.

2.1 What's new in NetBSD 2.0?

It is impossible to list every single improvement to NetBSD since the previous release, 1.6, however, a summary of the major new features in NetBSD 2.0 are below.

2.2 New ports and enhancements to existing ports

2.3 The NetBSD Packages Collection (pkgsrc)

pkgsrc has been significantly expanded and now contains almost 4000 packages. A number of new platforms are supported, including OpenBSD, IRIX and FreeBSD, and a new, portable bootstrap kit has been created making it much simpler to port to new operating systems.

3.1 Documentation

The documentation of NetBSD is mostly in the format for manual pages and makes up an excellent technical reference to the system. I won't deny that it is unsuited as a tutorial (not to mention the fact that you can't read it until you install NetBSD); these are the reasons for the existence of this guide.

After installation you will find some BSD guides in the /usr/share/doc directory. They are divided in three main sections, psd (UNIX Programmer's Supplementary Documents), smm (UNIX System Manager's Manual) and usd (UNIX User's Supplementary Documents). You can read the text on the terminal with, for example:

$ cd /usr/share/doc/smm/09.sendmail
$ nroff -me 09.sendmail/intro.me | more

or you can generate Postscript output using the makefiles.

It's undeniable that there is a lack of HOWTOs and for this reason you should make the most of the existing ones; the NetBSD release contains some documents in text format and on the NetBSD web site you can find further information and FAQ's.

All the versions of NetBSD contain the following files:

On the NetBSD web site you can find, amongst the others, the following guides:

3.2 The layout of a NetBSD installation

The layout of the files of a NetBSD installation is described in the aforementioned INSTALL file. For example, for the i386 platform the system binaries are in the i386/binary/sets directory and the sources are in the source/sets directory. The source/patches directory contains patches to the base release which usually fix bugs or security related problems discovered after the release.

3.3 Installation

The first thing to do before installing NetBSD is to read the release information and installation notes in the INSTALL file: this is the official description of the installation procedure. Next you should decide the installation media that you will use; you can choose between:

• ftp

• nfs

• CDROM

• floppy

• unmounted filesystem

• local directory

real:  6232 cyl,   16 heads,  63 sec
BIOS:   779 cyl,  128 heads,  63 sec   (LBA)

Filesystem  1K-blocks     Used    Avail Capacity  Mounted on
/dev/wd1a       31887    16848    13444    56%    /
/dev/wd1e      363507   173202   172129    50%    /usr

4.1 Installation example

The remaining part of this chapter deals with a real installation example for a common case: installation from CD-ROM. The concepts are the same for all types of installation (eg. ftp); the only difference is in the way the binary sets are found by sysinst. Please note that some details of the installation differ depending on the NetBSD release: this example was created with release 1.5.

For the sake of teaching, in the following example the most "difficult" options will always be chosen.

• BIOS partition table full: one or more existing partitions will be deleted to make room for NetBSD.

• fdisk partitioning using sectors instead of MB.

• manual modification of the disklabel created by sysinst, also using sectors.

• "custom" installation (meaning that you can select one by one the binary sets that you want to install).

This set of choices gives the impression that the installation is very complicated and requires a lot of work: remember that if you accept the defaults everything is much simpler. On the other hand, a tutorial which explains only the "easy" parts is not very useful (except from the marketing point of view...)

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

ne0     at isa? port 0x280 irq 9        # NE[12]000 ethernet cards
ne1     at isa? port 0x300 irq 10

6232 cyl, 16 heads, 63 sec  (6232 x 16 x 63 = 6281856 total sectors)
1 sector = 512 bytes
1 track = 63 sectors = 63 * 512 bytes = 32 K
1 cylinder = 16 * 63 * 512 bytes = 504 K

id:      Size    Offset       End FStype Bsize Fsize Mount point
---      ----    ------       --- ------ ----- ----- -----------
 a:    435453   2088579   2524031 4.2BSD  8192  1024 /
 b:    307200   2524032   2831231   swap
 ...

id:      Size    Offset       End FStype Bsize Fsize Mount point
---      ----    ------       --- ------ ----- ----- -----------
 a:    435453   2088579   2524031 4.2BSD  8192  1024 /
 b:    307200   2524032   2831231   swap
 ...
 e:   3450624   2831232   6281855 4.2BSD  8192  1024 /usr

5.1 If something went wrong

If the system doesn't boot it could be that the boot manager was not installed correctly or that there is a problem with the MBR (Master Boot Record). Reboot the machine from the boot floppy and when you see the prompt:

booting fd0a:netbsd - starting in ...

press the space bar during the 5 second countdown; the boot stops and a prompt is displayed. You can have a basic help with the "?" key or with the "help" command.

type "?" or "help" for help.
> ?
commands are:
boot [xdNx:][filename] [-adrs]
     (ex. "sd0a:netbsd.old -s")
ls [path]
dev xd[N[x]]:
help|?
quit
> boot wd0a:netbsd

The system should now boot from the hard disk instead of the foppy. 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 24.4 for a detailed description.

5.2 Login

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

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

5.3 Changing the keyboard layout

The keyboard has still the US layout; if you have a different keyboard it's better to change its layout now, before starting to configure the system. For example, to use the italian keyboard, give the following command:

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

A full list of keyboard mappings is in /sys/dev/wscons/wsksymdef.h but some of the more common maps are:

• de

• dk

• fr

• it

• jp

• sv

• uk

• us

This setting will last until the next reboot. To make it permanent, add the previous command at the end of the /etc/rc.local: it will be executed automatically the next time you reboot.

# echo "wsconsctl -k -w encoding=it" >> /etc/rc.local

There is also a better approach to the keyboard layout problem: you can compile a new kernel which uses your preferred layout by default. This will be described in Chapter 9.

5.4 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 amongst the best and most detailed you can find, although they are very technical.

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

The manual is divided in nine sections, containing not only basic infomations on commands but also the descriptions of some NetBSD features and structures. For example, take a look at the hier(7) man page, which describes in detail the layout of the filesystem used by NetBSD.

# man hier

Other similar pages are release(7) and packages(7). Each section of the manual has an intro man page describing its content. For example, try:

# man 8 intro

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

# man 3 time

To see all the available pages:

# man -a time

5.5 Changing the root password

If you haven't defined a password for root during installation (which was not possible on pre 1.5 systems) now it's time to do it, using the passwd command.

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

Password are not displayed on the screen while you type. Later we will see how to add other accounts on the system.

5.6 Changing the shell

The default shell for root is csh; if this doesn't mean anything to you, you should begin studying csh with (man csh): it's a good interactive shell although it lacks history editing (have a look at tcsh, bash or even the NetBSD /bin/sh for this). If you want to change your shell, use the chsh. The shells available on NetBSD after installation are:

• csh

• sh

• ksh

The new shell will come into effect the next time you login. In the mean time, you can issue the following command:

# set filec

that enables filename completion on the command line (with the ESC key; use Ctrl+D for a list of possible completions.)

You can also install other shells on the system, if you want to: tcsh, bash, zsh and other shells are available in the package collection (which we shall examine later).

This is a good time to create the shell's initialization files (.chsrc, .login, ...)

5.7 System time

NetBSD, like all UNIX systems, uses a system clock based on Greenwich time (UTC) 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, modifying the rtc_offset system variable. You can edit the kernel configuration file and recompile the kernel or you can patch directly the existing kernel (the new time will be effective only after rebooting): this is easier than you think. For example:

# gdb --write /netbsd
GNU gdb 4.17
Copyright 1998 Free Software Foundation, Inc.
...
This GDB was configured as "i386--netbsd"...(no debugging symbols found)...
(gdb) set rtc_offset=-60
(gdb) quit

The value supplied (-60) is the number of minutes west of UTC.

To display the current setting of the rtc_offset variable:

# sysctl kern.rtc_offset
kern.rtc_offset = -60

Now the kernel knows how to convert the time of the PC clock in the UTC system time but you must still configure the system for your local time zone (which you will find in /usr/share/zoneinfo/.) If you have already done this during the installation you can skip this step (although it is better to check that the setting is correct.) For example, for Italy:

# rm -f /etc/localtime
# ln -s /usr/share/zoneinfo/Europe/Rome /etc/localtime

Once everything is set up correctly, you can change the time with the following command:

# date [[[[[cc]yy]mm]dd]hh]mm

5.8 Basic configuration /etc/rc.conf

NetBSD uses the /etc/rc.conf for system configuration at startup: this file determines what will be executed when the system boots. Understanding this file is very important.

Starting from version 1.5 of NetBSD the administration of rc.conf has changed. In prior versions all the default values were stored in /etc/rc.conf and the user was supposed to modify directly this file; version 1.5 introduced the /etc/defaults/rc.conf file, which contains the default values. To modify a default value the user must write the new value in /etc/rc.conf: this definition overrides the one in /etc/defaults/rc.conf (which stays unchanged.)

Understanding this file is very important. The manual page contains a detailed description of all the options.

# man rc.conf

The first modifications are:

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

• Set "lpd=YES" to activate the printer spooler daemon

• Define an hostname for your machine (use a fully qualified hostname). If you have a standalone machine you can use any name (for example, "woody.toys.net".) If your machine is connected to a network, you should supply the correct network name.

  Instead of defining the host name in the configuration file, you can write it in the /etc/myname file: the result is the same.

  Note: Make sure that the hostname is resolvable, either using DNS or /etc/hosts, some programs do not work with an unresolvable hostname.

5.9 Rebooting the system

In this first session you have

• Configured the keyboard

• Changed the root password

• Changed root's shell (optional)

• Changed the system time and the RTC offset

• Defined the local time

• Configured /etc/rc.conf

Now it's time to reboot the system, with the following command:

# reboot

6.1 dmesg

At system startup the kernel displays a long sequence of messages on the screen: these messages give information about the kernel status (for example, available memory) and the peripherals that have been detected on the system. This information is very important for diagnosing hardware or configuration problems, and for determining the name of the devices for the peripherals (for example you can check if your network card has been detected as ne0 or ne1.) Usually these messages scroll on the screen too fast to be useful, but you can use the dmesg command to view them again.

# dmesg | more

If something on your system doesn't appear to work correctly and you ask for help on one of the NetBSD mailing lists, always remember to include the relevant dmesg output in your post: it will help other people diagnose your problem.

6.2 Mounting the 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 as any other file system, all you need to know is the device name and some options to the mount command. You can find the device name with the aforementioned dmesg command. For example, if dmesg displays:

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

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

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

in most cases NetBSD can also automatically detect the filesystem type. In most cases the following command is sufficient:

# mount /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 cdrom with:

# mount /cdrom

When the cdrom is mounted you can't eject it manually; you'll have to unmount it before you can do that:

# umount /cdrom

There is also a software command which unmounts the cdrom and ejects it:

# eject /dev/cd0a

6.3 Mounting the 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. 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 cdrom. 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 from/to floppy.

6.4 Accessing a DOS/Windows partition

If NetBSD shares the hard disk with MS-DOS or Windows, it is possible modify the disklabel and make the DOS partitions visible from NetBSD. First, you must determine the geometry of the DOS partition , for example using fdisk.

# fdisk wd0
NetBSD disklabel disk geometry:
cylinders: 6232 heads: 16 sectors/track: 63 (1008 sectors/cylinder)
...
Partition table:
0: sysid 6 (Primary 'big' DOS, 16-bit FAT (> 32MB))
    start 63, size 2088516 (1019 MB), flag 0x80
        beg: cylinder    0, head   1, sector  1
        end: cylinder  259, head   0, sector  4
1: sysid 169 (NetBSD)
    start 2088579, size 4193277 (2047 MB), flag 0x0
        beg: cylinder  259, head   0, sector  4
        end: cylinder  779, head   0, sector  1
2: <UNUSED>
3: <UNUSED>

The output of the fdisk command shows that the DOS partition begins at sector 63 and has a size of 2088516 sectors. The NetBSD partition begins at sector 2088579 (2088579 = 2088516 + 63). You will use this data to modify the BSD disklabel: all you have to do is add one line which defines the position and type of the MS-DOS partition, choosing one of the still unused partition id letters. Use the disklabel command to modify the disklabel. If you give the -e option to disklabel it will invoke your favourite editor ($EDITOR) to modify the disklabel. For example:

# disklabel -e wd0
...
#        size   offset     fstype  [fsize bsize  cpg]
...
  e:  3450624  2831232    4.2BSD    1024  8192    16   # (Cyl.  2808* - 6231)
  f:  2088516       63    MSDOS

The partitions from "a" to "e" were already used by NetBSD and the first available id was "f". The "size" and "offset" fields have been filled with the previously calculated numbers. Next, the mount point must be created. For example:

# mkdir /msdos

finally, a line will be added to the /etc/fstab file.

/dev/wd0f /msdos msdos rw,noauto 1 3

Now the MS-DOS partition can be mounted with a simple command:

# mount /msdos

With this method you can mount FAT and FAT32 partitions. If you want to mount the partition(s) automatically at startup, remove the "noauto" option from /etc/fstab.

/dev/wd0f /msdos msdos rw 1 3

6.5 Adding users

It's time to add new users to the system, since you don't want to use the root account for your daily work. NetBSD doesn't have a program to create new users; instead you should read the adduser manpage.

# man adduser

Following the instructions on the page you'll also begin using vipw which is the basic administration tool for new accounts under NetBSD.

6.6 Shadow passwords

Shadow passwords are enabled by default on NetBSD and can't be disabled: all the passwords in /etc/passwd contain an '*'; the encrypted passwords belong to another file, /etc/master.passwd, that can be read only by root. When you start vipw 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 a new /etc/master.passwd file. Finally, vipw launches pwd_mkdb, which creates the files /etc/pwd.db and /etc/spwd.db, two databases equivalent to /etc/passwd and /etc/master.passwd but faster to process.

As you can see, passwords are handled automatically by NetBSD; if you use vipw to edit the password file you don't need any special administration procedure.

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

6.7 Stopping and rebooting the system

The command used to halt and/or reboot the system is shutdown.

# shutdown -h now
# shutdown -r now

Two other commands perform the same tasks:

# halt
# reboot

halt/reboot and shutdown are not synonyms: the latter is more sophisticated. On a multiuser system you should really use shutdown: you can also schedule a shutdown, notify users, etc. For a more detailed description, see shutdown(8), halt(8) and reboot(8).

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

# lpd -s

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.

Before configuring /etc/printcap it is better to make a printer test, to check if the connection is working. For example:

# lptest 20 10 > /dev/lpt0

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

# lptest 20 10

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:

• changing the configuration of the printer

• using a simple printer filter (described later)

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

lp|local printer|HP DeskJet 690C:\
        :lp=/dev/lpa0:sd=/var/spool/lpd/lp:lf=/var/log/lpd-errs:\
        :sh:pl#66:pw#80:if=/usr/local/libexec/lpfilter:

The file format and options are described in detail in printcap(5). 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

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

#!/bin/sh
# Treat LF as CR+LF
printf "\033&k2G" && cat && exit 0
exit 2

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

The lptest command can be run again now, this time using the lpd spooler.

# lptest 20 10 | 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).

You can solve the staircase problem using a variety of tools and methods, for example C programs. The solution presented has the benefit of being very simple.

7.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 capable of converting a PostScript document in a sequence of commands that can be understood by the printer. The Ghostscript program, from the packages collection, can be used to this purpose (see Chapter 10). This section explains how to configure 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 a filter could be used: 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.

The new /etc/printcap file looks like this:

lp|local printer|HP DeskJet 690C:\
        :lp=/dev/lpa0:sd=/var/spool/lpd/lp:lf=/var/log/lpd-errs:\
        :sh:pl#66:pw#80:if=/usr/local/libexec/lpfilter:
ps|Ghostscript driver:\
        :lp=/dev/lpa0:sd=/var/spool/lpd/ps:lf=/var/log/lpd-errs:\
        :mx#0:sh:if=/usr/local/libexec/lpfilter-ps:

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 last step is the creation of the new spool directory and of the filter program.

# 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, in turn, sends to the printer a sequence of commands in the printer's control language. 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.

#!/bin/sh
# Treat LF as CR+LF
printf "\033&k2G" || exit 2
# Print the postscript file
/usr/pkg/bin/gs -dSAFER -dBATCH -dQUIET -dNOPAUSE -q -sDEVICE=cdj550 \
-sOutputFile=- -sPAPERSIZE=a4 - && exit 0
exit 2

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.

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

7.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 7-3. From wotan it will be possible to print Postscript files using Ghostscript on loge.

The first step is to enable on the loge host the print jobs submitted from the wotan host. This is accomplished inserting a line with the wotan host name in the /etc/hosts.lpd file on loge. The format of this file is very simple: each line contains the name of a host to be enabled.

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

lp|line printer on loge:\
        :lp=:sd=/var/spool/lpd/lp:lf=/var/log/lp-errs:\
        :rm=loge:rp=lp
ps|Ghostscript driver on loge:\
        :lp=:sd=/var/spool/lpd/lp:lf=/var/log/lp-errs:\
        :mx#0:\
        :rm=loge:rp=ps

There are four main differences between this configuration and the one of Example 7-3.

1. The definition of "lp" is empty.

2. The "rm" entry defines the name of the host to which the printer is connected.

3. The "rp" entry defines the name of the printer connected to the remote host.

4. It is not necessary to specify input filters because the definitions on the loge host will be used.

Now the print jobs for "lp" and "ps" on wotan will be sent automatically to printer connected to loge.

8.1 Building the tools

Once the sources have been obtained, the native platform tools have to be built before doing anything else. Doing this is simple, we will use the default object directory.

# mkdir /usr/obj
# cd /usr/src
# ./build.sh tools
   

If the tools have already been built and they only need updated, then the update option can be used to only rebuild tools that have changed.

# ./build.sh -u tools
   

Now that the native tools have been built, the tools for another target system can be created. In our example, sparc64 will be used.

# ./build.sh -m sparc64 tools
   

When the tools are finished building, information about them and several environment variables is printed out:

Summary of results:
         build.sh command: ./build.sh -u -m sparc64 tools
         build.sh started: Mon Jul 28 11:08:30 UTC 2003
         Bootstrapping nbmake
         MACHINE:          sparc64
         MACHINE_ARCH:     sparc64
         TOOLDIR path:     /usr/src/tooldir.NetBSD-1.6U-i386
         DESTDIR path:     /usr/src/destdir.sparc64
         RELEASEDIR path:  /usr/src/releasedir
         Created /usr/src/tooldir.NetBSD-1.6U-i386/bin/nbmake
         makewrapper:      /usr/src/tooldir.NetBSD-1.6U-i386/bin/nbmake-sparc64
         Updated /usr/src/tooldir.NetBSD-1.6U-i386/bin/nbmake-sparc64
         Tools built to /usr/src/tooldir.NetBSD-1.6U-i386
         build.sh started: Mon Jul 28 11:08:30 UTC 2003
         build.sh ended:   Mon Jul 28 11:11:14 UTC 2003
   

Now that the tools for sparc64 have been built, it is time to cross compile the kernel.

8.2 Cross Compiling a Kernel

A cross compiled kernel can be done by either going to the architecture conf directory and explicitly calling the cross compiled tools or the easier method of using build.sh.

Configuring the kernel is the same:

# cd /usr/src/sys/arch/sparc64/conf
# cp GENERIC MYKERNEL
   

Then edit MYKERNEL. Once finished, all that needs to be done is to use build.sh to build the kernel (it will also configure it):

# cd /usr/src
# ./build.sh -u -m sparc kernel=MYKERNEL
   

Notice that update was specified, the tools are already built, there is no reason to rebuild all of the tools. Once the kernel is built, build.sh will print out the location of it along with other information:

Summary of results:
         build.sh command: ./build.sh -u -m sparc64 tools
         build.sh started: Mon Jul 28 11:08:30 UTC 2003
         Bootstrapping nbmake
         MACHINE:          sparc64
         MACHINE_ARCH:     sparc64
         TOOLDIR path:     /usr/src/tooldir.NetBSD-1.6U-i386
         DESTDIR path:     /usr/src/destdir.sparc64
         RELEASEDIR path:  /usr/src/releasedir
         Created /usr/src/tooldir.NetBSD-1.6U-i386/bin/nbmake
         makewrapper:      /usr/src/tooldir.NetBSD-1.6U-i386/bin/nbmake-sparc64
         Updated /usr/src/tooldir.NetBSD-1.6U-i386/bin/nbmake-sparc64
         Building kernel without building new tools
         Building kernel:  MYKERNEL
         Build directory:  /usr/src/sys/arch/i386/compile/MYKERNEL
         Kernels built from MYKERNEL:
           /usr/src/sys/arch/sparc64/compile/MYKERNEL/netbsd
         build.sh started: Mon Jul 28 11:08:30 UTC 2003
         build.sh ended:   Mon Jul 28 11:11:14 UTC 2003
   

8.3 Build & Release

By now it is probably becoming clear that the toolchain actually works in stages. First is the native tools build (which actually has a step before it, makewrappers), then a kernel. Since build.sh will attempt to rebuild the tools at every invocation, using update saves time. It is also probably clear that outside of a few options, the build.sh semantics are basically [ build.sh command ]. So, it stands to reason that creating a build and/or release, is a matter of using the right commands.

It should be no surprise that building and creating a release would look like the following:

# ./build.sh -u -m sparc build
# ./build.sh -u -m sparc release
   

Looking at the information about environment variables (since so far only the defaults have been used), a build would be at:

/usr/src/destdir.sparc64
   

The release would be located at:

         RELEASEDIR path:  /usr/src/releasedir
   

8.4 Environment Variables

Not unlike the old building method, the toolchain has a lot of variables that can be used to direct things like where certain files go, what (if any) tools are used and so on. A look in src/BUILDING covers most of them. In this section two examples of changing default variables are given in two different ways.

# export DESTDIR=/usr/builds/sparc64
     

# setenv DESTDIR /usr/builds/shark
     

LDSTATIC=-static
     

9.1 Installing the kernel sources

Be patient: this operation lasts many minutes, because the repository contains hundreds of files. The sources live in /usr/src/sys; the symbolic link sys points to this directory. Therefore the following commands have the same effect:

# cd /usr/src/sys
# cd /sys

Once the sources are checked out, you can create a custom kernel: this is not as difficult as you think. In fact, a new kernel can be created in a few steps which will be described in the following sections.

9.2 Italian keyboard layout

Before compiling the kernel, Italian users should consider modifying the predefined layout for the italian keyboard, which is defined in the source file /sys/dev/pckbc/wskbdmap_mfii.c. In the default layout some characters useful for programmers are missing (for example, left and right braces and tilde). This is an alternative layout:

static const keysym_t pckbd_keydesc_it[] = {
...
KC(8),   KS_7,          KS_slash,       KS_braceleft,
KC(9),   KS_8,          KS_parenleft,   KS_bracketleft,
KC(10),  KS_9,          KS_parenright,  KS_bracketright,
KC(11),  KS_0,          KS_equal,       KS_braceright,
KC(12),  KS_apostrophe, KS_question,    KS_grave,
KC(13),  KS_igrave,     KS_asciicircum, KS_asciitilde,
KC(26),  KS_egrave,     KS_eacute,      KS_bracketleft, KS_braceleft,
KC(27),  KS_plus,       KS_asterisk,    KS_bracketright,KS_braceright,
...

The previous layout defines the following mappings:

9.3 Recompiling the kernel

To recompile the kernel you must have installed the compiler set (comp.tgz).

9.4 Build the toolchain

The NetBSD toolchain provides a simple mechanism for compiling the NetBSD system both natively or when the need arises, cross compiling for other targets. In this example, a native toolchain is built (as root) by simply typing:

# cd /usr/src
#  ./build.sh tools

Once the tools are built, the kernel can be reconfigured and compiled.

9.5 Creating the kernel configuration file

The kernel configuration file defines the type, the number and the characteristics of the devices supported by the kernel as well as several kernel configuration options. Kernel configuration files are located in the /sys/arch/i386/conf directory. The easiest way to create a new file is to copy an existing one and modify it: usually the best choice on most platforms is the GENERIC configuration. In the configuration file there are comments describing the options; a more detailed description is found in the options(4) man page.

# cd /sys/arch/i386/conf/
# cp GENERIC MYKERNEL
# vi MYKERNEL

The modification of a kernel configuration file basically involves three operations:

1. support for hardware devices is included/excluded in the kernel (for example, SCSI support can be removed if it is not needed.)

2. support for kernel features is enabled/disabled (for example, enable NFS client support, enable Linux compatibility, ...)

3. tuning kernel parameters.

Lines beginning with "#" are comments; lines are disabled by commenting them and enabled by removing the comment character. It is better to comment lines instead of deleting them; it is always possible uncomment them later.

The output of the dmesg command can be used to determine which lines can be disabled. For each line of the type:

<XXX> at <YYY>

both XXX and YYY must be active in the kernel configuration file. You'll probably have to experiment a bit before achieving a minimal configuration but on a desktop system without SCSI and PCMCIA you can halve the kernel size.

You should also examine the options in the configuration file and disable the ones that you don't need. Each option has a short comment describing it, which is normally sufficient to understand what the option does. Many options have a longer and more detailed description in the options(4) man page. While you are at it you should set correctly the options for the national keyboard support and for local time on the CMOS clock. For example, for Italy:

options RTC_OFFSET=-60
...
options PCKBD_LAYOUT="KB_IT"

The adjustkernel Perl script, which can be found at http://www.feyrer.de/Misc/adjustkernel, analizes the output of dmesg and automatically generates a minimal configuration file. To run it you need to have Perl installed on your system. The installation of new software is described in detail in the Chapter 10. If you want to install Perl now, download the pre-compiled package perl-5.00404.tgz and write the following command:

# pkg_add perl-5.00404.tgz

Now Perl is installed, configured and ready to work: easier than this it's impossible...

You can now run the script with:

# cd /sys/arch/i386/conf
# perl adjustkernel GENERIC > MYKERNEL

I tried this script and it worked very well, saving me a lot of manual editing. Beware that the script only configures the available devices: you must still configure manually the other options (eg. Linux emulation, ...)

9.6 Configuring the kernel

When you've finished modifying the kernel configuration file (which we'll call MYKERNEL), you should issue the following command:

# config MYKERNEL

If MYKERNEL contains no errors, the config program will create the necessary files for the compilation of the kernel, otherwise it will be necessary to correct the errors before running config again.

9.7 Generating dependencies and recompiling

Dependencies generation and kernel compilation is performed by the following commands:

# cd ../compile/MYKERNEL
# make depend
# make

It can happen that the compilation stops with errors; there can be a variety of reasons but the most common cause is an error in the configuration file which didn't get caught by config. Sometimes the failure is caused by a hardware problem (often faulty RAM chips): the compilation puts a higher stress on the system than most applications do. Another typical error is the following: option B, active, requires option A which is not active.

A full compilation of the kernel can last from some minutes to several hours, depending on the hardware. See the following table for some examples:

The output of the make command is the netbsd file in the compile directory: this file should be copied in the root directory, after saving the previous version.

# mv /netbsd /netbsd.old
# mv netbsd /

Customization can considerably reduce the kernel's size. In the following example netbsd.old is the install kernel and netbsd is the new kernel.

-rwxr-xr-x  1 root  wheel  1342567 Nov 13 16:47 /netbsd
-rwxr-xr-x  1 root  wheel  3111739 Sep 27 01:20 /netbsd.old

The new kernel is activated after rebooting:

# reboot

9.8 If something went wrong

When the PC is restarted it can happen that the new new kernel doesn't work as expected or even doesn't boot at all. Don't worry: if this happens, just reboot with the previously saved kernel and remove the new one (it is better to reboot "single user".)

• Reboot the machine

• Press the space bar at the boot prompt during the 5 seconds countdown

  boot:
  

• Type

  > boot netbsd.old -s
  

• Now issue the following commands to restore the previous version of the kernel:

  fsck /
  mount /
  mv netbsd.old netbsd
  exit
  

10.1 Installing the package collection

Before installing a program from source, you should download and install the package collection from the NetBSD site or from the mirror of your choice. This is described in the following steps.

1. Download the latest version of the package system sources, which include all the necessary makefiles and configuration files, from ftp://ftp.NetBSD.org/pub/NetBSD/NetBSD-current/tar_files/. The file to be downloaded is pkgsrc.tar.gz.

2. Remove the existing collection from your hard disk (if you already have installed it) with the following command:

   # cd /usr
   # rm -rf pkgsrc
   

3. Install the collection that you have downloaded:

   # tar -xzvpf pkgsrc.tar.gz -C /usr
   

   The execution of the previous command can last many minutes, because of the huge number of (small) files that are extracted. At the end, the framework required for the installation of new programs is ready and you can start installing them.

   Note: by now it is probably clear that the previous commands installed the configuration files required for the automatic installation of programs on your system: you have not yet installed the programs! Basically, the system now has a list of the available packages and the instructions to fetch, compile and install them.

   
   
   

When you have installed the package collection you can browse it with Lynx or Netscape and read the details and the descriptions of all the available packages and package categories. For example:

$ cd /usr/pkgsrc
$ lynx README.html

# mkdir /usr/pkgsrc_distfiles

DISTDIR=/usr/pkgsrc_distfiles

10.2 Updating the package collection

The package collection is frequently updated: you can find a new version on the ftp site almost weekly. To update the collection on your system follow the same instructions as for first time installation.

Sometimes, when updating the package collection, it will be necessary to update the "pkgtools" utilities too. You can easily spot if you need to do it: when you try to install a program the package system complains that your pkgtools are outdated.

# make
===> Validating dependencies for gqmpeg-0.6.3
Your package tools need to be updated to 2000/02/02 versions.
The installed package tools were last updated on 1999/01/01.
Please make and install the pkgsrc/pkgtools/pkg_install package.
*** Error code 1

The easiest way to update is:

# cd /usr/pkgsrc/pkgtools/pkg_install
# make install

After this you can resume the installation of the package which issued the original error message.

10.3 Example: installing a program from source

This section describes the installation of an example program: the cdrecord application, which simplifies the creation of new accounts on your system. First, cd to the /usr/pkgsrc/sysutils/cdrecord directory.

DISTNAME = cdrtools-2.0

# cd /usr/pkgsrc/sysutils/cdrecord
# make fetch-list

# cd /usr/pkgsrc/sysutils/cdrecord
# make

# make install

# make clean
# make clean-depends

# make clean CLEANDEPENDS=1

10.4 Example: installing a binary package

I have already explained in the first part of this chapter that the package system can install program from source but can also install binary packages, prepared by someone else for NetBSD. This second form of installation is faster because the compilation of the package is not needed and the tarballs for the binary package are usually smaller and faster to fetch. To install a binary package the package collection is not needed: only the "pkgtools" utilities are needed.

The tarballs for the binary programs usually have the extension .tgz while the source tarballs usually end with .tar.gz.

It is not strictly necessary to download binary packages prior to installation: you can also use ftp://-URLs. For example:

ftp://ftp.NetBSD.org/pub/NetBSD/packages/1.4.2/i386/All/tcsh-6.09.00.tgz

If you don't know what version of the package is available on the FTP site you can even leave out the version inormation and pkg_add will pick the latest version on the FTP server. For example:

# pkg_add ftp://ftp.NetBSD.org/pub/NetBSD/packages/1.4.2/i386/All/tcsh

It is also possible to set PKG_PATH to a ;-separated list of path and URLs and then omit that part for pkg_add:

# PKG_PATH="/cdrom;/usr/pkgsrc/packages/All;ftp://ftp.NetBSD.org/pub/NetBSD/packages/1.4.2/i386/All/"
export PKG_PATH
# pkg_add tcsh

The previous command installs the first tcsh binary package that it finds.

As an example, let's install the texinfo program in precompiled form.

1. Copy gtexinfo-3.12.tgz in a temporary directory.

2. Give the following command

   # pkg_add -v gtexinfo-3.12.tgz
   

3. Check that the package has been installed with the command

   # pkg_info
   

4. Remove the file gtexinfo-3.12.tgz from the temporary directory.

Precompiled packages are very practical to use because they require a minimal effort and time for installation, but source packages give more control because their compilation options can be customized. The installation is somewhat longer, because of the compilation, and this could be critical on some (older) platforms.

Before installing a precompiled package with pkg_add, it is better to examine it with the pkg_info command. For example:

# pkg_info -f jpeg-6b.tgz

It is worth examining the first CWD command, to check where the package is installed (base directory.) The most common base directories are /usr/pkg and /usr/X11R6. If the base directory is not what you want, you can change it with the -p of the pkg_add command. For example, the jpeg-6b.tgz package is installed in /usr/pkg by default, but you can install it in /usr/X11R6 if you extract it with the following command:

# pkg_add -p /usr/X11R6 -v jpeg-6b.tgz

10.5 Package management commands

The most important commands for package management are:

10.6 Quick Start Packaging Guide

This section details a quick start method for building relatively small Packages for the NetBSD packaging system. For more details on some of the intricacies on the NetBSD packaging system see pkgsrc documentation.

$ pkglint
OK: checking pkg/COMMENT.
OK: checking pkg/DESCR.
OK: checking Makefile.
OK: checking files/md5.
OK: checking patches/patch-aa.
looks fine.

$ tar -czf packagename.tgz package_dir

11.1 Introduction to TCP/IP Networking

IP-address        hostname [nickname [...]]

127.0.0.1               localhost
::1                     localhost

noon            IN      AAAA    3ffe:400:430:2:240:95ff:fe40:4385

zone "0.3.4.0.0.0.4.0.e.f.f.3.IP6.INT" {
        type master;
        file "db.reverse";
};

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.

11.2 Practice

#       $NetBSD: GENERIC,v 1.354.2.15 2001/05/06 15:18:54 he Exp $

options         NTP             # NTP phase/frequency locked loop

file-system     NFS             # Network File System client

options         NFSSERVER       # Network File System server

#options        GATEWAY         # packet forwarding

options         INET            # IP + ICMP + TCP + UDP

options         INET6           # IPV6

#options        IPSEC           # IP security

#options        IPSEC_ESP       # IP security (encryption part; define w/IPSEC)

#options        MROUTING        # IP multicast routing

options         NS              # XNS
#options        NSIP            # XNS tunneling over IP

options         ISO,TPIP        # OSI
#options        EON             # OSI tunneling over IP

options         CCITT,LLC,HDLC  # X.25

options         NETATALK        # AppleTalk networking protocols

options         PPP_BSDCOMP     # BSD-Compress compression support for PPP
options         PPP_DEFLATE     # Deflate compression support for PPP
options         PPP_FILTER      # Active filter support for PPP (requires bpf)

options         PFIL_HOOKS      # pfil(9) packet filter hooks
options         IPFILTER_LOG    # ipmon(8) log support

# Compatibility with 4.2BSD implementation of TCP/IP.  Not recommended.
#options        TCP_COMPAT_42

options         NFS_BOOT_DHCP,NFS_BOOT_BOOTPARAM

# Kernel root file system and dump configuration.
config          netbsd  root on ? type ?
#config         netbsd  root on sd0a type ffs
#config         netbsd  root on ? type nfs

# ISA serial interfaces
com0    at isa? port 0x3f8 irq 4        # Standard PC serial ports
com1    at isa? port 0x2f8 irq 3
com2    at isa? port 0x3e8 irq 5

# Network Interfaces

# MII/PHY support

# USB Ethernet adapters
aue*    at uhub? port ?         # ADMtek AN986 Pegasus based adapters
cue*    at uhub? port ?         # CATC USB-EL1201A based adapters
kue*    at uhub? port ?         # Kawasaki LSI KL5KUSB101B based adapters

# network pseudo-devices
pseudo-device   bpfilter        8       # Berkeley packet filter

pseudo-device   ipfilter                # IP filter (firewall) and NAT

pseudo-device   loop                    # network loopback

pseudo-device   ppp             2       # Point-to-Point Protocol

pseudo-device   sl              2       # Serial Line IP

pseudo-device   strip           2       # Starmode Radio IP (Metricom)

pseudo-device   tun             2       # network tunneling over tty

pseudo-device   gre             2       # generic L3 over IP tunnel

pseudo-device   ipip            2       # IP Encapsulation within IP (RFC 2003)

pseudo-device   gif             4       # IPv[46] over IPv[46] tunnel (RFC 1933)

#pseudo-device  faith           1       # IPv[46] tcp relay translation i/f

#pseudo-device  stf             1       # 6to4 IPv6 over IPv4 encapsulation

pseudo-device   vlan                    # IEEE 802.1q encapsulation

nameserver 194.109.123.2
nameserver 191.200.4.52
#lookup file bind

# /etc/nsswitch.conf
group:         compat
group_compat:  nis
hosts:         files dns 
netgroup:      files [notfound=return] nis
networks:      files
passwd:        compat
passwd_compat: nis

# /etc/ppp/peers/bignet
connect '/usr/sbin/chat -v -f /etc/ppp/peers/bignet.chat'
noauth
user alan
remotename bignet.it

# /etc/ppp/peers/bignet.chat
ABORT BUSY
ABORT "NO CARRIER"
ABORT "NO DIALTONE"
'' ATDT0299999999
CONNECT ''

user * password

alan * pZY9o

# /etc/ppp/peers/bignet.chat
ABORT BUSY
ABORT "NO CARRIER"
ABORT "NO DIALTONE"
'' ATDT0299999999
CONNECT ''
TIMEOUT 50
ogin: alan
ssword: pZY9o

/dev/tty01
lock
crtscts
57600
modem
defaultroute
noipdefault

# pppd call bignet

# tail -f /var/log/messages

#!/bin/sh
MODEM=tty01
POP=bignet
if [ -f /var/spool/lock/LCK..$MODEM ]; then
  echo ppp is already running...
else
  pppd call $POP
  tail -f /var/log/messages
fi

#!/bin/sh
MODEM=tty01
if [ -f /var/spool/lock/LCK..$MODEM ]; then
  echo -f killing pppd...
  kill -HUP `cat /var/spool/lock/LCK..$MODEM`
  echo done
else
  echo ppp is not active
fi

# chmod u+x ppp-up ppp-down

...
ne0 at isa0 port 0x280-0x29f irq 9
ne0: NE2000 Ethernet
ne0: Ethernet address 00:c2:dd:c1:d1:21
...

...
ne0 at isa? port 0x280 irq 9 # NE[12]000 ethernet cards
...

# ifconfig ne0
ne0: flags=8822<BROADCAST,NOTRAILERS,SIMPLEX,MULTICAST> mtu 1500 media: Ethernet 10base2

# ifconfig ne0 inet 192.168.1.1 netmask 0xffffff00

# ifconfig ne0
ne0: flags=8863<UP,BROADCAST,NOTRAILERS,RUNNING,SIMPLEX,MULTICAST> mtu 1500
          media: Ethernet 10base2
          inet 192.168.1.1 netmask 0xffffff00 broadcast 192.168.1.255

# ping 192.168.1.2
PING ape (192.168.1.2): 56 data bytes
64 bytes from 192.168.1.2: icmp_seq=0 ttl=255 time=1.286 ms
64 bytes from 192.168.1.2: icmp_seq=1 ttl=255 time=0.649 ms
64 bytes from 192.168.1.2: icmp_seq=2 ttl=255 time=0.681 ms
64 bytes from 192.168.1.2: icmp_seq=3 ttl=255 time=0.656 ms
^C
----ape PING Statistics----
4 packets transmitted, 4 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 0.649/0.818/1.286/0.312 ms

inet 192.168.1.1 netmask 0xffffff00

auto_ifconfig=YES

#     $NetBSD: hosts,v 1.6 2000/08/15 09:33:05 itojun Exp $
#
# 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
#
# 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

# slattach /dev/tty00
# ifconfig sl0 inet 192.168.1.1 192.168.1.2

# slattach /dev/tty00
# ifconfig sl0 inet 192.168.1.2 192.168.1.1

# ping 192.168.1.1

connect '/usr/sbin/chat -v CLIENT CLIENTSERVER'
local
tty00  
115200
crtscts
lock   
noauth
nodefaultroute
:192.168.1.2

11.3 Advanced Topics

# sysctl net.inet.ip.forwarding
net.inet.ip.forwarding = 1

map ppp0 192.168.1.0/24 -> 0/32 proxy port ftp ftp/tcp
map ppp0 192.168.1.0/24 -> 0/32 portmap tcp/udp 40000:60000
map ppp0 192.168.1.0/24 -> 0/32

#!/bin/sh
# /etc/ppp/ip-up
/etc/rc.d/ipnat forcestart

#!/bin/sh
# /etc/ppp/ip-down
/etc/rc.d/ipnat forcestop

# chmod u+x ip-up ip-down

# route add default 192.168.1.1

/dev/ra0a on /
/dev/ra0f on /usr
/dev/ra1a on /usr/src
/dev/ra2a on /export

buzz:/export/cli?/root on /
buzz:/export/common/usr on /usr
buzz:/usr/src on /usr/src

# /etc/exports
/usr/src -network 123.45.67.0 -mask 255.255.255.0
/export  -alldirs -maproot=root -network 123.45.67.0 -mask 255.255.255.0

buzz:/export/cli?/root / nfs rw
buzz:/export/common/usr /usr nfs rw,nodev,nosuid
buzz:/usr/src /usr/src rw,nodev,nosuid

$ showmount -e wuarchive.wustl.edu
Exports list on wuarchive.wustl.edu:
/export/home                       onc.wustl.edu 
/export/local                      onc.wustl.edu 
/export/adm/log                    onc.wustl.edu 
/usr                               onc.wustl.edu 
/                                  onc.wustl.edu 
/archive                           Everyone

$ cd /net/wuarchive.wustl.edu/archive/systems/unix/NetBSD

options INET6                 # IPv6
pseudo-device stf             # 6to4 IPv6 over IPv4 encapsulation

# ifconfig stf0 inet6 2002:3ee0:3972:1::1 prefixlen 16 alias  (local)

# route add -inet6 default 2002:cdb2:5ac2::1 (remote)

# /sbin/ping6 www.kame.net

# ifconfig ne0 inet6 alias 2002:3ee0:3972:2:1234:56ff:fe78:9abc

# sysctl -w net.inet6.ip6.forwarding=1

# rtadvd

12.1 Notes and Pre-Requisites

The examples in this chapter refer to BIND major version 8, however, it should be noted that the data- base format and named.conf are almost 100% compatible between version. The only difference I noticed was that the "$TTL" information was not required.

The reader should have a good understanding of basic hosts to IP address mapping and IP address class specifications.

12.2 What is DNS?

The Domain Name System converts machine names to IP addresses. The mapping is done from name to address and address to name. The difference between just plain hosts IP mapping and Domain mapping is that DNS uses a hierarchichal naming standard. This hierarchy works from right-to-left with the highest level being on the right. As an example, here is a simple domain break-out:

TOP-LEVEL                                .org
                                           |
MID-LEVEL                             .diverge.org
                     ______________________|________________________ 
                    |                      |                        |
BOTTOM-LEVEL strider.diverge.org   samwise.diverge.org   wormtongue.diverge.org

It seems simple enough, however, the system can also be logically divided even further if one wishes at different points. The example shown above shows three nodes on the diverge.org domain, but we could even divide diverge.org into subdomains such as strider.net1.diverge.org, samwise.net2.diverge.org and wormtongue.net2.diverge.org, in this case, 2 nodes reside on net2.diverge.org and one on net1.diverge.org.

12.3 The DNS Files

Now let's look at actually setting up a small DNS enabled network. We will continue to use the examples mentioned above, before we begin we must make a few assumptions:

• Our host-to-ip is working correctly

• We have IPNAT working correctly

• Currently all hosts use the ISP for DNS

Our Name Server will be the "strider" host, it also runs IPNAT and our two clients use strider as a gateway. It is not really relevant as to what type of interface is on strider, but for argument's sake we will say a 56k dial up connection.

So, before going any further, let's look at our hosts file on strider before we have made the alterations to use DNS.

127.0.0.1       localhost
192.168.1.1     strider
192.168.1.2     samwise sam
192.168.1.3     wormtongue worm

not exactly a huge network, it is worth noting that the same rules apply for larger networks as we discuss in the context of this section.

options {
        directory "/etc/namedb";
        allow-transfer { 192.168.1.0/24; };
        recursion yes;
        allow-query { 192.168.1.0/24; };
        listen-on port 53 { 192.168.1.1; };
};
zone "localhost" {
   type master;
   notify no;
   file "localhost";
};
zone "127.IN-ADDR.ARPA" {
   type master;
   notify no;
   file "127";
};
zone "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.int" {
   type master;
   file "loopback.v6";
};
zone "diverge.org" {
   type master;
   notify no;
   file "diverge.org";
};
zone "1.168.192.in-addr.arpa" {
   type master;
   notify no;
   file "1.168.192";
};
zone "." in {
   type hint;
   file "root.cache";
};

 1|$TTL    3600
 2|@              IN SOA  strider.diverge.org. hostmaster.diverge.org. (
 3|                        1       ; Serial
 4|                        8H      ; Refresh
 5|                        2H      ; Retry
 6|                        1W      ; Expire
 7|                        1D)     ; Minimum TTL
 8|                        IN NS   localhost.
 9|localhost.              IN      A       127.0.0.1
10|                        IN      AAAA    ::1

 1| $TTL    3600
 2| @              IN SOA  strider.diverge.org. root.diverge.org. (
 3|                        1       ; Serial
 4|                        8H      ; Refresh
 5|                        2H      ; Retry
 6|                        1W      ; Expire
 7|                        1D)     ; Minimum TTL
 8|                 IN NS   localhost.
 9| 1.0.0           IN PTR  localhost.

 1| $TTL    3600
 2| @              IN SOA  strider.diverge.org. root.diverge.org. (
 3|                         1       ; serial
 4|                         8H      ; refresh
 5|                         2H      ; retry
 6|                         1W      ; expire
 7|                         1D )    ; minimum seconds
 8|                 IN NS   strider.diverge.org.
 9|                 IN MX   10 maila.diverge.org.   ; primary mail server
10|                 IN MX   20 mailb.diverge.org.   ; secondary mail server
11| strider         IN A     192.168.1.1
12| maila           IN CNAME strider.diverge.org.
13| samwise         IN A     192.168.1.2
14| www             IN CNAME samwise.diverge.org.
15| mailb
16| worm            IN A     192.168.1.3

 1|$TTL    3600
 2|@              IN SOA  strider.diverge.org. root.diverge.org. (
 3|                     1       ; serial
 4|                     8H      ; refresh
 5|                     2H      ; retry
 6|                     1W      ; expire
 7|                     1D )    ; minimum seconds
 8|                IN NS   strider.diverge.org.
 9|1               IN PTR  strider.diverge.org.
10|2               IN PTR  samwise.diverge.org.
11|3               IN PTR  worm.diverge.org.

;       $NetBSD: root.cache,v 1.8 1997/08/24 15:50:47 perry Exp $
;
;       This file holds the information on root name servers needed to
;       initialize cache of Internet domain name servers
;       (e.g. reference this file in the "cache  .  file"
;       configuration file of BIND domain name servers).
;
;       This file is made available by InterNIC registration services
;       under anonymous FTP as
;           file                /domain/named.root
;           on server           FTP.RS.INTERNIC.NET
;       -OR- under Gopher at    RS.INTERNIC.NET
;           under menu          InterNIC Registration Services (NSI)
;              submenu          InterNIC Registration Archives
;           file                named.root
;
;       last update:    Aug 22, 1997
;       related version of root zone:   1997082200
;
;
; formerly NS.INTERNIC.NET
;
.                        3600000  IN  NS    A.ROOT-SERVERS.NET.
A.ROOT-SERVERS.NET.      3600000      A     198.41.0.4
;
; formerly NS1.ISI.EDU
;
.                        3600000      NS    B.ROOT-SERVERS.NET.
B.ROOT-SERVERS.NET.      3600000      A     128.9.0.107
;
; formerly C.PSI.NET
;
.                        3600000      NS    C.ROOT-SERVERS.NET.
C.ROOT-SERVERS.NET.      3600000      A     192.33.4.12
. . .

12.4 Using DNS

In this section we will look at how to get DNS going and setup strider to use it's own services.

NetBSD already provides a dns caching server install (shown in the next section). Along with this are the tools to manage the server at runtime. Before that can start, however, we must look at how to properly initialize the server.

Setting up named to start automatically is quite simple. In /etc/defaults/rc.conf simply go to the line named and replace NO with YES. Additional options can be specified on that line in between the quotes, for example, I like to use -g nogroup -u nobody, so a non root account runs the named process.

In addition to being able to startup named at boot time, it can also be controlled with the ndc facility. In a nutshell the ndc facility can stop, start or restart the named server process. It can also do a great many other things (see the ndc man page for more details).

The general usage is ndc.

Next we want to point strider to itself for lookups. We have two simple steps, first, decide on our resolution order. On a network this small, it is likely that each host has a copy of the hosts table, so we can get away with using hosts then dns, however, on larger networks it is much easier to use DNS. Either way, the file where this is determined is /etc/nsswitch.conf (see Example 11-2.) Here is part of a typical nsswitch.conf:

. . .
group_compat:   nis
hosts:          files dns
netgroup:       files [notfound=return] nis
. . .

the line we are concerned with is hosts, files means the system uses /etc/hosts to determine ip to name translation. The entry on the left is the first method of resolution.

The next file is /etc/resolv.conf, this file is the dns resolution file, the format is pretty self explanatory but we will go over it anyway:

domain diverge.org
search diverge.org
nameserver 192.168.1.1

In a nutshell this file is telling the resolver that this machine belongs to diverge.org, should search it before looking elsewhere and the nameserver address is 192.168.1.1 .

To test our nameserver we can use several commands, for example:

# host www.blah.net

here is the output of running host www.yahoo.com:

www.yahoo.com is a nickname for www.yahoo.akadns.net
www.yahoo.akadns.net has address 216.32.74.50
www.yahoo.akadns.net has address 216.32.74.51
www.yahoo.akadns.net has address 216.32.74.52
www.yahoo.akadns.net has address 216.32.74.53
www.yahoo.akadns.net has address 216.32.74.55

The procedure for setting up the client hosts are the same, setup /etc/nsswitch.conf and /etc/resolv.conf.

12.5 Setting up a caching only name server

A caching only name server has no local zones; all the queries go to the root servers and the replies are accumulated in the local cache. The next time the query is performed the answer will be faster because the data is already in the server's cache. Since this type of server doesn't handle local zones, to resolve the names of the local hosts it will still be necessary to use the already known /etc/hosts file.

Since NetBSD supplies defaults for all the files needed by a caching only server, the configuration of this type of DNS is very easy, and can be performed with a few commands, without writing a single line in the configuration files.

The program which supplies the DNS server is the named daemon, which uses the named.conf configuration file for its setup. The default file supplied by NetBSD is located in the /etc/namedb directory, but the daemon looks for it in the /etc/ directory, so we start by creating a link:

# ln -s /etc/namedb/named.conf /etc/named.conf

The name server is ready for use! We can now tell to the system to use it adding the following line to the /etc/resolv.conf file:

nameserver 127.0.0.1

Now we can start named.

# named

# nslookup
Default server: localhost
Address: 127.0.0.1
>

> www.mclink.it
Server:  localhost
Address:  127.0.0.1
Name:    www.mclink.it
Address:  195.110.128.8

> www.mclink.it
Server:  localhost
Address:  127.0.0.1
Non-authoritative answer:
Name:    www.mclink.it
Address:  195.110.128.8

# host www.mclink.it
www.mclink.it has address 195.110.128.8

13.1 sendmail

When an MTA, sendmail in the default installation, must deliver a message, if it's a local message it delivers it directly. If the message is for a different domain, the MTA must find out the address of the mail server for that domain. Sendmail uses the DNS service (described in Chapter 12) to find the required address (stored as an MX record by the DNS server) and delivers the message to the destination mail server.

The most used MTA in the BSD world is probably sendmail. Sendmail is controlled by a set of configuration files and databases, of which /etc/mail/sendmail.cf is the most important. In general, if you are not an expert it is better not to modify the /etc/mail/sendmail.cf file directly; instead, use a set of predefined macros and the m4 preprocessor, which greatly (well, almost) simplify the configuration.

Even using the macros, the configuration of sendmail is not for the faint of heart, and the next sections only describe an example which can be modified to suit different needs and different configurations. If you connect to the Internet with a modem, the example configuration file will probably fit all your needs: just replace the fictitious data with yours.

The first problem to be solved is that the local network we are dealing with is an internal network, i.e. not directly accessible from the Internet. This means that the names used internally have no meaning on the Internet; in short, "ape.insetti.net" cannot be reached by an external host: no one will be able to reply to a mail sent with this return address (some mail systems will even reject the message because it comes from an unknown host.) The true address, the one visible from everybody, is assigned by the provider and, therefore, it is necessary to convert the local address "carlo@ape.insetti.net" to the real address "alan@bignet.it". Sendmail, if correctly configured, will take care of this when it transfers the messages.

You'll probably also want to configure sendmail in order to send the e-mails to the provider's mail server, using it as a relay. In the configuration described in this chapter, sendmail does not directly contact the recipient's mail server (as previously described) but relays all its mail to the provider's mail server.

Since the connection with the provider is not always active, it is not necessary to start sendmail as a daemon in /etc/rc.conf: you can disable it with the line "sendmail=NO". As a consequence it will be necessary to launch sendmail manually when you want to transfer mail to the provider. Local mail is delivered correctly even if sendmail is not active as a daemon.

Let's start configuring sendmail.

carlo:         alan@bignet.it
root:          alan@bignet.it
news:          alan@bignet.it

# /usr/sbin/sendmail -bi -oA/etc/mail/genericstable

# cd /usr/share/sendmail/m4

divert(-1)dnl
include(`../m4/cf.m4')dnl
VERSIONID(`mycf.mc created by carlo@ape.insetti.net May 18 2001')dnl
OSTYPE(bsd4.4)dnl
dnl # Settings for masquerading.  Addresses of the following types
dnl # are rewritten
dnl #     carlo@ape.insetti.net
dnl #     carlo@ape
GENERICS_DOMAIN(ape.insetti.net ape)dnl
FEATURE(genericstable)dnl
FEATURE(masquerade_envelope)dnl
define(`SMART_HOST',`mail.bignet.it')dnl
FEATURE(redirect)dnl
FEATURE(nocanonify)dnl
dnl # The following feature is useful if sendmail is called by
dnl # fetchmail (which is usually the case.)  If sendmail cannot
dnl # resolve the name of the sender, the mail will not be delivered.
dnl # For example:
dnl #   MAIL FROM:<www-owner@NetBSD.org> SIZE=2718
dnl #   501 <www-owner@NetBSD.org>... Sender domain must exist
FEATURE(`accept_unresolvable_domains')dnl
dnl # accept_unqualified_senders is useful with some MUA, which send
dnl # mail as, for example:
dnl #   MAIL FROM:<carlo>
FEATURE(`accept_unqualified_senders')dnl
dnl # Mail for `smtp' mailer is marked `expensive' (`e' flag):
dnl # instead of connecting with the relay, sendmail puts it in
dnl # a queue for delayed processing.
dnl # Sendmail starts complaining about undelivered messages after
dnl # 16 hours.
define(`SMTP_MAILER_FLAGS',`e')dnl
define(`confCON_EXPENSIVE',`True')dnl
define(`confTO_QUEUEWARN', `16h')dnl
dnl # For european users
define(`confDEF_CHAR_SET',`ISO-8859-1')dnl
dnl # Enable the following three lines to use procmail as a local
dnl # delivery agent.  The third line is optional, only the first
dnl # two are required.
dnl # define(`PROCMAIL_MAILER_PATH', /usr/pkg/bin/procmail)dnl
dnl # FEATURE(local_procmail)dnl
dnl # MAILER(procmail)dnl
dnl # The following two mailers must always be defined
MAILER(local)dnl
MAILER(smtp)dnl

GENERICS_DOMAIN(ape.insetti.net ape)dnl
define(`SMART_HOST',`mail.bignet.it')dnl

# cp /etc/mail/sendmail.cf /etc/mail/sendmail.cf.bak
# m4 mycf.mc > /etc/mail/sendmail.cf

# newaliases

$ sendmail -v carlo
Subject: test
Prova
.
carlo... Connecting to local...
carlo... Sent

From: alan@bignet.it

$ sendmail -bt
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
Enter <ruleset> <address>
>

/map generics carlo
map_lookup: generics (carlo) returns alan@bignet.it

/tryflags ES
/try smtp carlo@ape.insetti.net

Trying envelope sender address carlo@ape.insetti.net for mailer smtp
rewrite: ruleset   3   input: carlo @ ape . insetti . net
rewrite: ruleset  96   input: carlo < @ ape . insetti . net >
rewrite: ruleset  96 returns: carlo < @ ape . insetti . net . >
rewrite: ruleset   3 returns: carlo < @ ape . insetti . net . >
rewrite: ruleset   1   input: carlo < @ ape . insetti . net . >
rewrite: ruleset   1 returns: carlo < @ ape . insetti . net . >
rewrite: ruleset  11   input: carlo < @ ape . insetti . net . >
rewrite: ruleset  51   input: carlo < @ ape . insetti . net . >
rewrite: ruleset  51 returns: carlo < @ ape . insetti . net . >
rewrite: ruleset  61   input: carlo < @ ape . insetti . net . >
rewrite: ruleset  61 returns: carlo < @ ape . insetti . net . >
rewrite: ruleset  94   input: carlo < @ ape . insetti . net . >
rewrite: ruleset  93   input: carlo < @ ape . insetti . net . >
rewrite: ruleset   3   input: alan @ bignet . it
rewrite: ruleset  96   input: alan < @ bignet . it >
rewrite: ruleset  96 returns: alan < @ bignet . it >
rewrite: ruleset   3 returns: alan < @ bignet . it >
rewrite: ruleset  93 returns: alan < @ bignet . it >
rewrite: ruleset  94 returns: alan < @ bignet . it >
rewrite: ruleset  11 returns: alan < @ bignet . it >
rewrite: ruleset   4   input: alan < @ bignet . it >
rewrite: ruleset   4 returns: alan @ bignet . it
Rcode = 0, addr = alan@bignet.it
>

/try smtp carlo

/tryflags HS
/try smtp carlo@ape.insetti.net

$ ls -l /usr/sbin/sendmail
lrwxr-xr-x  1 root  wheel  21 Nov  1 01:14 /usr/sbin/sendmail@ -> /usr/sbin/mailwrapper

13.2 fetchmail

Mail is received by the provider and it is not automatically transfered to the local hosts; therefore it is necessary to download it. Fetchmail is a very popular program that downloads mail from a remote mail server and forwards it to the local system for delivery (usually using sendmail.) It is powerful yet easy to use and configure: after installation, the file ~/.fetchmailrc must be created and the program is ready to run (~/.fetchmailrc contains a password so appropriate permissions on the file are required.)

This is an example .fetchmailrc:

poll mail.bignet.it
protocol POP3 
username alan there with password pZY9o is carlo here
flush 
mda "/usr/sbin/sendmail -oem %T"

Now the following command can be used to download and deliver mail to the local system:

$ fetchmail

The messages can now be read with mutt.

13.3 Reading and writing mail with mutt

Mutt is one of the most popular mail programs: it is "lightweight", easy to use and has lots of features. The man page mutt is very bare bones; the real documentation is in /usr/pkg/share/doc/mutt/, in particular manual.txt.

Mutt's configuration is defined by the ~/.muttrc file. The easiest way to create it is to copy mutt's example muttrc file (usually /usr/pkg/etc/Muttrc) to the home directory and modify it. The following example shows how to achieve some results:

• Save a copy of sent mail.

• Define a directory and two files for incoming and outgoing mail saved by mutt (in this example the directory is ~/Mail and the files are incoming and outgoing).

• Define some colors.

• Define an alias.

set copy=yes
set edit_headers
set folder="~/Mail"
unset force_name
set mbox="~/Mail/incoming"
set record="~/Mail/outgoing"
unset save_name
bind pager <up> previous-page
bind pager <down> next-page
color normal white black
color hdrdefault blue black
color indicator white blue
color markers red black
color quoted cyan black
color status white blue
color error red white
color underline yellow black
mono quoted standout
mono hdrdefault underline
mono indicator underline
mono status bold
alias pippo Pippo Verdi <pippo.verdi@pluto.net>

To start mutt:

$ mutt

13.4 Strategy for receiving mail

This section describes a simple method for receiving and reading mail. The connection to the provider is activated only for the time required to dowload the messages; mail is then read offline.

1. Activate the connection to the provider.

2. Run fetchmail.

3. Deactivate the connection.

4. Read mail with mutt.

13.5 Strategy for sending mail

When mail has been written and "sent" with mutt, the messages must be transferred to the provider with sendmail. Mail is sent from mutt with the y command, but this does not really send it; the messages are enqueued in the spool area; if sendmail is not active as a daemon it is necessary to start it manually or the messages will remain on the hard disk. The necessary steps are:

1. Write mail with mutt, send it and exit mutt.

2. Activate the connection with the provider.

3. Write the command /usr/sbin/sendmail -q -v to transfer the queued messages to the provider.

4. Deactivate the connection.

13.6 Advanced mail tools

When you start using mail, you won't probably have very sophisticated requirements and the already described standard configuration will satisfy all your needs. But for many users the number of daily messages will increase with time and a more rational organization of the mail storage will become necessary, for example subdividing mail in different mail boxes organized by topic. If, for example, you subscribe to a mailing list, you will likely receive many messages every day and you will want to keep them separate from the rest of your mail. You will soon find that you are spending too much time every day repeating the same manual operations to organize your mail boxes.

Why repeat manually the same operations when you can have a program perform them automatically for you? There are numerous tools that you can add to your mail system to increase its flexibility and automatically process your messages. Amongst the most known and used there are:

• procmail, an advanced mail delivery agent and general purpose mail filter for local mail, which automatically processes incoming mail using user defined rulesets. It integrates smoothly with sendmail.

• metamail, a tool to process attachments.

• formail, a mail formatter.

In the remaining part of this section a sample configuration for procmail will be presented for a very common case: delivering automatically to a user defined mailbox all the messages coming from a mailing list. The configuration of sendmail will be modified in order to call procmail directly (procmail will be the local mailer used by sendmail.) and a custom configuration file for procmail will be created.

First, procmail must be installed using the package system (mail/procmail.)

Next, the configuration of sendmail must be changed, in order to use procmail as local mailer. Uncomment the following three lines from the mycf.mc sendmail M4 prototype file and recreate the sendmail configuration file.

define(`PROCMAIL_MAILER_PATH', /usr/pkg/bin/procmail)dnl
FEATURE(local_procmail)dnl
MAILER(procmail)dnl

The first line defines the path of the procmail program (you can see where procmail is installed with the command which procmail.) The second line tells sendmail to use procmail for local mail delivery and the third adds procmail to the list of sendmail's mailers. The third line adds procmail to the list of sendmail's mailers (this line is optional.)

The last step is the creation of the procmail configuration file, containing the recipes for mail delivery.

Let's say that, for example, you subscribed to a mailing list on roses whose address is <roses@flowers.org> and that every message from the list contains the following line in the header:

Delivered-To: roses@flowers.org

The procmail configuration file (.procmailrc) looks like this:

PATH=/bin:/usr/bin:/usr/pkg/bin
MAILDIR=$HOME/mail
LOGFILE=$MAILDIR/from
:0
* ^Delivered-To: roses@flowers.org
roses_list

The previous file contains only one rule, beginning with the line containing ":0". The following line identifies all messages containing the string "Delivered-To: roses@flowers.org" and the last line says that the selected messages must go to the roses_list mailbox (which you should have created in $MAILDIR.) The remaining messages will be delivered to the default mailbox. Note that $MAILDIR is the same directory that you have configured with mutt:

set folder="~/Mail"

Of course the mailing list is only an example; procmail is a very versatile tool which can be used to filter mail based on many criteria. As usual, refer to the man pages for more details: procmail(1), procmailrc(5), and procmailex(5) (this last one contains many examples of configuration files.)

You can check that procmail is used as local mailer by sendmail if you run the latter in test mode:

$ /usr/sbin/sendmail -bt
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
Enter <ruleset> <address>
>

The following command displays the list of mailers known to sendmail:

> =M

You should find a line like the following one:

mailer 3 (local): P=/usr/pkg/bin/procmail S=EnvFromL/HdrFromL ...

13.7 News with tin

The word news indicates the set of articles of the USENET newsgroups, a service available on the Internet. Each newsgroup contains articles related to a specific topic. Reading a newsgroup is different than reading a mailing list: when you subscribe to a mailing list you receive the articles by mail and you read them with a standard mail program like mutt, which you use also to send replies. News, instead, are read directly from a news server with a dedicated program called newsreader like, for example, tin. With tin you can subscribe to the newsgroups that you're interested in and follow the threads.

After the installation of tin (from the package collection as usual) the only thing left to do is to write the name of the NNTP server in the file /usr/pkg/etc/nntp/server. For example:

news.bignet.it

Once this has been done, the program can be started with the command rtin. On the screen something similar to the following example will be displayed:

$ rtin
Connecting to news.bignet.it...
news.bignet.it InterNetNews NNRP server INN 1.7.2 08-Dec-1997 ready (posting ok).  
Reading groups from active file...
Checking for new groups... 
Reading attributes file...
Reading newsgroups file...
Creating newsrc file...
Autosubscribing groups...
Reading newsrc file...

Be patient when you connect for the first time, because tin downloads an immense list of newsgroups to which you can subscribe and this takes several minutes. When the donwload is finished, the program's main screen is displayed; usually no groups are displayed; to see the list of groups press y. To subscribe to a group, move on the group's name and press y.

Once that you have subscribed to some newsgroups you can start tin more quickly with the command rtin -Q. The search for new groups is disabled (-q), only active groups are searched (-n) and newsgroup description are not loaded (-d): it will not be possible to use the y (yank) command in tin. When tin is started with these option it can't tell if a newsgroup is moderated or not.

14.1 wscons

Wscons is NetBSD's new console driver. It offers virtual terminal, support for international keyboards, mouse handling, etc. The capabilities of wscons can vary depending on the port (wscons is not available on all ports): the i386 version is very feature rich.

If you are compiling a customized kernel, to enable wscons you must activate the relevant options and comment out the options of pcvt and pccons (they can't be enabled at the same time.) For example

#pc0    at isa? port 0x60 irq 1   # pccons generic PC console driver
#vt0    at isa? port 0x60 irq 1   # PCVT console driver

In the kernel configuration file you can also enable a foreign keyboard. For example, to use the italian keyboard by default:

options     PCKBD_LAYOUT="KB_IT"

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:

# screens to create
#       idx     screen  emul
#screen 0       -       vt100
screen 1        -       vt100
screen 2        -       vt100
screen 3        -       vt100
screen  4       -       -
#screen 4       80x25bf vt100
#screen 5       80x50   vt100

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

The virtual console must also be active in /etc/ttys. For example:

console "/usr/libexec/getty Pc"         pc3     off secure
ttyE0   "/usr/libexec/getty Pc"         vt220   on secure
ttyE1   "/usr/libexec/getty Pc"         vt220   on secure
ttyE2   "/usr/libexec/getty Pc"         vt220   on secure
ttyE3   "/usr/libexec/getty Pc"         vt220   off secure
...

The line

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

of /etc/ttys is used by the X server to find a free terminal. To use a screen different from number 4, a parameter of the form vtn must be passed to the X server (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 /usr/X11R6/lib/X11/xdm/Xserver. For example:

:0 local /usr/X11R6/bin/X +kb dpms -bpp 16 dpms vt8

For xdm3d the path is different: /usr/X11R6/share/xdm3d/Xservers.

font ibm  -  8  ibm  /usr/share/pcvt/fonts/vt220l.808

#screen 0       80x50   vt100
screen  1       80x50   vt100
screen  2       80x50   vt100
screen  3       80x50   vt100
screen  4       80x50   vt100
screen  5       80x50   vt100
screen  6       80x50   vt100
screen  7       80x50   vt100

ttyE0   "/usr/libexec/getty Pc"         vt220   on secure
ttyE1   "/usr/libexec/getty Pc"         vt220   on secure
ttyE2   "/usr/libexec/getty Pc"         vt220   on secure
ttyE3   "/usr/libexec/getty Pc"         vt220   on secure
ttyE4   "/usr/libexec/getty Pc"         vt220   on secure
ttyE5   "/usr/libexec/getty Pc"         vt220   on secure
ttyE6   "/usr/libexec/getty Pc"         vt220   on secure
ttyE7   "/usr/libexec/getty Pc"         vt220   on secure

14.2 pccons

This is the console driver found on the i386 install floppy. It doesn't offer virtual consoles and utility programs for configuration but takes up very little space.

14.3 pcvt

Pcvt is a VT220 terminal emulator and has more advanced functions than the simple pccons. It supports foreign keyboards and virtual consoles (with Ctrl-Alt-F1..F8 or with the F9..F12 function keys.) To activate pcvt the following lines must be uncommented in the kernel configuration file.

# Enable only one of the following lines
#pc0    at isa? port 0x60 irq 1
vt0     at isa? port 0x60 irq 1
# Options for PCVT console driver
#options FAT_CURSOR 
options PCVT_NETBSD=132
options PCVT_NSCREENS=3

To use a foreign keyboard you must activate it at boot; it is also necessary to choose the correct terminal. For example:

/usr/local/bin/kcon -m i2
TERM=pcvt25;    export TERM

/etc/ttys must be modified accordingly. For example:

#console "/usr/libexec/getty Pc"   pcvt25  on secure
ttyv0    "/usr/libexec/getty Pc"   pcvt25  on secure

The settings for the foreign keyboard (the italian keyboard in this example) must be loaded at boot, for example in /etc/rc.local:

KCONP=/usr/local/bin 
SCONP=/usr/local/bin 
LDFNP=/usr/local/bin
ISPCP=/usr/sbin
CURSP=/usr/local/bin
set_keybd=YES
#------------------------------------------------------
# if desired, setup keyboard for italian keyboard layout
#------------------------------------------------------
if [ X${set_keybd} = X"YES" -a -x $KCONP/kcon ]
then
  echo
  echo 'switching to italian keyboard layout'
  $KCONP/kcon -m i2
fi
echo '.'

/etc/ttys must be also modified:

#console  "/usr/libexec/getty Pc" pcvt25  on secure
ttyv0   "/usr/libexec/getty Pc" pcvt25  on secure
ttyv1   "/usr/libexec/getty Pc" pcvt25  on secure
ttyv2   "/usr/libexec/getty Pc" pcvt25  on secure

The pcvt utility programs must be compiled and installed.

# cd /sys/arch/i386/isa/pcvt/Util
# make
# make install

#!/bin/sh
# Set the screen to # lines
case $1 in
  25)
    /usr/local/bin/scon -s 25
    /usr/local/bin/cursor -s13 -e14
    ;;
  28)  
    /usr/local/bin/loadfont -c1 -f
    /usr/share/misc/pcvtfonts/vt220l.814
    /usr/local/bin/loadfont -c2 -f
    /usr/share/misc/pcvtfonts/vt220h.814
    /usr/local/bin/scon -s 28
    /usr/local/bin/cursor -s12 -e14
    ;; 
  40) 
    /usr/local/bin/loadfont -c3 -f
    /usr/share/misc/pcvtfonts/vt220l.810
    /usr/local/bin/loadfont -c4 -f
    /usr/share/misc/pcvtfonts/vt220h.810
    /usr/local/bin/scon -s 40
    /usr/local/bin/cursor -s8 -e10
    ;;
  50) 
    /usr/local/bin/loadfont -c5 -i
    /usr/share/misc/pcvtfonts/vt220l.808
    /usr/local/bin/loadfont -c6 -i
    /usr/share/misc/pcvtfonts/vt220h.808
    /usr/local/bin/scon -s 50
    /usr/local/bin/cursor -s6 -e8
    ;;
  *)
    echo "Invalid # of lines (25/28/40/50)"
    ;;
esac

15.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 thevi 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.

$ vi filename

# vi foo.txt

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

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

Amongst the most interesting extensions are:

• Extended regular expressions (egrep style), enabled with option extended.

• Tag stacks.

• Infinite undo (to undo, press u; to continue undoing, press .).

• Incremental search, enabled with the option searchincr.

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

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

15.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:

16.1 What is X?

The X Window System is a graphical environment available for NetBSD and many Unix (and non Unix) systems. In fact it is much more than that: thanks to the usage of the X protocol, the X Window System is "network transparent" and can run distributed applications (client-server). This means, roughly, that you can run an application on one host (client) and transparently display the graphical output on another host (server); transparently means that you don't have to modify the application to achieve this result. The X Window System is produced and mantained by the X Consortium and the current release is X11R6. The flavour of X used by NetBSD is XFree86, a freely redistributable open source implementation of the X Window System.

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

• Video hardware supported by XFree86.

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

• A window manager running on the X server. The window manager is essentially a special client that is allowed to control placement of windows. It also "decorates" windows with standard "widgets" (usually these provide window-motion, resizing, iconifying, and perhaps a few other actions). A window manager also may provide backdrops, etc. Window managers can also let you kill windows/programs by clicking on their windows, and so forth.

• A desktop manager (optional.) KDE and GNOME, for example, are desktops: they are suites of more-or-less integrated software designed to give you a well-defined range of software and a more or less common interface to each of the programs. These include a help browser of some kind, a "desktop-metaphor" access to your filesystem, custom terminals to replace xterm, software development environments, audio, picture/animation viewres, etc.

• Any other applications (3rd party X clients) that you have. These talk to the X server and to the window manager. Unless the window manager is part of the destkop (if any), the desktop probably doesn't get involved in much of anything that these applications do. (However, e.g., GNOME may be able to detect that you've installed the GIMP, for example, and so offer a menu to launch the GIMP.)

To summarize: in order to use a graphical environment you need

• the XFree86 system

• a window manager (XFree86 already comes with a very basic window manager called twm.)

• If you prefer a more sophisticated environment you'll probably want to install a desktop too, although this is not necessary. Desktops have some nice features that are helpful to users who come from environments such as MacIntosh or MS-WINDOWS (the KDE desktop, for example, has a very similar flavour to MS-WINDOWS.)

Normally, you can run at most one window manager at any given time on a given X server. (But you can run multiple X servers on a single computer.) If you are not running a window manager of your choosing, and start KDE/GNOME, then that desktop environment will run a window manager for you.

16.2 Configuration

If you haven't chosen a minimal configuration during installation, X is already installed and ready to run on your computer; you only have to create the menacing /etc/XF86Config file. To get an idea of what this file looks like, examine the /usr/X11R6/lib/X11/XF86Config.eg file. The structure of the configuration file is described formally in XF86Config(5), which can be examined with the following command:

# man XF86Config

Before configuring the system it is advisable to carefully read the documentation found in /usr/X11R6/lib/X11/doc: there are various README's for the video cards, for the mouse and even a NetBSD specific one (README.NetBSD.) I suggest to start by reading QuickStart.doc. You might have the feeling that other systems let you start more quickly and with less effort, but the time spent reading this documentation is not wasted: the knowledge of X and of your configuration that you gain will turn out very useful on many future occasions and you'll be able to get the most from your hardware (and software too.)

You can create the /etc/XF86Config file manually with an editor or you can generate it automatically with an interactive configuration program. The best known programs are xf86config and XF86Setup. The former is a text mode program and is installed by default with X; the latter is a graphics program which can be installed from the package collection.

You may find that a mixed approach is better: first create the XF86Config with one of the two programs and then check it and tune it manually with an editor.

The interface of the two programs is different but they both require the same set of information:

• the mouse type and the mouse device to be used

• the keyboard type and its layout

• the type of video card

• the type of monitor

Before configuring the system you should collect the required information.

16.3 The mouse

The first thing to check is the type of mouse you are using (for example, serial or PS/2, ...) and the mouse device (for example, wsmouse requires a different protocol.) If you are using a serial mouse, choose the required protocol and specify the serial port to which it is connected. For example, for a serial mouse on the first serial port:

Section "Pointer"
  Protocol    "Microsoft"
  Device      "/dev/tty00"
EndSection

For a mouse using the wsmouse device you might have:

Section "Pointer"
  Protocol    "wsmouse"
  Device      "/dev/wsmouse0"
EndSection

In the "Device" field you can also specify /dev/mouse provided that you have created the correct link in the filesystem. For example:

# ln -sf /dev/wsmouse0 /dev/mouse

16.4 The keyboard

Even if you have already configured your keyboard for wscons, you need to configure it for X too, in order to get a non US layout.

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

This is one area in which that configuration programs are weak and you may want to choose the standard layout and modify the generated configuration file manually.

# XkbDisable
# XkbKeymap   "xfree86(us)"
XkbModel        "pc102"
XkbLayout       "de"
XkbVariant      "nodeadkeys"

If you want to use the "Windows" keys on your keyboard, use pc105 instead of pc102 for XkbModel.

16.5 The monitor

It is very important to correctly specify the values of the horizontal and vertical frequency of the monitor: a correct definition shields the monitor from damages deriving from an incompatible setup of the video card. This information can be found in the monitor's manual. In the X documentation directory there is a file containing the settings of many monitors; it can be used as a starting point to customize your own settings.

16.6 Video card and X server

The video card can be chosen from the database of the automatic configuration programs; the program will take care of all the needed setups.

When you have selected the correct video card you must choose the X server for the card. Usually, the configuration programs can automatically determine the correct server, but some video cards can be driven by more than one server (for example, S3 Virge is supported by the SVGA and S3V servers); in this case, study the documentation of the servers to decide which one you need: different servers usualy have different capabilities and a different degree of support for the video cards.

16.7 Starting X

When you exit the configuration program, it creates the file /etc/XF86Config, which can be further examined and modified by hand.

Before starting X you should:

• check that the symbolic link /usr/X11R6/bin/X points to the correct X server:

  # ls -l /usr/X11R6/bin/X
  

• Verify that the configuration is correct. Launch:

  # X -probeonly
  

  and examine carefully the output.

Now you can start X with the following command:

# startx

If X doesn't fire up there is probably some error in the configuration file.

If X starts but doesn't work as expected (for example, you can't move the mouse pointer) you can exit quickly with the Ctrl-Alt-Backspace key combination (not available on all ports.) If everything worked correctly you are left in the X environment with the default window manager (twm): although it is a simple window manager many users feel that it is enough for their needs. If you want a highly configurable window manager with many bells and whistles, you have many choices in the package collection.

To start customizing X, try giving the following command in an xterm to change the background color:

# xsetroot -solid DarkSeaGreen

16.8 Customizing X

The look of the X environment can be customized in several ways. The easiest method is to copy the default .xinitrc file in your home directory and modify it. For example:

# cp /usr/X11R6/lib/X11/xinit/xinitrc ~/.xinitrc
# vi .xinitrc

The following example shows how to start the window manager (twm), open an instance of the xclock program in the lower right part of the screen and two xterm windows. The "Bisque4" color is used for the background.

the first part of the file is the same
...
# start some nice programs
twm &
xclock -geometry 50x50-1-1 &
xterm -geometry 80x34-1+1 -bg OldLace &
xsetroot -solid Bisque4 &
exec xterm -geometry 80x44+0+0 -bg AntiqueWhite -name login

With this type of setup, to exit X you must close the last xterm (the one with the "login" title.)

Even with this simple configuration X has a considerably nicer look. To give an even better look to the environment you can install some utility program from the package collection. For example:

16.9 Other window managers

If you don't like twm, which is a very simple window manager lacking many features and not very configurable, you can choose another window manager from the package collection. Some of the most popular are: fvwm2, olwm/olvwm (Open Look Window Manager), WindowMaker, Enlightenment, AfterStep.

In the rest of this section the installation of WindowMaker is described as an example. WindowMaker is a very nice looking and highly configurable window manager. To add the program the windowmaker-0.60.tgz precompiled package will be used, which depends on some other packages which must be installed. As usual, both pkg_add and make install will fetch the needed packages automatically, so there is no need to go through the dependencies manually.

# cd /usr/pkgsrc/x11/windowmaker
# make depends-list
xpm-3.4k
jpeg-6b
pkglibtool-1.2p2
giflib-3.0
libproplist-0.9.1
tiff-3.5.2

After adding the required packages, WindowMaker and some preconfigured themes can be added:

# pkg_add windowmaker-0.61.0.tgz wmthemes-0.6x.tgz

WindowMaker is now installed; to start it you must modify your .xinitrc and/or .xsession: substitute the line which calls twm with a line which calls wmaker. For example:

# start some nice programs
# start WindowMaker
wmaker &
xclock -geometry 50x50-1-1 &
xdaemon2 -geometry +0-70 &
...

In this example the xdaemon program is also started automatically.

Before starting WindowMaker the configuration program must be run:

$ wmaker.inst
$ startx

16.10 Graphical login with xdm

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

The configuration files for xdm are in the /usr/X11R6/lib/X11/xdm directory. In the Xservers file X is started by default on the vt05 virtual terminal; if you want to use another terminal instead, this is the right place to modify the setting. In order to avoid keyboard contention between getty and xdm it is advisable 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

in /etc/ttys you should have

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

(please note that vt04 corresponds to ttyE3 because vt start at 1 and ttyE start at 0.)

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

xsetroot -solid SeaGreen

Instead of setting a color, you can put an image on the background using the xpmroot program: For example:

xpmroot /path_to_xpm/netbsd.xpm

If you experiment a little with the configuration file you can achieve many nice looking effects and build a pleasing login screen.

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

option COMPAT_LINUX
option EXEC_ELF32

# pkg_info -a | grep suse
suse_base-6.1p1     Linux compatibility package
suse_x11-6.1p1      Linux compatibility package for X11 binaries
suse_compat-6.1p1   Linux compatibility package with old shared libraries
suse_libc5-6.1p1    Linux compatibility package for libc5 binaries

# make
# make install

17.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/
boot/
cdrom/
dev/
etc/
floppy/
home/
lib/
mnt/
opt/
proc/
root/
sbin/
usr/

How much space is required for the Linux emulation software? On my system I get the following figure:

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

Acrobat Reader, the program, has been installed in the usual directory for package binaries: /usr/pkg/bin/.

18.1 Basic hardware elements

In order to make audio work on your system you must know what audio card is installed. Sadly it 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 times.

Therefore, write the following command:

# dmesg | more

and look for the audio card and chipset. If you're lucky you don'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.

18.2 BIOS settings

This section is useful only to the owners of i386 PCs; on other architectures (eg. 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.

18.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.)

18.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 setup manually the IRQ and DMA for non-PnP ISA cards.

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 synthetizer produced by Yamaha; there are many OPL variants (eg. 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 works 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.

18.5 Advanced commands

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

• audioctl

• mixerctl

• audioplay

• audiorecord

# audioctl -a | more

# audioctl -w play=44100,2,16,slinear_le

# audioctl encodings

19.1 Fetching system and userland source

To install CVS (if you dont already have it), just do:

% pkg_add ftp://ftp.netbsd.org/pub/NetBSD/packages/OS Ver/arch/All/cvs-1.11nb2.tgz

Where OS Ver, and arch can be obtained by running

% sysctl kern.osrelease hw.machine_arch

To get the sources from scratch without having anything in /usr/src

% setenv CVSROOT :pserver:anoncvs@anoncvs.NetBSD.org:/cvsroot
% cd /usr
% cvs login
password: anoncvs
% cvs checkout -rnetbsd-<BRANCH> -PA src

Where <BRANCH> is the release branch to be checked out, for example, 1.6 would be 1-6, 2.2 would be 2-2. If 2.0 were the branch then it would look like:

% cvs checkout -rnetbsd-2-0 -PA src

Where <BRANCH> is the release branch to be checked out, for example, 1.6 would be 1-6, 2.2 would be 2-2. Note that the branch name does not include the patch level, thus for 1.6.2 it would still be 1-6. If 2.0 were the branch then it would look like:

% cvs checkout -rnetbsd-2-0 -PA src

Or do it by ssh, so that the data is encrypted:

% setenv CVS_RSH ssh
% setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot
% cd /usr
% cvs checkout -rnetbsd-<BRANCH> -PA src

To obtain the current source just omit "-rnetbsd-BRANCH" in the last line.

To just update the release source tree if you already got one:

% setenv CVSROOT :pserver:anoncvs@anoncvs.NetBSD.org:/cvsroot
% cd /usr
% cvs login 
password: anoncvs
% cvs -d $CVSROOT update -rnetbsd-BRANCH -PAd src

Or by ssh:

% setenv CVS_RSH ssh
% setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot
% cd /usr
% cvs -d $CVSROOT update -rnetbsd-BRANCH -PAd src

To update the current source tree, omit the BRANCH.

When you wish to do an update from an unclean tree, i.e. when you rebuild some part of the source or even the whole source tree or the kernel source, and didn't do a make cleandir you have to make object files in the source tree.

The object directories are necessary to do a "cvs update" on an unclean tree. An unclean tree is a source tree in which you have built parts of the tree, i.e. compiled parts or the whole source tree, without having done a "make clean" in those parts or a "make" cleandir on the whole source tree. Otherwise, cvs will want to create directories that have the same name as some of the binairies, and will fail. (Where you used to have a directory called "groff", you now build the binary "groff", but "cvs" must create all the empty directories before pruning them.)

So in /usr/src:

% makedir /usr/obj
% make obj

% makedir /usr/obj
% make obj

Now you're ready to do the cvs update. Or do a make cleandir in /usr/src before using cvs. It's easier and less work instead of making the objectdirs when updating from an unclean tree. CVS is going a lot faster then sup. I don't know exactly how long it's going to take to fetch all the sources. I have only experience with T1 and higher speed lines in which case it just takes an hour or a little more to fetch the complete source, depending of course how well the connection is at the moment. I have no experience how long it takes with a modem. However, in a case you are using a modem, you will wish to compress ond decompress data once it is transferred. In that case do

% cvs -z5 checkout .........

or

% cvs -z5 -d $CVSROOT update ......

The 5 is the level of compression, you can use any number between 1 and 9 where 1 is the fastest compression method and 9 the best but slowest compression method. Keep in mind that this will put extra load on the cvs server.

19.2 Fetching pkgsrc

Pkgsrc (package source), is a set of software utilities and libraries which have been ported to NetBSD. Its very easy this way to install and deinstall software on your NetBSD system: it fetches the sources files needed, patches the source if needed, configures it and builds the binairies and installs the binaries and man pages. It keeps a database of all packages installed and exactly which files belongs to a package and where the are stored.

To fetch all the pkgsrc from scratch:

% setenv CVSROOT :pserver:anoncvs@anoncvs.NetBSD.org:/cvsroot
% cd /usr
% cvs login 
(the password is: "anoncvs")
% cvs checkout -PA pkgsrc

Or by ssh:

% setenv CVS_RSH ssh
% setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot
% cd /usr
% cvs checkout -PA pkgsrc

This will create the directory pkgsrc in your /usr and all the package source will be stored under /usr/pkgsrc

To update the pkgsrc just do:

% setenv CVSROOT :pserver:anoncvs@anoncvs.NetBSD.org:/cvsroot
% cd /usr
% cvs login
(the password is: "anoncvs")
% cvs -d $CVSROOT update -PAd pkgsrc

Or by ssh:

% setenv CVS_RSH ssh
% setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot
% cd /usr
% cvs -d $CVSROOT update -PAd pkgsrc

However, make sure the pkgsrc dir is clean when you start udating. So do a make clean in /usr/pkgsrc if you aint sure.

20.1 Install physical media

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

From my DMESG:

Disk #1:
  probe(esp0:0:0): max sync rate 10.00MB/s
  sd0 at scsibus0 target 0 lun 0: <SEAGATE, ST32430N SUN2.1G, 0444> SCSI2 0/direct fixed
  sd0: 2049 MB, 3992 cyl, 9 head, 116 sec, 512 bytes/sect x 4197405 sectors
Disk #2
  probe(esp0:1:0): max sync rate 10.00MB/s
  sd1 at scsibus0 target 1 lun 0: <SEAGATE, ST32430N SUN2.1G, 0444> SCSI2 0/direct fixed
  sd1: 2049 MB, 3992 cyl, 9 head, 116 sec, 512 bytes/sect x 4197405 sectors
Disk #3
  probe(esp0:2:0): max sync rate 10.00MB/s
  sd2 at scsibus0 target 2 lun 0: <SEAGATE, ST11200N SUN1.05, 9500> SCSI2 0/direct fixed
  sd2: 1005 MB, 1872 cyl, 15 head, 73 sec, 512 bytes/sect x 2059140 sectors
Disk #4
  probe(esp0:3:0): max sync rate 10.00MB/s
  sd3 at scsibus0 target 3 lun 0: <SEAGATE, ST11200N SUN1.05, 8808 > SCSI2 0
  sd3: 1005 MB, 1872 cyl, 15 head, 73 sec, 512 bytes/sect x 2059140 sectors

20.2 Configure Kernel Support

The following kernel configuration directive is needed to provide CCD device support. It is enabled in the GENERIC kernel:

pseudo-device  ccd  4    # concatenated disk devices

In my kernel config, I also hard code SCSI ID associations to /dev device entries to prevent bad things from happening:

sd0     at scsibus0 target 0 lun ?     
# SCSI disk drives
sd1     at scsibus0 target 1 lun ?     
# SCSI disk drives
sd2     at scsibus0 target 2 lun ?     
# SCSI disk drives
sd3     at scsibus0 target 3 lun ?     
# SCSI disk drives
sd4     at scsibus0 target 4 lun ?     
# SCSI disk drives
sd5     at scsibus0 target 5 lun ?     
# SCSI disk drives
sd6     at scsibus0 target 6 lun ?     
# SCSI disk drives

20.3 Disklabel each volume member of the CCD

Each member disk of the CCD will need a special file system established. In this example, I will need to disklabel:

/dev/rsd0c
/dev/rsd1c
/dev/rsd2c
/dev/rsd3c

You will probably want to remove any pre-existing disklabels on the disks in the CCD. This can be accomplished one of two ways the dd command:

# dd if=/dev/zero of=/dev/rsd0c bs=8k count=1
# dd if=/dev/zero of=/dev/rsd1c bs=8k count=1
# dd if=/dev/zero of=/dev/rsd2c bs=8k count=1
# dd if=/dev/zero of=/dev/rsd3c bs=8k count=1

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:

# dd if=/dev/zero of=/dev/rsd0d count=1

This will make all data on the entire disk unaccessible.

The default disklabel for the disk will look similar to this:

# disklabel -r /dev/rsd0c
[...snip...]
bytes/sector: 512
sectors/track: 116
tracks/cylinder: 9
sectors/cylinder: 1044
cylinders: 3992
total sectors: 4197405
[..snip...]
3 partitions:
#        size   offset    fstype   [fsize bsize   cpg]
  c:  4197405       0     unused     1024  8192        # (Cyl.    0 - 4020*)

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 disklabels accordingly. Be sure to specify the path to the character device, not the block device.

# disklabel -e /dev/rsd0c

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:

3 partitions:
#        size   offset    fstype   [fsize bsize   cpg]
  c:  4196361     1044       ccd                       # (Cyl. 1 - 4020*)

Optionally you can setup a slice other than c to use, simply adjust accordingly below:

3 partitions:
#        size   offset    fstype   [fsize bsize   cpg]
  a:  4196361     1044       ccd                       # (Cyl. 1 - 4020*)
  c:  4197405       0     unused     1024  8192        # (Cyl. 0 - 4020*)

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 it's sanity checks.

20.4 Configure the CCD

Once all disk are properly labeled, you will need to generate a configuration file. The configuration file resides in /etc by default. You may need to create a new one. Format:

#ccd    ileave    flags   component    devices

Example in this case:

# more /etc/ccd.conf
ccd0  0  none /dev/sd0c /dev/sd1c /dev/sd2c /dev/sd3c

20.5 Initialize the CCD device

Once you are confident that your CCD configuration is sane, you can initialize the device using the ccdconfig command: Configure:

# ccdconfig -c -f /etc/ccd.conf

Unconfigure:

# ccdconfig -u -f /etc/ccd.conf

Initializing the CCD device will activate /dev entries: /dev/{,r}ccd#:

# ls -la  /dev/{,r}ccd0*
brw-r-----  1 root  operator   9, 0 Apr 28 21:35 /dev/ccd0a
brw-r-----  1 root  operator   9, 1 Apr 28 21:35 /dev/ccd0b
brw-r-----  1 root  operator   9, 2 May 12 00:10 /dev/ccd0c
brw-r-----  1 root  operator   9, 3 Apr 28 21:35 /dev/ccd0d
brw-r-----  1 root  operator   9, 4 Apr 28 21:35 /dev/ccd0e
brw-r-----  1 root  operator   9, 5 Apr 28 21:35 /dev/ccd0f
brw-r-----  1 root  operator   9, 6 Apr 28 21:35 /dev/ccd0g
brw-r-----  1 root  operator   9, 7 Apr 28 21:35 /dev/ccd0h
crw-r-----  1 root  operator  23, 0 Jun 12 20:40 /dev/rccd0a
crw-r-----  1 root  operator  23, 1 Apr 28 21:35 /dev/rccd0b
crw-r-----  1 root  operator  23, 2 Jun 12 20:58 /dev/rccd0c
crw-r-----  1 root  operator  23, 3 Apr 28 21:35 /dev/rccd0d
crw-r-----  1 root  operator  23, 4 Apr 28 21:35 /dev/rccd0e
crw-r-----  1 root  operator  23, 5 Apr 28 21:35 /dev/rccd0f
crw-r-----  1 root  operator  23, 6 Apr 28 21:35 /dev/rccd0g
crw-r-----  1 root  operator  23, 7 Apr 28 21:35 /dev/rccd0h

20.6 Create a 4.4BSD/UFS filesystem on the new CCD device

You may now disklabel the new virtual disk device associated with your CCD. Be sure to use the character device:

# disklabel -e /dev/rccd0c

Once again, there will be only one slice, so you may either recycle the c slice or create a separate slice for use.

# disklabel -r /dev/rccd0c
# /dev/rccd0c:
type: ccd
disk: ccd
label: default label
flags:
bytes/sector: 512
sectors/track: 2048
tracks/cylinder: 1
sectors/cylinder: 2048
cylinders: 6107
total sectors: 12508812
rpm: 3600
interleave: 1
trackskew: 0
cylinderskew: 0
headswitch: 0           # microseconds
track-to-track seek: 0  # microseconds
drivedata: 0
#        size   offset    fstype   [fsize bsize   cpg]
  c: 12508812        0    4.2BSD     1024  8192    16  # (Cyl. 0 - 6107*)

The filesystem will then need formatted:

# newfs /dev/rccd0c
Warning: 372 sector(s) in last cylinder unallocated
/dev/rccd0c:    12508812 sectors in 6108 cylinders of 1 tracks, 2048 sectors
        6107.8MB in 382 cyl groups (16 c/g, 16.00MB/g, 3968 i/g)
super-block backups (for fsck -b #) at:
[...]

20.7 Mount the filesystem

Once you have a created a file system on the CCD device, you can can mount the file system against an mount point on your system. Be sure to mount the slice labeled type ffs or 4.4BSD:

# mount /dev/ccd0c /mnt

Then:

# export BLOCKSIZE=1024; df
Filesystem  1K-blocks     Used   Avail Capacity  Mounted on
/dev/sd6a      376155   320290   37057    89%    /
/dev/ccd0c    6058800       1  5755859     0%    /mnt

Congratulations, you now have a working CCD. Please consult the rest of the manual for instructions on how to initialize the device at boot-time via RC. For more detail on any of the commands here, please see their respective man pages.

21.1 Configuring kernel support

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

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.

21.2 Setting up a cgd device

The best way to learn something is by practice. In this section we will look at an example of setting up cgd. In this example we have reserved the "h" partition of the wd0 disk for encryption purposes, and we want want to create an encrypted FFS filesystem. The first thing that needs to be done is to create a configuration file for the wd0h parition. This file is named /etc/cgd/wd0h. This file can be created using the cgdconfig. Suppose we want to use the Blowfish cipher and want to check for an FFS filesystem for verification, this command would create that configuration:

# cgdconfig -g -o /etc/cgd/wd0h -V ffs blowfish-cbc
   

The "-g" parameter forces cgdconfig to create a configuration file, the filename is specified by the "-o" parameter. The "-V" parameter specifies which verification method should be used, valid choices are none, disklabel, and ffs (which are explained above). The resulting configuration file looks like this:

algorithm blowfish-cbc;
iv-method encblkno;
keylength 128;
verify_method ffs;
keygen pkcs5_pbkdf2 {
        iterations 71564;
        salt AAAAgOGFALVANSHf61jf4XYlnUI=;
};
   

At this moment we have created a configuration file and we can start to use this configuration. The next thing that has to be done is to configure an cgd pseudo device. This can be done with the following command:

# cgdconfig -V none cgd0 /dev/wd0h
   

This command configures the cgd0 device to use the wd0h parition to store encrypted data. At this point we will not use verification, because the cgd0 "disk" does not have a valid FFS filesystem. cgdconfig will ask for a passphrase, just enter the passphrase you would like to use for this encrypted partition. You can use the cgd0 device as an normal disk and disklabel it. Create a partition with the 4.2BSD type and make a FFS filesystem on this partition with newfs.

After the initial partitioning and formatting the cgd pseudo-device can be unconfigured with:

# cgdconfig -u cgd0
   

After these configuration steps the encrypted partition can be used with:

# cgdconfig cgd0 /dev/wd0h
   

Note that the "-V" parameter is omitted. The verification method configured in /etc/cgd/wd0h will be used.

21.3 Swap encryption

A question that pops up quite often on the mailinglists is how one can setup NetBSD to encrypt swap. While the instructions above should be sufficient to know how to set up swap, we will provide a short outline in this section. In this example we will use wd0b for storage of the encrypted swap partition. Swap will be encrypted with the Blowfish cipher. As normal, the first step is to create a cgd configuration file. This time we will use the "-k" parameter to generate a random key, and we will not use a verification method (because the parition will be reinitialized after each boot). Execute the following command to generate /etc/cgd/wd0b:

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

With the configuration file set up we can configure the cgd0 pseudo-device:

# cgdconfig cgd0 /dev/wd0b
   

The next step is to configure the disklabel and to save it to /etc/cgd/wd0b.disklabel. Please refer to disklabel(8) for information about how to use disklabel to set up a swap partition.

Now we have to configure cgd to make sure cgd0 is configured during boot process of NetBSD. Add the following line to /etc/cgd/cgd.conf:

cgd0 /dev/wd0b
   

cgd0 is reinitialized with a blank disklabel after a reboot, because no verification is used and a random key is generated. So, the cgd0 device has to disklabelled with the disklabel we just saved during each boot. This can be done by creating the /etc/rc.conf.d/cgd and add this function (thanks to Lubomir Sedlacik):

swap_device="cgd0"
swap_disklabel="/etc/cgd/wd0b.disklabel"
start_postcmd="cgd_swap"
cgd_swap()
{
        if [ -f $swap_disklabel ]; then
                disklabel -R -r $swap_device $swap_disklabel
        fi
} 
   

Finally add the cgd0 partition you configured to /etc/fstab.

22.1 The rc.d Configuration

The rc files for the system reside under /etc, 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:

• /etc/rc runs the scripts in /etc/rc.d

• /etc/rc.subr contains common functions used by rc scripts.

• /etc/shutdown calls the scripts in /etc/rc.d in reverse order.

Additional scripts outside of the rc.d directory:

• /etc/rc.lkm loads or unloads Loadable Kernel Modules.

• /etc/rc.local almost the last script called at boot up, local daemons may be added here.

Following is the example from the system for an apache web server added to /etc/rc.local:

if [ -f /usr/pkg/etc/rc.d/apache ]; then
        /usr/pkg/etc/rc.d/apache start
fi

The /etc/defaults directory contains the default settings for NetBSD and the contents should not be changed. Within the rc context the only file of interest is rc.conf, this is the default rc configuration that ships with NetBSD. In order to alter a default setting, an override may be installed in /etc/rc.conf. For example, if you wanted to enable the Secure Shell Daemon:

# cd /etc; grep ssh defaults/rc.conf
sshd=NO                 sshd_flags=""
# echo "sshd=YES" >> rc.conf

Or just edit the file with your favorite editor. The same can be done with any default that needs to be changed.

Another way to make rc.conf easy to edit is to do the following:

# cd /etc/defaults
# cat rc.conf >> ../rc.conf

Then modify anything you need to.

Last and not least, the /etc/rc.conf.d/ directory can be used for scripts that are third party.

22.2 The rc.d Scripts

The actual scripts that control services are in /etc/rc.d. Once a service has been activated or told not to activate in /etc/rc.conf it can be also be modified by calling the rc script from the command line, for example if an administrator needed to start secure shell:

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

The rc scripts must receive one of the following arguments:

• start

• stop

• restart

• kill

An example might be when a new record has been added to the named database on a named server:

# /etc/rc.d/named restart
Stopping named.
Starting named.

A slightly more complex example is when a series of settings have been changed, for instance a firewall's ipfilter rules, ipnat configuration, and the secure shell server has switched encryption type:

# cd /etc/rc.d
# ./ipfilter restart; ./ipnat restart; ./sshd restart

22.3 The Role of rcorder and rc Scripts

As per the System Manager's Manual, rcorder is designed to print out a dependancy ordering of a set of interdependent files. It basically determines the order of execution one way or another. On some Unix systems this is done by numbering the files and/or putting them in separate run level directories. Which can be messy. On NetBSD this is done by the controlling scripts mentioned at the beginning of this document and by the contents of each rc script.

In the rc scripts there is a series of lines that have one of the following in them:

REQUIRE
PROVIDE
BEFORE
KEYWORD

These dicatate the dependencies of that particular rc script and hence rcorder can easily work either "up" or "down" as the situation requires. Following is an example of the nfsd rc script:

...
 PROVIDE: nfsd
 REQUIRE: mountd
. /etc/rc.subr
...

Here we can see that this script provides the nfsd service, however, it requires mountd to be running.

22.4 Additional Reading

There are other resources available pertaining to the rc.d system:

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

• Will Andrews wrote a Daemonnews article called The NetBSD rc.d System.

23.1 Overview

In this document we will look at a simple definition of inetd, how several files that relate to inetd work (not that these files are not related to other software), how to add a service to inetd and some considerations both to use inetd for a particular service and times when a service might be better off running outside of inetd.

23.2 What is Inetd

The internet super server listens on its own sockets, when it receives a request it then determines which server to connect the request to and starts an instance of the server program.

Following is a very simple diagram to illustrate inetd:

 pop3  ------  |
               | 
 ftpd -------  | INETD | ---- Internet / DMZ / Switch / Whatever . . . 
               |
 cvspserver -  |
   

In the above diagram you can see the general idea. The inetd server receives a request and then starts the appropiate server process. What inetd is doing is software multiplexing. An important note here, on many other UNIX-like systems, inetd has a package called tcpwrappers as a security enhancment, on NetBSD the secure behavoir of tcpwrappers was built in using libwrap.

23.3 Protocols

The first file is the protocols name data base which 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

Lets look at the second entry in the /etc/protocols db as an example:

icmp    1       ICMP            
   

Starting from the left, we see that the protocol name is icmp, the number is 1 and the only aliases listed is ICMP.

23.4 Services

The next file to consider is the service name data base that can be found in /etc/services. This db basically contains information about services and the mappings from protocol to port number. The format of the /etc/services file is:

service_name port_number protocol_name aliases

Lets take a look at the ssh entries as an example:

ssh             22/tcp
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).

23.5 RPC

The rpc program number data base is kept in /etc/rpc and contains name mappings to rpc program numbers, the format of the file is:

server_name program_number aliases

For example, here is the nfs entry:

nfs             100003  nfsprog
   

23.6 Inetd

Last and definitely not least of the files we are concerned with is the internet super-server file, /etc/inetd.conf. The inetd.conf file basically provides enabling and mapping of services the systems administrator would like to have multiplexed through inetd.

The previous files were very much informational for the system and hence their layout was also relatively simple, the inetd.conf file, however, is a little more complex (but not too much) and deserves a little deeper explanation.

The basic field layout of the inetd.conf file is:

service_name socket_type protocol wait/nowait user:group server_program arguments

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, wait/nowait is set to nowait, the user is root, path is /usr/libexec/ftpd and program name and arguments is ftpd -ll. Notice in the last field, the program name is different from the service-name.

23.7 Adding a Service

Many times a systems administrator will find that they need to add a service to their system that is not already in inetd or they may wish to move a service to it because it does not get very much traffic. This is usually pretty simple, so as an example we will look at adding a version of pop3 on a NetBSD system.

In this case we have retrieved and installed the cucipop package. This server is pretty simple to use, the only oddities are different path locations. Since it is pop3 we know it is a stream oriented connection with nowait. Using root will be fine, the only item that is different is the location of the program and the name of the program itself.

So the first half of the new entry looks like this:

pop3   stream  tcp     nowait  root
   

After installation, pkgsrc deposited cucipop in /usr/pkg/sbin/cucipop. So with the next field we have:

pop3   stream  tcp     nowait  root /usr/pkg/sbin/cucipop
   

Last, we want to use the Berkeley mailbox format, so our server program must be called with the -Y option. This leaves the entire entry looking like so:

pop3   stream  tcp     nowait  root /usr/pkg/sbin/cucipop cucipop -Y
   

Now, to have inetd use the new entry, we simply restart it using the rc script:

# /etc/rc.d/inetd restart
   

All done, in most cases, the software you are using has documentation that will specify the entry, in the off case it does not, sometimes it helps to try and find something similar to the server program you will be adding. A classic example of this is a MUD server which has built-in telnet. You can pretty much borrow the telnet entry and change parts where needed.

23.8 When to use or not to use inetd

The decision to add or move a service into or out of inetd is usually arrived at based on serverload. As an example, on most systems the telnet daemon does not require as many new connections as say a mail server. Most of the time the administrator has to feel out if a service should be moved.

A good example I have seen is mail services such as smtp and pop. I had setup a mail server in which pop3 was in inetd and exim was running in standalone, I mistakenly assumed it would run fine since there was a low amount of users, namely myself and a diagnostic account. The server was also setup to act as a backup MX and relay in case another heavily used one went down. When I ran some tests I discovered a huge time lag for pop connections remotely. This was because of my steady fetching of mail and the diagnostic user constanty mailing diagnostics back and forth. In the end I had to move the pop3 service out of inetd.

The reason for moving the service is actually quite interesting. When a particular service becomes heavily used, of course, it causes a load on the system. In the case of a service that runs within the inetd meta daemon the effects of a heavily loaded service can also harm other services that use inetd. If the multiplexor is getting too many requests for one particular service, it will begin to affect the performance of other services that use inetd. The fix, in a situation like that, is to make the offending service run outside of inetd so the response time of both the service and inetd will increase.

23.9 Other Resources

Following is some additional reading and information about topics covered in this document:

24.1 Creating install boot floppies for i386

First of all, you need to be running a kernel with the vnd pseudo device enabled (this is the default for a GENERIC kernel.).

24.2 Creating a CD-ROM

To create a data CD-ROM the mkisofs and cdrecord programs can be used: both SCSI and IDE recorders are supported. IDE/ATAPI drives are supported by NetBSD without the need of an emulation layer, because the driver can receive ATAPI commands directly, which is a simple and elegant solution.