NomadBSD Handbooklet


  1. Intro
  2. Installation
    1. Choosing a USB flash drive
    2. Downloading and writing the image
  3. The NomadBSD setup
  4. Overview
  5. Key bindings
    1. Global keybindings
    2. Terminal keybindings
  6. Enable/Disable desktop components, and auto-start programs
  7. Adding applications to the plank panel
  8. Display manager settings: Auto login, default user, and theme
  9. Adding a preconfigured user account
  10. Filesystem
    1. Automount
    2. Extending filesystem support
      1. exFat
      2. BTRFS, ReiserFS, XFS
  11. Networking
    1. Wireless Networking
  12. Graphics
    1. Multihead setup
    2. Changing display settings
  13. Sound
    1. Selecting the default audio device
  14. Advanced Topics
    1. Resetting NomadBSD
      1. Limitations
    2. Disabling the graphics driver menu
    3. Disabling the automatic graphics driver setup
    4. Installing NomadBSD on a hard disk
    5. Running NomadBSD in VirtualBox
    6. Installing Linux® packages
  15. Troubleshooting
    1. Errata
    2. Boot process
      1. The boot process stops at the mountroot prompt
    3. Graphics
      1. ATI/AMD
      2. NVIDIA
      3. Distorted/squished EFI framebuffer screen
      4. Hybrid Combination/Switchable Graphics


NomadBSD is a 64bit live system for USB flash drives, based on FreeBSD®. Together with automatic hardware detection and setup, it is configured to be used as a desktop system that works out of the box, but can also be used for data recovery, for educational purposes, or to test FreeBSD®'s hardware compatibility.


Choosing a USB flash drive

NomadBSD performs well on USB 2.X flash drives, but writing many small files can be very slow. To improve performance, you should consider using a USB 3.X flash drive even on a USB 2.X port, as they tend to be faster. See USB 3.0 Flash Drive Roundup. Do not use cheap no-name thumb drives they sell at super markets and drug stores. These drives are very slow and unreliable.

Downloading and writing the image

Instructions for writing the image to a flash drive from different operating systems can be found here.

The NomadBSD setup

When you boot NomadBSD for the first time, it will run the setup wizard which allows you to set your locale, timezone, keyboard settings, password, encryption, and default applications. The setup creates a new partition for the /home directory which uses the remaining space on the storage device. Depending on the size, creating the file system can take several minutes.


  1. Openbox menu. You can reach it by pressing the Windows® key (or Super key)/⌘ key (Mac®), or by right-clicking on the background image (root window).
  2. DSBBatmon. By hovering over the icon you can see the battery's current status and charge. Clicking on it brings up the configuration menu.
  3. DSBMixer. By hovering over the icon you can see the current volume of the master channel. Using the mouse wheel on it lets you change the master volume. Clicking on it brings up the main window of DSBMixer.
  4. DSBMC. Clicking on the icon brings up the main window in which you can see all the mountable storage devices attached to the system. Use the context menu of the device icons to select an action (un/mounting, opening, playing, ejecting) or double click to mount and open the device in your default file manager. You can use the preferences menu to change the file manager, autoplay setting, and multimedia programs.
  5. Date and time. Clicking in that area brings up a calendar.

Key bindings

Global keybindings





Terminal keybindings



Enable/Disable desktop components, and auto-start programs

The program DSBAutostart (Openbox menu -> Settings -> Autostart Settings) allows you to control which programs are automatically executed when the graphical interface starts. Further, it allows you to enable/disable some components of the NomadBSD desktop. The changes take place after logging out and in again.

Adding applications to the plank panel

Open your preferred graphical file manager, and navigate to /usr/local/share/applications. You can also get there by clicking the shortcut Applications on the side pane. Use Drag&Drop to add application icons to the plank panel.

Display manager settings: Auto login, default user, and theme

The display manager, Slim, used by NomadBSD is configured to automatically log in the default user nomad. The program nomadbsd-dmconfig (Openbox menu -> Settings -> Display manager settings) allows you to change/disable the default user, and to enable/disable auto login. Furthermore, it lets you change the theme. If you want to add a new theme, copy the theme's directory to /usr/local/share/slim/themes/. To see a preview in nomadbsd-dmconfig copy a screenshot of the login screen to /usr/local/share/slim/themes/your-theme-name/preview.png.

Adding a preconfigured user account

If you want to add a further preconfigured user account use nomadbsd-adduser (Openbox menu -> System -> Add user). Since NomadBSD is configured to automatically log in the user nomad you need to change that behaviour in order to be able to log in as another user. See nomadbsd-dmconfig.


NomadBSD comes with a bunch of pre-installed filesystems (CD9660, FAT, HFS+, NTFS, Ext2/3/4). You can mount storage devices via DSBMC (see Overview), which is a graphical client for DSBMD.


Execute the command dsbmc-cli -a to automount all currently connected storage devices, and to enable automounting on devices attached later to the system. To start this command automatically on session start, open DSBAutostart, and add a new entry for the above command.

Extending filesystem support

The following subsections describe how to extend the filesystems support. Rebooting the system, or restarting DSBMD is not necessary.


Unfortunately, sysutils/fusefs-exfat requires a license from Microsoft®, and so it can't be pre-installed. You have to build it yourself by using the ports:

