Understanding CVSup, Mounting, Ports and Init on FreeBSD

Most tech savvy geeks can work their way through a FreeBSD install, even if
they have no prior UNIX experience. However installing an OS and configuring an OS are two totally different things. This article is targeted towards anyone who might be wondering about FreeBSD, but doesn’t know what to do with it after they install it. This isn’t then end-all be-all of FreeBSD howto’s. Just some of the simple stuff. Update: Some of the readers of OSNews have emailed me concerning corrections that need to be made in this article. Dig in (third page) for more.


So you’ve taken the first step and installed FreeBSD. Now you’re wondering what to do with this new operating system. Unlike some of the bigger Linux distributions, FreeBSD gives you a basic install, and leaves it upto you to add in what you want. Lets say that you want to set up this box as a SMB file server for your network. To do that we will need to install Samba. This seems like the perfect time to see that “ports tree” that youkeep hearing so much about in action. The first thing we need to do is install
the cvsup package. Cvsup is a utility that reads a conf file, known as a ‘sup-file’ that tells it what server to use, and what to download. In essencewhat it does is it compares your local copy of the ports tree to the copy of the ports tree on the cvsup server. It then downloads everything in the ports tree that is newer than what is on your machine. The easiest way of installing cvsup is with the pkg_add command. All you have to do is login in as root, and type “pkg_add -r cvsup” and it will automatically download the cvsup package from a FreeBSD server and install it. You can also find on the CD under the
/cdrom/Packages/All directory. Now that it is installed, we need to create our custom sup-file. The templates are located in the /usr/share/examples/cvsup directory. We want to copy the ports-supfile someplace where we won’t loose it.
I prefer the /root directory, but copy it wherever you want to. Next we need toedit the file, so open it up in your editor of choice. Note that unless you choose to install your favorite editor during the install you might have to get by with vi for now. First we have to change the cvsup host server, so we go over to freebsd.org and consult the handbook.

After you locate a cvsup server closest to you, change the
“CHANGE_THIS.freebsd.org” to whatever server is closest to you. Now we need to set up which collections we want to download whenever we run cvsup. The ports tree is divided into several sections such as ports-cad, ports-german, etc,
etc. By default the sup-file uses the ports-all collection, which is all of the collections. Since I don’t know any language besides English, I commented out
all of the foreign language collections. NOTE: If you do comment out any of the collections, be sure that you DO comment out the ports-all entry and that you DO NOT accidentally comment out the ports-base entry. Nothing horribly bad will happen if you do other than you will have to cvsup the ports tree again. After you have edited the file, run the command “cvsup ports-supfile”. You should see lots of messages fly by as the ports tree is updated. The time it takes to update depends on two things, the speed of your ‘Net connection, and how long ago you last updated. Depending on how long ago you downloaded the ISO image of the -RELEASE CD it could be pretty outdated, so it could take awhile for the process to complete. In my opinion it is better to answer “Yes” during the install when it asks you if you want to install the ports tree from CDROM. Even though it might be out of date, some of the ports will still be current, which will save you time and bandwidth when you first cvsup.

Mounting CDROM’s

One of the first things I had to do when I first installed FreeBSD was mount my CDROM so that I could install cvsup. I didn’t know about the -r flag yet, but even if you don’t need it for a package, you will probably need to read a CDROM sooner or later. All you have to do is find the device name of your CDROM(look in dmesg | more). After you find that open your /etc/fstab file and add a new
line that consists of /dev/xxx /cdrom cd9660 ro,noauto 0 0 where /dev/xxx is whatever device your CDROM is. After that you have to type “mount /cdrom” and then you can access the contents of the CDROM under the /cdrom
directory. If for some reason you don’t have a /cdrom directory, just type “mkdir /cdrom”. Also, by default you have to be root to mount filesystems, that includes CDROM’s.


