Project 1: VM Bring-Up and First Boot

Build a reproducible FreeBSD VM that boots cleanly and has verified network connectivity.

Quick Reference

Attribute	Value
Difficulty	Level 1
Time Estimate	Weekend
Main Programming Language	Shell (sh) (Alternatives: csh, Python)
Alternative Programming Languages	sh, csh, Python
Coolness Level	Level 2
Business Potential	Level 1
Prerequisites	Unix shell basics, basic networking, VM familiarity
Key Topics	bsdinstall, boot chain, disk layout, VM networking

1. Learning Objectives

By completing this project, you will:

Create a reproducible VM specification for FreeBSD and document it clearly.
Install FreeBSD with a chosen filesystem (UFS or ZFS) and verify the boot chain.
Validate networking in NAT and bridged modes with deterministic checks.
Troubleshoot common boot and network failures in a VM context.

2. All Theory Needed (Per-Concept Breakdown)

Concept 1: FreeBSD Installation and Boot Chain

Fundamentals FreeBSD installation is intentionally consistent so that you can recreate a system from notes alone. In a VM, the hypervisor supplies virtual hardware and the installer writes a partition scheme that must match the firmware mode (UEFI or BIOS). The FreeBSD boot chain is a linear path: firmware loads the boot loader, the loader reads configuration, the kernel initializes hardware and mounts the root filesystem, and the rc system starts services. If any step is mismatched, the system fails early and predictably. This is useful because it makes failures diagnosable. The installer, bsdinstall, is also opinionated: it expects you to choose a filesystem and create a swap partition, and it installs a coherent base system that is separate from third-party packages. For this project, you need to understand how each installation decision maps to boot success and how to verify that success after the first reboot.

Deep Dive into the concept FreeBSD is a complete, integrated operating system. The installation process is designed to produce a stable base that can be updated as a unit, so the installer focuses on disk layout, base system distribution sets, and initial configuration. In a VM, you control a limited set of hardware parameters-CPU count, RAM size, disk type, and network adapter mode. Each of these parameters affects the boot chain. For example, enabling UEFI implies you will have an EFI System Partition (ESP) that the firmware can read; if you install with a BIOS boot block but later flip the VM to UEFI, you will get “no bootable device.” Similarly, if you choose ZFS, you must allocate enough RAM and create a pool that the loader can see and the kernel can import at boot.

The boot chain in FreeBSD is explicit and layered. Firmware runs first, then hands control to the FreeBSD loader. The loader reads /boot/defaults/loader.conf and your overrides in /boot/loader.conf. It then loads the kernel (/boot/kernel/kernel) and any necessary modules (storage drivers, network drivers, ZFS). The kernel probes devices, mounts the root filesystem, and launches the rc system. The rc system reads /etc/rc.conf and starts services in a predictable order, relying on scripts in /etc/rc.d and /usr/local/etc/rc.d for third-party services. Knowing this chain is how you fix boot issues: you identify the stage that failed and check the configuration or device detection that corresponds to it.

Installation choices also affect how you recover. With UFS, you use classic fsck and restore strategies; with ZFS, you can use snapshots and boot environments. In a VM, recovery is even easier because you can take hypervisor snapshots. However, relying on snapshots instead of understanding the boot chain is a mistake. Snapshots hide the problem instead of teaching you the fix. The right mental model is “firmware -> loader -> kernel -> rc.” Whenever you fail to boot, you ask: did firmware find the boot block? did the loader find the kernel? did the kernel mount the root filesystem? did rc execute? Each answer points to a specific file or setting.

The installer also reinforces the base vs packages split. FreeBSD’s base system lives under / and /usr, while third-party packages install into /usr/local. That separation means the install stage is mostly about base system coherence, not about adding apps. Your VM should first be a clean base system that boots and connects to the network. Only after that do you add services or packages. This project creates that stable foundation and teaches you to trust a documented install recipe.

Operationally, the installation and boot chain is easiest to keep stable when you treat it as a small contract between configuration, tooling, and observable outputs. Write down the exact files that own the state and the commands that reveal the current truth. Then verify the contract at three points: immediately after you make the change, after a reboot, and after a deliberate disturbance such as restarting services or reloading modules. FreeBSD rewards this discipline because it rarely hides state; if something changes, it is usually in a file you control. Make a habit of collecting a before-and-after snapshot of commands and outputs so you can explain which change caused which effect.

