Acadix Software

SPCM HPC Cluster Management
Lightweight Portable Job Scheduler
Biostar-tools Metaport
Another Programmer's Editor
Diskimage Tools
Personal Github Site
Auer Lab Github Site

Desktop-installer: Use your Cleverness for Creativity

How would you like to spend minimal time setting up your workstation or laptop, and most of it doing creative work? This is the design goal of desktop-installer, and FreeBSD helps make it possible.

The core purpose of desktop-installer is to help you quickly and easily create the most reliable and secure desktop system available, so you can spend your time on productive work rather than tedious systems management.

FreeBSD provides the vast majority of the features necessary to make a great desktop system for WEB browsing, editing documents, playing music and videos, developing software, and much more. It also offers solid support for most popular PC hardware. However, fully configuring a stock FreeBSD desktop system by hand is a bit like assembling a 1,000-piece jigsaw puzzle. Unless your goal is to learn how to integrate the components of a Unix desktop environment, manual configuration would not be a good use of your valuable time.

There are some important issues that new FreeBSD users are unlikely to know about, such as ensuring that your ports tree and packages are in sync, how to correctly configure devd, sound devices and graphics drivers, to name a few.

Desktop-installer is a post-install script that embodies the extensive knowledge needed to configure a clean, reliable FreeBSD desktop system. It automates the process of configuring a FreeBSD workstation or laptop computer, allowing typical users to set up a fully functional desktop environment in less than an hour.

More than a dozen popular desktop environments and window managers are explicitly supported and any other can be configured with relative ease using the "Custom" option.

The VirtualBox guest environment is automatically detected and configured with the VirtualBox guest additions, so you can easily try out desktop-installer even if you don't have a spare PC. Parallels and VMWare Fusion are also automatically detected and configured with a basic graphics setup. Hyper V can also run FreeBSD, but in our experience it is slow and unreliable. Windows users are advised to install VirtualBox instead. Note that Hyper V should be disabled via Control Panel if you are running a different virtualization system.

Design Principals

  • Desktop-installer is strictly a configuration tool, i.e. a convenient user interface for integrating standard FreeBSD tools and ports. Unlike most desktop distributions built on FreeBSD and Linux, desktop-installer does not duplicate components of or add components to the FreeBSD base. Our goal is to work with the underlying operating system, not around it, integrating the many features already provided by FreeBSD to create a fast, stable, and secure desktop experience.

    Any general enhancements made to FreeBSD for the sake of desktop-installer will be desktop-independent and available via the ports collection for use with or without desktop-installer.

    One of the primary objectives of desktop-installer is long-term sustainability. Since man-hours are costly, efforts are focused on improving the functionality of the end-result, not the appearance of the tool.

    Desktop-installer does not try to compensate for FreeBSD's shortcomings. We prefer to leave them exposed so that there is motivation to fix them in the FreeBSD base or ports system.

  • Desktop-installer will not impose any arbitrary limitations. While the GUI distributions tend to support only AMD64 systems running the latest FreeBSD release, desktop-installer allows you to use any supported version of FreeBSD on any supported CPU architecture. ARM, PowerPC, RISC-V and Sparc are treated no differently than x86. Desktop-installer is tested on an iMac G5 and a Rock 64, in addition to numerous x86 PCs and laptops. While we can't guarantee that all ports/packages will work on all platforms, desktop-installer won't stand in your way.

How it Works

The desktop-installer script installs necessary ports/packages, configures the graphical desktop of your choice and performs basic setup for devices and services such as devd, WiFi, sound, Bluetooth, printing and remote login.

Using desktop-installer, a typical desktop system can be fully configured and ready to use in less than an hour on reasonably modern hardware with a reasonably fast Internet connection.

Some user input is required, but desktop-installer should provide sufficient guidance. You should not have to search the web for complicated instructions on configuring software and services. Anything that does not work out-of-the-box is considered a bug and should be reported. The end-user is only expected to run desktop-installer and answer the questions.

Is FreeBSD the Right OS for your Desktop?