The various Linux distro’s(except for slackware) use the sysinitV style of rc files to determine what gets started at boot up. FreeBSD on the other hand uses a bsd-style init system. Essentially all you have to do to start something at
boot time it to write a shell script that starts the program, make the script executable, put a .sh ending on it and place it in the /usr/local/etc/rc.d directory. Note that it is a requirement that the script ends with .sh. Also
note that the /etc directory has several rc.* files, but not a rc.d directory. That’s because by convention you should place your startup scripts in the /usr/local/etc/rc.d directory, in fact you’ll notice that almost anything installed via ports or packages, and for the most part compiled by hand will either install by default in /usr/local/ or /usr/X11R6 instead of /opt and

After cvsup completes, you are ready to install some apps! First of all, if your editor of choice isn’t installed already, cd into the /usr/ports/editors directory and have a look around. For instance if I wanted to install the vim
editor I would move into the vim directory and as root type “make”. This command will read the Makefile in that directory and download and compile the newest version of vim. After that completes, type “make install” to actually
install the compiled binaries. After the installation type “make clean” to remove the temporary files created during the compile. In our example we are configuring a Samba server, so go ahead and follow the make, make install, make clean steps for the samba port in the /usr/ports/net/samba directory. After it is installed the smb.conf file is located in the /usr/local/etc/ directory. Also if you would like samba to startautomatically when the OS boots you need to take a quick glance at the startup script in /usr/local/etc/rc.d to make sure that it has the correct suffix. Some
(but not all) ports install the startup script with a .default suffix so that if you want it to start automatically you have to manually rename it. Which is
a good thing, or at least I think it is. At the time of this article’s writing there are 6740 applications in FreeBSD’s port tree, and my ports tree (the Makefiles and any source patches that are required for the port) takes up only 165MB.

This ports tree contains most of the popular open source applications that are available today. These applications can be updated regularly and it would be a huge hassle to constantly check the Web in case a new version of one of your installed packages has been released. This is where the amazing freshports.org comes to the rescue. Freshports is a neat web site dedicated to FreeBSD’s ports tree. You can subscribe to Freshports, and set up a list of watched ports, and then whenever one of your watched ports is upgraded you get an email notification of it! Then all you have to do is sync your ports tree, and upgrade your port. Which brings me to the next subject, package maintenance. As we saw above, pkg_add installs binary packages, and if used with the -r flag it will download the package for you (eg. pkg_add -r bash2 will download and install bash version 2). Now that
we have installed a few packages/ports, type “pkg_info | more” to get a listing of installed software. Don’t be surprised if the “| more” becomes necessary before too long. Also notice that both packages that you installed with pkg_add and also posts that you compiled via the ports tree both show up, pkg_info doesn’t care which way they were installed.

Now we need to delve back into the ports tree again, this time to /usr/ports/sysutils/portupgrade. This extremely handy application takes care of upgrading a previously installed port. Lets say that after installing vim, we
get an email from Freshports telling us that the vim port has been updated. So all we have to do is type “pkg_info | grep vim” to get the “proper” package name for vim (eg. the output I get from this is vim-6.0.185). Then all you have to do is type “portupgrade vim-6.0.185” and goes about the process of downloading, compiling, and upgrading vim. If portupgrade reports that vim doesn’t need upgrading, make sure you cvsup’d your ports tree recently. The tar files that are downloaded from the Internet to be compiled are stored in /usr/ports/distfiles, if your short on disk space that directory is a good place to reclaim disk space. Also note that by installing the portupgrade port, you also get the pkg_deinstall command, which is a nice neat wrapper for pkg_delete. I recommend using pkg_deinstall, it’s much easier to use when it comes time to remove a package that several other packages depend on. One last note on package management, if portupgrade ever tells you that you need to manually run “pkgdb -F”, it is safe to delete what are known as “Stale Dependencies”. They are simply pointers to packages that are either gone, or updated and the database hasn’t been updated to reflect the changes. Upgrading with “make buildworld” One of the best things about FreeBSD is the way that “FreeBSD” itself is a defined set of utilities, and when FreeBSD is updated, so are those included utilities. The most common way of upgrading an existing FreeBSD installation is to with the “make buildworld” and “make installworld” commands.

