Set Up OpenBSD as a Laptop or Workstation

Synopsis #

An OpenBSD workstation uses the base system, the Xenocara X Window System, firmware, and packages for the required applications. This guide covers setup in order, with links to the detailed installation, graphics, networking, multimedia, maintenance, and backup chapters.

Hardware support varies by exact device and release. Complete Check Hardware Compatibility Before Installing before depending on a laptop’s wireless interface, graphics, suspend and resume, or external displays.

Install the Complete Base Sets #

For a general workstation, install all release sets, including the Xenocara sets. The official installation guidance recommends all sets for new users. Applications that do not display windows may still depend on libraries or fonts from the X sets.

If X sets were omitted, boot the installed bsd.rd, choose (U)pgrade, and select the missing sets. Do not copy individual libraries from release archives into a running system.

Follow Complete the First 30 Minutes After Installation before adding a desktop environment. This establishes current firmware, errata, packages, administrative access, and a known-good reboot.

Confirm Graphics and Input #

The base system includes the X server and window managers. OpenBSD currently starts fvwm(1) when no alternative X session is configured. The locally developed cwm(1) window manager is also included in the base system.

The recommended way to start X is the base xenodm(1) display manager. Configure the intended user session, enable xenodm, and keep a text console available during the first test.

Confirm keyboard, pointing devices, native resolution, and every required display output. The X Window System chapter contains detailed session configuration and troubleshooting.

Select One Session Path #

Use either a base window manager or one packaged desktop environment as the initial configuration. Installing several full desktop environments at once makes session and service failures harder to isolate.

Search available packages with pkg_info(1) and install the selected package with pkg_add(1) . Package names and required services can change between releases, so consult the package README installed under /usr/local/share/doc/pkg-readmes/ before enabling services or editing login classes.

pkg_info -Q xfce
doas pkg_add xfce
less /usr/local/share/doc/pkg-readmes/xfce

Use the package name and README path reported for the installed release. The graphical environments chapter documents the supported session choices in more detail.

Configure a Graphical Login Only After Testing #

Enable xenodm after selecting and configuring the intended session.

doas rcctl enable xenodm
doas rcctl start xenodm

Keep a text console available while testing. A failed session normally returns to the display manager; switching to a virtual terminal permits inspection of ~/.xsession-errors and system logs.

Configure Networking #

For a single wireless network, store the join and address-configuration lines in the interface’s /etc/hostname.if file. For several known networks, add multiple join lines as an auto-join credential list. Candidate selection considers security and signal quality rather than line order. Protect files that contain WPA keys.

Use the networking chapter for interface configuration and the wireless firmware guide when the adapter cannot be used before firmware installation. Verify the full path, not only association:

ifconfig
route -n show
host openbsd.org

Verify Audio and Media Devices #

Test base audio before installing a large media stack. sndioctl(1) displays and changes audio controls, while audioctl(8) reports device parameters.

sndioctl
audioctl

OpenBSD applies privacy controls to audio recording and video devices. Grant access only to applications and users that require it. Configure Multimedia on OpenBSD describes audio, microphone, webcam, and recording configuration, while Troubleshoot Web Browsers isolates profile, sandbox, graphics, and conferencing failures.

Evaluate Power Management #

Use apm(8) to inspect battery and AC state where supported.

apm

Test suspend and resume repeatedly before relying on the machine for unsaved work. Include the following conditions in the test:

  • battery and AC power;
  • lid close and explicit suspend;
  • wireless reconnection;
  • audio after resume;
  • each required external display;
  • encrypted storage, if used.

Hardware that boots successfully can still have incomplete suspend, backlight, or display support. Configure Laptop Power Management provides the complete apmd, suspend, lid-action, verification, and recovery workflow. Preserve a complete dmesg from both a clean boot and a resumed session when reporting a failure.

Add Applications Conservatively #

Install applications in small groups and read each relevant package README. Avoid raising login-class limits or changing kernel parameters merely because a guide for another operating system recommends it. Apply a limit change only when the OpenBSD package README or a reproducible failure establishes the requirement.

Use pkg_add(1) to keep packages current:

doas pkg_add -u

Base-system errata and release upgrades remain separate operations, described in the updating and upgrading chapter .

Apply Establish a Conservative Security Baseline after the required workstation services and applications are known. Check service dependencies before disabling daemons or adding permissions to solve an application problem.

Establish Backups Before Daily Use #

Back up user data and locally maintained configuration before the workstation becomes the only copy. A useful plan includes:

  • /home and other user-data filesystems;
  • locally changed files under /etc;
  • package and service configuration under /usr/local and /etc;
  • browser profiles and authentication material, subject to encryption and access controls;
  • an independently stored record of disk encryption and recovery requirements.

Test restoration of selected files. A backup that has never been read is not a verified recovery method. The storage chapter covers OpenBSD backup tools and storage layouts.

Report a bug