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.