You can get a copy of the source sup file in
/usr/share/examples/cvsup/stable-cvsup. Be sure to change the host name of the server. Now all you have to do it type “cvsup stable-cvsup”, and you get the latest and greatest copy of the stable source code for Freebsd-4.x. Once again the time it takes for this complete depends on the speed of your Internet connection and the time elapsed since you last cvsup’d the source tree. The ports tree is universal no matter what version of FreeBSD your using, so the ports tree you cvsup on a -STABLE system is the same as what you get if you cvsup on -CURRENT. The source tree however is made up of many versions. There are the -STABLE and the -CURRENT trees. The -CURRENT tree is currently in
testing (think beta) and should not be used on production systems. The -STABLE tree is made up of the “stable” source code. The versions of FreeBSD that is available as ISO’s are simply periodic snapshots of the -STABLE tree. You
should track the -STABLE tree for your production servers, as the -STABLE tree is updated with bug fixes and security patches.

After the cvsup finishes, cd into the /usr/obj directory and make sure that it is empty. When you compile the source code for -STABLE or -CURRENT the temporary files go into the /usr/obj directory. If there are files in this
directory it is possible that they could conflict with the newer files that we are trying to compile. It’s just best to empty that directory before we start. Now cd into the /usr/src directory and type “make buildworld”. The compiles the new code, but does not install it. After that finishes we have to boot into single user mode. Reboot the machine, before you get the message telling you to press Enter to boot /kernel, hit any key. That should drop you at a prompt, type “boot -s /kernel”. In FreeBSD the OS’s kernel is /kernel, what the above command does is tell the loader to boot /kernel into single user mode. After it
boots into single user mode, it will ask for a path to your preferred shell, or use sh by default. After you set the shell, type “fsck -p” which checks the filesystem for inconsistencies. Next type “mount -u /”, this changes status of the / partition from read-only to read-write. Now type “mount -a” – this mounts all of the filesystems in the /etc/fstab file that do NOT have the “noauto”
option. Finally cd into the /usr/src directory and type “make installworld”. This step actually installs the new files from the /usr/obj directory. After it finishes hit the “Ctrl-D” combo to boot the machine into multi-user mode.

Finally, to finish the upgrade we have to compile a new kernel. Now cd into the /usr/src/sys/i386/conf directory. In a default install there should be a LINT and a GENERIC file. The GENERIC file is the conf file for the system’s default kernel; we need to make a copy of it. I copied mine like this “cp GENERIC NATHAN”, you can name your copy anything you want. After that you need to edit
your kernel to add any options you might need or remove ones you don’t need. The kernel conf file contains some comments about what each option does, however for more detailed information look in the LINT file. Don’t edit the
GENERIC file, as every time you cvsup the source tree that file gets replaced with the newer GENERIC file and you would loose your changes. After you have finished editing your file, run “config NATHAN” or whatever you named your
file. The config program parses the file and makes sure that there are no typos or other errors. If for some reason you would need to add debugging info into the kernel run the config program with the -g flag. A kernel with debugging code results in a larger kernel, you probably don’t need it unless your hacking kernel code. After config runs it will instruct you to cd into the
../../compile/NATHAN directory. Once you are in that directory, run “make depend”, which makes sure that you have everything thing needed to compile the kernel, it’s recommended by the config program, however it’s not required. After that finishes simply run “make”, which actually compiles the kernel, once that completes type “make install” which will install the kernel in /kernel. It renames the existing /kernel to /kernel.old, and installs the new one as /kernel. If there is a /kernel.old from a previous compile, it gets
overwritten. After that, all that is left to do is reboot!

If for some reason the new kernel will not boot, drop down to the boot loader prompt like we did when booting into single user mode. Except this time, type “boot /kernel.old”, which will boot the “old” or previous working kernel.

Some of the readers of OSNEWS have emailed me concerning corrections that need to be made in this article. The next few paragraphs explain what is changed, and why. Please take note that anything said here should be used in place
of anything said above.

1)In the “ports” section I explained that in order to update an installed package via portupgrade that you have to type “pkg_info | grep *name*” to get the “proper” name of the package. I used vim as the example there, and I will
here. Instead of having to type out “portupgrade vim-6.0.85”, you can just type “portupgrade vim”. This way is much easier, and much simpler. Please note that in order for either of these methods to work, your package database has to be free of all stale dependencies. If it isn’t you will just get an error from portupgrade telling you to run “pkgdb -F” manually.