At scale, the installation and boot chain is also about failure containment. Identify what must remain available when something breaks and design a safe escape hatch. For example, keep console access for firewall changes, keep a previous boot environment for upgrades, or keep a dataset snapshot before risky edits. The same pattern applies across domains: define invariants, define the rollback path, and then only proceed when you can trigger that rollback quickly. Finally, test the failure path while the system is healthy; you learn more from a controlled rollback than from an emergency. This perspective turns the lab exercise into an operational capability you can trust on production systems.

How this fits on projects

This concept is central to this project’s Section 3.1 and Section 5.1.
It reappears in P07 Boot Environments when you reason about bootability.

Definitions & key terms

bsdinstall -> Interactive FreeBSD installer.
UEFI/BIOS -> Firmware interfaces that dictate boot partition layout.
Loader -> FreeBSD boot loader that applies tunables and loads the kernel.
Kernel -> Core OS component that initializes hardware and mounts root.
rc system -> Startup framework that runs services defined in rc.conf.
UFS -> Traditional Unix File System.
ZFS -> Copy-on-write filesystem and volume manager.

Mental model diagram

Firmware (UEFI/BIOS)
 |
 v
FreeBSD Loader (loader.conf)
 |
 v
Kernel + Modules
 |
 v
Root FS Mounted
 |
 v
rc System -> Services

How it works (step-by-step, with invariants and failure modes)

VM firmware reads the boot partition (EFI or freebsd-boot).
Loader reads config and loads kernel + required modules.
Kernel probes devices and mounts the root filesystem.
rc reads /etc/rc.conf and starts services.

Invariants:

Firmware mode must match the partitioning scheme.
Root filesystem must be discoverable by the kernel.
Loader must be able to read /boot on the target disk.

Failure modes:

Firmware mismatch: “No bootable device.”
Missing kernel modules: root filesystem not found.
Corrupt /boot or incorrect loader config.

Minimal concrete example

freebsd-version
uname -r
sysctl kern.bootfile

Common misconceptions

“Any Linux VM settings work for FreeBSD.” -> FreeBSD is sensitive to firmware and disk type.
“ZFS is always better.” -> ZFS is powerful but adds RAM and complexity.
“rc.conf is like systemd unit files.” -> It’s a declarative configuration file, not a unit definition system.

Check-your-understanding questions

Why does changing BIOS/UEFI after install break boot?
What is the loader responsible for before the kernel runs?
At what step does /etc/rc.conf become relevant?

Check-your-understanding answers

The firmware expects a boot partition format that no longer matches the disk.
Reading loader configuration and loading kernel/modules into memory.
After the kernel mounts the root filesystem and starts the rc system.

Real-world applications

Building standardized VM images for labs or CI.
Debugging boot failures during upgrades or migrations.

Where you’ll apply it

Section 3.1 What You Will Build
Section 5.1 Development Environment Setup
Section 5.10 Phase 1
Also used in: P07 Boot Environments, P10 Update Runbook

References

“Absolute FreeBSD, 3rd Edition” (Ch. 2-4)
FreeBSD Handbook: Installation and Boot Process

Key insights A repeatable install is a boot chain you can explain from memory.

Summary A FreeBSD VM boots reliably when firmware, loader, kernel, and rc are aligned. Installation choices define that alignment.

Homework/Exercises to practice the concept

Install once with UFS and once with ZFS and compare boot behavior.
Change firmware mode after install and observe the failure.
Write down your exact installer choices as a reproducible checklist.

Solutions to the homework/exercises

UFS uses less RAM, ZFS adds snapshots and checksums.
Reverting firmware mode restores boot.
A checklist makes future rebuilds deterministic.

Concept 2: VM Networking Modes and Interface Configuration

Fundamentals FreeBSD networking in a VM is shaped by the hypervisor’s network mode and the guest’s interface configuration. NAT gives outbound Internet access but blocks inbound connections; bridged mode places the VM directly on the LAN so other devices can reach it. Inside FreeBSD, interface configuration is done with ifconfig for immediate changes and /etc/rc.conf for persistent settings. DNS resolution is configured in /etc/resolv.conf. The essential mental model is “hypervisor mode decides reachability, guest config decides IP and routes.” If you mix those responsibilities, you will chase ghosts. For this project, you must know how to identify the interface name (often em0 or vtnet0), how DHCP assigns an address, and how to switch to a static IP safely.

