Computer Networks (CSCI 0431), Spring 2025

pete > courses > CSCI 0431 Spring 25 > FreeBSD setup and use

FreeBSD setup and use

FreeBSD is a descendant of UNIX, so you will find that it operates similarly to Linux in most respects. Installation is a bit easier. The following instructions contain guidance for both ARM and x86 machines; there are many commonalities, so the differences are intermingled. For ease of use, it might be a good idea to take your own notes of commands pertinent to your specific situation.

Users on Mac ARM machines (ie, M1 or M2) will use UTM for virtualization. There are two hurdles here: there is no VSCode build for FreeBSD ARM (you could compile it yourself but it will possibly take literally days and consume literally hundreds of gigabytes of disk); but the GUI isn’t usable anyway. If you wish to use VSCode, the solution is to edit files on your host and then copy them to the virtual machine to compile/run them. This probably sounds tedious; we will make it efficient (instructions below).

Users on x86 machines (ie, Windows machines, older Macs) will use VirtualBox for virtualization. Both VSCode and the GUI are available; you may, of course, use whatever interface/editor you like.

In any event, it is probably a good idea to keep a copy of your code on your host machine, if only for backup purposes.

(Note: yes, there is a version of VirtualBox available for Mac ARM hosts. It’s still in development, though, and it was not reliable for me.)

This page may seem overwhelming. Take it slowly and ask me for help if you get stuck. There is no problem here that cannot be fixed. (Ask me how many times I reinstalled Linux from scratch when I was first learning to use it.) But backup your code.

Since these instructions are new this semester, there may very well be bugs in them. Please do not hesitate to ask for clarification or correction. I will make sure any modifications/improvements are clearly marked.

Download install media

Visit https://www.freebsd.org.

Click Download FreeBSD. Scroll down to FreeBSD 14.2-RELEASE. For UTM users, in the "Installer" column, click "aarch64". VirtualBox users, in the "Installer" column, click "amd64". In both cases, in the resulting list of files, download the one that ends in -disc1.iso. (Be careful: there are others that are close but not quite.) This file is the "install media" and will be referenced as such in subsequent instructions.

Virtual machine setup

For UTM

Download and install or update: https://mac.getutm.app.

Run UTM.

Click Create a New Virtual Machine. Select Virtualize. Select Other.

Boot ISO Image: click the "Browse" button and select the install media file you downloaded above.

Hardware: set Memory to a power of 2 no less than 1024 MB and no more than half the memory of your machine. It is probably safe to leave it at 1024 MB, and we can easily tweak it later on if need be. Leave processors at default (or, if you have many to spare, increase it if you feel like it—not necessary).

Storage: 64 GB will be more than enough. I wouldn’t set it lower than 16 GB. The disk space won’t be consumed until it is actively used, so there is little downside to over-allocating here.

Shared directory: skip. (FreeBSD doesn’t implement the protocols that UTM uses for this purpose; we’ll use a different mechanism to share files between guest and host, described below.)

For VirtualBox

Download and install or update: https://www.virtualbox.org.

Run VirtualBox.

Click New.

Virtual machine Name and Operating System: set name to whatever you want; leave ISO image as "<not selected>"; set Type to "BSD"; set Version to "FreeBSD (64-bit)".

Hardware: set Memory to a power of 2 no less than 1024 MB and no more than half the memory of your machine. It is probably safe to leave it at 1024 MB, and we can easily tweak it later on if need be. If you intend to use VSCode, I suggest no less than 2048 MB. If you have lots of processors to spare, you can increase that value, but it’s not necessary: 1 is fine. Make sure Enable EFI is turned off.

Virtual Hard disk: click "Create a virtual Hard Disk Now". Set Disk Size to no less than 16 GB. Make sure "dynamically allocated" is selected. The disk space won’t be consumed until it is actively used, so there is little downside to over-allocating here.

In the settings, click Display. Set Graphics Controller to "VBoxSVGA" (ignore warnings about "Invalid Settings Detected"). Make sure Enable 3D Acceleration is turned off.

In the settings, in the Storage section, in the line reading "IDE Secondary Device 0", click "Choose a disk file…". Select the install media file you downloaded above.

Installation

Start the virtual machine.

You should see a "Welcome to FreeBSD" screen. This is the bootloader. Let the bootloader count down to zero or press enter to Boot Multi-user.

Welcome: select Install.

Keymap Selection: select Continue with default keymap.

Set Hostname: choose whatever you want. Probably best if it’s all lowercase, no spaces, no punctuation (hyphen is okay).

