NomadBSD Handbooklet


  1. Intro
  2. Installation
    1. Choosing a USB flash drive
    2. Downloading an writing the image
  3. Overview
  4. Key bindings
  5. Enable/Disable desktop components, and auto-start programs
  6. Filesystem
    1. Automount
    2. Extending filesystem support
      1. exFat
      2. BTRFS, ReiserFS, XFS
  7. Networking
    1. Wireless Networking
  8. Multihead setup
  9. Advanced Topics
    1. Resetting NomandBSD
      1. Limitations
    2. Disabling the graphics driver menu
    3. Disabling automatic graphics driver setup
    4. Installing NomadBSD on a hard disk
    5. Running NomadBSD in VirtualBox
  10. Troubleshooting
    1. Errata
    2. Graphics
      1. ATI/AMD
      2. NVIDIA


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.


  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



Enable/Disable desktop components, and auto-start programs

The program DSBAutostart (Openbox menu -> Settings -> DSBAutostart) 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.


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 or the Git repo:

# pkg install autoconf
# pkg install 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.

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 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.

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 partitition, 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.



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



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.