Deep Dive into the concept NAT and bridged networking solve different problems. NAT is ideal for basic Internet access and safer defaults because it hides the VM behind the host’s IP. Bridged mode is necessary when you need inbound SSH, service testing, or realistic LAN behavior. In a VM lab, you will often start with NAT for convenience, then switch to bridged to validate access from other machines. The catch is that the VM’s IP address becomes part of the LAN, so you must choose an IP that does not conflict and ensure your LAN allows it.

FreeBSD’s networking model is simple and explicit. ifconfig is the primary tool for interface configuration: it can bring interfaces up/down, assign addresses, and configure media options. For persistence, the rc system reads /etc/rc.conf at boot. For a DHCP interface, you set ifconfig_em0="DHCP". For a static IP, you set ifconfig_em0="inet 192.168.1.50/24" and a default router with defaultrouter="192.168.1.1". DNS is configured in /etc/resolv.conf either by DHCP or by manual edits. The resolver file is not controlled by rc directly, so if DHCP is active it may be overwritten; understanding that interaction is key.

Troubleshooting starts with layers: link, IP, route, DNS. ifconfig shows link and IP, netstat -rn shows routes, and drill or host can test DNS. In a VM, there is an extra layer: the hypervisor’s virtual switch. If the guest is configured correctly but unreachable, check whether the VM is attached to the right network and whether your host allows bridged traffic. In bridged mode, some Wi-Fi networks block unknown MAC addresses. This is not a FreeBSD issue but a network policy. Knowing this prevents wasted time.

Finally, deterministic validation matters. Use fixed test IPs and a consistent DNS query so you can compare outcomes. For example, always test ping -c 1 freebsd.org and drill freebsd.org with the same resolver. Document the command outputs in your lab notes so you can prove the configuration works and spot regressions after later projects.

Operationally, virtual networking modes and interface configuration is easiest to keep stable when you treat it as a small contract between configuration, tooling, and observable outputs. Write down the exact files that own the state and the commands that reveal the current truth. Then verify the contract at three points: immediately after you make the change, after a reboot, and after a deliberate disturbance such as restarting services or reloading modules. FreeBSD rewards this discipline because it rarely hides state; if something changes, it is usually in a file you control. Make a habit of collecting a before-and-after snapshot of commands and outputs so you can explain which change caused which effect.

At scale, virtual networking modes and interface configuration is also about failure containment. Identify what must remain available when something breaks and design a safe escape hatch. For example, keep console access for firewall changes, keep a previous boot environment for upgrades, or keep a dataset snapshot before risky edits. The same pattern applies across domains: define invariants, define the rollback path, and then only proceed when you can trigger that rollback quickly. Finally, test the failure path while the system is healthy; you learn more from a controlled rollback than from an emergency. This perspective turns the lab exercise into an operational capability you can trust on production systems.

How this fits on projects

This concept is applied directly in Section 3.4, Section 5.4, and Section 6.
It becomes critical in P05 Network Lab and P09 Jail Lab.

Definitions & key terms

NAT -> Network Address Translation; outbound access, inbound blocked.
Bridged -> VM appears on the LAN with its own IP.
DHCP -> Automatic IP assignment protocol.
Static IP -> Manually assigned IP and netmask.
resolv.conf -> DNS resolver configuration file.

Mental model diagram

[VM] --(virtual NIC)--> [Hypervisor Switch]
 NAT mode: VM -> Host -> Internet
 Bridged: VM -> LAN -> Internet

How it works (step-by-step, with invariants and failure modes)

Hypervisor assigns virtual NIC to NAT or bridged mode.
FreeBSD boots and runs dhclient or static config.
Interface is assigned an IP and default route.
DNS resolution is configured in /etc/resolv.conf.

Invariants:

Interface name in rc.conf must match actual device.
Default route must point to valid gateway.
DNS server must be reachable.

Failure modes:

Wrong interface name -> no IP assigned.
NAT mode when you expect inbound SSH -> connection fails.
DNS missing -> ping works by IP but not by hostname.

Minimal concrete example