Distribution Select: unselect all. (Use arrow keys to move up and down the list, press space to select/unselect, press enter to commit.)

Partitioning: select Auto (UFS). (NOT ZFS.) Select Entire Disk. Select GPT. Finish. Commit.

Set root password to whatever you want. (For what it’s worth, I don’t think it’s important to use a strong password in this case. I use "root".)

Network Configuration: select the only option (vtnet0 in UTM, em0 in VirtualBox). IPv4: yes. DHCP: yes. IPv6: no. Resolver Configuration: unchanged (just press enter).

Select local or UTC (Greenwich Mean Time) clock: Mac users (both UTM and VirtualBox), select Yes; Windows users (select No).

Time Zone Selector: America -> United States -> Eastern. Confirm.

Time & Date: correct and select Set Date. Or just select Skip. Same with the time.

System Configuration: defaults are fine (do NOT disable sshd).

System Hardening: defaults are fine.

Firmware installation: let it time out.

Add User Accounts: no. (We’ll do that later.)

Select Exit.

Manual Configuration: Yes.

At the resulting shell prompt, run "halt -p". It may take a few seconds to start doing so, but the virtual machine will shut down. Close the virtual-machine window when it is done, but leave UTM/VirtualBox running.

In UTM, in the configuration for the virtual machine, in the CD/DVD line, click the down arrow and select Clear.

In VirtualBox, in the Storage section, in the IDE Secondary Device 0 line, click the install media filename and select "Remove disk from virtual drive".

Done.

First boot

Upon first boot, you should update the system, bootstrap the pkg system, install/configure packages like sudo, a better shell, a text editor, and a graphical environment; and create a user for yourself (do NOT get in the habit of logging in as the root user).

Update the system

This step should run on the first boot, immediately after installing FreeBSD in a new virtual machine, and then thereafter whenever updates are published by the FreeBSD Project. (For the purposes of this course, you don’t need to do it ever again.)

Easy peasy:

# freebsd-update fetch
# freebsd-update install
# reboot

The "fetch" step will show, in turn, lists of files to be removed, added, and updated. Each list will be piped through more (which is, no joke, very much like less); you can tell because the last line of the output will be "(END)" or just ":". This is meant to give you, the system administrator, the opportunity to verify the changes being made to your system. We trust these changes, so just press 'q' to quit each of the three instances of more.

As of Sunday, 09 February 2025, running freebsd-update on 14.2-RELEASE will only cause updates, so there is only one set of files to confirm.

Bootstrap `pkg`

Initial setup of the "pkg" utility that allows for installing third-party software (ie, software not written by the FreeBSD folks). You only need to do this once:

# pkg bootstrap

Install packages

In general:

# pkg install name-of-package

Packages you need to install: sudo, vde2, rsync

Packages you need to install (VirtualBox): xorg, xfce, wireshark, virtualbox-ose-additions

Packages you need to install (UTM): wireshark-nox11

Packages you really ought to install: a more full-featured shell (bash and zsh are popular options; if you don’t know what you’ve used in the past, pick bash; to change default shell, see the "Create a user" section); an editor (vim if you’re into that sort of thing; vscode is not available on ARM Macs, workaround below)

Feel free to install other packages as you see fit.

Some packages require configuration tweaking after you install them.

After you install `sudo`…

Run visudo, which will open up the sudo configuration file in vi. Hold down the j key to move the cursor down, until you get to the line that says "Uncomment to allow members of group wheel to execute any command". Use j to move the cursor to the following line. Press x twice to delete the first two characters in that line. Type :wq and press enter to save and exit. You are now a vi master.

After you install `virtualbox-ose-additions`…

Run these two commands (note that the "#" prompt indicates they are to be run as root; you may use sudo):

# sysrc vboxguest_enable="YES"
# sysrc vboxservice_enable="YES"

After you install virtualbox-ose-additions, you should reboot the VM.

After you install `wireshark` (or `wireshark-nox11`) …

Run these two commands, again as root:

# echo "own  bpf* root:network" >> /etc/devfs.conf
# echo "perm bpf* 0660" >> /etc/devfs.conf

If you want to use sudo here, you have to jump through a hoop because of the output redirection:

$ sudo sh -c 'echo "own  bpf* root:network" >> /etc/devfs.conf'
$ sudo sh -c 'echo "perm bpf* 0660" >> /etc/devfs.conf'

Reboot the VM after running these commands.

Create a user

Replace "username" below with a name of your choosing.

# pw user add username -m -G wheel,network
# passwd username

(Your user needs to be a member of the wheel and network groups for sudo and wireshark, respectively.)

