Sofware in Review
Tech news
Software reviews
Hardware reviews
Discuss technology
Sofware in Review → Linux/BSD hacking → BSD tutorials →

Using OpenBSD 3.9

By Jem Matzan

Many people responded to the call for OpenBSD and OpenSSH donations by purchasing an OpenBSD CD set. Those CDs are beginning to arrive in the mail, and when they do, how are you going to use them? If you're a software enthusiast who has never used OpenBSD before, you might enjoy installing it by yourself and figuring it out as you go. If, however, you're looking for a more practical approach to using OpenBSD as a desktop or server operating system, here's a guide to get you started.

Are you looking for information on OpenBSD 4.0 or later? Try this article instead.

Secure by default

First of all, you should familiarize yourself with the concept of secure by default. A simple way of explaining it is, everything is turned off until you turn it on. That means that the Web server is not going to start until you manually add httpd to the 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 and Unix-like operating systems, but you'll spend a lot less time securing it -- maybe no time at all, if you follow the instructions in the manual pages.

Quick OpenBSD facts

  • Default shell: Korn shell (ksh) for root; Bourne shell (sh) for users; the C shell (csh) is also included by default.
  • Default editor: vi
  • File system: BSD Fast File System (FFS) with soft updates (no journalling necessary)
  • Kernel: 4.4BSD-based, monolithic, SMP-capable, does not support external kernel modules by default
  • Binary support: OpenBSD, FreeBSD, SCO/ISC, SVR4, Linux, BSD/OS
  • Supported architectures: Alpha, AMD64/EM64T, cats, hp300, hppa, i386, luna88k, mac68k, macppc, mvme68k, mvme88k, sgi, sparc, sparc64, vax, zaurus
  • Hardware support (i386)

Making it easier to mount CD drives

First you need a mount point for your CD or DVD drive. I recommend /mnt/cdrom (create it with mkdir /mnt/cdrom), but you can do whatever you want -- just remember what it is so you can mount the CD drive on it later, and modify the below instructions accordingly.

OpenBSD's default /etc/fstab file does not have a line for CD/DVD drives. Most people's optical drive will use the /dev/cd0a device node, though there are a few others. Type ls /dev/cd* to see all of the possibilities. You may want to test mount them with a CD in the drive if you are unsure which node is the right one.

Once you have a directory to mount to and you know which device node corresponds with your optical drive, it's time to add a line to /etc/fstab:

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

Setting up Ports and packages

OpenBSD doesn't include much software in the default system, so you'll probably have to add most of the programs that you need. There are two ways to add software to OpenBSD: through the Ports tree, and through precompiled binary packages. Neither is necessarily better than the other, but here are some basic observations about both systems that will help you decide which approach to take:

  • Ports compiles each program from source code, which allows you to modify the Makefile to accommodate specific needs; packages are already compiled with the default options.
  • Packages are installed moments after they are downloaded; Ports can take a long time to compile.
  • Packages are easier to upgrade when it comes time to switch to the next OpenBSD release; Ports are trickier to upgrade, and will take much longer to reinstall.
  • There are about 200 more programs in Ports than there are in the package repository. Many of these extra programs are proprietary (the Java Development Kit, for instance).
  • It's easier to find programs in Ports than it is the package database, especially when you're offline. You can, however, use the Ports tree to find a program you want to install, then use pkg_add to install the package.

My recommendation is to install the Ports tree (see below for instructions), but use packages whenever possible. The two may be used in conjunction with each other (see below), but if you do not install the Ports tree you will have to know the exact package names, as OpenBSD package tools do not use any kind of name resolution. That means you can't just type pkg_add gnome and have GNOME installed. You have to know the exact package name, which has its version number and patch level appended to it. Since you probably don't know exactly what version and revision of GNOME is available for the current release of OpenBSD, you'll have to use your OpenBSD CD to browse the package list. Alternatively you can connect to the OpenBSD FTP server and search through the same list online.

