OpenBSD Handbook

    Theme
    • Part I. Install & Configure
      • Introduction to OpenBSD
      • Installing OpenBSD
      • The X Window System
      • Networking on OpenBSD
      • System Configuration
      • OpenBSD Basics
      • Managing Software: Packages and Ports
    • Part II. Daily Operations
      • OpenBSD Desktop Environments
      • Multimedia
      • Printing
      • Linux Compatibility
      • Windows Compatibility
      • Games
    • Part III. System Administration
      • Virtualization
      • Storage and File Systems
      • Updating and Upgrading
      • Localization
      • The OpenBSD Boot Process
      • Security
    • Part IV. Networking & Daemons
      • Services
        • Database
          • MariaDB
          • PostgreSQL
          • Redis
          • memcached
        • Directory
          • YP (NIS)
          • LDAP
        • File
          • NFS
          • Samba
        • FTP Services
          • ftpd
          • ProFTPD
          • vsftpd
          • Pure-FTPd
          • TFTP
        • Mail
          • OpenSMTPD Mail Server
          • Dovecot IMAP and POP3 Server
          • Postfix
          • Exim
          • Rspamd
        • Name
          • Unbound DNS Resolver
          • NSD Authoritative DNS Server
          • BIND DNS Server
        • Networking
          • OpenBGPD
          • rad
          • DHCP on OpenBSD
          • slaacd
        • Web
          • Apache HTTP Server
          • nginx Web Server
          • OpenBSD httpd Web Server
          • relayd Reverse Proxy
        • Logging
          • syslogd
        • Monitoring
          • SNMP
        • Remote Access
          • Audit OpenSSH
          • OpenSSH Server
        • File Synchronization
          • rsync
        • Messaging
          • RabbitMQ Message Broker
        • Time
          • NTP Time Synchronization
        • Load Balancing
          • Build Redundant Load-Balanced Gateways
          • Load Balance Services with NAT or DSR
          • Build an HA HTTPS Load Balancer
      • PF
        • pfctl cheat sheet
        • PF Anchors
        • PF Filter Rules
        • PF Forwarding
        • PF Lists and Macros
        • PF Load Balancing
        • PF Logging
        • PF NAT
        • PF Options
        • PF Policies
        • PF Shortcuts
        • PF Tables
      • Advanced Networking
        • High Availability and State Replication
        • Multi-WAN and Policy-Based Routing
        • VPN and Cryptographic Tunneling
        • Classic and Lightweight Tunnels
        • IPv6 at Scale
        • QoS and Traffic Shaping
        • MPLS and Label Distribution
        • Network Services at Scale
        • Virtualization and Host Networking
        • Large-Scale L2 and L3 Design
        • Telemetry, Logging, and Flow Export
        • Hardening and Operational Safety
        • Reference Architectures
        • Troubleshooting Playbooks
      • Serial Communication
    • Part V. Miscellaneous
      • Virtualization Cheat Sheet
      • OpenBSD Cheatsheet
      • How-to Guides
        • Installation and First Boot
          • Complete the First 30 Minutes After Installation
          • Check Hardware Compatibility Before Installing
          • Bootstrap Wi-Fi Firmware Without Ethernet
          • Run OpenBSD as a Virtual Machine Guest
          • Install OpenBSD on a VPS or Cloud Server
          • Install OpenBSD with Full-Disk Encryption
          • Run FreeBSD on OpenBSD with vmd
          • Dual-Boot OpenBSD on a UEFI System
          • Automate OpenBSD Installation with Autoinstall and PXE
        • Desktops and Laptops
          • Set Up OpenBSD as a Laptop or Workstation
          • Configure Laptop Power Management
          • Troubleshoot Web Browsers on OpenBSD
          • Use Plan 9 Tools on OpenBSD
          • Build a Minimal Desktop with suckless Tools
          • Install Z shell (zsh)
        • Networking and Remote Access
          • Create an Administrator Account with doas and SSH Keys
          • Configure Secure Remote Access with OpenSSH
          • Use FIDO Security Keys with OpenSSH
          • Configure Wi-Fi Roaming and Wired Failover
          • Troubleshoot PF, NAT, and Routing
          • Route Multiple VLANs with PF
          • Configure a Road-Warrior WireGuard VPN
          • Route IPv6 Networks without NAT
          • Test OpenBGPD with Two Providers
          • Unlock an Internal Service with an SSH Key
          • Build a Simple Router and Firewall
        • Servers and Services
          • Set Up WordPress on OpenBSD
          • Build a Mail Server with OpenSMTPD, Dovecot, and Rspamd
        • Security, Maintenance and Recovery
          • Establish a Conservative Security Baseline
          • Recover Access and Reset the Root Password
          • Collect OpenBSD Diagnostic Evidence
          • Troubleshoot Package Installation and Update Failures
          • Schedule Recurring Maintenance
          • Monitor an OpenBSD System
          • Back Up and Restore an OpenBSD System
          • Configure softraid RAID1
          • Recover an OpenBSD System That Does Not Boot
        • Building, Automation and Virtual Machines
          • Manage OpenBSD with Ansible
          • Build Third-Party Software from Ports
          • Build OpenBSD from Source
          • Plan a Docker Workload Migration to OpenBSD
      • OpenBSD for Linux Users
      • OpenBSD for FreeBSD Users
      • OpenBSD for macOS Users
    • OpenBSD FAQ
    • OpenBSD Handbook Style Guide
    • OpenBSD Architectures
      • OpenBSD Package Search
        • Synopsis
        • Writing a chapter
        • Names and manual pages
        • Command examples
          • Privileges and changes of context
          • Commands and output
          • Configuration files and terminal transcripts
        • Writing across editions

        OpenBSD Handbook Style Guide

        Synopsis #

        The Handbook assumes familiarity with a Unix shell. Explain the OpenBSD detail that matters to the task. For example, an administrator may know how to start a service and still need to know whether it will start again after a reboot.

        To interpret a command block, see Command examples . The same conventions apply when writing a new procedure.

        Writing a chapter #

        Give the chapter a title that names the task or subject. Open with a short synopsis that says what the reader can accomplish and what the procedure assumes. If a step requires a particular release, a package, a second host, or console access, say so before the reader needs it.

        Use direct verbs and formal American English. A heading such as “Check the web server configuration” tells the reader what the step does. Give each action its own instruction when the distinction matters. For example, “enable at boot” and “start now” describe two different operations in rcctl(8) . Spell out an unfamiliar abbreviation at first use, such as network address translation (NAT).

        Put a warning immediately before the action that carries the risk. For a disk operation, identify which disk will be overwritten and how to confirm its identity. End a procedure with an observable check. If the goal is to serve a page, request that page from a client. Checking the configuration alone answers a different question.

        Names and manual pages #

        Use inline code for commands (httpd), options (-n), and paths (/etc/httpd.conf). In prose, link the first relevant mention to the OpenBSD manual and include its section number. For example, httpd(8) describes how to run the server, while httpd.conf(5) describes what belongs in its configuration file. To open the latter on an installed system, run man 5 httpd.conf.

        Check options and defaults against the manual for the OpenBSD release covered by the chapter. When comparing systems, identify which system a command runs on. A familiar command name can take different options on OpenBSD, FreeBSD, or Linux.

        Command examples #

        A shell block contains the lines to enter. The leading $ or # prompt is omitted. Use the Copy code button to copy the whole block, or select individual lines. Keep characters that belong to the command. The $ in "$HOME" expands a variable, $(...) substitutes command output, and a # can introduce a shell comment. At the start of an executable script, #!/bin/sh selects the interpreter.

        Identify values the reader must supply. For example, if a procedure uses iwm0, explain how to find the wireless interface on the reader’s machine. Do the same for sample hostnames, paths, user names, and disk names wherever a literal copy would act on the wrong object.

        Privileges and changes of context #

        Show ordinary commands as an unprivileged user. Use doas(1) when a command needs administrative privileges. The account must have permission to run that command. See Create an Administrator Account for initial setup.

        On a host with /etc/httpd.conf configured, this command checks the file without starting the web server.

        doas httpd -n
        

        Use Run in the root shell for a block that assumes an existing root session, such as an installer or recovery shell. Check which process needs the privilege. In a command containing >, the calling shell opens the destination file, even when the command before it runs under doas.

        Start a new block whenever the reader must reboot, log back in, change hosts, or inspect a result before continuing. During a release upgrade, show the base-system upgrade in one block. Tell the reader to wait for the new release to boot and complete the release-specific steps before presenting the package update. See Updating and Upgrading for the sequence.

        Commands and output #

        Introduce the command, then put its result in a separate block labeled Example output. For example, uname(1) can print the operating system name.

        uname -s
        

        Example output

        OpenBSD
        

        Use a shell block (sh) for commands and a plain-text block (text) for output. The copy button belongs on the command. When a result varies by host, identify the field or message worth checking.

        Configuration files and terminal transcripts #

        Name the file before showing its contents. For example, the following line belongs in /etc/myname, the hostname file described in myname(5) . Replace the example hostname with the host’s own fully qualified name.

        router1.example.org
        

        Use Example terminal transcript and a console block when prompts, input, and responses need to be read together. In this established sftp(1) session, pwd asks for the remote directory. The program prints the next line. Enter quit at the next sftp> prompt to leave the session. Copying the entire transcript into a shell would also paste the prompts and the program’s response.

        Example terminal transcript

        sftp> pwd
        Remote working directory: /home/alice
        sftp> quit
        

        Writing across editions #

        Translate explanations, headings, captions, and explanatory comments. Preserve commands, options, configuration directives, literal answers, and terminal output so readers can match them to the screen. Put a translation of an unfamiliar message beside the transcript.

        Use international technical Spanish in the Spanish edition. For example, use compruebe in an instruction, root for the account, and raíz for the root of a filesystem. Link to the chapter in the reader’s language when a translation exists. Give corresponding headings the same section ID. A link ending in #command-examples then leads to the command conventions in either language.

        Report a bug
        • Synopsis
        • Writing a chapter
        • Names and manual pages
        • Command examples
          • Privileges and changes of context
          • Commands and output
          • Configuration files and terminal transcripts
        • Writing across editions