2)Worthy of mention is “portupgrade -ar”. Until this afternoon I didn’t know this even existed! What the -ar does is tell portupgrade to upgrade all installed packages recursively. Which in a nutshell means, upgrade all of my
installed apps, and anything that they depend on fuction. As always, you should cvsup your port’s tree to get the latest version before running portupgrade.

On a server it might not be a good idea to blindly upgrade you apps, but the -ar flags save a lot of time on computers that are used as desktops, or anywhere else that you want the absolute latest version of everything.

3)In the above article I stated that “You should track the -STABLE tree for your production servers, as the -STABLE tree is updated with bug fixes and security patches.” THIS IS WRONG! The -STABLE tree is a development stage just like
-CURRENT. Code that has been tested in -CURRENT is patched and then put into -STABLE for more testing. Think of -CURRENT as alpha quality code, and -STABLE as beta quality. For production servers, the FreeBSD handbook recommends that you use the -RELEASE snapshots. The -RELEASE snapshots are recommended for production servers that must be as stable as possible. When the next -RELEASE
version comes out, you can then edit your cvsup tags to obtain the -RELEASE source code and follow the routine for upgrading via source.

I should note however that both my desktop and server have been running the -STABLE tree for several months. Neither of them have ever had any problems from the effects of running -STABLE. However for critical servers that can’t go
down, run -RELEASE.

4)According to the Handbook, the proper way of building a new kernel is as follows:

cd /usr/src
make buildkernel KERNELCONF=*MYKERNEL*
make installkernel KERNELCONF=*MYKERNEL*

where *MYKERNEL* is whatever you named your edited copy of GENERIC.

This is for installing a new kernel along with a new “system”. As in you should only follow these steps if you have cvsup’d(or updated your source some other way) and have completed the buildworld process. If you are simply compiling a new kernel to add a feature, use the “old” method of config, make, make install. That method is used only when you have *NOT* cvsup’d your source. It would
appear that the old way of doing it still works regardless of whether or not you’ve cvsup’d because that is the way I have done it for almost a year. But the documentation recommends that we use the new way, so we will. Here is a link to the handbook, scroll down towards the bottom
for more info on compiling the kernel.

I would like to thank the reader(s) that emailed me concerning the errors in my article. I’d also like to apologize to the readers, I try to not make mistakes like this, but I’m only human so sometimes they slip though.

Links of Interest
FreeBSD Handbook
comparison of -STABLE and -CURRENT

FreeBSD list of ports
FreeBSD Diary

If you have suggestions and ideas for future FreeBSD-related articles that you would like to see on OSNews, please let me know by emailing me directly.

About the Author:
Nathan Mace is currently a senior enrolled at the University of Charleston, West Virginia, majoring in Computer Information Systems. He is interested in all types of operating systems, expecially Unix-type OSes such as Linux, *BSD’s, and commercial Unices. Nathan can be reached at [email protected]


  1. 2002-03-19 6:58 pm
  2. 2002-03-19 7:00 pm
  3. 2002-03-19 7:14 pm
  4. 2002-03-19 7:37 pm
  5. 2002-03-19 8:21 pm
  6. 2002-03-19 8:41 pm
  7. 2002-03-19 8:53 pm
  8. 2002-03-19 9:22 pm
  9. 2002-03-20 12:06 am
  10. 2002-03-20 3:40 am
  11. 2002-03-20 4:59 am
  12. 2002-03-20 7:16 am
  13. 2002-03-20 8:52 am
  14. 2002-03-20 9:08 am
  15. 2002-03-20 1:05 pm
  16. 2002-03-20 4:04 pm
  17. 2002-03-20 7:18 pm
  18. 2002-03-20 7:21 pm
  19. 2002-03-20 7:33 pm
  20. 2002-03-20 7:36 pm
  21. 2002-03-20 9:02 pm
  22. 2002-03-20 10:32 pm
  23. 2002-03-21 12:16 am
  24. 2002-03-23 8:39 am
  25. 2002-03-25 7:37 pm