ifconfig
netstat -rn
drill freebsd.org

Common misconceptions

“Bridged is always better.” -> NAT is safer for initial installs.
“DNS is part of networking.” -> It is a separate resolver config that can fail independently.

Check-your-understanding questions

Why does NAT block inbound SSH by default?
Which rc.conf entries are required for a static IP?
How do you verify routes without pinging a hostname?

Check-your-understanding answers

NAT maps outbound connections only; no inbound mapping exists.
ifconfig_em0 with IP/netmask and defaultrouter.
Use netstat -rn and ping the gateway IP.

Real-world applications

Building test servers reachable from your LAN.
Simulating production networking inside a lab.

Where you’ll apply it

Section 3.2 Functional Requirements
Section 5.4 Concepts You Must Understand First
Section 5.10 Phase 2
Also used in: P05 Network Lab, P09 Jail Lab

References

“Absolute FreeBSD, 3rd Edition” (Ch. 7-8)
FreeBSD Handbook: Networking

Key insights Networking is two systems: hypervisor mode outside, rc.conf inside.

Summary VM networking works when the hypervisor mode and guest configuration agree. Test link, IP, route, and DNS separately.

Homework/Exercises to practice the concept

Switch between NAT and bridged and document the IP changes.
Configure a static IP and verify routes after reboot.
Break DNS deliberately and recover it from the console.

Solutions to the homework/exercises

NAT IP differs from LAN IP; bridged matches LAN subnet.
Correct rc.conf entries persist across reboots.
Restore /etc/resolv.conf or restart DHCP.

3. Project Specification

3.1 What You Will Build

A FreeBSD VM with a documented hardware profile, a clean install (UFS or ZFS), verified boot chain, and working network connectivity in NAT and bridged modes. The deliverable includes a reproducible install checklist, a VM snapshot, and command output proving the system is operational.

Included:

VM spec (CPU, RAM, disk, firmware mode, NIC mode)
FreeBSD install with chosen filesystem
Verified boot and version checks
Networking tests in NAT and bridged modes

Excluded:

Desktop environment or GUI
Jails or advanced services
Package installs beyond base system

3.2 Functional Requirements

VM specification documented: CPU, RAM, disk size/type, firmware, NIC mode.
Successful install: FreeBSD boots to multi-user mode without errors.
Version verification: freebsd-version and uname -r recorded.
NAT connectivity test: outbound ping and DNS resolution succeed.
Bridged connectivity test: inbound SSH reachable from another host.

3.3 Non-Functional Requirements

Performance: Boot to login prompt in under 90 seconds on typical hardware.
Reliability: Two consecutive reboots succeed without manual intervention.
Usability: Install checklist can be followed by another person to reproduce the VM.

3.4 Example Usage / Output

$ freebsd-version
14.1-RELEASE

$ uname -r
14.1-RELEASE

$ ping -c 1 freebsd.org
PING freebsd.org (96.47.72.84): 56 data bytes
64 bytes from 96.47.72.84: icmp_seq=0 ttl=49 time=35.2 ms

--- freebsd.org ping statistics ---
1 packets transmitted, 1 packets received, 0.0% packet loss

3.5 Data Formats / Schemas / Protocols

rc.conf (networking)

ifconfig_em0="DHCP"
# For static IP:
# ifconfig_em0="inet 192.168.1.50/24"
# defaultrouter="192.168.1.1"

Install checklist (plain text)

Firmware: UEFI
Filesystem: UFS
Disk: 40G VDI
Network: NAT

3.6 Edge Cases

Firmware mode changed after install -> boot failure.
Wrong interface name in rc.conf -> no IP address.
Bridged mode on restricted Wi-Fi -> VM unreachable.
DHCP server unavailable -> no DNS resolution.

3.7 Real World Outcome

You have a VM that boots reliably and is reachable for remote work. You can reproduce the install with your checklist and verify connectivity with deterministic commands.

3.7.1 How to Run (Copy/Paste)

# From VM console
freebsd-version
uname -r
ifconfig
netstat -rn
ping -c 1 freebsd.org

3.7.2 Golden Path Demo (Deterministic)

Use NAT mode.
Set TZ=UTC so timestamps are stable.
Use the fixed hostname freebsd.org for a deterministic test.