If you installed a new shell (eg, bash), cause the new user to use that shell:

# chsh -s /usr/local/bin/bash username

Make the obvious replacement for zsh.

Use the GUI

As on the Linux virtual machines, log in as your normal user (ie, not root) and run:

$ startxfce4

ssh to the virtual machine

With UTM, this easy. Open a Terminal on your Mac, and run:

$ ssh username@192.168.64.2

(where username is the name of the user you created for yourself in the VM).

With VirtualBox, this is slightly less easy. In the configuration for your virtual machine, click on Network. In the "Adapter 1" tab, click Advanced. Click Port Forwarding. In the window that pops up, click the green "+" sign. In the row that appears, enter the following values in the given columns:

Name: whatever
Protocol: TCP
Host IP: 127.0.0.1
Host Port: 2222
Guest IP: 10.0.2.15
Guest Port: 22

Click Ok. If the VM was running when you did this, you may need to reboot it. But maybe not. If the following command doesn’t work, reboot the VM and try again. This setup step only need to be done once.

Now, open a terminal (both Mac and Windows) and run:

$ ssh -p 2222 username@127.0.0.1

where username is the name of the user you created for yourself in the VM.

Editing files (includes Copying files)

The code for your assignments must compile and run on FreeBSD. As with Systems Programming, you will submit your code by pushing to a git repository, and I will retrieve your code by pulling from that repository. This means you will have both a local repository (on your own computer, to which you will commit your code) and a remote repository (on weathertop, to which you will push your code). First, I describe the various arrangements and how to set them up; then, I describe the day-to-day development workflow for each.

If your text editor of choice runs in a terminal (eg, vim), you can just install that editor inside the virtual machine (see "Install packages" above). You can run your text editor from the shell, either within a terminal in the VM’s GUI or within an ssh session.

If your text editor of choice does not run in a terminal, my guess is that you want to use VSCode. If you are using an x86 machine (either Mac or Windows) with VirtualBox and XFCE, you can install and run VSCode inside the virtual machine: the package is called vscode; once installed, it is available in the Applications -> Development menu, or by running vscode from the shell.

If you want to run VSCode and you are using an ARM machine with UTM, it’s not quite so simple: there is no pre-compiled package that you can install. You could potentially download the source code and install it yourself, but my understanding is that this takes literally days to complete and in excess of 100G of disk space. And it might not even work because JavaScript/Electron is a mess. The solution is to run VSCode outside the virtual machine and then copy your code to the virtual machine whenever you want to compile/run it. (You can use this workflow on an x86 machine, too, though you don’t have to.)

Suggested workflow: editor running on virtual machine

In this setup, the "local repo" will be in your virtual machine’s filesystem.

After you create the git repo on weathertop, clone it on the virtual machine. Edit files within the cloned repo, commit to that repo, push to weathertop.

Suggested workflow: VSCode running on host, copying files to virtual machine

In this setup, the "local repo" will be in your host’s filesystem.

After you create the git repo on weathertop, clone it on your host. Also select a directory within your virtual machine that you will use for compiling and running your code. Edit files within the cloned repo on your host. When you want to copy your code to the virtual machine:

host$ cd /path/to/cloned/repo/dir/on/host
host$ rsync -va --delete ./ 192.168.64.2:path/to/vm/dev/dir/

The trailing slashes are important! Do not forget them! Put these commands in a shell script to avoid having to type them out all the time. Note that "path/to/vm/dev/dir" is a relative path: it is relative to your home directory.

(VSCode might have the ability to run such a script automatically after every save. The feature is probably called something like "post-save hook". If you figure out how to do it, let me know and I will share the documentation here.)

After copying the files using rsync, you can compile and run the files by sshing into the virtual machine.

Running Wireshark

On VirtualBox, within XFCE4, click the Applications menu, select Internet, click Wireshark.

On UTM, you need to install Wireshark on the host (ie, on OS X); download it from https://www.wireshark.org and be sure to follow the instructions in the "Read me first" file. Don’t skip the part that sets up the PATH.

Then, with the VM running, open a Terminal and:

$ ssh username@192.168.64.2 'tshark -l -i dev -w - not tcp port 22' | wireshark -k -i -

where username is the name of the user you created for yourself in the VM and dev is the name of interface within the VM whose traffic you wish to capture (with UTM, this is vtnet0; with VirtualBox, this is em0).

You should see both the wireshark window pop up and a bunch of text in the Terminal window. This bunch of text is likely obscuring a password prompt (because you need to give your password to ssh). Look closely at the terminal output to make sure it’s asking for your password, and then type it. Then wireshark will do what we want.