Understanding the FreeBSD Installer: A Comprehensive Guide for All Users

The FreeBSD installer represents more than just a means to get the operating system onto your hardware—it embodies the project's philosophy of providing users with choice, control, and flexibility whilst maintaining sensible defaults for those who prefer a straightforward installation experience.

The Foundation: What is bsdinstall?

At its core, bsdinstall functions as FreeBSD's system installer, designed for both installing new systems from media such as CD-ROMs or USB drives, and for preparing virtual machine images and jails on live systems. Much like the venerable make utility familiar to developers, bsdinstall operates through a target-based architecture, accepting specific installation targets and their parameters as arguments.

When invoked without arguments, bsdinstall automatically executes the 'auto' target, which provides a standard interactive installation by sequentially invoking other subtargets. This design elegance allows for both user-friendly guided installations and sophisticated scripted deployments—a duality that makes FreeBSD particularly attractive across different use cases.

The installer's architecture consists of three primary components working in harmony. First, there's bsdconfig, a comprehensive library of shell routines that bsdinstall leverages extensively. Second, bsddialog provides the text-based user interface, handling both user input and progress monitoring throughout the installation. Finally, bsdinstall itself orchestrates the entire installation process, coordinating between these components and the underlying FreeBSD system.

Before You Begin: Preparation and Planning

The FreeBSD Project strongly recommends backing up all important data before installing any operating system, emphasising that backups should never be stored on the system being installed but rather on removable media, another networked system, or cloud storage. Once the installer formats your system's disk, any existing data will be permanently lost—making this precautionary step absolutely critical.

Planning your installation properly ensures a smoother experience. If FreeBSD will share disk space with another operating system, you'll need to decide which disk or partition will host FreeBSD, potentially using partition resizing tools to create the necessary space without destroying existing data. For systems running multiple operating systems, FreeBSD supports both the traditional Master Boot Record (MBR) partitioning scheme and the more modern GUID Partition Table (GPT).

Network connectivity requirements deserve careful consideration. Certain FreeBSD installation methods require network access to download installation files, and even after installation, you may need to configure network interfaces. If your network environment uses DHCP, configuration becomes automatic. Otherwise, you'll need to obtain specific network information from your administrator, including IP address, subnet mask, default gateway address, domain name, and DNS server addresses.

Hardware requirements vary by architecture and version, with details available on the FreeBSD Release Information page for each release. It's prudent to check the FreeBSD Errata page for your intended version before installation, as occasionally bugs affecting the installation process are discovered and documented there.

Acquiring and Preparing Installation Media

FreeBSD offers multiple installation image types to accommodate different scenarios and preferences. The bootonly ISO contains only the installer itself, requiring an active internet connection during installation to download necessary files—it's the smallest option. The disc1 ISO includes everything needed to install FreeBSD, its source code, and the Ports Collection, whilst the dvd1 ISO adds popular binary packages for window managers and applications, enabling a complete system installation without internet access.

For USB-based installations, memstick images contain all files needed to install FreeBSD, its source, and the Ports Collection, and must be written directly to a USB stick. There's also a mini-memstick variant that, like the bootonly ISO, downloads components during installation.

Verifying your downloaded image's integrity protects against corruption and ensures authenticity. FreeBSD provides SHA256 and SHA512 checksum files alongside installation images, allowing you to calculate and compare checksums to verify file integrity. This verification step, whilst optional, represents best practice and takes only moments to complete.

Starting Your Installation Journey

By default, the installer makes no changes to your disk until you confirm a specific warning message, allowing you to safely exit at any point before that confirmation. This design philosophy respects the cautious nature of system administrators whilst providing clear points of no return.

After booting from installation media, you'll encounter the FreeBSD boot loader menu. This menu waits ten seconds for user input before proceeding, offering options including multi-user boot, single-user mode for system repair, escape to a loader prompt for low-level commands, system reboot, console selection between video and serial, kernel selection, and boot options. Most users simply press Enter to continue with the standard installation.