3.7.3 If CLI: provide an exact terminal transcript

$ TZ=UTC freebsd-version
14.1-RELEASE

$ TZ=UTC uname -r
14.1-RELEASE

$ TZ=UTC ping -c 1 freebsd.org
PING freebsd.org (96.47.72.84): 56 data bytes
64 bytes from 96.47.72.84: icmp_seq=0 ttl=49 time=35.2 ms

--- freebsd.org ping statistics ---
1 packets transmitted, 1 packets received, 0.0% packet loss

$ echo $?
0

Failure demo (deterministic)

$ TZ=UTC ping -c 1 192.0.2.1
PING 192.0.2.1 (192.0.2.1): 56 data bytes

--- 192.0.2.1 ping statistics ---
1 packets transmitted, 0 packets received, 100.0% packet loss

$ echo $?
2

4. Solution Architecture

4.1 High-Level Design

+---------------------+
| Host OS + Hypervisor|
+----------+----------+
 | VM config (CPU/RAM/Disk/NIC)
 v
+---------------------+
| FreeBSD Base System |
| - Boot chain |
| - rc.conf |
+----------+----------+
 |
 v
+---------------------+
| Networking Verified |
+---------------------+

4.2 Key Components

Component	Responsibility	Key Decisions
VM spec	CPU/RAM/Disk/NIC choices	Balance simplicity vs ZFS needs
Installer	Disk layout and base install	UFS vs ZFS, UEFI vs BIOS
rc.conf	Persistent network config	DHCP vs static
Validation commands	Proof of success	Deterministic tests

4.3 Data Structures (No Full Code)

InstallChecklist
- firmware: UEFI
- filesystem: UFS|ZFS
- disk_size_gb: 40
- nic_mode: NAT|Bridged
- notes: free text

4.4 Algorithm Overview

Key Algorithm: Reproducible VM Bring-Up

Create VM with documented settings.
Install FreeBSD with chosen filesystem.
Reboot and verify version outputs.
Test NAT networking, then bridged networking.
Snapshot VM after success.

Complexity Analysis:

Time: O(install time + reboot count)
Space: O(disk size + snapshots)

5. Implementation Guide

5.1 Development Environment Setup

# Verify ISO checksum on host
shasum -a 256 FreeBSD-RELEASE-amd64-disc1.iso

# (Optional) Create a notes folder
mkdir -p ~/freebsd-lab/notes

5.2 Project Structure

freebsd-vm-lab/
+-- checklist.txt
+-- outputs/
| +-- version.txt
| +-- network.txt
+-- snapshots/
 +-- after-install.txt

5.3 The Core Question You’re Answering

“Can I reliably reproduce a clean FreeBSD install in a VM?”

A reproducible install is the base of every reliable operations workflow.

5.4 Concepts You Must Understand First

Stop and research these before coding:

Boot chain (firmware -> loader -> kernel -> rc)
NAT vs Bridged networking
UFS vs ZFS trade-offs

5.5 Questions to Guide Your Design

Which firmware mode is consistent with your hypervisor and disk layout?
Do you need ZFS features now or can you start with UFS?
Is NAT enough for your initial validation, or do you need bridged now?

5.6 Thinking Exercise

Boot Failure Simulation

After install, switch firmware mode and document the exact failure message. Then revert and confirm recovery.

5.7 The Interview Questions They’ll Ask

Why would you pick UFS over ZFS in a VM?
What does the FreeBSD loader do?
How do you debug “No bootable device”?
What is the difference between NAT and bridged networking?
Which files control boot-time configuration?

5.8 Hints in Layers

Hint 1: Start simple Use UEFI + GPT unless your hypervisor forces BIOS.

Hint 2: Reduce variables Use NAT for the first boot, then switch to bridged.

Hint 3: Verify with commands Capture freebsd-version and uname -r immediately.

Hint 4: Recover quickly Take a VM snapshot after the first successful boot.

5.9 Books That Will Help

Topic	Book	Chapter
Installation	“Absolute FreeBSD, 3rd Edition”	Ch. 2-3
Boot process	“Absolute FreeBSD, 3rd Edition”	Ch. 4
Networking basics	“Absolute FreeBSD, 3rd Edition”	Ch. 7-8

5.10 Implementation Phases

Phase 1: Foundation (2-4 hours)

