OpenBSD Handbook

“Linux people do what they do because they hate Microsoft. We do what we do because we love Unix.”

– Theo de Raadt

The OpenBSD Handbook is a practical reference for system administrators. It explains how to install, secure, and run OpenBSD 8.0 on servers, appliances, and workstations, with configuration examples and step-by-step procedures.

How OpenBSD Differs #

OpenBSD is a Unix-like operating system whose components are developed together. The project focuses on simplicity, correctness, and security.

  • Coherent base system. Kernel, userland, toolchain, and core daemons are developed together. Administrative interfaces such as rcctl(8) are consistent across services.
  • Security engineering. Proactive code audits, privilege separation, and exploit mitigations are standard practice. Application sandboxes pledge(2) and unveil(2) are part of the base system.
  • Practical defaults. The PF firewall is configured via pf.conf(5) . A minimal web server (httpd(8) ) uses httpd.conf(5) . Other base components include relayd(8) , smtpd(8) , bgpd(8) , and OpenSSH.
  • Documentation first. Manual pages are the primary reference; start with man(1) . Package management begins with pkg_add(1) .
  • Predictable releases. A new release appears roughly every six months. Binary patches are applied with syspatch(8) . Upgrades between releases can be automated with sysupgrade(8) .

Strengths and Trade-offs #

OpenBSD emphasizes code correctness, security, and a consistent base system. Hardware support varies; check the drivers for the intended machine before installation. Ports and packages provide third-party software.

How to Use This Handbook #

This handbook adds explanations, procedures, and cautions to the manual pages. Each section links to the relevant manuals and includes practical examples. Conventions:

  • Shell command blocks omit prompts and use explicit doas for privileged operations. Installer/root-shell contexts and terminal transcripts are labeled separately.
  • Command output and configuration fragments are shown exactly as entered or produced.
  • The first reference to a command, daemon, configuration file, or system call links to its manual page.

Start with the Introduction for the project background and main concepts.

Start Here #

Common tasks and entry points:

  • Frequently asked questions. Releases, installation, security, packages, networking, and software compatibility. -> /faq/
  • Install and bootstrap. Disk layout, networking, users, first login. -> /install/
  • Secure the base. Privilege model, doas, file permissions, cryptography, patching with syspatch, release upgrades with sysupgrade. -> /security/
  • Networking. Interfaces, autoconfiguration, bridging, VLANs, wireless, routing. -> /networking/
  • PF firewall. Policy design, NAT, redirection, tables, anchors, testing with pfctl (see pfctl(8) ). -> /pf/
  • Web and proxies. httpd, TLS, OCSP, reverse proxying, health checks with relayd(8) . -> /httpd/ ยท /relayd/
  • Mail transport. OpenSMTPD basics (see smtpd(8) ), local delivery, relaying. -> /mail/
  • Storage. Disks, partitions, softraid, encryption, filesystems, backups. -> /storage/
  • Virtualization. Native virtualization with vmd(8) and the vmm(4) device. -> /vmm/
  • Packages and ports. Searching, installing, version locks, building from ports with pkg_add(1) . -> /packages/
  • Upgrades and maintenance. Release planning, backups, post-upgrade checks. -> /upgrading/
  • Workstation topics. X Window System, graphics, audio, daily tools. -> /x11/

For deeper reference, consult the manuals: Manuals -> https://man.openbsdhandbook.com/

Scope and Audience #

The handbook is for administrators running OpenBSD servers, network appliances, and workstations. It covers common tasks, configuration choices, and troubleshooting.

Report a bug