# pkg install autoconf automake
# mkdir /home/ports
# ln -s /home/ports /usr
# svnlite co /usr/ports/Mk
# svnlite co /usr/ports/Templates
# svnlite co /tmp/fusefs-exfat
# cd /tmp/fusefs-exfat
# make DISTDIR=/tmp install

or the Git repo:

# pkg install autoconf automake
# git clone
# cd exfat
# autoreconf --install
# ./configure
# make && make install


Install the package fusefs-lkl for BTRFS, ReiserFS, and XFS support.

# pkg install fusefs-lkl


Wireless Networking

The program wifimgr (Openbox menu -> Network -> WiFi Networks Manager) allows you to connect to a wireless network.


Multihead setup

By default, NomadBSD enables all connected outputs (monitors). The tool ArandR (Openbox menu-> Settings -> ArandR) allows you to configure the position, resolution, etc. of your monitors. Save your changes to ~/.screenlayout/ which is automatically executed on session start.

Changing display settings

The program (Openbox menu-> Settings -> Display Settings) allows you to change the brightness, gamma, screen mode, display power management (DPMS) settings, etc.


Selecting the default audio device

Right-click on the speaker/volume indicator icon in the panel, and choose Preferences from the menu. In the preferences window go to the Default device tab, select the sound card/device, and click on Ok. In order to take effect make sure to restart your audio application(s).

Advanced Topics

Resetting NomadBSD

If you are a tester, or your experiments with the systems left a total mess, you might want to reset NomadBSD.

Warning: The reset will delete /home, /private, /etc, /var, /root, and /usr.local.etc. Make a backup if there are any files you want to keep.

You can reset NomadBSD as follows:

  1. Boot into single-user mode by (re)booting and choosing 2 in the boot menu.
  2. Execute /usr/libexec/nomadbsd-reset

After rebooting you'll be greeted by the setup again.


If you have modified or deleted system files from directory trees other than /home, /private, /etc, /var, /root, /tmp, and /usr.local.etc, you might not be able to cleanly reset NomadBSD.

Disabling the graphics driver menu

If you want to disable the graphics driver menu, add

initgfx_menu="NO" to /etc/rc.conf.

By default, initgfx will try autodetection, but you can instead define a default driver to use by setting initgfx_default to "scfb" or "vesa" in /etc/rc.conf.

Disabling the automatic graphics driver setup

If you want to create your own graphics driver settings, you can disable initgfx by adding

initgfx_enable="NO" to /etc/rc.conf.

Installing NomadBSD on a hard disk

Start Openbox menu -> System -> NomadBSD Installer and follow the instructions.

Note: The NomadBSD installer will use the entire disk. Installing to a single partition is currently not possible.

Running NomadBSD in Virtualbox

  1. Download and extract an image you intend to run.
  2. NomadBSD will use the remaining space on a USB flash drive for its /home partition, but since we intend to run it from an image file, we increase the (potential) size of the image as follows: truncate -s +4G nomadbsd-x.y.z.img. If you need more or less extra space, change the -s parameter accordingly.
  3. Create a vmdk file: VBoxManage internalcommands createrawvmdk -filename ~/nomadbsd.vmdk -rawdisk /full/path/to/nomadbsd-x.y.z.img
  4. Start VirtualBox, and create a new virtual machine. Select Use an existing virtual hard disk file in the Hard disk settings, and choose nomadbsd.vmdk which we created in 3.

  5. Go to Settings -> Display and set the video memory to 128MB or more.

  6. Go to Settings -> System -> Processor and set the number of processors to 2.

Installing Linux® packages

Before you can install Linux® packages it is necessary to enable Linux® binary compatibility. Let's say you want to install linux-sublime you can proceed as follows:

# kldload linux
# sysrc linux_enable=YES
# pkg install linux-sublime



If you experience any problems, consult the NomadBSD Errata first.

Boot problems

The boot process stops at the mountroot prompt

If you are using a USB 3.X port, try to use a USB 2.X port instead.



If you are booting a system with ATI/AMD graphics via UEFI, you might experience some problems. Due to a conflict with the EFI framebuffer, NomadBSD might crash or hang when the graphics driver gets loaded, or it just isn't able to start the X window system.

Try the following workaround:

  1. (Re)boot and enter the boot submenu Boot Options (6).
  2. Change Disable syscons to On by pressing the key matching the item number.
  3. Go back to main menu, and press <Enter> to boot.

Note: You won't see any boot messages until the graphics driver gets loaded.


If you see an error message like device_attach: nvidia0 attach returned 6 you could try to add debug.acpi.disabled="sysres" to /boot/loader.conf.

Distorted/squished EFI framebuffer screen

If you happened to see that the screen content seems to be squished into the upper 1/3 of your monitor you can try the following:

  1. Reboot, and then enter the loader prompt by pressing 3 at the boot menu.
  2. Type:
    gop set 0

If that didn't solve the problem, enter the loader prompt as described above, and type list gop to see a list of supported modes. According to the list try another mode number for the gop set command in 2.). If you found a mode that resolves the problem, you can save that setting by adding the line exec="gop set X" to /boot/loader.conf, where X is the mode number.

Another way to solve this problem is to boot your system in legacy mode. Consult your EFI/BIOS manual.

Hybrid Combination/Switchable Graphics

NomadBSD doesn't support switchable graphics like Optimus yet. If the Xorg server fails to start, disable one of the GPUs in your system's BIOS/UEFI.