OpenBSD Basics

Synopsis #

This chapter introduces fundamental concepts and administrative tools in OpenBSD. It explains how to manage users and groups, control file permissions, configure shell environments, manipulate processes, manage services, and handle installed software. The chapter also describes important conventions and outlines key security design principles unique to OpenBSD.

Command Examples #

Shell command blocks omit the $ and # prompt characters. Use the Copy button to copy a command block, or select individual lines. Replace example hostnames, paths, and other placeholders before running a command.

Commands that require administrative privileges use doas(1) . These examples assume that the account has permission to run the indicated command through doas; see Create an Administrator Account for initial setup. Blocks labeled Run in the root shell apply to an existing root session, such as an installer or recovery shell.

Example output appears separately from commands. Blocks labeled Example terminal transcript illustrate an interactive session and are not intended to be pasted into a shell. A # within a command block can still introduce a real shell comment, and $ within a command can introduce a variable or substitution.

User and Group Management #

User and group accounts in OpenBSD define access control boundaries for system resources and services.

Account Types #

Root (UID 0): The superuser account with unrestricted access.
Regular Users: Interactive accounts typically part of groups like users or staff.
System Accounts: Non-login accounts (e.g., _ntpd, _smtp) with restricted shells like /sbin/nologin, used by daemons and system services.

Creating Users #

To create a user interactively:

doas adduser

The adduser(8) script will prompt for login name, full name, shell, groups, and password.

To create a user non-interactively:

doas useradd -m -s /bin/ksh -G wheel alice
doas passwd alice

-m: Creates the home directory.
-s: Sets the shell (/bin/ksh is default).
-G: Adds the user to supplementary groups (e.g., wheel).

The `wheel` Group #

The following doas policy permits members of wheel to run privileged commands. doas can instead authorize named users or other groups; wheel membership is a policy choice. su has separate authentication and group rules.

Example /etc/doas.conf entry:

permit persist :wheel

With this rule, users in wheel may execute commands as root after authentication.

Inspecting User Information #

The following commands show user account data:

id
whoami
groups
getent passwd alice

id: Shows UID and GID info.
whoami: Displays the current username.
groups: Lists group memberships, including the primary group.
getent: Retrieves account details from the system database.

Modifying Users #

To add supplementary groups:

doas usermod -G wheel,staff alice

To change the primary group:

doas usermod -g staff alice

To edit user attributes interactively:

doas chpass alice

Removing Users #

To remove a user and delete their home directory:

doas userdel -r alice

File Permissions and Ownership #

OpenBSD uses traditional UNIX-style file permissions to define access control. Each file and directory has associated permissions for three categories of users:

Owner (user) — the file’s creator or designated owner
Group — users belonging to the file’s group
Others — all remaining users

Each category can have read (r), write (w), and execute (x) permissions.

Viewing Permissions #

Permissions can be viewed with ls -l:

ls -l /etc/passwd

Example output:

-rw-r--r--  1 root  wheel  1234 Jul 10 12:00 /etc/passwd

This indicates:

-: a regular file (directories show d)
rw-: the owner (root) can read and write
r--: the group (wheel) can read only
r--: others can read only

Understanding Numeric and Symbolic Permissions #

Each permission class (user, group, others) is represented by a digit between 0 and 7, based on the sum of:

4 = read (r)
2 = write (w)
1 = execute (x)

The following table shows all possible combinations:

Value	Symbolic	Meaning	Directory Listing
0	—	No permissions	—
1	–x	Execute only	–x
2	-w-	Write only	-w-
3	-wx	Write and execute	-wx
4	r–	Read only	r–
5	r-x	Read and execute	r-x
6	rw-	Read and write	rw-
7	rwx	Read, write, and execute	rwx

A full permission mode such as 755 breaks down as:

7 = rwx for the owner
5 = r-x for the group
5 = r-x for others

To apply it:

doas chmod 755 script.sh

Changing Permissions with Symbolic Mode #

Symbolic mode allows explicit changes to individual permission bits:

doas chmod u+x script.sh
doas chmod g-w file.txt
doas chmod o= file.txt

u, g, o, a: user, group, others, all
+, -, =: add, remove, set exactly
r, w, x: permission types

