The OpenBSD 4.0 Crash Course

Next Page

Book Cover
The OpenBSD 4.0 Crash Course
By Jem Matzan
...............................................
Publisher: O'Reilly
Pub Date: January 01, 2007
ISBN-10: 0-596-51015-2
ISBN-13: 978-0-596-51015-2
Pages: 64

Table of Contents
Overview

OpenBSD is a Unix-like computer operating system that is widely regarded for its excellent documentation and its fanatical focus on security. "The OpenBSD Crash Course" Short Cut will help you get an x86 or AMD64/EM64T server, desktop, or network appliance up and running quickly with OpenBSD. You'll learn how to install or upgrade OpenBSD on x86 and AMD64 machines, how to configure it for server or workstation use, and how to properly maintain it until the next release.

Next Page


Table of Contents

Previous Page

Book Cover
The OpenBSD 4.0 Crash Course
By Jem Matzan
...............................................
Publisher: O'Reilly
Pub Date: January 01, 2007
ISBN-10: 0-596-51015-2
ISBN-13: 978-0-596-51015-2
Pages: 64

Table of Contents

Copyright
Chapter 1. Learn OpenBSD Quickly
Chapter 2. Understanding OpenBSD 4.0
 | Section 2.1. What Is OpenBSD?
 | Section 2.2. What Is OpenBSD Good For?
 | Section 2.3. Supported Architectures and Hardware
Chapter 3. Installing OpenBSD 4.0
 | Section 3.1. Installation Methods
 | Section 3.2. Booting from the Installation Disc
 | Section 3.3. Installation Walkthrough
Chapter 4. Upgrading from OpenBSD 3.9
 | Section 4.1. Upgrading the Base System and Package Sets
 | Section 4.2. Post-Installation Upgrading
Chapter 5. Post-Install Configuration
 | Section 5.1. First Boot in OpenBSD 4.0
 | Section 5.2. Creating User Accounts
 | Section 5.3. A Quick Introduction to the vi Editor
 | Section 5.4. Customizing the Terminal
 | Section 5.5. CD/DVD Mounting Made Easy
 | Section 5.6. Installing the Ports Tree and the Base System Source Code
 | Section 5.7. Using the OpenBSD Package Tools
 | Section 5.8. Custom Kernel Configurations
 | Section 5.9. Enabling Binary Compatibility with Other OSes
 | Section 5.10. Shutting Down and Restarting the Computer
Chapter 6. OpenBSD as a Desktop Operating System
 | Section 6.1. Configuring X.org
 | Section 6.2. Installing a Desktop Environment or Window Manager
 | Section 6.3. Starting X.org
 | Section 6.4. Finding and Installing Desktop-Oriented Programs
 | Section 6.5. Font Configuration
Chapter 7. Server Installation and Service Configuration
 | Section 7.1. The inetd Internet Super-Server
 | Section 7.2. Apache
 | Section 7.3. Databases
 | Section 7.4. Mail Transfer Agents
 | Section 7.5. Mail Delivery Agents
 | Section 7.6. OpenLDAP
 | Section 7.7. NFS
 | Section 7.8. NIS
 | Section 7.9. BIND
 | Section 7.10. CARP
 | Section 7.11. Basic Packet Filter Setup
 | Section 7.12. Enabling and Configuring OpenNTPD
Chapter 8. Installing the Languages of the Web
 | Section 8.1. Java
 | Section 8.2. PHP
 | Section 8.3. Perl
 | Section 8.4. Ruby
 | Section 8.5. Python
Chapter 9. Automation and Reporting
 | Section 9.1. The Cron Daemon
 | Section 9.2. Insecurity Reports
 | Section 9.3. Syslog
Chapter 10. Keeping OpenBSD Up-to-Date
 | Section 10.1. Staying Up-to-Date with Ports and Packages
 | Section 10.2. Switching to the OpenBSD 4.0-STABLE Branch
 | Section 10.3. Switching to OpenBSD-CURRENT
Chapter 11. Where to Go for Help
 | Section 11.1. Commercial Support for OpenBSD
 | Section 11.2. Further Reading

Previous Page


Copyright

Copyright © 2007, O'Reilly Media, Inc.. All rights reserved.


Chapter 1. Learn OpenBSD Quickly

OpenBSD has some of the industry's finest integrated documentation, but it can take a long time to figure out which packages you need to get certain services running, and how to configure them once installed. If you are totally new to Unix-like operating environments, this guide could be a little over your head in some places, but if you read it from start to finish and stick with it when things get difficult, you'll end up with a functional and useful operating system. If you already have some experience with any Unix-like operating system, you'll probably feel right at home with OpenBSD and may want to skip ahead to the sections that apply to you.

While there are some suggestions and system administration tips sprinkled throughout "The OpenBSD Crash Course," it is not designed to teach you how to administer a server. It's impossible to anticipate each reader's hardware configuration and goals for working with OpenBSD, so instead of telling you how to set up your machine to perform specific tasks, this guide will show you how to install and configure various services and programs. This Short Cut is organized into two sections: desktop and server. From those two starting points, you can customize OpenBSD to meet nearly any need.

If you're new to OpenBSD, start at the beginning and skip ahead when you hit a section that isn't relevant to what you need to do. If you just want to get a system up and running quickly, skip ahead to the sections that apply to your situation.


Chapter 2. Understanding OpenBSD 4.0

This section will briefly introduce you to OpenBSD and its capabilities and ideal uses.


Section 2.1. What Is OpenBSD?

2.1. What Is OpenBSD?

OpenBSD is a Unix-like computer operating system that is widely regarded for its excellent documentation and its fanatical focus on security. In October of 1995, Theo de Raadt forked the NetBSD code and formed OpenBSD with the goal of making a free (in the context of rights, not price), highly functional operating system that concentrated on security while remaining as portable as possible. NetBSD was originally based on the last release of the academic replacement for AT&T Unix known as the Berkeley Software Distribution (4.4BSD-Lite), so OpenBSD's heritage reaches back considerably further than many other operating systems in development today.

OpenBSD is designed to be secure by default. The simplest way to explain this concept is to say that everything that could potentially be a security risk is turned off or disabled until you turn on or enable it. That means that while you may have the Apache web server installed, it is not going to start until you either run its daemon from the command line or manually add httpd (the service name that corresponds to Apache) to the system startup script. OpenSSH services will also be unavailable unless specifically enabled. Because it is secure by default, you may have to do more initial configuration with OpenBSD than with most other Unix-like operating systems, and that is why this guide existsto show you how to get an OpenBSD machine up and running quickly.


Section 2.2. What Is OpenBSD Good For?

2.2. What Is OpenBSD Good For?

OpenBSD is frequently employed as a web, email, and FTP server, though it can just as easily run BIND to do DNS name resolution, OpenLDAP to form a directory server, and the PostgreSQL and MySQL databases, among a few others. Many people also use OpenBSD in a network appliance machine as a firewall, router, and wireless access point.

You can also make a suitable desktop operating system out of OpenBSD if you wish. The X.org server is provided on the installation media, and relatively recent editions of KDE, GNOME, Xfce, Fluxbox, Enlightenment (e16), IceWM, and other window managers are available through the Ports system (a collection of optional software that is common to all operating systems in the BSD family). A respectable selection of desktop software is also available, including Firefox, the GIMP, LyX, Evolution, G-Rip, XMMS, and many more. There is an OpenOffice.org port, but it is nonfunctional in OpenBSD 4.0.

One thing you won't get with OpenBSD is hardware 3-D acceleration for graphics cards, so while you can get a highly usable 24-bit color display in X.org with nearly any video card, you won't be able to play 3-D-accelerated games like Unreal Tournament or Tux Racer. The issue here is not X.org drivers but kernel drivers; Nvidia, AMD, and Intel refuse to make OpenBSD drivers or supply sufficient hardware documentation for OpenBSD programmers to make their own.

There are more than 3,700 programs available for OpenBSD, but through a procedure that you'll learn about in a later chapter, you can also run Linux, FreeBSD, SCO Unix, System V Release 4, HP-UX, and BSD/OS binary programs in OpenBSD with little or no performance loss.


Section 2.3. Supported Architectures and Hardware

2.3. Supported Architectures and Hardware

