Acadix Home

Acadix Software

Auto-admin
Desktop-installer
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.

Desktop-installer installs and configures desktop-independent tools and features, such as QMediaManager, a GUI application that is automatically launched when removable media are inserted.

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

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 https://ftp.freebsd.org/pub/FreeBSD/releases/ISO-IMAGES/ or one of the mirrors, ftp2, ftp3, etc.

To install from a USB stick, download the a ".img" image file and image the USB drive with it. Under Windows, you can use a tool such as Rufus. On Unix systems (including macOS), you can use the dd command. Replace "file.img" with the name of the file you downloaded and "/dev/da0" with the name of the device that appears in /dev when you plug in a USB stick.
```
dd if=file.img of=/dev/da0 bs=64k conv=sync
```
If installing from a CD/DVD drive or installing on a virtual machine, download a .iso image. Use CD/DVD burning software to burn a disc for real hardware, or just load the .iso into the virtual CD/DVD drive in the virtual machine. A -disc1.iso file is a generally a good choice. The -disc1.iso.xz files will download faster and can be uncompressed with "unxz" if you have it. Choose "amd64" for an x86-based PC, or "aarch64" for a VM on ARM-based Macs.

Boot from the USB stick or CD/DVD drive and follow the instructions on the screen to install FreeBSD. This can be completed in a few minutes by experienced users, but your first time through, you should take your time and read all instructions carefully.

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.

System clocks may be set to local time or UTC (GMT). Make sure the virtual machine and host are in agreement on this. VirtualBox has a check box in system settings for systems with the clock set to UTC.

Lastly, adjusting the boot order of the VM will make the guest OS installation a bit smoother. Configure the VM to boot from hard disk first, then optical disk (you will use a .iso file for install). The VM will then boot from the .iso image during install, and from the virtual hard disk after install.

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. Below are some basic pointers to get you through without all the gory details.
```
If installing under VirtualBox:

    Select the VBoxSVGA video adapter
    Load the FreeBSD disc1 or other ISO file into the virtual CDROM
    1G RAM is sufficient
    
FreeBSD install:

    Accept default answers to most questions.
    
    A few pointers:
	Hostname:
	    Full hostname, e.g. freebsd13.local, freebsd13.my.domain
	    
	System components:
	    Don't bother with ports, will install later
	    Installing src now will save a little time
	    
	Filesystem:
	    Auto (UFS) for most installs, ZFS for high-end systems
	    Entire disk, GPT for most systems
	    
	If installing on real hardware:
	    Enable ntpdate, ntpd, powerd
    
	Whether real hardware or virtual machine:
	    Enable moused (solves problems with various mouse drivers)
	    Enable clear_tmp
	
	Add users: no (auto-admin does this better)
    
	If installing under VirtualBox:
	    It's hard to eject CD fast enough after Reboot
	    Use ACPI shutdown in Machine menu instead, then eject virtual CD
```
After completing the installation and rebooting, log in as root and install the desktop-installer port or package:

pkg install -y desktop-installer
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.
The base OS can be upgraded to newer versions using "auto-upgrade-base", which is also available in the "auto-admin" menu under "Software Management".

If you have modified any system files that are being upgraded, this process may require some manual editing to transfer your changes. FreeBSD's upgrade tools will notify you when this is necessary.

Also, we don't recommend overusing upgrade tools on any operating system. It is best to periodically back up your files and do a fresh install, in order to clean up any corruption that has accumulated due to user error, improper shutdowns, and bit rot.

Caution: The FreeBSD project currently does not guarantee binary compatibility of the kernel interface across point releases. I.e., kernel modules compiled on FreeBSD 14.1 may not work properly on 14.2. This can affect things like the DRM (direct rendering module, for accelerated graphics), and VirtualBox virtualization. Older releases are supported for 3 months after a new point release, and binary packages are only built for the older release during this period. Hence, to avoid potential problems, it is best to wait until a release actually reaches EOL (end-of-life) before upgrading the base.
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.

Some additional conveniences might be nice, such as a desktop-independent CAPS lock indicator for keyboards lacking a CAPS lock LED. This could be done as a tiny trayable Qt app.

Source code and problem reports are available on Github.