Once booting completes, a welcome menu presents several choices. The default Install option launches the interactive installer, whilst alternative options include accessing a FreeBSD shell for manual disk preparation or using Live CD mode to explore FreeBSD before committing to installation. The Live CD option proves useful for those still evaluating whether FreeBSD suits their needs, though it requires authentication with username 'root' and a blank password, and performance is significantly slower than an installed system.

Configuring Your System's Foundation

The installation process begins with straightforward but important decisions. After keymap files load, bsdinstall displays a menu for selecting the keyboard mapping that best matches your physical keyboard, with the option to test your selection before proceeding. If uncertain, the default United States keymap serves as a safe, internationally recognised option.

Next, you'll set the hostname for your newly installed system, which should be unique on your network and preferably fully qualified, such as 'machine3.example.com'. This hostname becomes your system's network identity, so choose thoughtfully if you're joining an existing network infrastructure.

The component selection screen allows customisation of what's installed. Components available include base-dbg and kernel-dbg (base tools and kernel with debug symbols), lib32 packages (for running 32-bit applications on 64-bit systems), the Ports Collection (which requires about 3 GB of disk space), complete FreeBSD source code (requiring 1 GB initially and 5 GB for recompilation), and the FreeBSD Test Suite. For most users, the pre-selected defaults of base system and kernel suffice perfectly.

Disk Partitioning: Choices and Strategies

Bsdinstall offers four methods for disk space allocation: Auto UFS partitioning, which automatically configures UFS filesystems; Auto ZFS, creating a root-on-ZFS system with optional GELI encryption support; Manual partitioning for advanced users wanting customised configurations; and Shell access for command-line partitioning using utilities like gpart, fdisk, and bsdlabel.

Guided UFS partitioning provides the simplest path for newcomers. When selecting this method, you'll choose which connected disk to use, then decide whether to use the entire disk or create partitions in free space. GPT is generally the most appropriate partitioning scheme choice for modern computers, particularly on AMD64 architecture, whilst older systems incompatible with GPT should use MBR.

The installer displays your partition layout for review before committing, with options to revert to original values, automatically recreate partitions, or manually modify the configuration. This final review opportunity ensures you're comfortable with the proposed setup before any permanent changes occur.

For those requiring more sophisticated configurations, manual partitioning offers complete control. A standard FreeBSD GPT installation uses at least three partitions: freebsd-boot or efi for boot code, freebsd-ufs for the UFS filesystem (or freebsd-zfs for ZFS), and freebsd-swap for swap space. Partition sizes can use convenient suffixes—K for kilobytes, M for megabytes, G for gigabytes—or the keyword 'auto' to consume all remaining space.

ZFS enthusiasts can opt for the root-on-ZFS guided partitioning mode. This mode works only with whole disks, offering various pool types including stripe, mirror, RAID10, RAIDZ1, RAIDZ2, and RAIDZ3, each with different redundancy and performance characteristics. Configuration options include pool naming, forcing 4K sectors for future-proofing, disk encryption via GELI, partition scheme selection, swap configuration including size, mirroring, and encryption options.

Understanding partition layout philosophy helps with planning. Hard drives transfer data faster from outer tracks to inner ones, so smaller, frequently accessed filesystems should occupy outer regions, whilst larger partitions like /usr belong towards inner disk areas. The /var partition size reflects intended machine usage, holding mailboxes, log files, and printer spools—most users need about one gigabyte, though more may be required for mail servers or systems with extensive logging. For /usr, at least 2 gigabytes is recommended, as it contains Ports Collection and system source code, with user home directories defaulting to /usr/home.

Swap space configuration warrants careful consideration—the swap partition should typically be about double the physical memory size, though systems with minimal RAM may benefit from more swap, and configuring too little can cause issues if memory is later added.

Network Configuration and Connectivity

After disk configuration, the installer asks for a new password to be selected for the system management account (root).

Then it presents a list of detected network interfaces for configuration.

Wireless interfaces trigger an automatic scan for available networks. Networks are identified by their SSID, with scan results showing encryption types available for each network. If your desired network doesn't appear, you can rescan after checking antenna connections or repositioning closer to the access point.