Should you use FreeBSD + desktop-installer, GhostBSD, Ubuntu Linux, one of the many other open source options, or just get a Mac? It depends on your specific needs and preferences, of course. If you're not sure and you want to increase your odds of getting it right the first time, check out our mostly unbiased summary of the topic.

Target Audience

Desktop-installer is meant for people with a little Unix experience who want full freedom to configure a stock FreeBSD system, but don't want (or can't afford) to spend time on tedious systems setup tasks like configuring Xorg, USB device support, WiFi drivers, CUPS printing services, NTP, EXFAT support, etc.

One of the goals is to help budding Unix gurus take the next step beyond point-and-click systems and begin to learn more about the internals of a traditional Unix system. Desktop-installer helps you set up such a system quickly and securely, so you have a usable system where you can learn at your own pace while getting other work done.

Examples of users likely to benefit from using desktop-installer:

  • Unix developers who prefer to spend their time on creative work rather than configuring their desktop environment
  • Sysadmins doing mass-deployments of Unix desktop systems
  • Server admins who want a simple GUI in the data center
  • Anyone who is ready to move beyond the limitations of a point-and-click system aimed at novice users
  • Anyone who can benefit from the unique features and reliability of FreeBSD

Configuring your Desktop System

  1. FreeBSD supports two major releases at any given time, currently 12.x and 13.x. We strongly recommend using the latest major FreeBSD release for desktop systems. Legacy releases may be preferred for certain server applications, but they may not have the latest device drivers and base libraries needed for some desktop applications.

    First perform a basic FreeBSD installation by booting from an install CD, DVD, or USB drive. The standard FreeBSD installer, BSDInstall, is easy to use and flexible enough for most installations. Use one of the images at or one of the mirrors, ftp2, ftp3, etc.

    Desktop-installer will install and replace base components as needed, but you can speed up the process by making the following choices during the OS install:

    • Install the src component, since it is required by some ports that build device drivers.
    • DO NOT INSTALL A PORTS TREE AT THIS STAGE. The ports tree in the install images will need to be replaced by a git clone anyway, so don't waste your time.
    • Do not add users. You can use the more user-friendly auto-admin menu for this after running desktop-installer.

    If installing under VirtualBox, we DO NOT recommend using the VM images provided by FreeBSD. A fresh install from the disc1 ISO image can be completed in under 5 minutes, so a preconfigured VM image doesn't offer much convenience. A fresh install also allows you to configure your VM settings, disk size, and base FreeBSD installation as you want instead of figuring out how to modify the preconfigured VM image.

    Also important for VirtualBox: Use the vboxsvga virtual GPU rather than vmsvga. At the time of this writing, it works better with VirtualBox guest additions for features such as automatic screen resize.

    If you have a high-end machine with 4 or more GiB of RAM, you may want to try booting from ZFS. BSDinstall makes booting from ZFS easy whether you are using a single disk, a mirror, or a RAID-Z array with multiple disks.

    For low-end machines with less than 4 GiB of RAM, UFS2, with its small memory footprint, may provide better overall performance. UFS2 is a highly underrated file system offering great performance, reliability, and features, so don't think you're missing out by not using ZFS. ZFS is most beneficial to high-end storage servers and usually not much of an advantage on the average laptop or desktop machine.

    BSDInstall is menu-driven and fairly self-explanatory if you take default options, but if you want to customize your installation or if you're new to operating system installations and want detailed instructions, you can find them in the FreeBSD Handbook.

  2. After completing the installation and rebooting, log in as root and install the desktop-installer port or package:

    pkg install -y desktop-installer
  3. Run desktop-installer as the root user and follow the instructions on the screen.

Note that desktop-installer will halt on most errors. This is fairly rare, but it can happen. Broken ports/packages are the most common cause of this. If you run into any problems while running desktop-installer, resolve the problem manually, and simply run desktop-installer again. It will remember your previous answers, so you can quickly get back to where you left off.