Mount your OpenBSD CD and then switch to its directory so that you can browse it. Assuming you mounted it on /mnt/cdrom, the i386 package directory is in /mnt/cdrom/3.9/packages/i386/ (assuming you're installing packages in OpenBSD 3.9 -- if not, change the version number in the path). Use the ls command to look through the directory and find programs that you want to install.

Next you'll need to tell your package installer where to look for package files. By default it takes a command line argument, so you have to specify an address and file name for every package you want to install plus all of its dependencies. Obviously that is not a very efficient way to do things, so let's add a default path for the pkg_add command to look in.

Initially you may want to use the OpenBSD CD because it's quick, available, and doesn't require an Internet connection. It doesn't have all of the OpenBSD packages on it, though -- just the ones there was space for. If you want access to more packages, you'll need to use the FTP site (detailed below). To add the CD as the default package location, use vi to open /root/.profile and then add these two lines at the bottom:

export PKG_PATH=/mnt/cdrom/3.9/packages/i386/

The "3.9" and "i386" will change depending on the release of OpenBSD you're using and the architecture of your computer. If you're installing OpenBSD 3.8 or 4.0 on an AMD64 or VAX machine, change the directories accordingly. Before you install any packages, make sure the correct CD is in and mounted.

If you want to install packages at a later time and don't want to lug around your OpenBSD CDs, or if you didn't find the programs you want on the CD, you can use an FTP package mirror instead. First find a mirror in this list that is closest to your location. Then add it to /root/.profile as shown above:

export PKG_PATH=

The mirror site above is only an example -- use one from the list I linked to above.

Log out for the changes to take effect. The next time you log in, pkg_add will automatically retrieve any packages you tell it to, plus their dependencies. If you try to install a program from Ports, OpenBSD will check to see if there is a package available first; if so, it downloads that instead (to remove this feature, comment out the FETCH_PACKAGES line in your profile). Here's an example:

pkg_add -v gnome-desktop-2.10.1.tgz

The -v flag makes the output more verbose; it is not required. In the above example, GNOME and all of its dependencies will then be downloaded and installed on OpenBSD 3.8.

After you've added a package source, whenever you try to install a program from Ports, OpenBSD will automatically try to retrieve the package first. So even though there is no name resolution for packages, Ports can act in that regard.

Adding the Ports tree and OpenBSD source code

OpenBSD does not install the Ports tree or the operating system source code by default. To install them yourself, just copy them over from CD #3 or download the source files from the OpenBSD FTP site. You can find them in the /pub/OpenBSD/3.8/ directory (substitute 3.8 for your release version). The files are called src.tar.gz and ports.tar.gz.

Unzip and untar the src.tar.gz file to the /usr/src/ directory, and the ports.tar.gz file to the /usr directory (it will unpack to a new /usr/ports/ directory). That's basically all there is to it.

Java support

Installing a Java Development Kit on OpenBSD is more difficult than on most other OSes. On the other hand, most other OSes don't really care about licensing to the degree that OpenBSD does. Since proprietary packages cannot be included with OpenBSD, you'll have to use the Ports tree to install the JDK. There is currently no option to install a standalone Java Runtime Environment without the development kit.

To install a JDK (and by association, a Java Runtime Environment as well), first you're going to have to manually retrieve the JDK binaries, source code, and BSD patch sets from a few Web sites, then you're going to have to compile them from source. It takes a long time, so I suggest fetching the files all at once, then letting OpenBSD work on compiling them overnight. This process also requires a lot of free space in /tmp and /usr, so make sure you've got some room to work with. The amount of free space necessary depends on which JRE or JDK version you are installing. At minimum, a few hundred megabytes; at maximum, maybe more than 1GB. The reason why you need so much disk space and compile time is, Java must bootstrap from a previous version. That means that JDK 1.5 bootstraps from 1.4, which bootstraps from 1.3. So you're downloading files for and compiling three JDKs. That is, unfortunately, the price you pay for using Java on OpenBSD.

The file names, versions, and addresses will change with every release. A sure-fire way to find out what files require manual fetching is to go to /usr/ports/devel/jdk/1.5 (assuming you want Java 5.0 -- versions 1.3 and 1.4 are also available) and type in make. Any initial dependencies will be fetched and compiled, and when it reaches a point where your intervention is required, the exact names and Web addresses of the files you need to retrieve will be printed on the screen. Go to the addresses, download the files, and save them to /usr/ports/distfiles/, then continue the build. If you miss a file or two, the build process will tell you which files you're missing.

As an example, here are the file names and addresses for JDK 1.5 on OpenBSD 3.9:

Lastly, you will have to add the Java executable path to your shell configuration file. Assuming you are using the default Bourne (sh) or Korn shells (ksh), the file to edit is ~/.profile. If you're using the C shell (csh), the file is ~/.cshrc. Bash is ~/.bashrc, and the Z shell (zsh) is ~/.zshrc. Somewhere in one of these files you will find a PATH environment variable. Add /usr/local/jdk-1.5.0/bin to it (or whatever Java version you installed). Some programs may require a JAVA_HOME setting as well:

export JAVA_HOME=/usr/local/jdk-1.5.0/

Log out for the changes to take effect. Remember to go to the /usr/ports/devel/jdk/1.3 and 1.4 directories and run make deinstall clean to remove the older JDKs and build files that you bootstrapped from.

Enabling FreeBSD and Linux binary support

OpenBSD comes with a variety of binary compatibilities compiled into the kernel. They are, however, disabled by default. To enable them, edit /etc/sysctl.conf and skip down to the end of the file where the binary emulation section is. Uncomment any lines that you need support for. Most people will want Linux binary support:


FreeBSD binary support is in the same section. Again, just uncomment it to enable it. Feel free to look through the rest of the file to see if there are any other options you might be interested in (I usually enable wsmouse, which is the console mouse driver).

To achieve optimum Linux binary compatibility, you will also need to install the redhat_base package, then create a /proc directory and a line in /etc/fstab to mount it at boot:

/proc  /proc  procfs  rw,linux  0 0

Recompiling the kernel

I'll start this section by saying that you probably won't ever need to do this. Even if you often find yourself messing with Linux or FreeBSD kernel options, you're likely to never need to mess with OpenBSD's -- pretty much everything is compiled in by default. Some say that the fewer kernel options you have (in other words, taking out what you don't need), the better the kernel performs (or at very least, the smaller it is), but I haven't done any performance testing to verify that.

The kernel configuration files are in /sys/arch/i386/conf (substitute i386 for your architecture if it is different). The standard kernel config is in the GENERIC file. If you want to compile a custom kernel, I recommend creating a separate file based on GENERIC rather than screw around with the original. Traditionally a custom config file is called MYKERNEL -- so just copy GENERIC to MYKERNEL and edit from there. The SMP kernel options are in GENERIC.MP. If you're on an SMP machine, don't bother editing the file -- it only contains a few SMP-specific options that override GENERIC -- just skip to the next step.

Once you've got your configuration the way you want it, run the config program on it:

/usr/sbin/config MYKERNEL

If errors are detected, fix them and re-run config. If no errors are detected, switch to the directory that config created:

cd ../compile/MYKERNEL

Then compile the kernel:

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

SMP support for multi-core, multi-CPU, and Hyper-Threaded machines

If you're on a multi-core or multi-CPU system and want to use the SMP kernel, you do not need to recompile anything to get SMP support. While OpenBSD uses the single-CPU kernel by default, you have the option of installing the kernel during the installation process. If you choose that option, will be in your / directory.

Before you switch to, test it out by typing it in at the boot prompt when the system starts (before OpenBSD starts its init process). If all goes well, just switch to your root directory and move to bsd:

mv bsd

Further information

OpenBSD has the most thorough, easy to follow documentation of any operating system I've ever used. Just use the man command to look up nearly anything that is included with the base system or installed packages. If you're new to OpenBSD, type man afterboot to get some tips and instructions for setting up and configuring various services and devices.

If you're still stuck after reading the documentation, a great source for online BSD help is the OpenBSD section of the BSD Forums Web site.