For WPA2-protected networks, you'll input the password (Pre-Shared Key), with characters displayed as asterisks for security. The installer then moves to IPv4 configuration, where DHCP automatic configuration is available if your network provides a DHCP server. Static configuration requires manual entry of IP address, subnet mask, and default router address.

IPv6 configuration similarly offers both automatic StateLess Address AutoConfiguration (SLAAC) and manual static configuration options. The DNS resolver configuration converts hostnames to network addresses and vice versa—if DHCP or SLAAC was used, these values may already be populated; otherwise, enter your local network's domain name and at least one DNS server address.

If installing from bootonly or mini-memstick images, you'll select a mirror site for downloading distribution files. Selecting a mirror geographically close to your location reduces download time and bandwidth usage.

Finalising System Configuration

Time zone configuration requires selecting geographic region, country, and specific time zone, enabling your system to automatically handle regional time changes like daylight saving time. After time zone selection, you can set the system date and time, though these steps may be skipped if you prefer to configure them later.

The services menu lets you choose which system services start at boot, including local_unbound (local caching DNS resolver), sshd (Secure Shell daemon for remote access), moused (mouse support for command-line console), ntpdate (boot-time clock synchronisation), ntpd (ongoing network time synchronisation), powerd (power management), and dumpdev (crash dump enabling for debugging). Enable only services your system actually requires.

Security hardening options deserve careful attention. Available hardening measures include hiding processes from other users and groups, hiding jail processes, restricting kernel message buffer reading, disabling process debugging facilities for unprivileged users, randomising process IDs, cleaning /tmp at startup, disabling syslogd network sockets, disabling sendmail, requiring root password for single-user mode, restricting DTrace destructive actions, and enabling address space layout randomisation. These options enhance security but some may affect legitimate system functionality, so understand each before enabling.

The installer strongly recommends creating at least one user account rather than logging in as root, since root access provides essentially unlimited power without protection.

During user account creation, you'll provide username, full name, optionally a specific user ID, login group, additional group memberships (such as 'wheel' for administrative access), shell preference, home directory location and permissions, and password configuration.

Installation Completion and Next Steps

After configuration completes, the installer presents a final configuration menu allowing adjustments before finishing. This menu provides access to add additional users, change the root password, modify hostname, reconfigure network settings, adjust services, review security hardening, change timezone, and even download the FreeBSD Handbook. Take advantage of this opportunity to verify all settings are correct.

Before rebooting, bsdinstall offers to open a shell within the new system for any additional manual configuration. This proves invaluable for experienced administrators who need to make adjustments not covered by the standard installation process.

Upon first boot of your newly installed system, informational messages display during startup, and after booting completes, you'll see a login prompt where you should enter the username created during installation rather than logging in directly as root. These boot messages can be reviewed later using Scroll-Lock or by examining /var/run/dmesg.boot.

If SSH was enabled during installation, the first boot may take slightly longer as the system generates SSH host keys, with subsequent boots proceeding faster. The system displays SSH key fingerprints during first boot for verification purposes.

Advanced Installation Techniques

Bsdinstall supports unattended or minimally-attended installations through scripting, useful for modified physical media or diskless network installations. Scripts consist of two parts: a preamble setting installation options including disk partitioning and distribution selection, and an optional setup script running under chroot in the newly installed system before bsdinstall exits.

A typical automated installation script sets the PARTITIONS and DISTRIBUTIONS variables in the preamble, followed by a shell script section beginning with the standard shebang that executes system configuration commands. For ZFS-based automated installations, the script exports variables like ZFSBOOT_VDEV_TYPE, ZFSBOOT_DISKS, and nonInteractive to control pool creation and installation behaviour.

On FreeBSD release media, a script placed at /etc/installerconfig runs automatically at boot, with the system rebooting after installation completes—this enables unattended network installation of new systems. This capability proves invaluable for enterprise deployments requiring consistent, reproducible installations across multiple machines.

Environment variables provide extensive control over installation behaviour. Key variables include DISTRIBUTIONS (specifying which components to install), BSDINSTALL_DISTDIR (directory containing or receiving distribution files), BSDINSTALL_DISTSITE (URL for downloading distributions), BSDINSTALL_CHROOT (target directory for unpacking and mounting), and various BSDINSTALL_SKIP_* flags to bypass specific interactive steps.