Goals: Create VM and complete install. Tasks:

Document VM settings and create the VM.
Install FreeBSD with your chosen filesystem. Checkpoint: VM boots to login prompt.

Phase 2: Connectivity (2-3 hours)

Goals: Validate NAT networking. Tasks:

Run ping and DNS tests.
Save command outputs to outputs/network.txt. Checkpoint: NAT tests succeed with exit code 0.

Phase 3: Remote Access (2-3 hours)

Goals: Validate bridged access. Tasks:

Switch NIC to bridged.
Confirm the VM receives a LAN IP. Checkpoint: Another host can ping the VM.

5.11 Key Implementation Decisions

Decision	Options	Recommendation	Rationale
Firmware mode	UEFI, BIOS	UEFI	Matches modern GPT defaults
Filesystem	UFS, ZFS	UFS for first install	Simpler and less RAM
Network mode	NAT, Bridged	NAT first, then bridged	Safer initial setup

6. Testing Strategy

6.1 Test Categories

Category	Purpose	Examples
Smoke Tests	Basic boot and login	`freebsd-version`, `uname -r`
Network Tests	Connectivity and DNS	`ping`, `drill`
Reboot Tests	Persistence	reboot twice and retest

6.2 Critical Test Cases

Boot success: System reaches login prompt on two consecutive boots.
NAT connectivity: ping -c 1 freebsd.org returns exit code 0.
Bridged reachability: Another host can ping the VM IP.

6.3 Test Data

Hostnames: freebsd.org
Test IPs: 192.0.2.1 (non-routable failure case)

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall	Symptom	Solution
Firmware mismatch	“No bootable device”	Reinstall with matching UEFI/BIOS
Wrong interface name	No IP after boot	Check `ifconfig -a` and update rc.conf
Bridged blocked by LAN	VM unreachable	Use wired LAN or allowed bridge mode

7.2 Debugging Strategies

Boot stage isolation: Identify which boot stage failed and check configs.
Layered networking checks: Link -> IP -> Route -> DNS.

7.3 Performance Traps

Assigning too little RAM for ZFS causes slow boots and instability.

8. Extensions & Challenges

8.1 Beginner Extensions

Create a second VM using a different filesystem.
Document a one-page install checklist.

8.2 Intermediate Extensions

Enable serial console access and document it.
Automate your VM build steps with a shell script.

8.3 Advanced Extensions

Use UEFI boot with custom loader tunables.
Build a reusable VM image for teammates.

9. Real-World Connections

9.1 Industry Applications

CI test runners: reproducible FreeBSD images for automated tests.
Security labs: disposable VMs for patch validation.

freebsd-vm-bhyve: automation scripts for FreeBSD VMs.
packer templates: image creation pipelines for FreeBSD.

9.3 Interview Relevance

Boot process: explain firmware, loader, kernel, rc.
Networking: NAT vs bridged and persistent config.

10. Resources

10.1 Essential Reading

“Absolute FreeBSD, 3rd Edition” by Michael W. Lucas - Ch. 2-4, 7-8
FreeBSD Handbook - Installation and Boot Process

10.2 Video Resources

“Installing FreeBSD in a VM” - FreeBSD Foundation presentations

10.3 Tools & Documentation

VirtualBox/VMware/UTM: VM configuration documentation
FreeBSD Handbook: authoritative OS usage reference

P02 Post-Install Baseline - adds users and SSH.
P05 Network Lab - deeper networking practice.

11. Self-Assessment Checklist

11.1 Understanding

I can explain the FreeBSD boot chain clearly.
I can describe why UEFI vs BIOS matters.
I can explain NAT vs bridged networking.

11.2 Implementation

All functional requirements are met.
All test cases pass.
I can reproduce the install from my checklist.

11.3 Growth

I can explain this setup in an interview.
I documented at least one failure and recovery.
I can teach someone else to reproduce it.

12. Submission / Completion Criteria

Minimum Viable Completion:

VM boots to login prompt twice in a row.
NAT networking test passes with exit code 0.
Install checklist is written and saved.

Full Completion:

All minimum criteria plus:
Bridged networking test passes from another host.
VM snapshot created after success.

Excellence (Going Above & Beyond):

Automated VM setup script created.
Reinstall done from checklist with identical results.