The script begins with some basic questions about how you want your system configured, and then runs unattended while installing the desktop system and other common software. After the desktop environment is installed, it will ask a few more questions about configuring your graphics environment and some typical optional software and services.

Selecting a desktop during setup...

[Desktop-installer screenshot]

Most popular desktop environments and a few window managers are explicitly supported. You can also use any other DE or WM in the FreeBSD ports tree by selecting "Custom". To use "Custom", you need only know the category/portname of the desktop you want, and the command for starting the desktop from xinit or xsession, e.g. start-lumina-desktop for the Lumina desktop. This command can be found in category/portname/pkg-plist. The only other advantage to explicitly supported desktops is automatic installation of a few common utilities, such as qpdfview and qterminal for Lumina. You can easily install the utilities you want using "pkg install" or "auto-admin" after a Custom desktop install.

Typically less than an hour later...

[Desktop-installer screenshot]

Maintaining your Desktop System

  • Many common tasks, including some described below, can be performed via the auto-admin menu. Simply run "auto-admin" and select an option.

  • Subscribe to the FreeBSD security notifications list. This is a spam-free, very low-volume email list to notify users about important security updates for FreeBSD. Typically a small group of security fixes are announced once every few months.

  • Update your system frequently using "auto-update-system" (also available in the auto-admin menu). This script, automatically installed as a dependency of desktop-installer, ensures that your installed packages, ports tree, and base system are all up-to-date and that the ports tree and installed packages remain in sync. With no command-line options, it runs interactively. To update everything unattended, run "auto-update-system --defaults" or "auto-update-system --yes" (same as --defaults + reboot). Run "auto-update-system --help" for more details.

  • Most software on FreeBSD systems is installed from the FreeBSD ports collection. The ports system allows you to quickly install pre-built binary packages, or just as easily (but slowly) build from source with alternative build options such as additional compiler optimizations or optional features. FreeBSD's ability to automatically install from source also you to cleanly and easily install software whose license forbids redistribution as a binary package.

    To install a binary package, use "pkg install package-name". To build from source, use "cd /usr/ports/category/package-name && make install". Run "man ports" and "man pkg", or browse the FreeBSD Handbook for additional info.

    You can browse the ports collection on the website or via the auto-admin menu to list all available binary packages in a terminal window.

    Note: Your currently installed packages should be reasonably up-to-date before installing new software. The system does a good job ensuring that appropriate versions of dependencies are installed, but if your installed packages are months old, you may encounter problems.

  • FreeBSD has strong default security settings and is immune to most malware, but even a technically secure system is only as safe as your own habits. Secure your password and change it frequently. Be careful about running arbitrary software downloaded from the web or from a USB stick. Installing all of your software via FreeBSD ports adds a strong layer of security, but not a guarantee.

  • Back up your important files regularly, preferably off-site. It's easy to do using rsync or one of the backup tools available in the FreeBSD ports collection. If your disk fails, just install a new disk, quickly rebuild your system using desktop installer again, and restore your files.

  • Use the auto-admin menu to manage user accounts. Be sure to add new users to the "wheel" group to allow "su" to root, the "operator" group to allow use of "shutdown", and the "video" group to ensure optimal graphics performance.

Future Plans

At this stage, the main focus of desktop-installer development is improving reliability and usability. We want desktop-installer to be the most trouble-free experience you've ever had with setting up a desktop system. We're not there yet, but we're moving fast in that direction. No major new features are planned, but new desktop environments and window managers may be added to the menu.

As stated earlier, FreeBSD has all the features necessary for a typical desktop user. There are a few shortcomings, though. Some potential improvements are listed below, all of which will be desktop-independent and implemented as stand-alone FreeBSD ports so that they can be used with or without desktop-installer. Some desktop environments such as KDE provide such tools, but our goal is to provide freedom of choice and consistency across desktop environments.

  • GUI battery monitor with popup warnings and automatic shutdown
  • GUI removable media manager
  • GUI systems management app for services, user management, etc.
  • GUI update manager to notify you about important security updates

Source code and problem reports are available on Github.