Troubleshooting Installation Issues

Some installation problems can be avoided or resolved by updating firmware on hardware components, particularly motherboard BIOS, though manufacturers caution against updating BIOS without good reason as the process can potentially render systems inoperative if it fails.

If your system hangs during hardware probing at boot or behaves strangely during installation, ACPI may be the culprit—FreeBSD makes extensive use of ACPI on i386 and AMD64 platforms. You can disable ACPI by setting the hint.acpi.0.disabled hint to "1" in the third-stage boot loader, though this resets each boot, so add it to /boot/loader.conf for persistence.

Checking the Hardware Notes listed on the FreeBSD Release Information page for your target version ensures your hardware is supported, potentially avoiding compatibility issues.

The Path Forward: Ongoing Development

The FreeBSD installer has evolved significantly but continues developing to meet modern expectations whilst maintaining its core strengths of flexibility and scriptability. Recent developments include experimental work towards graphical installation modes, enhanced accessibility features, and improved usability for both newcomers and experienced administrators.

The installer's architecture, based on shell scripts with specific components implemented in C, allows for extensibility whilst maintaining the reliable foundation that FreeBSD users have come to trust. Ongoing efforts aim to make FreeBSD installation more accessible through features like desktop environment installation options during setup, improved hardware detection and driver installation, and enhanced accessibility support including screen readers and alternative input methods.

The FreeBSD Foundation actively supports installer development, recognising its crucial role as many users' first interaction with FreeBSD. Community contributions continue enhancing the installer's capabilities, whether through bug fixes, feature additions, or documentation improvements.

Conclusion

The FreeBSD installer represents decades of refinement, balancing approachability for newcomers with the flexibility demanded by advanced users and enterprise deployments. Its target-based architecture enables everything from simple interactive installations to sophisticated automated deployments, whilst maintaining the reliability and transparency that define the FreeBSD project.

Whether you're installing FreeBSD for the first time or orchestrating automated deployments across hundreds of servers, bsdinstall provides the tools and flexibility to accomplish your goals. The installer embodies FreeBSD's broader philosophy: providing powerful capabilities with sensible defaults, never limiting what users can achieve whilst making common tasks straightforward.

As you embark on your FreeBSD journey, remember that the installation process is merely the beginning. The robust, secure, and performant system you're installing has powered everything from personal workstations to critical internet infrastructure for decades. The FreeBSD community stands ready to support your success through comprehensive documentation, active mailing lists, and a welcoming culture of knowledge sharing.

The installer's combination of guided assistance and advanced options ensures that regardless of your experience level or deployment requirements, you can confidently install FreeBSD knowing you're building on a solid, well-maintained foundation that will serve you reliably for years to come.

Disclaimer

This article has been prepared by The Distrowrite Project with the noble aim of providing accurate, educational content about FreeBSD installation procedures. Whilst every effort has been made to ensure accuracy and completeness, readers should consult official FreeBSD documentation for the most current information. FreeBSD and the FreeBSD logo are registered trademarks of The FreeBSD Foundation. Other product and company names mentioned herein may be trademarks of their respective owners. This article is provided for educational and informational purposes only and does not constitute professional advice. The Distrowrite Project and its contributors do not endorse or promote any activities involving malware, viruses, or other harmful content that may compromise the integrity of networks, devices, or infrastructure. Readers are solely responsible for their use of the information provided and should exercise appropriate caution when installing or configuring operating systems. Always maintain proper backups and verify installation media integrity before proceeding with any installation.

References

FreeBSD Handbook: Installing FreeBSD
https://docs.freebsd.org/en/books/handbook/bsdinstall/
FreeBSD Manual Pages: bsdinstall(8) https://man.freebsd.org/cgi/man.cgi?query=bsdinstall&manpath=FreeBSD+14.3-RELEASE+and+Ports
FreeBSD Foundation: Installer Usability https://freebsdfoundation.org/our-work/journal/browser-based-edition/networking-3/installer-usability/

🗼

Search This Blog

The Distrowrite Project