Information and Services by Zac Hester

Zac's Guide to Installing FreeBSD

Purpose

Whenever I install FreeBSD, I like to have a nice, clean, up-to-date installation of the OS. I do a custom install, a custom kernel, and update all of my source trees. This document is to serve as an ongoing reference to the latest and most accepted methods to complete the installation without traipsing all over the web trying to find the best sequence of commands.

This document was started on August 30th, 2004. The latest changes were made on January 31, 2008. The current Release branch of FreeBSD is 6.3. Following this guide exactly will get you 6.3.

Initial installation

Because of the GUI in sysinstall, this section is left terse on purpose.

  1. Load FreeBSD from CD at boot time.
  2. After sysinstall starts, select "Custom."
  3. In "Partition," give FreeBSD as much of the disk as you need.
  4. In "Label," create five partitions (figures based on a 20G disk):
    • / -- 1G
    • swap -- 2G (2x RAM)
    • /var -- 1G
    • /tmp -- 512M
    • /usr -- (everything left)
  5. In "Distributions," select all the stuff you want, or just use "All."
  6. In "Media," select what you have (I use FTP mostly).
  7. Finally, "Commit" and confirm all the user checks.

Sit back, and watch the marvels of modern computing as the OS is installed.

When finished, sysinstall will usually ask if you want to do any last-chance configuration. I usually say "Yes" and put in a root password, add myself a user (who is a member of wheel), set the time zone, and anything else that would be specific to your particular site.

Install cvsup

After the reboot process and you're running off the OS on the hard disk, don't do anything serious and install cvsup. (The exception to this rule is if you need to complete the installation remotely. In which case, set up your remote host daemons [ssh, ftp, etc], then come back to this part.)

host# pkg_add -r cvsup-without-gui
host# rehash

Update Your Sources

After installing cvsup, the next step is to use it. Throw these supfiles into /usr/local/etc/cvsup:

/usr/local/etc/cvsup/cvsup-ports
*default host=cvsup.FreeBSD.org
*default base=/usr
*default prefix=/usr
*default release=cvs tag=.
*default delete use-rel-suffix compress
ports-all
/usr/local/etc/cvsup/cvsup-releng
*default host=cvsup.FreeBSD.org
*default base=/usr
*default prefix=/usr
*default release=cvs tag=RELENG_6_3
*default delete use-rel-suffix compress
src-all
/usr/sup/refuse
doc/da_*
doc/de_*
doc/es_*
doc/el_*
doc/fr_*
doc/it_*
doc/ja_*
doc/nl_*
doc/no_*
doc/pl_*
doc/pt_*
doc/ru_*
doc/sr_*
doc/zh_*
ports/arabic
ports/chinese
ports/french
ports/german
ports/hebrew
ports/hungarian
ports/japanese
ports/korean
ports/portuguese
ports/polish
ports/russian
ports/ukrainian
ports/vietnamese

After the refuse file and supfiles are in place, run cvsup...

host# cd /usr/local/etc/cvsup
host# cvsup cvsup-ports && cvsup cvsup-releng

This will take a while. After its finished (it should say, "Finished Successfully").

Create a Custom Kernel

The first thing to do is go into /usr/src/sys/i386/conf, copy the GENERIC configuration file to a file name of your choosing (when managing multiple computers, it's common to use the host name as the name of the new kernel, so my fictitious kernel conf would be "HOST").

After you have a new copy of the GENERIC config, edit it and strip it down to just what you need to make the hardware run. The big savings are in the SCSI area (if you're not using SCSI) and all the network adapters you don't have. If this is a server, strip out all the USB and Firewire stuff, too. Make sure to change everywhere it says "GENERIC" to "HOST"

Let's Build Us an OS

We're ready to recompile everything at this point, so say goodbye to your neat and tidy little off-the-shelf copy of FreeBSD...

host# cd /usr/src
host# make buildworld \
 && make buildkernel KERNCONF=HOST \
 && make installkernel KERNCONF=HOST

I put three commands on one line for a reason: all of these may take some time. I've found this procedure to be straight-forward enough that it's not necessary to stop at each point and look around (or whatever people do at the in-between points). The next section is to be run after you reboot the system and log back in as root.

host# make installworld

After this is done, I usually like to reboot, just to be cute, but you do what you want. When installworld is finished, you'll need to merge all your configuration files. This seems to be mostly applicable to the configs in /etc, but it may affect others. The utility mergemaster is made for checking all the diffs and asking you if the changes are cool. If you're updating from a fresh install, go ahead and say "yes" to all changes (if you haven't already made any serious changes). On my clean, FTP install, mergemaster has very little for me to change. If you're updating from something old, everyone says to make a backup of your entire /etc directory, so do it.

Bask in Up-to-Date Bliss

You've done the hard part. Everything from here out is up to your needs. Install your ports for servers or desktops or routers or whatever, and you'll have the best, most up-to-date machine in the outfit. Don't forget to tell everyone you just installed the most current release of FreeBSD. Trust me, they'll know what you're talking about.

Something broke, now what?

If one of the steps above didn't finish or started spitting out error messages (warnings are usually okay if they're coming from the compiler), I usually scrap it and start over. (Again, this doesn't apply for people updating existing systems.)

The process that is most likely to cause you trouble is creating the custom kernel. If this goes bad, you probably won't even be able to boot. If this happens, use the startup menu to drop into the boot prompt and bootstrap the GENERIC kernel (one is always kept somewhere). Go back and recopy the GENERIC configuration file into your "HOST" file and edit it all over again. This time, be a little more cautious about removing things (check the LINT config for in-depth explanations of every little section). Rebuild your kernel and reboot with your fingers crossed.

One problem I hit was trying to cvsup with the wrong release tag. At one point (during the 5.2 series of FreeBSD), the Handbook claimed that you should use RELENG_5_2_1 to update your source tree to the latest release. In fact, that tag didn't exist on any CVS servers (at least when I tried it, it didn't), so I only succeeded in deleting my source tree when trying to update my system. Only by trial and error did I find that RELENG_5_2 was the latest *correct* tag for the 5.2 series.

Also, you should be aware that using CVS tags with only major version numbers (ie. RELENG_5), will fetch you a very handsome stable or maybe even beta version of FreeBSD; which, if you're reading this guide, you almost certainly do NOT want. The moral of the story is to try to research the CVS tags before you run CVS.

Wow, that was really helpful, can I give you money?

Oh, silly Unix user... of course you can give me money. See the PayPal link at planetzac.net.

Document Updates

Last Modified: January 31, 2008