OpenBSD works with a diverse array of hardware on 16 different computing platforms, but for the sake of brevity, this guide will cover only the most popular and common CPU architectures: i386 (otherwise known as x86 or IA32) and AMD64 (also known as x86-64 or EM64T). Ideally you should have at least 10 GB of hard drive space (though you can get away with much less if you're building a network appliance) and at least 128 MB of RAM (but the more, the better).

The BSD operating systems have an unwarranted reputation for poor peripheral hardware support. In reality, OpenBSD natively supports more network and RAID devices than any other operating system. That means two things: first, the days of hunting for and installing third-party drivers are over; second, if a device isn't recognized out of the box by OpenBSD, there is nothing you can do to OpenBSD to get it to work. What you won't get, though, is support for chiefly desktop hardware such as high-end sound cards (though many ordinary sound cards will work), some kinds of scanners, and other things that are generally unnecessary in a server, network appliance, workstation, or work-oriented desktop machine. In other words, OpenBSD is not quite as suited to home desktop use as FreeBSD or GNU/Linux.

What about laptop systems? Most Pentium 3, Celeron, Pentium M (Centrino), Pentium 4 M, Pentium 4, Celeron M, early Turion, and some Core Duo (Centrino Duo) notebook computers have been reported to work wonderfully with OpenBSDsoftmodems and exotic hardware (like fingerprint readers, webcams, and certain Wi-Fi cards) aside. Native ACPI and wireless networking support in OpenBSD is frequently superior to that of even some the fanciest desktop GNU/Linux distributions.

If you have a mass-produced workstation or server, chances are good that everything you need to workvideo, sound, network, drive controller, PCI/AGP controllerwill be fully supported. If you have a home-built system that is more than a year old, it's probably going to be okay, too. If you just built a top-of-the-line Intel Core 2 Duo system with the latest, fanciest 802.11g wireless card, a $400 PCI Express video card, and you expect to set up a RAID-5 array with the built-in SATA fake-RAID controller on your just-released Abit motherboard...well, you're probably going to have at least a moderate amount of trouble with any operating system, but OpenBSD 4.0 probably won't work very well for you. The more your target computer resembles the latter scenario, the less pleased you'll be with OpenBSD at this time.

If you aren't sure if a critical piece of hardware will work with OpenBSD 4.0, your first stop should be the hardware compatibility list for your processor architecture:

  • For i386 (x86): http://www.openbsd.org/i386.html#hardware

  • For AMD64 (x86-64): http://www.openbsd.org/amd64.html#hardware

Once you have an idea of what hardware support is like for your computer, it's time to begin the installation process. If you're upgrading from OpenBSD 3.9, skip the following section and go directly to "Upgrading from OpenBSD 3.9."


Chapter 3. Installing OpenBSD 4.0

This section will walk you through the entire OpenBSD installation process, from start to finish.


Section 3.1. Installation Methods

3.1. Installation Methods

There are three ways to install OpenBSD: over a network, by bootstrapping from an existing OpenBSD system, or through installation media (CD or floppy disk). Not all methods are supported by every architecture, but both x86 and AMD64 support all three installation procedures.

By far the quickest, easiest, and most comprehensive method for modern computers is to use the official OpenBSD installation CDs. These are available for U.S. $50 (plus shipping) directly from the OpenBSD Project's web site: http://www.openbsd.org/orders.html.

If you need to install OpenBSD right away and have a working broadband Internet connection, you can perform an FTP installation by using a minimal install floppy disk or CD, then retrieving the installation files from one of many OpenBSD mirror sites. The mirror list is at this address: http://www.openbsd.org/ftp.html#ftp.

If you choose a mirror site that is close to you, the download will take less time than if you choose one that is far away. It's a good idea to write down two or three mirror addresses just in case one happens to be down when you need it; you may have to type these in during installation. In addition to installation, you will also need an FTP mirror address for some other important things later, so it's a good idea to have them written down so that you don't have to look them up again.

The directory on the server that has the ISO files for the i386 minimal install CD and floppies is pub/OpenBSD/4.0/i386/, and the AMD64 ISO can be found at pub/OpenBSD/4.0/amd64/.

There are three floppy image files, of which you need only one if you are installing from the floppy drive:

floppy40.fs

This image is generally suitable for PCs that have a PCI or ISA network card; have an IDE, SATA or simple SCSI disk; and include support for some PCMCIA cards.

floppyB40.fs

This image is more suited to servers. It contains drivers for many kinds of RAID controllers, and some of the less common SCSI adapters. However, support for many standard SCSI adapters and many EISA and ISA network chips is not present.

floppyC40.fs

This image is designed for laptop computers, and supports a wide range of CardBus and PCMCIA devices.

And three CD imagesagain, you need only the one that applies to you:

cdrom40.fs

This is essentially a conglomerate of all three of the above floppy images. It can be used to make either a bootable 2.88M floppy or a CD.

cd40.iso

This is the CD ISO file that you are most likely to use. It has the widest selection of drivers.

cdemu40.iso

This CD image uses "floppy emulation" booting by using the cdrom40.fs image. This is only for use in special situations when the cd40.iso file won't work (usually on older systems).

Download the image appropriate to your situation (this will very likely be the cd40.iso file), then follow the instructions below.

3.1.1. Burning a CD from an ISO file

You have probably created a CD or DVD from an ISO file before. If so, follow your usual procedure. If you haven't created a CD from an ISO file in the past, then the instructions for doing so are dependent on your current operating system. Skip down to the subsection below that applies to your situation.

3.1.1.1. Microsoft Windows

You should already have some kind of CD/DVD writing program like Nero or Easy CD Creator on your computer. Navigate the program's menus until you find the option for creating a CD from an ISO image. Select the cd40.iso image in the ensuing file dialog, and then choose to burn the CD image to the disc.

If you do not have any such program, you can download one for free at either of these addresses:

http://isorecorder.alexfeinman.com/isorecorder.htm
http://www.cdburnerxp.se/download.php

After the CD writing program is downloaded and installed, run it. For example, using CDBurnerXP, you'd insert a blank disc, then click on the Start New Data Disc Compilation button. After that, go to the File menu and select Write Disk From ISO File. Choose the cd40.iso file from the ensuing file dialogue, then click Write Disc.

3.1.1.2. Unix, GNU, and BSD systems

You can use the cdrecord command-line utility or the Qt-based K3b program to make ISOs into CDs. K3b should be pretty self-explanatory. Here's a quick cdrecord example (remember to change it for your specific system):

cdrecord -eject speed=24 dev=0,1,0 cd40.iso

3.1.1.3. Mac OS X

Start the Disk Utility from the Applications menu, then drag-and-drop the cd40.iso file to its sidebar. Click the file in the Disk Utility sidebar to select it; then go to the menu, select the Image submenu, and click on Burn.

3.1.2. Creating a diskette from an FS file

Refer to the section below that corresponds with the operating system you're using.

3.1.2.1. From Unix-like operating systems

Most BSD, GNU and Unix systems can format and check a disk by using the fdformat utility. Its usage is simple:

fdformat /dev/rfd0c

where the /dev/rfd0c represents your floppy disk's device node. This is only an example and may not apply to your specific operating system, so change the above command appropriately. If you see all Vs in the resulting format routine, the disk is safe to write to.

To commit your floppy image to disk, use the dd command as such:

dd if=floppy40.fs of=/dev/rfd0c bs=32k

Again, you must modify the above command to fit your situation.

3.1.2.2. From Microsoft Windows

The first thing you'll need is a program that can write floppy images to disks. Windows does not natively include such a utility, but the OpenBSD Project has a few of them available for you to use on Windows. The one that should work best for current Windows systems (2000, XP, Vista) is ntrw. You can download it from the directory / pub/OpenBSD/4.0/tools/ on the same OpenBSD mirror that you downloaded the floppy ISO from.

Once downloaded, start the Command Prompt utility and run the program in it with the following syntax:

ntrw floppy40.fs a:

3.1.3. Installing over PXE

If you can't use a CD or diskette, and your network infrastructure supports booting over a network connection via the Preboot eXecution Environment (PXE), you can install OpenBSD over it. PXE gurus probably just need to know the name of the file from the OpenBSD FTP server that the operating system boots from. That file is pxeboot, and the installation kernel is bsd.rd, so these two files need to be in the appropriate directory on your FTP server. PXE booting can be very tricky because it involves other machines and services, so that's as far as the OpenBSD Crash Course goes on this subject. If you need more detailed PXE boot instructions, the OpenBSD Project has them here: http://www.openbsd.org/faq/faq6.html#PXE.


Section 3.2. Booting from the Installation Disc

3.2. Booting from the Installation Disc

Most computers default to some slight variation of the following boot order: network, floppy disk, optical drive (CD), and then hard drive. If no boot files are found on any of those devices, you get an error message on the screen; most people will never see it unless they have a serious hard drive problem. There is a chance, though, that your computer will try to boot from the hard drive before any other devices. That's fine for normal, everyday operation, but it's no good for installing operating systems. In order to boot from your OpenBSD installation disc or disk, you will have to set your BIOS to boot from the drive that contains the installation media. If the BIOS looks to your hard drive for boot information first, it's likely that the CD or diskette will not be seen at all. You can test this by inserting the OpenBSD installation media in the appropriate drive shortly after the computer starts. If it boots from the diskette or CD and you see a bunch of lines of blue-highlighted text after a short delay, then you're all setgo ahead and skip down to the installation walkthrough.

3.2.1. Modifying the boot order

When they first power on, nearly all computers will tell you what key to press to enter the BIOS setup (if your computer offers a boot selection menu, such as F12 on some Dells and Option on Macs, you can use that to select the CD-ROM without having to poke around in BIOS setup). If you cannot see this screen, then press the following keys a few times when the computer beeps just after it is powered on: DEL (delete), F1, and F2. (If the machine is made by Compaq, the key to press may be F10 instead.) Once you get to the blue or black BIOS setup (sometimes called CMOS setup) screen, look for a Boot or an Advanced CMOS Setup section, and modify the boot order so that the CD-ROM or floppy drive is first, and the hard drive second. This is usually done by selecting drives from a drop-down list or by pressing the + and - keys to move a selection up or down in the list. When you've done that, save and exit setup, and the computer will restart with the new settings.

If you were successful, you should see a brief OpenBSD boot screen, followed by a few screens of blue-highlighted text that show the boot process. If the CD or disk fails to boot, you may not have adjusted the BIOS properly, or the installation media you made may be damaged or improperly burned (if this is the case, try burning it at a lower speed than you did the first time).

You should now continue on to the next section, which explains the exact installation process.


Section 3.3. Installation Walkthrough

3.3. Installation Walkthrough

The OpenBSD Project provides decent installation instructions. You can find them in the liner notes in the CD set, or a more comprehensive instruction manual at this address: http://www.openbsd.org/faq/faq4.html.

Even though it's already been done twice, for the sake of completeness, this guide includes its own unique step-by step installation instructions below. If you are upgrading from OpenBSD 3.9, skip down to the section on upgrading.

3.3.1. Initial installation settings

When the installation media finishes booting, you'll be asked whether you would like to install, upgrade, or go straight to the command-line shell. Type i and press Enter.

Next you'll be asked to choose a terminal type. The default is vt220and that's fine, but it is forever in black and white. Type in pcvt25 and press Enterthat's a good color terminal that should work well with any modern computer.

If you live in the United States or Canada, type us at the keyboard layout (kbd(8) mapping) screen. If you use a Dvorak keyboard or a keyboard in a different country, press l (lowercase L) to see a list of keyboard types, then type in the appropriate one and press Enter.

Type in yes when you're asked if you'd like to proceed with the installation.

3.3.2. Slices, partitions, and filesystems

All BSD systems have a common method of dividing up hard disks, even though the partition types and filesystem formats differ among all of the BSD derivatives.

First you must assign a certain area of the disk for your operating system. This area is called a slice. You may then divide the slice up into a number of partitions, on which you will put filesystems. This differs from DOS, Windows, and GNU/Linux in that they do not deal with slicesjust partitions. If you do not have enough free, unpartitioned space on your existing hard drive, you may want to consider installing a second drive specifically for it. You can also install a removable or hot-swappable hard drive bay and switch hard disks as needed. You can also use a partition resizing tool such as gparted to create free space on your hard drive. Such utilities can be installed on most Unix-like operating systems, and many live CDs (such as the Ubuntu Linux installation disc, and the Knoppix and Kanotix live software distributions) have them readily available.

Now that you know what's about to happen, let's get back to the installation.

If you only have one hard drive in the system, press Enter when you're asked which hard disk you'd like to install to. If you have multiple hard drives and only want to install to one of them, OpenBSD should print out a list of device nodes that relate to hard drives. Generally this is wd0, wd1, etc., labeled according to their order of connection. Type in the device node of the disk you wish to install to and press Enter. The default is wd0.

Now you'll be asked if you'd like to use the entire disk for OpenBSD. If you want to try to get fancy with the slicing of your OpenBSD disk, that's fine, but it's only going to make things more difficult from here on. It is strongly recommended that you type Y and press Enter. This will erase everything on your hard drive.

Next you'll create partitions for your slice. You need a minimum of two: a root partition and a swap partition, but if you are designing the system for maximum security, you'll want to create partitions for the following directories:

  • /

  • /tmp

  • /var

  • /usr

  • /home

If you're taking this route, you will have to think ahead to what will be in these directories. /tmp can easily be 1 GB, as can /, but /var may end up needing a lot of space if you're going to be hosting a Web or email server. /usr can be anywhere from 6 GB to twice that, depending on how many programs you're going to install. /home may not need much space at all if there won't be any user accounts, but if you're building a desktop system, /home should be big enough to accommodate user files (email, documents, pictures, movies, music, etc.).

The reason why separate partitions are more secure and reliable is because the installation utility will automatically assign different levels of permissions to each partition if you use the ones prescribed above. Secondly, one particular service, if compromised or misconfigured, can't fill up the entire disk with garbage very easily if it has influence over only one partition. Lastly, if a filesystem becomes corrupt for some reason, only a small portion of your system will be lost.

If you get lost in the partition command line, type ? and press Enter to see a list of commands. Unfortunately the list is a little too long for most PC screens, and you miss the commands at the top. The full list of commands is:

  • a creates a partition

  • b sets OpenBSD disk boundaries

  • ? prints the list of commands

  • c changes a partition size

  • D sets the disk label to the default

  • d deletes a partition

  • e edits the drive parameters

  • g sets the method of determining disk geometry

  • M shows the entire OpenBSD manpage for disklabel

  • m modifies an existing partition

  • n sets the mount point for a partition

  • p prints the disk label

  • q saves changes and quits the partition editor

  • r recalculates the amount of free space

  • s saves the disk label to a file

  • u undoes the most recent change

  • w writes the label to the disk

  • X toggles expert mode

  • x exits without saving changes

  • z zeroes out the partition table

So let's get on with partition creation by pressing a. The first question you'll be asked is which partition you're creating. Start with partition A by typing a and pressing Enter. When asked for an offset, press Enter to accept the default. The next variable is size; this will be your root partition, so give it the space you've decided it needs (use G as an abbreviation for gigabytes).

If you were totally confused by partitions earlier and figured you'd just wing it, make the root partition the entire size of the disk minus 2 GB, and then press Enter. If you do this, you won't be bothering with other partitions such as /var and /home (they will all live in the root).

The next question is filesystem type. You can accept the default (4.2BSD). Next you'll be asked for the mount point; that will be / so type a slash and press Enter to create the partition.

Press a again to create a swap partition. Partition B is reserved for swapspace, so choose that. Size it accordingly (or if you're winging it, give over your remaining 2 GB to this partition).

If you were winging it, you've just used up all your disk space, which is fine. But if not, repeat this process with further partitions, starting with the letter d (c is reserved), sizing them according to your plan and giving them the proper mount points. When you're done, press w to write the label to the disk, and then press q and then Enter to save and quit the partition utility.

After the partition table's been written, if you chose to use several partitions, you'll be asked to verify each partition's mount point. If you decided to use one big partition, the installation utility will likely move on to network configuration. For the mount points, just press Enter for each one. When you find that you are starting over at the beginning again, type done and press Enter.

Next you'll be asked if you're sure you want to proceed. Type y and press Enter.

3.3.3. Network configuration

Once the disk has been sliced, partitioned, and formatted, you'll be asked to set the hostname. This is the machine's namename it whatever you wish.

Next you'll be asked if you'd like to configure the network. Type y and press Enter.

If OpenBSD recognizes your network devices, it'll list them by module name. (Note that Intel Centrino (IPW) wireless chips in laptop computers may be recognized, but will not work until a binary firmware blob is manually loaded from the command line after installation is complete.) Most people will probably have only one network device here, but if you have several, choose the one that will be your primary Internet connection and press Enter.

After that, you'll be given the chance to change the media options for your network device. Most people will not have to change anything here, so press Enter.

If this network device has a static IPv4 address, type it in now and press Enter. If it is assigned an IP address from a DHCP server (if it's connecting to a router or directly to a broadband Internet connection like a cable or DSL modem, then it's likely those devices will assign you a dynamic IP address through DHCP as well), type in dhcp and press Enter.

If you put in a static IP address, you'll be asked for a netmask (subnet mask) at this point. Type it in and press Enter.

Next, you'll be asked for your IPv6 address. If you are on an IPv6 network instead of IPv4, enter your static IP address here. Most people will just press Enter for the none default. If this machine will function as an IPv6 router, choose rtsol here.

If you have another network interface to initialize, this process will repeat for that device. Note that the installer will crash if you try to use DHCP with more than one network interface; you can change this manually later (by editing the /etc/hostname file for each network interface) if necessary.

If you have a domain name and DNS server for this machine, now's the time to put them in. If you chose DHCP earlier, then just leave the default entries as they are and press Enter. The nameservers are written to the /etc/resolv.conf file, and are overwritten every time a new host is dynamically configured. Next you'll be asked if you'd like to use the nameserver right now. Press Enter to accept the default yes.

The default route setting is next. If you are setting up OpenBSD as a network router and want to set the default route now (presumably you've already set up your interfaces accordingly), you certainly may. Most people will want to leave this as is and press Enter.

Next you'll be asked if you'd like to configure the hosts file with the ed editor. Unless you already know how to use ed, say no here and remember to do it later if necessary. When asked if you'd like to do any manual network configuration, your answer should probably be no unless you are using this machine as a network appliance of some kind and require unusual settings. All of these things can be changed later through the various network config files in the /etc directory if necessary.

When prompted, type in your root password and press Enter, and then do it once more to ensure that you typed it properly.

3.3.4. Package sets

Now it's time to install package sets. Skip down to the section below that applies to your situation.

3.3.4.1. From the official CD

If you are installing from the official OpenBSD CD set, the package installation will be a breeze: just type cd here and press Enter. Assuming you only have one optical drive in your computer, press Enter again to accept the default, or type the device node of the particular CD drive that you're using for the installation and press Enter. Press Enter a third time to accept the default package set location.

Now skip down to the subsection on choosing package sets.

3.3.4.2. Over FTP/HTTP

If you're installing from a floppy or minimal install CD, type in ftp here (or http if that's the server type of the mirror you chose earlier) and press Enter. You'll then be asked for the FTP or HTTP proxy server (if you don't have one, use none). You'll then be asked for the mirror address and the directory on that mirror that the OpenBSD package sets are in. Type in the mirror address that you wrote down earlier, and leave the directory at its default, which should be automatically detected as pub/OpenBSD/4.0/i386 or pub/OpenBSD/4.0/amd64, depending on which architecture you're installing on.

You may be asked if you'd like to view a list of known FTP mirrors. You should already have one or two written down, so this procedure is not necessary. If you forgot to write down an FTP mirror address, or if the one you wrote down doesn't work, here are some that should:

ftp://ftp5.usa.openbsd.org/
ftp://rt.fm/
ftp://ftp.kd85.com/

Now continue to the subsection on choosing package sets.

3.3.4.3. Choosing package sets

The default package set list will be shown to you. This includes more than the bare minimum installation, which would be the following:

  • bsd

  • bsd.rd

  • base40

  • etc40

These minimum package sets will get you a working, networked operating system and absolutely not one thing more, but unless this is what you want (perhaps if you're designing some types of network appliance, for instance), at very least you should leave the default package selections as they are but add what you need. (You can probably do without the games if hard drive space is a concern, but they won't pose a security risk, so there's no harm in leaving them in.)

If you are on a multi-CPU, multi-core, or Hyper-Threaded machine, select the bsd.mp package for installation; that's the multiprocessor-aware kernel, and you'll need it to use both CPUs or cores.

If you are using this as a desktop system, just type all and press Enter to select all packages, including the X server. To select a package, type its name in and press Enter. To deselect a package, do the same thing with a - in front of the package name (to "subtract" it from the list).

Type done and press Enter when you're done, and then press Enter to begin copying the selected files to your machine. This process will take anywhere from a few minutes to more than an hour, depending on how many package sets you selected and where they are coming from.

Once all of the package sets you selected are installed, you'll be asked for the location of other package sets. Type done here and press Enter.

3.3.5. The final few steps

The next question asks if you'd like to start the OpenSSH daemon when the system boots. If you don't need remote access and are planning to do all your work through this machine itself (or a serial terminal connected to it), type no and press Enter. Otherwise, if you need to be able to log into the machine over the network, press Enter to select the default yes.

Now you'll be asked if you want to start the OpenNTPD network time protocol daemon at boot time. The default is no, but it'll help keep accurate time on your machine if you choose yes here, so unless you have a good reason not to enable OpenNTPD, type yes and press Enter.

Next you'll be asked if you intend to run the X Window System (X.org). If you say yes here, a system-level setting for the AGP aperture will be adjusted according to your detected hardware. This makes it more efficient to display graphics, but it could be a theoretical security risk (attacks via the graphics processor). All things considered, it's not much of a security concern, but if you aren't going to run X.org on this machine (or if you have a graphics adapter that uses a proprietary bus or a non-AGP interface such as PCI or PCI Express), there is absolutely no sense in turning it on. The default here is no, so if you want to enable it, type yes and press Enter.

The following option ("Change the default console to com0?") is for serial terminalsyou don't want to change this unless you will be primarily administering this machine over a serial terminal. The default is no.

Finally, you'll be asked to set the local time zone. Type a ? (question mark) and press Enter to see the list. When you've identified the name of your time zone, type it in and press Enter. (Many of the time zones are shown as a list of prefixesfor example, US/. Type the prefix associated with your location, press Enter, and you'll be prompted for the subtime zone.)

The installer will then finish, and you'll be directed to use the halt command. Do so, and when the system is halted, eject the CD or floppy you booted from, then press Enter to reboot into OpenBSD.

Now skip down to the section on post-install configuration.


Chapter 4. Upgrading from OpenBSD 3.9

OpenBSD supports upgrades only from the release immediately prior to the one you want to install. In this case, that version is 3.9, so if you are using a release that is older than 3.9, there are no guarantees that this process will work for you.

The method listed here is the quickest, easiest, and most predictable method of upgrading. You could alternatively download the OpenBSD 4.0 source code via CVS and build the entire operating system from scratch, but it'll take a long time and may not work perfectly. If this is what you want to do, find the section below on switching to the OpenBSD 4.0-STABLE branch and follow those directions instead.


Section 4.1. Upgrading the Base System and Package Sets

4.1. Upgrading the Base System and Package Sets

Since you are already familiar with the OpenBSD installation process, there's no need to hold your hand through it. Here are the upgrade instructions in short form:

  1. At the installation mode prompt, press the u key.

  2. Type pcvt25 for the terminal type (unless you have a good reason to use a different term mode).

  3. Type your keyboard language/region hereit's probably us if you are reading this guide in English.

  4. Type yes hereof course you want to proceed!

  5. In most cases, the default partition selection should be exactly what you want. However, this part can be tricky because you have to know which partitions match up to what filesystems. If you have no idea, reboot back into the existing version of OpenBSD and see what your /etc/fstab file says. You can also boot from the OpenBSD 4.0 media, choose Shell at the installation mode prompt, and then mount your hard drive partitions and see what's on them.

  6. Unless you have a good reason to change the network settings, opt to have the installer use the network configuration from your existing OpenBSD installation.

  7. Press Enter to choose the default setting of no to the manual network configuration question. If you decide to type yes instead, you'll be brought to the shell, and you'll have to start the installation process all over again.

  8. There should be no reason to edit the fstab file (and if there is and it's non-critical, you can do this later with a more sensible editor than ed), so press Enter.

  9. If you're installing from the official CD set, press Enter to go with the default locations for the package sets. If you are installing over FTP, then you'll have to type ftp when the installer asks where the sets are, and then you'll be asked to put in the OpenBSD FTP mirror that you wrote down earlier. If you forgot to do that, then here are a few that should work for you:

    • ftp://ftp5.usa.openbsd.org/

    • ftp://rt.fm/

    • ftp://ftp.kd85.com/

  10. You should know which package sets you want or don't want, so select at will. Type done and press Enter when you're finished, then press Enter again to install the sets. Choosing no here will bring you back to the package set location screen.

  11. The actual upgrade process takes anywhere from 2 to 45 minutes depending on where you're getting the updated package sets from, how many you need to upgrade, and what either your optical drive or Internet connection speed is.

  12. Press Enter to choose the default done to the question on installing more sets.

  13. When you get to the command line, type halt and press Enter. Remove the diskette or CD and press Enter to restart.


Section 4.2. Post-Installation Upgrading

4.2. Post-Installation Upgrading

This section is valid only for people who are performing an upgrade from a previous version of OpenBSD. If that's not you, skip down to the next section on the first boot into OpenBSD.

This is the second part of the upgrade process, and it assumes that you've upgraded from the official OpenBSD CD set or via FTP. Updating the /etc files can take a half-hour or more, so make sure you've got the time to dedicate to properly performing the remainder of this upgrade. Feel free to ignore the sections below that do not apply to your situation.

4.2.1. Checking for updated config files

The upgrade process you just went through did not install any files to /etc because that would have overwritten your existing config files. You can probably leave your old 3.9 configuration files just as they are without running into any problems, but if you want to be safe (or for the sake of completeness), you should retrieve the etc40.tgz package from an FTP mirror or the installation media, unpack it to a temporary directory, and merge it into your /etc directory by hand. Here's a quick overview of how this is done:

  1. Mount the installation disc for your architecture, or use the ftp command to log into an OpenBSD mirror site.

  2. If you are using FTP, download the etc40.tgz file. It will be in the the /pub/OpenBSD/4.0/i386/ or /pub/OpenBSD/4.0/amd64/ directory.

  3. Change to the /tmp directory, to which you'll be extracting the updated files (alternatively, you can create a directory for this purpose if you're worried about the existing clutter in /tmp interfering with your upgrade):

    cd /tmp

  4. Unpack the tarball (substitute the location of the etc40.tgz file on your machine):

    tar zxvf /mnt/cdrom/4.0/i386/etc40.tgz

  5. Now unpack the X.org configuration tarball if you have X.org installed (if not, skip this step):

    tar zxvf /mnt/cdrom/4.0/i386/xetc40.tgz

  6. More than just the contents of the /etc directory will be unpackedyou'll also get some dotfiles, and root and var directories. This is because these directories also contain files that may need to be copied over.

Now comes the tedious part: you have to move the new files to the old /etc directory by hand, carefully taking into account the customizations you've made to the old config files. Unless you have an extremely versatile and active system that provides many network services and has many users, you should have a decent idea of which files are safe to move and which have to be manually edited first. According to the OpenBSD Project, the following files can probably be copied over to /etc as they are:

  • chio.conf

  • dvmrpd.conf

  • netstart

  • pf.os

  • rc

  • security

  • services

  • mail/helpfile

  • mail/localhost.cf

  • mail/sendmail.cf

  • mail/submit.cf

  • mtree/

  • ppp/ppp.conf.sample

The following files have changed significantly since 3.9 and need to be copied over or merged by hand if you've made important changes to them:

  • changelist

  • ftpusers

  • mail/aliases

  • rc.conf

  • ssh/ssh_config

  • ssh/sshd_config

Many files have not changed at all since 3.9 (/root/.login and /root/.klogin, to name two), and others have changed only a little bit, and in ways that may not affect you. The OpenBSD Project recommends that you take a look at these files to see how they've changed, and to possibly incorporate those changes to your existing files:

  • hostapd.conf

  • ipsec.conf

  • rc.local

  • sensorsd.conf

  • spamd.conf

4.2.2. Updating your .profile

If you merged the new and old /root/.profile configurations, you may have saved an outdated PKG_PATH variable setting. If so, make sure you update it to 4.0 before you proceed with updating programs.

Perhaps this is the first time you've heard of PKG_PATH. It is, after all, a relatively new feature to OpenBSD. If that is the case, you should definitely set it. See the section below on auto-fetching packages for details on what this feature is and how to configure and use it.

4.2.3. Updating Intel Centrino firmware

If you are using an Intel Pro Wireless (Centrino) chip, you may need to update the firmware to version 3.0. You can do that with pkg_add as follows:

pkg_add http://damien.bergamini.free.fr/iwifw/OpenBSD/iwi-firmware-3.0.tgz

It may be necessary to delete the old iwi-firmware package before you install the new one. If so, use pkg_delete to get rid of it.

4.2.4. Adding a new mrouted user

mrouted, the multicast router daemon, has changed to the point that it needs a new user account. To create it, run this command:

useradd -u87 -g=uid -c"DVMRP Daemon" -d/var/empty -s /sbin/nologin _dvmrpd

4.2.5. Upgrading the Ports tree

Upgrading your Ports tree is best done through CVS. Alternatively, you can try to overwrite the existing Ports tree with the Ports tarball on the OpenBSD source code disc (assuming you bought the official CD set), but that's kind of hacky and can lead to a lot of trouble if you have many programs installed through Ports.

To update the Ports tree using CVS, follow this process:

  1. First you need an anonymous CVS mirror near you to pull files from. There's a complete list at this address: http://www.openbsd.org/anoncvs.html#WHICH

  2. Next, get to the Ports directory: cd /usr/ports

  3. Finally, use CVS to update the Ports tree (this mirror address is just an example; use a mirror close to your location and substitute it for this one):

    cvs -d anoncvs@anoncvs1.usa.openbsd.org:/cvs update -PdrOPENBSD_4_0

4.2.6. Upgrading your installed programs

Now that you've upgraded the Ports tree, you're in a better position to update your installed programs. A recent addition to the pkg_add command is the ability to upgrade packages. So if you've installed all of your programs through the pkg_add command, or by auto-fetching packages through the Ports tree, use this command to upgrade your software and all of its dependent packages:

pkg_add -ui -F update -F updatedepends

If there are any questions as to which package versions to upgrade from or to, you'll be asked to choose from a list.

4.2.7. Upgrading the base system source code

If you installed the OpenBSD base system source code into /usr/src, it'll have to be replaced. If you installed the source because you wanted to compile a custom kernel, you probably want to save that kernel config as well. Instead of deleting the /usr/src directory, it would be a better idea to overwrite it with the new source, which would keep your previous kernel configuration file in place. It's a pretty simple operation:

  1. Mount CD 3 from the official OpenBSD CD set, or download src.tar.gz from an OpenBSD FTP mirror.

  2. Change to the /usr/src directory:

    cd /usr/src

  3. Unpack the tarball (your location may vary):

    tar zxvf /mnt/cdrom/src.tar.gz

4.2.8. Recompiling your old custom kernel

This should be pretty simplejust do what you did last time you compiled the kernel. Here's a refresher:

You need the updated OpenBSD source code first, so if you didn't go through the previous section on performing this procedure, scroll up and do it now.

  1. Navigate to the right directory (change i386 to amd64 if that's what you installed):

    cd /sys/arch/i386/conf

  2. Run config on it (MYKERNEL is the sample kernel config file):

    /usr/sbin/config MYKERNEL

  3. Change to the compile directory:

    cd ../compile/MYKERNEL

  4. Then run this:

    make depend

  5. Then:

    make install

You're all set: restart the computer to load the new kernel.


Chapter 5. Post-Install Configuration

Now that you've got OpenBSD installed, it's time to start configuring it. Let's start from the beginning with your first experience with the operating system after installation's over.


Section 5.1. First Boot in OpenBSD 4.0

5.1. First Boot in OpenBSD 4.0

The boot loader will pause briefly in case you want to load an alternate kernel. If you can't wait the few seconds, press Enter to skip it.

When you get to the login prompt, log in as root and put in your root password. You'll be greeted with a paragraph of welcome text and a new mail notification. If you are asked for your terminal type, type in pcvt25 and press Enter. Go ahead and read the welcome message, then type in mail and press Enter to read the email. You'll see a list of messages come up, but really there is only one right now, from Theo de Raadt. To read it, type more 1 (that's the number one) and press Enter.

As you'll see, the email is a welcome message from the OpenBSD project leader. Press the spacebar to scroll down to the next page of text. It's not terribly long, but it does tell you some basic information about OpenBSD that you'll find helpful, including a suggestion to read the afterboot manpage. When you're done, you should see a & prompt. Type x and press Enter to quit the mail program, then type man afterboot to read a more in-depth introduction to OpenBSD.


Section 5.2. Creating User Accounts

5.2. Creating User Accounts

For reasons of safety and security (mostly to prevent yourself from doing any serious damage to your own operating system), it's best to create a user account to work from. If necessary, you can switch to root permissions from within that account by using the su command (the user must be a member of the wheel group to do this).

The command that you would use on most Unix-like operating systems is useradd. If you're already familiar with this command and how to use it, go ahead and run it. If you have several user accounts to add, or would like a simpler utility for adding users, OpenBSD has a neat little script called adduser. The first time you run adduser, you are asked to set the default user parameters. After those are set, you'll be able to initialize a new user account. So let's get started: type adduser and press Enter.

Go ahead and put in the default user account settings. If you don't know what to put in here, just press Enter to accept the defaults. Once those are set, you'll be asked for a username and user-specific settings. Go ahead and put them in as they appear. When you're asked to invite the user to other groups, you will probably want to type in wheel here, as that's the group that allows a user to switch to root permissions. If you do not want this user to be able to gain root access (if it's an account for someone else other than you, for instance), then don't invite them to the wheel group.

At the end of the procedure, you'll be asked to verify the account settings you just entered. After you approve them, the account will be created, and that user will be able to log in.


Section 5.3. A Quick Introduction to the vi Editor

5.3. A Quick Introduction to the vi Editor

The default editor in OpenBSD (and most other Unix-like operating systems) is vi. It's a little old and archaic, and requires time and determination to learn to use it effectively. If you want to learn more about it, install the Vim package from the OpenBSD Ports tree later on (Vim is an improved version of vi) and go through the in-program tutorial. For now, though, you just need to know how to use it. Here's a list of basic commands:

  • Press i to enter insert mode, which allows you to type and erase text

  • Press Escape to exit insert mode

  • Press colon (:) and then type w and press Enter to save a file, as in :w

  • Press the d key twice to delete a line

  • Press the / key and then enter a search string to perform a search

  • Press the o key to skip to the next line, insert a line break, and enter insert mode

  • Type in :q and press Enter to quit vi

  • To save and then quit, type :wq and press Enter

  • To quit without saving, type :q! and press Enter

Remember to exit insert mode before you try to execute other commands.


Section 5.4. Customizing the Terminal

5.4. Customizing the Terminal

Even if you're eventually going to end up controlling this machine remotely through OpenSSH, or if you're going to be running a graphical desktop environment, you still have some configuration work to do from the terminal. Wouldn't it be helpful to adjust your key repeat rate and maybe add some color output to your screen? This section is entirely optional, but you will likely find it helpful.

5.4.1. Changing the terminal type

The default VT220 terminal emulator is not able to display color, and it's difficult to see what you're doing in command-line text editors when you can only see black and gray. Fortunately this is a setting that can easily be changed; just follow this process:

  1. Change to the home directory of the user whose terminal type you want to change (remember that root's home directory is /root):

    cd /home/user/

  2. Now edit the .profile configuration file with vi or your preferred text editor.

  3. Add this line above the PATH statement:

    export TERM=pcvt25

  4. For the root user, erase or comment out (by putting # symbols before each line) the three-line if statement at the bottom of the /root/.profile file. It should look like this:

    if [ -x /usr/bin/tset ]: then
   eval '/usr/bin/tset -sQ \?$TERM'
fi

Erasing or commenting this if statement keeps OpenBSD from asking you what terminal type you want to use every time you log in.

You will have to log out and log back in for these changes to take effect. From this point forward, you should be able to see colors where appropriate (for example, in applications such as Vim, Emacs, Lynx, Mutt, etc.).

5.4.2. Setting the key repeat delay and rate

Is the keyboard delay and repeat rate too slow for you? If you're going to be primarily controlling this system through a serial terminal or over OpenSSH, there isn't much sense in changing these settings. If you're going to be working from a keyboard connected directly to the machine, however, there are two settings you can edit to modify the key repeat rate and repeat delay.

First let's play with them in real time to see which numbers you prefer, starting with the repeat rate. Run this command:

wsconsctl keyboard.repeat.del1=300

If that's too fast or too slow for you, run the same command with a lower or higher number. When you find a rate that you prefer, write it down for right now. We'll make this setting permanent in a moment.

Next, let's try changing the key repeat delay. Be warned that if you set this number too low, it can be extremely difficult to type your way out of it:

wsconsctl keyboard.repeat.deln=50

Again, adjust the number to your preference, but try not to go so low that you can't type normally. Once you've got your preferred number, write it down.

Now let's make these settings permanent. Edit the /etc/wsconsctl.conf file. You'll notice that the first two settings you find are are similar to the commands you've just run. If the lines are commented out (in other words, if there's a # before them), uncomment them and set their numbers to the ones you wrote down. Remember that del1 is the repeat rate and deln is the repeat delay.

Save and exit the file when you're finished. Since you've already adjusted the settings for your current session, you won't have to re-log or restart the computer for them to take effect.


Section 5.5. CD/DVD Mounting Made Easy

5.5. CD/DVD Mounting Made Easy

Before you go much further, it might be a good idea to make it easier to mount your optical drive. By default, you have to do it by hand with a command like this:

mount -t cd9660 /dev/cd0a /mnt

You're going to run out of predefined mount points if you have any other disks or drives to mount, so the default method really isn't meant to be a permanent solution. If this machine is meant to be a server that you'll never need to put CDs into (upgrading aside), there's no need to make any changes; you can leave it as is. Otherwise, follow this procedure:

  1. First you'll need a more convenient place to mount the optical drive. I suggest /mnt/cdrom (usually the standard in GNU systems) or /cdrom (usually the standard in FreeBSD). Regardless of what the directory name is, you have to create it. /mnt/cdrom will be the example used throughout this guide, so that's the one we'll use right now, though you're free to change it to your preference. Use the mkdir command to create it:

    mkdir /mnt/cdrom

  2. Next, open /etc/fstab with your preferred text editor and add this line (you may have to change the device node if you have several CD drives):

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

  3. Save and exit the editor. Now you can use the mount and umount commands without having to type the device name and mount point each time.


Section 5.6. Installing the Ports Tree and the Base System Source Code

5.6. Installing the Ports Tree and the Base System Source Code

Installing the Ports tree and the base system source code is optional. You need Ports only if you need more than a handful of extra programs and you know exactly what they are. You need the OpenBSD source code if you want to be able to switch to the OpenBSD 4.0-STABLE branch, which recompiles the base system if security patches become available.

The Ports system downloads the source code of the program you want to install, applies OpenBSD-specific patches, and then compiles and installs it and all of its dependencies. Obviously there are quicker, easier, and more disk-efficient ways to install software, so if you only need a few programs, it might be easier to use the pkg_add command to install them, assuming they have few dependencies. A lot of the time, though, you don't really know what you need until you've had the system up and running for a while, and sometimes you end up needing another program a few months down the line. Whether or not you should install the Ports tree depends on what you're going to do with your OpenBSD machine. If it's just going to be a router or a wireless access point, it might be best to install the few packages you need (if any) and forget about Ports entirely. If this is going to be a web, email, or other network server, Ports will probably make your life easier unless you have the most basic of configurations in mind. If this is to be a desktop machine, you definitely want Ports. If you change your mind later, you can always install or remove the Ports tree.

5.6.1. Installing the Ports tree

  1. If you have the official OpenBSD CD set, the Ports source code can be found on disc 3. So insert that disc into your optical drive and mount it (this assumes you followed the earlier tutorial on modifying /etc/fstab to make CD mounting easier):

    mount /mnt/cdrom

  2. Now change to the destination directory:

    cd /usr/

  3. Finally, unpack the Ports tarball:

    tar zxvf /mnt/cdrom/ports.tar.gz

If you installed over FTP, you'll have to fetch the Ports tarball from your local FTP mirror before you can unpack it. You can connect to it from the command line by using the ftp command. Log in as anonymous and use your email address as the password. Navigate to the / pub/OpenBSD/4.0/ directory, and then use the get command to retrieve ports.tar.gz. This command will do the trick (substitute your local mirror for openbsdmirror below):

ftp ftp://openbsdmirror/pub/OpenBSD/4.0/ports.tar.gz

Once the file is downloaded, unpack it to the /usr directory. It will unpack its own /usr/ports directory and populate it with the almost 4,000 program entries in the Ports tree.

Once the Ports tree is unpacked, you're ready to use it. Instructions for that are in the next section.

5.6.2. Installing the base system source tree

This procedure is almost identical to that of the Ports tree. Here's the process:

  1. Mount disc 3 of the OpenBSD CD set, or download the src.tar.gz file from your local OpenBSD mirror. If you'd like an example of how to do this, read the preceding subsection on installing the Ports tree.

  2. Switch to the /usr/src/ directory:

    cd /usr/src

  3. Unpack the src.tar.gz file:

    tar zxvf /mnt/cdrom/src.tar.gz

When it is done, you will be able to switch to the patch branch and compile your own OpenBSD kernel. Details on what these things are and how to do them are included in later sections of this guide.


Section 5.7. Using the OpenBSD Package Tools

5.7. Using the OpenBSD Package Tools

The pkg_add command is useful for fetching and installing packages, but it's a real pain to have to type in an exact path to the package, which will be on either disc 1 or 2 of your CD set, or from a remote FTP mirror. Fortunately, a relatively new variable in OpenBSD called PKG_PATH allows you to easily do this. It sets a patheither local or remoteto a directory of OpenBSD packages. If you have PKG_PATH set to an online OpenBSD package repository, it makes it much easier to install packages with pkg_add or through the Ports tree. If you have a lot of installed programs, whether they be from Ports or from the pool of precompiled packages, this is definitely the way to go. Here's how to take advantage of it:

  1. Unless you already have one written down, go to this address and find an OpenBSD mirror that is close to you: http://www.openbsd.org/ftp.html#ftp.

  2. Edit the /root/.profile configuration file. On a blank line, type in this line, substituting the FTP mirror address you selected in the previous step for openbsdmirror (also substitute amd64 for i386 if you're using the AMD64 edition):

    export PKG_PATH=ftp://openbsdmirror/pub/OpenBSD/4.0/packages/i386/

  3. And put this line below it:

    export FETCH_PACKAGES=yes

  4. Save and exit the editor, then re-log in so that the changes can take effect. If you are logging in as a regular user and using su to install packages, you will need to make the same changes to your user's ~/.profile configuration as well.

With the above changes, whenever you try to install a program through the Ports tree, Ports will first look for a binary package in the directory you specified. If it finds one, it also looks for dependent packages. If no precompiled binaries are found, Ports goes ahead and compiles the program from source, along with any dependencies. If you install a package with the pkg_add command, you need to type only the package name (not the full version information and path), and dependencies are automatically calculated for you.

5.7.1. Installing programs through Ports and pkg_add

There are more than 3,700 programs in the Ports tree, and about 3,400 of them have precompiled binary package equivalents. As mentioned in the previous subsection, you can use Ports to retrieve binary packages if you make the changes listed above.

The advantage that Ports has over the plain pkg_add command is that it's much easier to find a program you're looking for. Just go to /usr/ports/ and look through the categories; then cd to that category and look for the program you want. Vim, for instance, can be found in /usr/ports/editors/vim/.

If there is any question as to what one of the programs in Ports does, take a look at the DESCR file in that program's pkg directory. DESCR provides a basic description of what each program does.

If you can't find a package through ordinary navigation of the Ports tree, switch to the /usr/ports directory and run this command:

make search key=searchterm

Replace searchterm with a search word. For instance, if you are looking for all programs that relate to the Fluxbox window manager, you would type this:

make search key=fluxbox

This is not case-sensitive, so capital letters don't matter. You'll be shown a list of programs in the Ports tree that have descriptions that contain the word you searched for. If the list is too long to read in one screen, hold down the Shift key and press Page Up to scroll the screen buffer back a little.

Once you change to the program's directory in the Ports tree, run this command to install the program:

make install clean

First, Ports will check to see if there is a package available. If there is, it'll fetch it and any dependent packages and install them. If there is no package, the source code will be retrieved, and the program and all of its dependencies will be compiled and installed, and then the temporary build files and source code tarballs will be deleted.

The pkg_add command is used like this:

pkg_add packagename

The package tools now do name resolution, so if you need to install, for instance, the GIMP graphics program, you won't need to specify the version number (unless there are several variants of the package available).

If you want to find out more about pkg_add, view its manual by running this command:

man pkg_add

Though there are a few more package tools, the only other ones you're likely to use are pkg_info, which tells you what packages are currently installed and what versions they are (it can also be used on individual packages to tell you all about them), and pkg_delete, which removes a particular package.


Section 5.8. Custom Kernel Configurations

5.8. Custom Kernel Configurations

Most people will never have to recompile the OpenBSD kernel. If you're working on a system where you measure memory or storage in kilobytes, or if your hardware is supported in OpenBSD but is not compiled into the GENERIC kernel, you can use the instructions in this section to trim your kernel down or build a kernel with the hardware support you need.

You must have the OpenBSD base system source code (see the earlier section "Upgrading the base system source code") installed in order to continue with this section.

5.8.1. Creating a custom OpenBSD kernel

You can find the default kernel configuration file in the /sys/arch/i386/conf directory (The /sys directory is actually a symlink to /usr/src/sys). Make sure you substitute amd64 for i386 if necessary. It's a plain text file, so you can view it with the less command or edit it with your preferred text editor.

Feel free to have a look at GENERIC, but don't touch. If you want to create your own kernel config file, copy GENERIC to some other name so that if things go wrong or if you want to go back to a stock kernel, it's as easy as recompiling with a different config name. So copy GENERIC to a filename like MYKERNEL, and then work with that instead.

The lines that have a # preceding them are commented out, so they are not compiled into the kernel. You'll probably notice, looking through the default configuration that most things are compiled into the kernel. To remove something from the kernel you're compiling, comment it out; to put something in that isn't there now, uncomment it.

There is a separate configuration for multi-CPU configurations or multi-core processors: GENERIC.MP. It contains an include to pull in the contents of GENERIC and adds these three lines:

option MULTIPROCESSOR
cpu* at mainbus?
ioapic* at mainbus?

If you need a custom SMP kernel, it might be easier to copy and paste these three lines somewhere in your MYKERNEL configuration rather than create a MYKERNEL.MP.

Once you've got your kernel configuration the way you want it, follow this process to compile and install it:

  1. Run this command (assuming you followed the example and used MYKERNEL as the custom config filename):

    /usr/sbin/config MYKERNEL

  2. Then change to the directory the preceding command created:

    cd ../compile/MYKERNEL

  3. Now it's time to compile:

    make clean && make depend && make && make install

If your config file is in order, the kernel should compile and install properly. At this point, all you have to do is restart the system for the new kernel to take effect.

If you need a detailed description of kernel configuration options, see the options manpage.


Section 5.9. Enabling Binary Compatibility with Other OSes

5.9. Enabling Binary Compatibility with Other OSes

As mentioned earlier, OpenBSD has the ability to run binaries from some other kinds of Unix or Unix-like operating systems. This binary compatibility is restricted to certain processor architectures (i386, mostly) and is not turned on by default. Fortunately, enabling it is simple. Assuming you want to permanently enable binary compatibility, follow this procedure:

  1. Edit the /etc/sysctl.conf file with your text editor of choice.

  2. At the end of the file you'll see six commented-out lines that deal with binary compatibility. Uncomment the ones relevant to your situation. The next time you restart the computer, binary compatibility for the operating systems you specified will be enabled.

  3. If you don't want to restart, use the sysctl command to enable compatibility for this session: just type sysctl and then after it, copy and paste the line from the sysctl.conf file that you want enabled and press Enter.

  4. If you want true FreeBSD compatibility, you'll have to install the /usr/ports/emulators/freebsd_lib package, which provides some essential FreeBSD software libraries.

  5. If you want full Linux binary compatibility, you'll have to install the /usr/ports/emulators/redhat package, which provides some essential GNU software libraries. You will also have to create a /proc directory and add this line to /etc/fstab:

    /proc /proc procfs rw,linux 0 0

Not all binaries will work, but most should. Anything that has architecture- or system-specific code (such as something that interfaces directly with your computer hardware) will probably not work.

FreeBSD binaries will use the /emul/freebsd directory as their "shadow root" directory, where a sort of dummy skeleton of a FreeBSD system is kept. A similar directory can be found for Linux binaries in /emul/linux.

If you have trouble running binaries from supported platforms, each of them has a manpage that has specific troubleshooting tips:

  • man compat_freebsd

  • man compat_linux

  • man compat_svr4

  • man compat_ibsc2

  • man compat_aout

  • man compat_bsdos


Section 5.10. Shutting Down and Restarting the Computer

5.10. Shutting Down and Restarting the Computer

Most configuration changes don't need a full restart to take effect: they are either immediately applied or require you to log out. To do that, type exit and press Enter. After a brief pause, you'll be brought to the login prompt.

If you need to shut your computer off, log in as root, type halt , and press Enter.

If you want to reboot, log in as root, type reboot, and press Enter.


Chapter 6. OpenBSD as a Desktop Operating System

Believe it or not, OpenBSD makes a fine desktop operating system for Unix-savvy people who don't play 3-D games or have high-performance computing requirements. It also makes a great development platform for practically any modern computer programming language.

You definitely want the Ports tree installed for a desktop operating environment because you'll probably be installing a relatively large number of programs.


Section 6.1. Configuring X.org

6.1. Configuring X.org

There is no clean way to install X.org after OpenBSD has been installed. The best (and officially supported) way to do it is during installation. If you did not install X.org and want to install it now, it would be easiest to reinstall OpenBSD.

Configuring X.org is simple. Just run this command from a root terminal:

X -configure

The preceding command is reasonably competent when it comes to auto-detecting your hardware and settings. The best way to test it is to use it with the window manager or desktop environment that you plan on being in most often. The configuration file will be saved to /root/xorg.conf.new. Go ahead and move it over to the proper directory with this command:

mv /root/xorg.conf.new /etc/X11/xorg.conf

If you want to test the configuration right away, you can do so with the default OpenBSD window manager, fvwm. The startx script is already configured to use it, so just type startx and press Enter to test out the settings. When you want to leave fvwm, you can press Ctrl-Alt-Backspace to kill the X session. If you see some X.org settings that need to be changed, or if X fails to start with the startx script, you can edit /etc/X11/xorg.conf and make any necessary changes.

Configuring X.org is a subject unto itself, so here are a few basic pointers:

  • If the scroll wheel does not work on your mouse, add this line to the mouse's InputDevice section:

    Option ZAxisMapping "4 5"

  • If you get no display at all, go to the Device section for the video card and change the Driver line from its current setting (it's probably something like ati, nv or fbdev) to vesaa generic setting that should work with any video card, but won't force you into a low resolution or color depth. Since OpenBSD can't do 3-D acceleration anyway, you've got nothing to lose.

  • If the color depth and/or screen resolution are not to your liking, you need to adjust the Screen section. Since the default configuration doesn't show you the options you need, here is a good example that you can copy and paste into your xorg.conf file (be sure to completely replace any existing Subsection "Screen" section):

    Section "Screen"
        Identifier "Screen0"
        Device "Card0"
        Monitor "Monitor0"
        SubSection "Display"
                Viewport 0 0
                Depth 24
                Modes "1280x1024" "1024x768" "800x600"
                Virtual 0 0
        EndSubSection
EndSection

    In the above sample configuration, Depth is color depth in bits (24 is the highest you can go), and Modes are the resolutions you want to be able to use. The first resolution is the default startup resolution; it is perfectly acceptable to list only one resolution here. Leave Virtual and Viewport alone; they set screen parameters that you usually don't need to touch.

At this point, you've configured X.org as much as you can without installing your preferred window manager or desktop environment.


Section 6.2. Installing a Desktop Environment or Window Manager

6.2. Installing a Desktop Environment or Window Manager

Now that you have X.org reasonably well configured, it's time to install the window manager or desktop environment that you prefer to work from. Here's where to find them:

  • KDE: /usr/ports/x11/kde

  • GNOME: /usr/ports/x11/gnome

  • Xfce: /usr/ports/x11/xfce4

  • Enlightenment (E16): /usr/ports/x11/enlightenment

  • Fluxbox: /usr/ports/x11/fluxbox

  • Blackbox: /usr/ports/x11/blackbox

  • IceWM: /usr/ports/x11/icewm

  • Windowmaker: /usr/ports/x11/windowmaker

If your window manager of preference isn't listed here, take a look through /usr/ports/x11 and see if you can find it there. There is currently no support for Enlightenment E17 through Ports, but it very well may compile from source.

There are many extras and add-ons for various desktop environments and window managers in the /usr/ports/x11 directory, so you should definitely take a look through it to make sure you've got everything you need.

Lastly, you can hack the Makefile for many of these packages if you want only certain components installed.


Section 6.3. Starting X.org

6.3. Starting X.org

The /usr/X11R6/bin/xinit script is the default method of starting the X server from a user account, though you can also use startx or the GNOME desktop manager (GDM) or KDE desktop manager (KDM) if you have either one of those desktop environments installed. Only the root user can run the gdm or kdm binaries from the command line, so unless you want to run this service as root (a security risk), you will have to either configure xinit to start KDE or GNOME, or set GDM or KDM to start as a boot service. Theoretically you could start your window manager of preference by adding it as a command-line argument to xinit, but realistically you'll probably just want to have one graphical environment.

The default X.org login manager is the old, traditional, and relatively boring XDM. There are two good things about XDM in OpenBSD: it is easily started as a boot service, and it is fairly easy to configure.

XDM is configured through the /usr/X11R6/lib/X11/xdm/xdm-config file, though that file draws on other config files in the same directory. By default, XDM starts the plain-old fvwm window manager, which most people will probably want to change. To do this, edit the /usr/X11R6/lib/X11/xdm/Xsession file and look for this line:

/usr/X11R6/bin/fvwm

Change this path and executable to the one for your window manager or desktop environment of choice. If you aren't sure what the executable is, just take a look through the /usr/X11R6/bin and /usr/local/bin directories. GNOME and KDE are tricky; you have to use these executables to start them outside of GDM and KDM:

/usr/local/bin/gnome-session
/usr/local/bin/startkde

To make OpenBSD start XDM by default (instead of going to the terminal login screen), edit /etc/rc.conf, and in the following line, change NO to empty double quotes "":

xdm_flags=NO         # for normal use: ""

If you want to use GDM or KDM instead of XDM, you have to go through /etc/rc.local instead of /etc/rc.conf. At the end of the rc.local file, insert one of these lines:

/usr/local/bin/gdm
/usr/local/bin/kdm

If you don't want to log in graphically and will be using X.org only part-time, it makes more sense to use the xinit script instead of a login manager. You could edit the /etc/X11/xinit/xinitrc script directly, but it would be better to copy it to the home directories of the users who need to use X.org and rename it ~/.xinitrc. This is the local user override for the global xinitrc. Edit it as you prefer, replacing the #Start some nice programs section with your own preferred applications (or just type the path and executable for your favorite window manager or desktop environment as explained above, and don't start any desktop applications by default).

To start xinit, just type xinit and press Enter. By default, X.org looks in the current user's home directory for a .xinitrc file, and if there isn't one, the default settings are used.


Section 6.4. Finding and Installing Desktop-Oriented Programs

6.4. Finding and Installing Desktop-Oriented Programs

This part is tricky because desktop programs are hidden all over the place in the OpenBSD Ports tree. You have to think about the programs you want and what categories they might fit into, and then browse the Ports tree and see if you can find them. Some of the more common programs and their locations are listed here:

  • OpenOffice.org: /usr/ports/editors/openoffice (OpenOffice.org is broken in OpenBSD 4.0, but it does work in the development branch, which a later section will show you how to convert to if you wish.)

  • AbiWord: /usr/ports/editors/abiword

  • LyX: /usr/ports/print/lyx

  • Vim: /usr/ports/editors/vim

  • Emacs: /usr/ports/editors/emacs21

  • XEmacs: /usr/ports/editors/xemacs21

  • Eclipse (you need to install a JDK first; see the section on Java for instructions): /usr/ports/devel/eclipse

  • Gnumeric: /usr/ports/math/gnumeric

  • Firefox: /usr/ports/www/mozilla-firefox

  • Opera: /usr/ports/www/opera (this is the GNU/Linux edition, so Linux binary compatibility is required)

  • Adobe Flash Player/Plugin: /usr/ports/www/opera-flashplugin (this is the GNU/Linux edition, so Linux binary compatibility is required)

  • Adobe Acrobat Reader/Plugin: /usr/ports/print/acroread (this is the GNU/Linux edition, so Linux binary compatibility is required)

  • Evolution: /usr/ports/mail/evolution

  • Bluefish: /usr/ports/www/bluefish

  • The GIMP: /usr/ports/graphics/gimp

  • Grip: /usr/ports/audio/grip

  • XMMS: /usr/ports/audio/xmms

  • AmaroK: /usr/ports/audio/amarok

  • Rhythmbox: /usr/ports/audio/rhythmbox

  • Audacity: /usr/ports/audio/audacity


Section 6.5. Font Configuration

6.5. Font Configuration

Now for the tricky part, achieving antialiased fonts. Most desktop operating systems have elaborate software frameworks and predefined configuration files so that you don't ever have to give any thought to the smoothness of your fonts, but OpenBSD makes you work for your reward.

The first thing you're going to need are more fonts, and as a general rule, the more proprietary they are, the better they will look. Specifically, you want fonts from Microsoft and Adobe, and they're in the following directories:

  • /usr/ports/x11/msttcorefonts

  • /usr/ports/print/ghostscript

It might be helpful to install these font packages as well, though they aren't necessary to achieve optimal font rendering quality:

  • /usr/ports/x11/freefonts

  • /usr/ports/x11/artwiz-aleczapka

If you have any additional fonts that you transferred from another operating system (font files are generally interchangeable between OSes), transfer them to the /usr/X11R6/lib/X11/fonts/misc directory (or create your own directory in /usr/X11R6/lib/X11/fonts for those files if you wish, but make sure you add it to the configuration file below).

Now you need to make sure that X.org is configured to use these new fonts. Edit the /etc/X11/xorg.conf from a root terminal, and then add the following lines to the "Section Files" section:

FontPath "/usr/local/lib/X11/fonts/freefont/"
FontPath "/usr/local/lib/X11/fonts/artwiz-aleczapka/"
FontPath "/usr/local/lib/X11/fonts/mscorefonts/"
FontPath "/usr/local/lib/X11/fonts/ghostscript/"

Save the file, but don't restart the X server just yet; there are a few more things that have to be done to fully enable antialiasing.

Now you have to tell Xft about those same font directories, so edit the /etc/X11/fs/config file and find the line that starts with catalogue =. Note that this file may be read-only by default. If it is, run this command prior to editing the file:

chmod +w /etc/X11/fs/config

Once inside the file, you should see some font directories there similar to (but not the same as) the ones listed above. Add your new font directories to the catalogue line, separated by commas. You should end up with something similar to this (new entries are shown in bold):

catalogue = /usr/X11R6/lib/X11/fonts/misc/,/usr/local/lib/X11/fonts/freefont/,
/usr/local/lib/X11/fonts/artwiz-aleczapka/,/usr/local/lib/X11/fonts/mscorefonts/,
/usr/local/lib/X11/fonts/ghostscript/,/usr/X11R6/lib/X11/fonts/TTF/,/usr/X11R6/lib/X1
1/fonts/Type1/,/usr/X11R6/lib/X11/fonts/CID/,/usr/X11R6/lib/X11/fonts/75dpi/,
/usr/X11R6/lib/X11/fonts/100dpi/

Next, use your preferred text editor to create the /etc/fonts/local.conf file and put this into it:

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "/etc/fonts/fonts.dtd">
<fontconfig>
    <dir>/usr/local/lib/X11/fonts/freefont/</dir>
    <dir>/usr/local/lib/X11/fonts/artwiz-aleczapka/</dir>
    <dir>/usr/local/lib/X11/fonts/mscorefonts/</dir>
    <dir>/usr/local/lib/X11/fonts/ghostscript/</dir>
</fontconfig>

The above configuration will register the new font directories with the fontconfig program. The "real" configuration file is /etc/fonts/fonts.conf, but it has an include statement for local.conf, so your changes will be properly recognized. In general it's a good idea to follow this practice (modifying local configuration files rather than the master ones) for as many system configuration files as you can with OpenBSD because the master files tend to be overwritten when you upgrade OpenBSD or certain subsystems.

Finally, you need to initialize all of your new font directories with fontconfig. To do so, first switch to each new directory:

cd /usr/local/lib/X11/fonts/freefont

Then run these commands:

mkfontscale && mkfontdir

Repeat the above for each font directory you installed:

/usr/local/lib/X11/fonts/artwiz-aleczapka
/usr/local/lib/X11/fonts/mscorefonts
/usr/local/lib/X11/fonts/ghostscript

Do you use any programs that require the Qt graphics toolkit (KDE depends on Qt)? If soor if you're not surerun this command from a terminal:

qtconfig

If nothing happens when you run that, then you don't have Qt installed and don't need to worry about changing settings. If the qtconfig window comes up, look over its settings and change them to your preferences. Of particular interest should be the Fonts and Appearances tabs. Make sure you select a default font that is antialiased (I suggest Times New Roman at a size of 12pt). In the GUI Style drop-down box in the Appearances tab, select either Platinum or Windows for smoother edges in your window elements. Go to the File menu and select Exit when you're done.

Do you use any programs that require the GTK+ graphics toolkit? If soor if you're not sureedit your user's ~/.profile configuration file and add this line to it:

export GDK_USE_XFT=1

Now it's time to kill the X server and then log out (type exit and press Enter to log out, or if you've started from XDM, GDM, or KDM, press Ctrl-Alt-Backspace to restart the X server). When you log back in again, you should have much more attractive fonts than before.

6.5.1. Troubleshooting

If you've followed the directions and your fonts still look jagged, run this command from a terminal:

/usr/X11R6/bin/xdpyinfo

If you don't see the word RENDER in the list of extensions, your video card driver doesn't support the technology necessary to render antialiased fonts. This should be a relatively rare situation.

If you see a little improvement in some applications but no change in others, you're likely experiencing configuration problems with GNOME, KDE, or the individual programs that you're using. The Opera Web browser, for instance, has its own font settings. GNOME and KDE both have font antialiasing settings for GTK- and Qt-based programs, respectively. Firefox also has its own antialiasing settings that you can adjust through the about:config page. Fine-tuning these programs is an issue specific to each of them individually, not to OpenBSD or its implementation of X.org.

Linux and FreeBSD binaries may need some special attention when it comes to fonts because they actually have their own X11 directories in /emul. This is generally a problem only for people upgrading from OpenBSD 3.9, who may have more than one version of their emulation environment.


Chapter 7. Server Installation and Service Configuration

OpenBSD comes with some services available through the base system, and many others available through Ports or packages. Special notes concerning each kind of server are detailed below. Remember that this guide is only here to familiarize you with these services as they apply to OpenBSD; actually configuring, running, and managing the services is well beyond the scope of this Short Cut.

It goes without saying that security is the primary focus of outward-facing servers. Even on OpenBSD, you will want to remove (or simply not install) unnecessary components, disable unused services, and disconnect unused devices.


Section 7.1. The inetd Internet Super-Server

7.1. The inetd Internet Super-Server

All Internet and local network services on OpenBSD can be started manually from the command line, or you can add a line to /etc/rc.local to start them at boot time. Some already have default entries in rc.conf, and others can have their own configuration lines in rc.conf.local. There is nothing inherently wrong with starting each daemon individually and letting it do its own thing quietly in the background. There could be a performance advantage to using the inetd Internet super-server, however. This program acts as a sort of router, monitoring incoming network requests and directing them to the proper services. Be careful that you don't try to use more than one method to start services at boot time, or else you could run into strange problems.

inetd is itself started through /etc/rc.conf, and it's configured through /etc/inetd.conf. Each inetd entry must be listed as a service in /etc/services and use a protocol listed in /etc/protocols. If your server is not doing well under heavy network loads, you may want to experiment with using inetd to start and manage some or all of your services.

For the most part, the rest of this guide will cover only the rc.conf and rc.local methods of starting services, as they are the easiest and probably most oft-used methods to start the servers outlined below.

That doesn't mean that you should totally ignore inetd, though. At the very least, you may want to look through /etc/inetd.conf to make sure that it isn't running any unnecessary services. If you're configuring OpenBSD as some kind of specialized network server, inetd is almost certainly running services that you can and should disable.


Section 7.2. Apache

7.2. Apache

Apache 1.3.29 is installed by default as part of the OpenBSD 4.0 base system and includes many extra patches to enhance its performance and security. Apache 2 cannot be included with OpenBSD because of some unacceptable terms in version 2 of the Apache software license. Because of this limitation, the OpenBSD Project has concentrated on doing more with Apache 1.3, to the point that it is almost a different web server in its own right. However, some people may have a specific need for Apache 2 because of the requirements of other software. Those people can download the Apache 2 source code from the Apache web site and compile it on OpenBSD without any extra concern.

The OpenBSD-modified Apache 1.3 comes with the following modules installed by default:

  • mod_cern_meta

  • mod_info

  • mod_rewrite

  • mod_auth_anon

  • mod_define

  • mod_log_agent

  • mod_speling

  • mod_auth_db

  • mod_digest

  • mod_log_referer

  • mod_unique_id

  • mod_auth_dbm

  • mod_expires

  • mod_mime_magic

  • mod_usertrack

  • mod_auth_digest

  • mod_headers

  • mod_mmap_static

  • mod_vhost_alias

  • mod_ssl

If you need to add more modules, you can do so through the Ports tree, generally in the /usr/ports/www directory.

You can start the Apache HTTP daemon manually by typing apachectl start and pressing Enter. If you'd like to start it at boot time automatically, edit the /etc/rc.conf file and replace the NO with "" in this line:

httpd_flags=NO       # for normal use: "" (or "-DSSL" after reading ssl(8))

Obviously if you need to use mod_ssl, you need to use the -DSSL flag inside the quotes. See the httpd manpage for more information on loading extra modules here. Specific Apache modules may have their own manpages as well.

By default, Apache runs in a chrooted environmentin other words, Apache operates as though nothing exists outside of the ServerRoot, which is by default /var/www. So if you have extra Apache modules installed that need to use programs or configuration files in any directory outside of /var/www and its subdirectories, then they will not be able to function properly. More details are available in the httpd manpage, but if you just need to get this working right now by eliminating the chroot jail, start Apache with the -u flag, either from the command line, or in the quotes in the previously mentioned Apache section of /etc/rc.conf. Circumventing the chroot jail will make your system less secure if Apache is compromised. For optimal security, the www user should not be able to write to any files or directories in ServerRoot.

The Apache 1.3 configuration files are kept not in /etc, but in /var/www/conf/. You should look over httpd.conf and adjust it for optimal performance on your computer. By default, the settings may be a little too limited for web sites that get thousands of visitors per day.


Section 7.3. Databases

7.3. Databases

No databases are installed by default in OpenBSD, but you can find MySQL, SQLite, and PostgreSQL in /usr/ports/databases along with several database-specific Perl modules and other extras and add-ons.

7.3.1. MySQL

Once installed, you can find the global MySQL configuration in /etc/my.cnf, but if you want to set server-specific configuration options, you can create an override my.cnf in /var/mysql. User-specific configurations can be stored in each user's home directory.

Be warned that the default my.cnf is designed for old, low-power, low-memory servers and does not scale well under moderately heavy loads. This is more or less the standard default configuration for MySQL, though, so if you've configured it before, you should already know what you're doing.

To make mysqld start automatically at boot time, add these lines (or something similar that fits your needs) to /etc/rc.conf.local:

if [ -x /usr/local/bin/mysqld_safe ]; then
    echo -n ' mysql'; /usr/local/bin/mysqld_safe &
fi

7.3.2. SQLite

There are two versions of SQLite available for OpenBSD: 2.8.17 and 3.3.6, and they can be installed from /usr/ports/sqlite and /usr/ports/sqlite3, respectively.

The sqlite or sqlite3 executable is located in /usr/local/bin, and there is no configuration file because SQLite is by definition "zero-configuration."

7.3.3. PostgreSQL

You can install the PostgreSQL client via Ports from /usr/ports/databases/postgresql, but if you want the server and documentation, you'll have to add them yourself:

pkg_add postgresql-server postgresql-docs

Automatically starting and stopping PostgreSQL is not quite as easy. Add these lines to /etc/rc.local to start it at boot time (that's one line between the if and the fi, not two, so be careful when you copy and paste this text):

if [ -x /usr/local/bin/pg_ctl ];
then su -l _postgresql -c "nohup /usr/local/bin/pg_ctl start -D /var/postgresql/data
-l /var/postgresql/logfile -o '-D
/var/postgresql/data'" echo -n ' postgresql'
fi

And to automatically shut it down cleanly when the system shuts down, add these lines (this time it's two lines between the if and the fi) to /etc/rc.shutdown:

if [ -f /var/postgresql/data/postmaster.pid ]; then
    su -l _postgresql -c "/usr/local/bin/pg_ctl stop -m fast -D /var/postgresql/data"
    rm -f /var/postgresql/data/postmaster.pid
fi

You can find the PostgreSQL configuration files in /var/postgresql/data/. By default, the system is not tuned to accept a large number of database connections, so you'll have to modify some kernel parameters if you're expecting a fair amount of database usage. Check out the documentation in the /usr/local/share/doc/postgresql directory for more details. Of particular interest is the README.OpenBSD file, which has the aforementioned advice on system tuning for PostgreSQL.


Section 7.4. Mail Transfer Agents

7.4. Mail Transfer Agents

OpenBSD has a security-audited version of Sendmail built into the base system, but it does support Postfix as well. The configuration procedures are detailed below.

7.4.1. Sendmail

This is the default MTA on OpenBSD; it's actually part of the base system, and thus has undergone extensive security auditing and includes OpenBSD-specific patches. In other words, it may differ technologically from Sendmail implementations on other operating systems, but in terms of functionality it should be largely the same as what you're used to elsewhere.

Unless you have a really good reason to use a different MTA, you should probably stick with Sendmail because of its integration with the operating system and the fact that it has OpenBSD's stellar reputation for security behind it. Sendmail is also the most thoroughly documented MTA for OpenBSD, so if you're new to Unix-like mail servers, it will probably be easier for you to set up and use Sendmail than any other MTA.

The Sendmail configuration files are in /etc/mail, but that's not where you should change them. If you want to generate configuration files (.cf files), you need to go to /usr/share/sendmail/cf and edit the .mc files that are appropriate to your situation. For most people, this should be openbsd-proto.mc, though to be sure that you do everything right the first time around, you should definitely read the sendmail manpage and maybe the relevant sections of the /usr/share/sendmail/README file as well.

If you wish to use TLS, see the starttls manpage for details, and make sure you uncomment the TLS-specific sections of openbsd-proto.mc before you create your .cf files.

Sendmail is ordinarily started through /etc/rc.conf and is not configured to accept incoming network traffic by default, so you'll have to change the sendmail_flags setting to whatever you need it to be to work with your network configuration (an example is given in a comment in rc.conf, and all relevant flags are explained in the sendmail manpage).

7.4.2. Postfix

Postfix can be installed from /usr/ports/mail/postfix, but you'll have to hack the Makefile first so that you can specify which authentication method you want: local (just plain Postfix), LDAP, SASL2, or MySQL. Regardless of which package you choose, the configuration files will be kept in /etc/postfix.

Next you need to replace OpenBSD's Sendmail implementation with Postfix's by running this command:

/usr/local/sbin/postfix-enable

(You can of course switch back to OpenBSD's Sendmail by running postfix-disable.)

Next you have to stop the cron job that runs sendmail every 30 minutes and change the daemon startup options:

  1. Edit the root account's cron table (you must be logged in as root):

    crontab -e

  2. Comment out or delete the line below this comment:

    # sendmail clientmqueue runner

  3. Save and exit the cron table; then edit /etc/rc.conf and change the sendmail_flags line to this:

    sendmail_flags="-bd -q30m"

  4. Since Postfix runs chrooted in the /var/spool/postfix directory, you may want to modify some of the files there, specifically in /var/spool/postfix/etc.


Section 7.5. Mail Delivery Agents

7.5. Mail Delivery Agents

The default MDA in OpenBSD is popa3d, but it's pretty limited, so some tips on installing and configuring the IMAP and POP3 portions of Courier and Cyrus are also below.

7.5.1. popa3d

This is OpenBSD's default POP3 MDA. You could read the popa3d manpage and then figure out a good command to put into /etc/rc.local to start it at boot time, but it's more easily initialized through inetd. Edit /etc/inetd.conf and uncomment this line:

#pop3 stream tcp nowait root /usr/sbin/popa3d popa3d

popa3d requires no configuration because it only fetches mail from local mailboxes, so you have to have a user account on the system with a non-null password. It's pretty simple, and should do perfectly for most servers that only need email for a small number of users. If you need IMAP, or if you need something a little more complex, you should probably use Courier-IMAP instead.

7.5.2. Courier-IMAP

Technically Courier is a complete MTA, but many people just use the MDA portion of it to deliver messages to local or virtual user accounts. In OpenBSD, only the MDA portion of Courier (Courier-IMAP) is available, and it's in /usr/ports/mail/courier-imap. Before you install it, make sure you check out the pkg directory and the Makefile to see what flavors are available. Specifically, you can build in support for LDAP, MySQL, PostgreSQL, and POP3.

At the end of the Courier-IMAP installation you'll be given a screenful of instructions. Basically they are:

  1. Make a configuration directory:

    mkdir /etc/courier-imap

  2. Copy over the default configuration files to it:

    cp /usr/local/share/examples/courier-imap/* /etc/courier-imap/

  3. Put this line in /etc/rc.local to start Courier-IMAP at boot time:

    mkdir -p /var/run/courier-imap && /usr/local/libexec/authlib/authdaemond start

  4. Edit your config files in /etc/courier-imap, then generate OpenSSL certificates with the mkimapdcert script.

7.5.3. Cyrus-IMAPd

There's a memory mapping incompatibility between Cyrus and OpenBSD, so if you use this MDA, you could have some performance problems under heavy loads. Courier-IMAP is a better choice for a full-featured MDA.

If you're committed to using Cyrus anyway, you can find it in /usr/ports/mail/cyrus-imapd. Make sure you check out the DESCR file in the pkg directory to see the warnings, recommendations, and the different flavors you can build.


Section 7.6. OpenLDAP

7.6. OpenLDAP

OpenLDAP is not included with OpenBSD by default, but you can install the client libraries and tools through the /usr/ports/databases/openldap directory. If you want to run an OpenLDAP server on OpenBSD, you need the -server package, which is not compiled by default in Ports. You can either hack the Makefile or use the pkg_add command to install the openldap-client and openldap-server packages.

Once installed, you can find the system-wide client configuration file in /etc/openldap/ldap.conf, or you can create a user-specific client configuration in ~/.ldaprc file (it doesn't exist; you have to create it).

Configuring an OpenLDAP server is just as easy: the config file is /etc/openldap/slapd.conf, and there are some sample schemas in /etc/openldap/schema.

To start the slapd and slurpd daemons automatically at boot time, add these two lines to /etc/rc.local (they should go before any LDAP-dependent services if you're running any):

/usr/local/libexec/slapd
/usr/local/libexec/slurpd

Of course, there are a few switches that can be run with these daemons, so if you need to do more than just this basic configuration, see the slapd and slurpd manpages. There is also more to configuring OpenLDAP, but such configuration has nothing to do specifically with OpenBSD. There are, however, many LDAP-specific manpages in OpenBSD 4.0:

  • ldap

  • ldap.conf

  • slapd

  • slapd.conf

  • slapd.access

  • slapacl

  • slapadd

  • slapauth

  • slapcat

  • slapdn

  • slapindex

  • slaptest

  • slappasswd

  • slurpd

  • ldappasswd

  • ldapmodify


Section 7.7. NFS

7.7. NFS

If you need to run an NFS server on OpenBSD, edit /etc/rc.conf and change the NO to a YES in these lines:

nfs_server=NO        # see sysctl.conf for nfs client configuration
portmap=NO           # Note: inetd(8) rpc services need portmap too

Then scroll down a bit and find this line:

nfsd_flags="-tun 4"  # Crank the 4 for a busy NFS fileserver

These default options should be fine for most people. The -tu flags mean that both TCP and UDP clients will be served, and the -n 4 flag sets the concurrent connections to four, so up to four clients will be able to connect at once. Set this to a higher number if necessary, but if you do, edit the /etc/sysctl.conf file and uncomment this line and change the 4 to the same number you just set in rc.conf:

#vfs.nfs.iothreads=4       # number of nfsio kernel threads

You'll also want to set your remote mount points in the /etc/exports file (see the exports manpage for details). There are two other NFS-related programs that you should know about: nfsstat, which monitors NFS statistics, and mount_nfs, which mounts NFS volumes.


Section 7.8. NIS

7.8. NIS

First of all, you do know that OpenLDAP is a more secure, scalable, and in general more modern alternative to NIS, right? If possible, you should use OpenLDAP over NIS. If it's not possible, no big dealOpenBSD has tools in the base system to handle NIS (or, more accurately, YP, which stands for either Yellow Pages or Yellow Pee, depending on whom you ask). YP is compatible with NIS, but not NIS+.

You can enable YP and set some options for it in /etc/rc.conf:

ypserv_flags=              # E.g. -1 for YP v1, -d for DNS etc
yppasswdd_flags=NO         # "-d /etc/yp" if passwd files are in /etc/yp

Enabling the yppasswd_flags means that you have to create an /etc/yp file. It's best to read the manpages for yp and ypinit to figure out what has to go into it. You also need to enable portmap in /etc/rc.conf by changing the NO to a YES in the following line:

portmap=NO           # Note: inetd(8) rpc services need portmap too

Now go to the /var/yp directory and make sure that the Makefile.yp file is configured properly for your situation. Next you need to create an /etc/defaultdomain file and put this machine's domain name in it. Then type this command, substituting the master domain name you just put into the /etc/defaultdomain file for domainname:

ypinit -m domainname

You'll then be asked a series of questions. Answer them in accordance with your configuration. When the process is complete, YP will be initialized and should start automatically at boot time.


Section 7.9. BIND

7.9. BIND

BIND version 9.3.2-P1 is part of the OpenBSD base system, so it's installed by default. You can find the generic configuration files in /var/named/etc (the only one that is used is named.conf, which is a clone of named-simple.conf), and your domain zone files go in /var/named/master and /var/named/slave. You might think that /var/named looks a little strange with its /etc and /dev directories and such; the reason for this silliness is that the name daemon runs in a chroot jail with /var/named as the root directory. So if BIND is compromised, the furthest an attacker can get is /var/named and all levels below it.

BIND is started through /etc/rc.conf, and the line you want to enable in specific is:

named_flags=NO             # for normal use: ""

Change the NO to "".


Section 7.10. CARP

7.10. CARP

CARP stands for Common Address Redundancy Protocol, and it's useful for failover protection for networked computers. Basically you create a CARP interface that routes traffic to a group of computers that all share the same IP address. Among those computers, there is one that handles all traffic by default. If that computer fails to properly announce its availability, CARP redirects its traffic to one or more machines. This means that you have to have at least two computers that are configured for the same services and/or contain identical data so that when the main machine fails or experiences too high a load, the backup machine can pick up where the main machine left off. CARP must therefore be configured on at least three machines: the gateway, the primary host, and the backup host. The primary host will advertise its availability at an interval that you specify; if the gateway and the backup host don't receive that advertisement within the allotted time, the backup host will take over until the primary host is available. If your primary host has multiple interfaces that connect to different networks, you can set up a CARP interface for all of them or some of themit's up to you, but the primary host must match its backup hosts if you want all network traffic to be rerouted to the backup server (or servers).

In the above explanation, the "gateway" machine is just a nickname; it does not have to be your Internet gateway, but since CARP is so frequently used for firewall failover protection, it makes sense in that context. The "gateway" machine could just as easily be a workstation or nearly any kind of server that depends on a persistent network connection to another computer.

Note that CARP doesn't sync your data or settings between machines. If one interface or machine goes down, all CARP does is pass the network connection on to the next available CARP interface (which is presumably but not necessarily on another computer) in the group. For this reason, CARP is frequently paired with pfsync to transfer firewall state, or rsync to transfer data to a failover machine.

Assuming you have only one network interface that needs failover protection, the first thing you need to do on the gateway, host, and backup systems is create a carp0 interface. You can easily do this via the ifconfig program from the command line, but it's better to automatically create the interface at boot time. To do that you need to create an /etc/hostname.carp0 file on the primary host and put this into it:

vhid 1 carpdev em0 pass yourpass 10.1.1.102 netmask 255.255.255.0

In the above example, the vhid parameter identifies the redundancy group. You can choose a number from 1 to 255, but 1 is easiest, especially if you have only one group of machines to protect. The carpdev parameter identifies the local network interface that needs failover protection. In essence you're providing failover for interfaces, which in turn provides failover for machines. In the example, em0 is the device node of the network interface; yours will almost certainly be different. The pass parameter defines a password, which is followed in in the example by yourpass. This is a password that must be in the configuration of every CARP-enabled machine in the group. 10.1.1.102 is the IP address that the primary and backup hosts will share. The netmask parameter defines the subnet mask of 255.255.255.0.

Each backup machine in the group must have a similar but slightly different CARP configuration:

vhid 1 carpdev rl0 pass yourpass 10.1.1.102 netmask 255.255.255.0 advskew 100

In this example, there are two differences. First, the carpdev variable is rl0 instead of em0 because the backup machine has a different network card that uses a different device node. If the two machines were physically identical, their interface nodes would match. Second, there is a new variable: advskew. This setting lags the backup machine's availability advertisement so that it is broadcast significantly less often than the primary host. This setting is what defines the primary and backup hosts; the machine with the lowest advskew is the one that gets the IP address.

There is one more step to take to ensure that the primary host is the preferred machine. Add this line to your /etc/sysctl.conf file:

net.inet.carp.preempt=1

This setting is also useful for machines that have multiple CARP interfaces, but that's getting a little too deep into theoretical CARP configuration. The above example is as basic a CARP scenario as I could think of, but your situation may very well require more customization, and there are a number of other settings that are not shown in the example here. See the CARP manpage for more details.


Section 7.11. Basic Packet Filter Setup

7.11. Basic Packet Filter Setup

The OpenBSD kernel has a built-in Packet Filter (PF) that can restrict network traffic from a given interface to a given interface, essentially turning the kernel into a firewall. PF is enabled by default, but IP forwarding is not, so if you're building a firewall machine, the first thing you need to do to use PF is to turn this feature on. Edit /etc/sysctl.conf and add this line:

net.inet.ip.forwarding=1

Then change the NO to a YES in this line in /etc/rc.conf:

pf=NO

PF is configured through the /etc/pf.conf file. The first section deals with macros, which are essentially variables that represent groups of interfaces or services. So if you were also using this machine as a router and wanted all outgoing interfaces to have the same rules, you would create a macro like this one:

internal_if = "{ em0, rl0, rl1, ixp0 }"

The four items in brackets represent network interface nodes.

You can create as many macros as are useful to you. You're not limited to interfaces, either; you can use IP addresses, IP ranges, and service names from the /etc/services file.

Next you're expected to write some filtering rules. The best place to get an idea for rules and rule syntax is to look in the "Filter Examples" section of the pf.conf manpage. Basically it goes something like this:

block/allow service from interface/network to internal

Where block blocks traffic and allow allows it; service refers to traffic coming in on a certain port; from interface/network specifies where the traffic is coming from; and to internal specifies the internal IP address, subnet mask, or interface that the traffic will be directed to (usually this is "any"). This is only a very basic explanation, and unfortunately there is no easy way to learn how to write PF rules (or rules for any other firewall with fine-grained control); you'll just have to move on the pf and pf.conf manpages from here.


Section 7.12. Enabling and Configuring OpenNTPD

7.12. Enabling and Configuring OpenNTPD

The OpenBSD network time protocol daemon (OpenNTPD) is a cleanly designed, secure NTP daemon that is included in the base system by default. You can enable it through /etc/rc.conf by changing the NO to empty double quotes "" in this line:

ntpd_flags=NO              # for normal use: ""

The configuration file is /etc/ntpd.conf, and all you really need to do in it is put some NTP server addresses in (the default setting is a pool of addresses, so you probably won't need to change it), and uncomment and configure the listen line if you want this machine to provide NTP service to your network. If you need a more advanced OpenNTPD configuration, see the ntpd.conf manpage.


Chapter 8. Installing the Languages of the Web

Compared to many other Unix-like operating systems, OpenBSD comes with very few development languages installed. Below are the processes for installing them and some of their most common add-on components.


Section 8.1. Java

8.1. Java

The Java Development Kit is tricky to install because Sun Microsystems places so much restriction on distribution of the necessary JDK files (though Sun has announced that this is due to change soon, so this process may be completely different in OpenBSD 4.1 when it comes out in May of 2007).

You can install the JDK from Ports, but you'll be asked to retrieve several files from the Web. In an effort to save you some time, the files for the JDK 1.5 (Java 5.0) are listed here (if you want to use 1.4.2 instead, just go to /usr/ports/devel/jdk/1.4/ and run make and follow the directions):

From this address:

http://wwws.sun.com/software/communitysource/j2se/java2/download.html

you need these files:

  • jdk-1_5_0-src-scsl.zip

  • jdk-1_5_0-src-scsl.zip

From this address:

http://www.eyesbeyond.com/freebsddom/java/jdk15.html

you need this file:

  • bsd-jdk15-patches-3.tar.bz2

From this address:

http://java.sun.com/products/archive/j2se/5.0/index.html

you need this file:

  • jdk-1_5_0-solaris-i586.tar.Z

And from this address:

http://www.apache.org/dist/xml/xalan-j/

you need this file:

  • xalan-j_2_7_0-bin.tar.gz

All of the above-listed files need to be placed in the /usr/ports/distfiles directory.

To install the JDK 1.5.0, go to /usr/ports/devel/jdk/1.5 and run this command:

make install clean

Or if you don't want a browser plug-in to be created, use the FLAVOR variable:

FLAVOR=no_web make install clean

Note that the AMD64 edition of OpenBSD does not yet support a Java browser plug-in.


Section 8.2. PHP

8.2. PHP

PHP versions 4 and 5 are both available through Ports in the /usr/ports/www/php4 and /usr/ports/www/php5 directories, respectively. The default settings are to make the PHP core and the mod_php Apache module, but none of the extra extensions, which can be seen in the /extensions/pkg directory within /usr/ports/www/php4 or /usr/ports/www/php5. Each extension has a DESCR- prefix in that directory; this is a text file that tells you about the package. Use the pkg_add command and replace the DESCR- with php4- or php5- to add an extension package, as in this example:

pkg_add php5-mysqli

Note that you will have to choose a PHP distribution: either the standard core or the hardened core. Edit the Makefile accordingly.

By default, no php.ini configuration file is generated for you. The directory you want to put it in is /var/www/conf (unless you've changed your web root), and the example files are in /usr/local/share/examples/php5 (or php4 if you installed that instead). So copy over /usr/local/share/examples/php5/php.ini-recommended or php.ini-dist to /var/www/conf/php.ini and edit it according to your preference. Keep in mind that the PHP defaults are not generally desirable in a production environment, so the -recommended configuration file is probably a better starting point than -dist for most people.


Section 8.3. Perl

8.3. Perl

Perl 5.8.8 is included as part of the OpenBSD base system, so there's nothing more you have to do to start using it. If you need to install extra Perl modules, you'll find them through Ports in various directories, but mostly in /usr/ports/devel/ and /usr/ports/printalways with a p5- prefix. Apache-specific Perl modules (including mod_perl) are in /usr/ports/www.


Section 8.4. Ruby

8.4. Ruby

Ruby can be installed through Ports in the /usr/ports/lang/ruby directory, with other Ruby-related software being in /usr/ports/devel and /usr/ports/www/ with a ruby- prefix. If you're looking for Ruby on Rails, you can find it in /usr/ports/www/ruby-rails.


Section 8.5. Python

8.5. Python

Python 2.3 and 2.4 are available through Ports in the /usr/ports/lang/python directory. Extra Python modules and other Python-related software can generally be found in the /usr/ports/devel directory with a py- prefix. Some Apache-specific Python software can be found in the /usr/ports/www directory.


Chapter 9. Automation and Reporting

Since "The OpenBSD Crash Course" is not a guide to the Unix/BSD/GNU command-line environment, the exact usage of the system logger and the cron daemon will not be covered here. The sections below cover how to use them on OpenBSD, but if you want a full explanation of what they are and what they do, you'll have to look up their manpages.


Section 9.1. The Cron Daemon

9.1. The Cron Daemon

OpenBSD's automatic script execution utility is Vixie-cron, and like most cron implementations on other Unix-like operating systems, OpenBSD's cron table can be edited with the crontab -e command. The default editor for this function is vi. If you run crontab right now as the root user, you'll notice that it's already got a page or so worth of entries. Most of these are necessary for regular OpenBSD maintenance, though you can certainly adjust them if needed. Each user has his own private cron table, but if you want to restrict this privilege to only certain users, you can do so with the /var/cron/cron.allow and/or the /var/cron/cron.deny config files. You may want to take a look around /var/cron to see some of the other files there as well.

OpenBSD's cron can perform commands or scripts in two time-interval formats: the traditional five-number time format (Mins Hours Days Months Day of the week) and simpler word formats:

  • @monthly

  • @weekly

  • @daily

  • @hourly

Hourly is at the top of the hour, daily tasks are performed at midnight, weekly is Sunday, and monthly is on the first of every month.

The OpenBSD standard cron scripts are /etc/daily, /etc/weekly, and /etc/monthly, all of which have default entries in root's crontab.


Section 9.2. Insecurity Reports

9.2. Insecurity Reports

At some point in the future, you may notice that the root account gets two daily email messages from the system. These are regulated by the /etc/daily script and run via cron early in the morning.

One email is the daily output report, and it tells you how much traffic your network devices handled and the state of your disk partitions and filesystems. It's helpful to keep an eye on these things to make sure that you don't run out of disk space and that there are no software problems (which can cause unusually high or low network bandwidth numbers).

The second email is the daily security audit, and it checks file permissions in the base system to make sure that files which should not be executable are not, and that configuration files that should not be world-readable are protected. Some files may actually show a diff of the changes in certain files like /etc/resolv.conf.


Section 9.3. Syslog

9.3. Syslog

There's nothing fancy about OpenBSD's system logger: it's the plain old syslog that you know and love. It outputs to /var/log/messages unless specifically split into separate files via the /etc/syslog.conf file. By default the system log output is distributed to several topic-specific files in /var. You may want to look this config file over to make sure it's reporting to your preferences.


Chapter 10. Keeping OpenBSD Up-to-Date

While OpenBSD may have had only one remote security hole in the default install in more than 10 years, the stats are a little different for nondefault installs. The more services you enable and the more programs you install, the more you have to worry about applying security patches. The below subsections will tell you how to keep your operating environment up-to-date with the latest security patches.

No matter what operating system you use, securing it is a process, not an event. Most of the below processes should be made into scripts and automated through cron, or manually performed on a regular (probably weekly or monthly) basis.


Section 10.1. Staying Up-to-Date with Ports and Packages

10.1. Staying Up-to-Date with Ports and Packages

If you followed the earlier directions for setting the PKG_PATH and FETCH_PACKAGES variables, all you have to do to update your packages is run this command:

pkg_add -ui

If you have programs compiled through Ports, you'll have to update the Ports tree in accordance with the -STABLE branch (also known as the "patch branch") to get updated security patches. With the sole exception of OpenSSH, new versions of programs are never made available through the patch branch; all you get are patches for security holes. If you want newer versions, you have to run -CURRENT (the active development branch of OpenBSD) or wait a few months for the next official release. If you run a -CURRENT Ports tree, you must run a -CURRENT source tree as well. The -CURRENT branch is meant for OpenBSD developers and people who like to work with rapidly changing and possibly experimental software; do not use it in a production environment.

Here's how to switch Ports from the -RELEASE to the -STABLE branch to keep everything secure and up-to-date:

  1. You start by updating the Ports infrastructure so that it includes post-release patches. To do this, you need to know an anonymous OpenBSD CVS server address. There is a complete and current list of OpenBSD 4.0 AnonCVS servers on this site: http://www.openbsd.org/anoncvs.html#CVSROOT.

  2. Make that CVS server the default for your system by editing the ~/.profile config file and adding this line somewhere (substitute your chosen AnonCVS mirror for the one in the example):

    export CVSROOT=anoncvs@anoncvs1.usa.openbsd.org:/cvs

  3. The above setting will not take effect until you log out and log back in, so make it valid for the current session by typing the same line above into a root terminal (again, substitute your chosen mirror):

    export CVSROOT=anoncvs@anoncvs1.usa.openbsd.org:/cvs

  4. Now you're ready to update the Ports tree. Change to its directory:

    cd /usr/ports

  5. Next, fetch the updated code:

    cvs -q up -r OPENBSD_4_0 -Pd

  6. Now recompile or refetch updated packages:

    make update

Once it's done compiling, your Ports tree will be up-to-date. You should probably also switch your base system to the patch branch as well. Go on to the next subsection to learn how to do that.

One last note: The preceding change to the ~/.profile configuration file will work only for the current user, which is assumed to be root. If you are using the su command to switch to root permissions from an unprivileged user account, you will have to make this change to that user's ~/.profile as well.


Section 10.2. Switching to the OpenBSD 4.0-STABLE Branch

10.2. Switching to the OpenBSD 4.0-STABLE Branch

Switching to the -STABLE edition of OpenBSD 4.0 means that you will have to recompile the base system from source code. This will take up a significant amount of space in /usr/src, and it will take anywhere from a half-hour to several hours to perform the recompile. In other words, this is not a trivial process, and on a production server should be scheduled for off-peak hours.

Let's get started:

  1. The first thing you have to do to switch to the patch branch is to download the updated source code for your system. If you do not currently have the OpenBSD source code installed in /usr/src, it will be easier to download the source tarball from an OpenBSD FTP mirror or disc 3 of the official CD set than it will be to download everything from the AnonCVS server. The file is called src.tar.gz, and you want to unpack it to the /usr/src directory. There are instructions for doing this earlier in "The OpenBSD Crash Course."

  2. Next you need to update the source code to include post-release patches. To do that, you need to know an anonymous OpenBSD CVS server address. There is a complete and current list of OpenBSD 4.0 AnonCVS servers on this site:

    http://www.openbsd.org/anoncvs.html#CVSROOT

  3. Make that CVS server the default for your system by editing the ~/.profile config file as instructed in the previous section.

  4. The above step will not take effect until you log out and log back in, so make it valid for the current session by typing in the same line above into a root terminal (again, substitute your chosen mirror):

    export CVSROOT=anoncvs@anoncvs1.usa.openbsd.org:/cvs

  5. Now you need to get into the proper directory:

    cd /usr

  6. Then you need to use CVS to fetch the -STABLE source code:

    cvs checkout -P -rOPENBSD_4_0 src

  7. Once the code is done downloading, it's time to compile it. You're going to start with the kernel, then reboot into the new kernel, then recompile the rest of the base system (sometimes referred to as the "userland") and then reboot one last time.

    Start with rebuilding the kernel. Change to the kernel configuration directory (replace i386 with amd64 if that's your architecture):

    cd /sys/arch/i386/conf

  8. Now run config on your kernel configuration file (replace GENERIC with your custom kernel config file if you have one):

    /usr/sbin/config GENERIC

  9. Next, change to the compile directory:

    cd ../compile/GENERIC

  10. Then build it:

    make clean && make depend && make && make install

  11. Once it's done, reboot the system:

    reboot

  12. Once you've restarted and logged in again, you need to remove the old /usr/obj directory's contents:

    rm -rf /usr/obj/*

  13. Now change to the /usr/src directory:

    cd /usr/src

  14. Remake the contents of /usr/obj with the new code:

    make obj

  15. Change to this directory:

    cd /usr/src/etc

  16. Now make some other ancillary files:

    env DESTDIR=/ make distrib-dirs

  17. Go back to the source directory:

    cd /usr/src

  18. Time for the build:

    make build && make install

All you have to do now is reboot the system, and your operating system will be fully up-to-date with the latest patches.


Section 10.3. Switching to OpenBSD-CURRENT

10.3. Switching to OpenBSD-CURRENT

To switch to -CURRENT (again, this is not recommended for production machines, and if you choose to do this, both the Ports tree and the OpenBSD base system source code must be brought up to -CURRENT):

  1. Choose an AnonCVS mirror and set the CVSROOT variable as instructed in the previous section.

  2. Now move into the proper directory:

    cd /usr

  3. Then fetch the -CURRENT source code for both the base system and Ports:

    cvs checkout -P src ports

  4. Once the code is done downloading, it's time to compile it. You're going to start with the kernel, then reboot into the new kernel, then recompile the userland and reboot one last time, and then recompile anything you installed from Ports.

    Start with rebuilding the kernel. Change to the kernel configuration directory (replace i386 with amd64 if that's your architecture):

    cd /sys/arch/i386/conf

  5. Now run config on your kernel configuration file (replace GENERIC with your custom kernel config file if you have one):

    /usr/sbin/config GENERIC

  6. Next change to the compile directory:

    cd ../compile/GENERIC

  7. Then build it:

    make clean && make depend && make && make install

  8. Once it's done, reboot the system:

    reboot

  9. Once you've restarted and logged in again, you need to remove the old /usr/obj directory's contents:

    rm -rf /usr/obj/*

  10. Now change to the /usr/srcdirectory:

    cd /usr/src

  11. Remake the contents of /usr/obj with the new code:

    make obj

  12. Change to this directory:

    cd /usr/src/etc

  13. Now make some other ancillary files:

    env DESTDIR=/ make distrib-dirs

  14. Go back to the source directory:

    cd /usr/src

  15. Time for the build:

    make build && make install

  16. Reboot one last time, and you'll be in a fully OpenBSD-CURRENT operating system:

    reboot

  17. You will now have to update the Ports tree. First, go to the Ports directory:

    cd /usr/ports

  18. Now rebuild and reinstall all updated packages:

    make update


Chapter 11. Where to Go for Help

The OpenBSD Project maintains many mailing lists, most of them for internal developer communication. Some of the lists are open to users, and you can get some assistance if you're having trouble. Be warned, though, that you're likely to earn ridicule from a mailing list if you fail to try to help yourself first. In other words, if you've tried the processes in this guide, read through the relevant manpages, and made an honest effort to get something to work, you've paid your dues. But remember that people will be more willing to help you if you're polite; common mistakes made by many new users include putting "urgent" in their requests for help, and getting short-tempered and impatient. Above all, never ask for a private email response to your query; the mailing lists are there to help everyone. If you show up on a mailing list asking some elementary question that you could have more easily answered by using the man command and act like the community is obligated to respond to your every beck and call, you're likely to be at best ignored and at worst mocked and taunted.

Remember to search the list archives for your question. In many cases, other people have had the same problem you have, and the OpenBSD community has already printed a solution. Frequently asked questions are not suffered gladly.

You can view or subscribe to the OpenBSD mailing lists at this address:

http://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long

As a more web-friendly alternative to mailing lists, there are the BSD Forums:

http://www.bsdforums.org

It's free to sign up for and use the BSD Forums, and the forum software is more user-friendly and more easily searched than the mailing lists are.

Lastly, the author of this guide maintains a general technology discussion and technical support forum:

http://www.tjrforum.com

You're welcome to post there as long as you remain polite. Registration is required, but offered at no charge. If you feel stupid for not knowing how to do something that should be obvious, the TJR Forum is probably the best place for you to go. If you need help with an advanced configuration, the BSD Forums are probably a better starting point.


Section 11.1. Commercial Support for OpenBSD

11.1. Commercial Support for OpenBSD

Dozens of consulting companies offer commercial support services for OpenBSDso many that it's not reasonable to list them all here. If you are going to run OpenBSD in a production environment and need to have an expert available over the phone 24/7, support contracts are available through the companies in this list:

http://www.openbsd.org/support.html


Section 11.2. Further Reading

11.2. Further Reading

If you want to learn more about OpenBSD, or need more intensive explanations of the various components of OpenBSD (beyond what the manpages tell you), there are a couple of definitive "dead tree" books out there that can help you:

  • Absolute OpenBSD by Michael W. Lucas (No Starch Press). This is a great, in-depth exploration of OpenBSD, but it's now three years (and six OpenBSD versions) out of date, so some information may be old.

  • Mastering FreeBSD and OpenBSD Security by Yanek Korff et al. (O'Reilly). This book is designed for system administrators who want to improve their OpenBSD server's security.