Use symbolic mode for fine-grained adjustments and numeric mode for explicitly setting all three categories.

Special Permission Bits #

In addition to the standard permission bits, OpenBSD supports three special modes:

Special Bit	Octal Prefix	Symbol (ls -l)	Meaning
setuid	4000	`s` in user execute	Executable runs with the owner’s UID
setgid	2000	`s` in group execute	Executable runs with the group’s GID
sticky bit	1000	`t` in others execute	File owner, directory owner, or root may delete files

setuid Example #

doas chmod 4755 /usr/local/bin/somescript

This sets:

4 (setuid) + 755 → 4755
Owner execute becomes s: -rwsr-xr-x

Use ls -l to see the s:

ls -l /usr/local/bin/somescript

setgid Example #

doas chmod 2755 /usr/local/bin/teamcmd

Group execute becomes s: -rwxr-sr-x

On OpenBSD, new files inherit the parent directory’s group without a setgid requirement. Group write access can be granted explicitly:

doas chmod 775 /var/shared

sticky Bit Example #

On shared directories like /tmp, the sticky bit prevents users from deleting each other’s files:

doas chmod 1777 /tmp

Files in /tmp can only be deleted by their owner, the directory owner, or root, even though the directory is world-writable.

The sticky bit appears as t:

ls -ld /tmp

drwxrwxrwt  10 root  wheel  5120 Jul 11 15:10 /tmp

To combine special bits with standard permissions, prefix the numeric mode accordingly:

chmod 4755 → setuid + 755
chmod 2755 → setgid + 755
chmod 1777 → sticky + 777

Use these bits with care: they affect security and process behavior.

Finding and Deleting Files #

The find(1) utility traverses a file hierarchy and evaluates an expression for each entry. Tests such as -type, -name, and -mtime restrict the set of matching paths. Actions such as -print and -delete operate only on paths that pass the preceding tests.

Previewing Matches #

Run the complete search expression with -print before deleting files. The following commands list regular files named *.core and regular files older than seven 24-hour periods:

find /var/tmp -type f -name '*.core' -print
find /var/tmp -type f -mtime +7 -print

The -x option prevents traversal into file systems mounted below the starting path:

find -x /var -type f -name '*.core' -print

Deleting Matches #

Replace -print with -delete only after the matches have been checked:

doas find /var/tmp -type f -name '*.core' -delete

Expression order is significant. Tests must appear before -delete; placing -delete first can remove entries that a later test would have excluded.

The -delete action implies depth-first traversal. Files and subdirectories are processed before their parent directory. It cannot be combined with symbolic-link following, and it removes a directory only when that directory is empty. The following command removes empty directories below a build directory while preserving the starting directory:

doas find /var/tmp/build -mindepth 1 -type d -empty -delete

When another program must process the matches, prefer -exec ... {} + or -print0 with a null-delimited consumer. Plain newline-delimited output is unsafe for pathnames that contain whitespace or shell metacharacters.

Shell Configuration #

The default shell in OpenBSD is ksh(1) (based on the Public Domain Korn Shell).

Shell Profiles #

User shell initialization files include:

~/.profile: Executed by login shells
~/.kshrc: Used for interactive ksh sessions (referenced in .profile)

A minimal .profile:

export ENV="$HOME/.kshrc"
export PATH="/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin"
umask 022

Process Management #

Processes can be listed, controlled, or monitored using standard utilities.

Viewing Processes #

ps aux
top

ps aux: Shows all running processes.
top: Provides an interactive, real-time view.

Controlling Processes #

kill -TERM 1234    # Gracefully stop process
kill -KILL 1234    # Forcefully terminate
pkill httpd        # Terminate by name

Service Management #

OpenBSD services are managed using rcctl(8).

Enabling and Starting Services #

doas rcctl enable ntpd
doas rcctl start ntpd

Disabling and Stopping Services #

doas rcctl stop ntpd
doas rcctl disable ntpd

Restarting and Configuring #

doas rcctl restart httpd
doas rcctl get httpd flags

To check a service’s status:

doas rcctl check ntpd

Installed Software and Version Info #

OpenBSD includes a minimal base system. Additional software is installed using pkg_add(1).

To view system version:

uname -a