FreeBSD Buildworld Information
Information and tips regarding using cvsup
and buildworld on a FreeBSD 4.X i386 system
This document was last updated March 25, 2002.
FreeBSD 4.5-RELEASE is the current release,
FreeBSD 4-STABLE is our targeted version using cvsup.
Currently cvsup/buildworld updating from FreeBSD versions 4.1, 4.2, 4.3, 4.4, 4.5 directly to 4-STABLE should be ok.
Cvsup updating from FreeBSD versions prior to 4.1 directly to 4-STABLE will have problems that need special handling. Please check the /usr/src/UPDATING document after your cvsup, before any buildworld steps. If necessary, search the freebsd-stable and freebsd-questions mailing list archives for more information on this subject.
***The Usual Warnings Are Correct***
If you are uncomfortable with losing any data on the computer you are using these procedures on, then have tested backups of your data before proceeding.
It is not a bad idea to be familiar with using a fixit floppy or CD, booting single user, mounting your existing partitions, setting your path, etcetera, on your system before needing to apply them if a problem does occur.
Make sure you have enough free disk space
Check your available disk space with "df"
# df -k
Some approximate guidelines for available diskspace needed for a buildworld:
/usr/src needs at least 350MB
/usr/obj needs at least 390MB
/tmp needs at least 25MB
200MB for working space would be a good idea
So for a system with no /usr/src installed yet, and an empty /usr/obj directory, a good rule of thumb would be 1GB free in the /usr partition.
Create a backup set of current system information to floppy
Create the sintr script and run it to produce the text file /tmp/sintr/mybox.txt that contains important system information that can help in recovering a broken system. Copy the mybox.txt file to floppy disk or other removable media for safe keeping.
sintr.sh Bourne shell script
Create on disk backups of system information
Also create on disk backups of your /etc directory, the working kernel and the /modules directory. Your kernel copy should be kept in /, the /modules and /etc directory backups can be placed in another partition or subdirectory, in these examples I use /var as my backup location.
Copy your /etc directory tree to free space on /var
# cp -Rp /etc /var/etc.XXX
Make a backup copy of /modules on /var
# cp -Rp /modules /var/modules.XXX
Make a backup copy of your kernel on /
# cp -p /kernel /kernel.XXX
And make copies of your custom kernel configuration files, along with LINT and GENERIC to /var/etc.XXX/mykernelconfs
# mkdir -p /var/etc.XXX/mykernelconfs # cp /usr/src/sys/i386/conf/* /var/etc.XXX/mykernelconfs/
Create boot and fixit floppy sets
This is especially important if your FreeBSD system is your only access point to the internet. If you have another computer that can connect to the internet and create these disks as needed you may want to skip this step.
Make sure you have working boot, mfsroot, and fixit floppies or CD's for the version of FreeBSD you are currently running, also create a set of boot and fixit disks for the FreeBSD version you are upgrading to (4-STABLE). Floppy sets close in date to the 4-STABLE you are cvsuping to can be found at the link below:
Listing of 4-STABLE recent snapshots by date with a "floppies" subdirectory
Read /usr/src/UPDATING located on your hard drive
This document could change after every cvsup session, so be sure to check it after your cvsup to confirm that your procedures will be correct.
# more /usr/src/UPDATING
Make sure you are using version cvsup-16.1e or later
As of March 6, 2002 the current non-gui package is located at:
The current with-gui package is located at:
To install the cvsup-16.1f.tgz package:
# pkg_add -v cvsup-16.1f.tgz
If cvsup is already installed check it's version:
# cvsup -v CVSup client, non-GUI version Copyright 1996-2001 John D. Polstra Software version: SNAP_16_1f Protocol version: 17.0 Operating system: FreeBSD4 http://www.polstra.com/projects/freeware/CVSup/ Report problems to firstname.lastname@example.org
CVSup has extensive documentation in the form of an FAQ, located at: www.polstra.com/projects/freeware/CVSup/faq.htm
Find your "best" cvsup server using traceroute
Go to www.freebsdmirrors.org cvsup servers for a listing of FreeBSD cvsup servers, then start testing to determine which site is best for you.
# traceroute cvsup1.freebsd.org
The last line from the traceroute should be the cvsup server, the number of hops is the first number on that line (lower is better), the last number on the line is the average response time (lower is better). Average response time is the most important factor. Two sites may have similar response times, so a lower number of hops would be the deciding factor.
Setup your /etc/cvsupfile
Edit your /etc/cvsupfile line:1 accordingly from your traceroute tests.
from: *default host=cvsup1.FreeBSD.org
to: *default host=cvsup2.au.freebsd.org
(which would select a cvsup server in Australia :-)
Example /etc/cvsupfile for a system already running FreeBSD 4-STABLE
*default host=cvsup1.FreeBSD.org *default base=/usr *default prefix=/usr *default release=cvs *default tag=RELENG_4 *default delete # If your network link is a T1 or # faster, comment out the following line. *default compress src-all *default tag=. ports-all doc-all
If cvsuping for the first time "Adopt" your current source tree
Adopt your current source tree before cvsuping to a later release. This means running your cvsup the very first time with your current release tag.
An example follows:
You have installed from a FreeBSD 4.2 CD set and have also installed the FreeBSD 4.2 source distributions, now you want to cvsup/buildworld to 4-STABLE. Your first cvsup session would use a cvsupfile like this to adopt your 4.2-RELEASE source tree.
Example /etc/cvsupfile for a system adopting the FreeBSD 4.2-RELEASE source files:
*default host=cvsup1.FreeBSD.org *default base=/usr *default prefix=/usr *default release=cvs *default delete use-rel-suffix # If your network link is a T1 or # faster, comment out the following line. *default compress src-all tag=RELENG_4_2_0_RELEASE list=cvs:RELENG_4 *default tag=. ports-all doc-all
You do not need to do a buildworld after this cvsup adoption step, this is used to synchronize your source tree file additions and deletions properly.
Now you run a second cvsup using this src-all line "src-all tag=RELENG_4" to cvsup the 4-STABLE source files. See the following cvsupfile example.
Example /etc/cvsupfile for a system that has finished adopting the FreeBSD 4.2-RELEASE source files and now is ready to cvsup to the 4-STABLE source files :
*default host=cvsup1.FreeBSD.org *default base=/usr *default prefix=/usr *default release=cvs *default delete use-rel-suffix # If your network link is a T1 or # faster, comment out the following line. *default compress src-all tag=RELENG_4 *default tag=. ports-all doc-all
After finishing this cvsup step you should edit your /etc/cvsupfile according to the "Example /etc/cvsupfile for a system already running FreeBSD 4-STABLE" listed previously in this document.
Here is the listing of FreeBSD release tags
Tip: if you are using a dial-up or slow internet connection and did not install the FreeBSD source files from your CD, you can save a lot of bandwidth by installing the source distributions from the sysinstall menu before you run your first cvsup session, and then adopting your current release before updating to FreeBSD-STABLE.
Run cvsup from a shell script, with each session logged
Create and use this Bourne shell script for cvsup sessions with a running log:
mycvsup.sh Bourne shell script
Or if you want to just use the command line without logging:
# /usr/local/bin/cvsup -g -L 2 /etc/cvsupfile
Setup your /etc/make.conf file
Examine your /etc/make.conf file and confirm that all overrides for the /etc/defaults/make.conf file are correct for the system you are building for.
If you don't have an /etc/make.conf file you have not read and followed the handbook chapter on makeworld you were directed to earlier in this article.
You would normally have at least these settings in your /etc/make.conf for a standard Pentium III system:
CPUTYPE=i686 CFLAGS= -0 -pipe NOPROFILE=true # Avoid compiling profiled libraries
Example CPU types from the 4-STABLE /etc/defaults/make.conf
# Currently the following CPU types are recognized:
# Intel x86 architecture:
# (AMD CPUs) k7 k6-2 k6 k5
# (Intel CPUs) p4 p3 p2 i686 i586/mmx i586 i486 i386
# Alpha/AXP architecture: ev6 pca56 ev56 ev5 ev45 ev4
It is up to you to select and edit the correct processor type and other settings in your /etc/make.conf file. Some other settings you may want to check into are:
# By default, the ports collection attempts to use XFree86 3.3.X. # If you are running XFree86 4.X, uncomment this line. # #XFREE86_VERSION= 4 # #USA_RESIDENT= YES # # if you want the "compat" shared libraries installed as part # of your normal builds, uncomment these: # #COMPAT1X= yes #COMPAT20= yes #COMPAT21= yes #COMPAT22= yes #COMPAT3X= yes #COMPAT4X= yes # # The list of languages and encodings to build and install # #DOC_LANG= en_US.ISO8859-1 ru_RU.KOI8-R
Start the buildworld process
"YOURKERNEL" is an example kernel configuration file name, substitute your custom kernel name. If you are not using a customized kernel then use "GENERIC" as your kernel configuration file name.
Run your cvsup if you have not already.
Before every buildworld:
# cd /usr/obj/ # pwd (confirm you are in /usr/obj) # chflags -R noschg * # rm -rf usr # ls -la (to confirm everything in /usr/obj/ was deleted) # cd /usr/src # make cleandir && make cleandir (yes, run make cleandir twice)
From the /usr/src/UPDATING file is a step necessary if you have been building linux modules. The "$KERNCONF" in this following paragraph represents the name of your custom kernel that you have been building. These steps are not harmful if you have not been building linux modules, so if in doubt, go ahead and run them.
20011110: Some linux module changes, merged from current, require that you clean out the old compile directory. If you are building with MODULES_WITH_WORLD=yes, then you need to cd to src/sys/modules/linux and run "make cleandir". If not, then you need to cd src/sys/compile/$KERNCONF and do a make modules-clean.
Our pre-buildworld preperation is done, on to the buildworld
# cd /usr/src # make buildworld # make buildkernel KERNCONF=YOURKERNEL # make installkernel KERNCONF=YOURKERNEL # shutdown -r now
It is strongly advised to run the installworld and mergemaster steps in single user mode. Reboot into single user mode using your newly created kernel from the make kernel steps. This reboot also helps to confirm that your new kernel is working before continuing with the installworld.
Get to single user mode at bootup
When your screen shows:
Hit [Enter] to boot immediately, or any other key for command prompt.
You then press the space bar to interrupt the boot loader:
At the "ok" prompt type in:
Accept /bin/sh as your shell, then at the "#" prompt type in:
# fsck -p # mount -t ufs -a # swapon -a
You have now booted into single user mode, fsck'ed your drive, mounted your ufs partitions, and turned disk swapping on. Now on to the installworld:
# cd /usr/src # make installworld # mergemaster -v
When running mergemaster the safe answer is usually "i" to install the new file, you can always go back to your /etc/myetc/ backup (see backup steps above) and reconcile any differences by hand. A few examples of user edited files that can change are master.passwd, group, inetd.conf, hosts, and named.conf.
The mergemaster screen represents a split view of the old version of the file and the proposed new version, line by line. The left side of the screen represents the existing file information, the right side of the screen represents the new file information. So when using the "m" (merge) key to select a merge you have the option of selecting "r" (right) to insert the proposed new line into your file, selecting the "l" (left) key keeps your existing line. After using the "m" key and completing your merge it is a good idea to use the "v" (view) key to view the proposed merged file before using the "i" (install) key to install the merged file. You will be given the opportunity to redo the merge again from the beginning of this file if you find something wrong in your proposed merged version.
For files that you have changed, you probably should select the "m" option and always select the "r" option for the new version line and "l" for the rest of the lines. If some of the lines in the new version are things you want, select them with "r". New user or group lines for the master.passwd and group files should always be installed because the operating system needs these users and groups to correctly handle ownership and permissions for base-system programs and daemons
Once you have done this, the merged/installed files will no longer be listed if you run mergmaster again for this installworld session.
If mergemaster wants to recreate your /dev entries, rebuild any databases, alias files, or run mk_pwdb on your master.passwd, always reply yes to allow the mergemaster script to do these steps for you.
Reconcile any needed changes by hand to your /etc files if necessary after mergemaster has run, then shutdown and restart with your updated FreeBSD system.
When rebooted you can type in:
# uname -a
To confirm the version of the FreeBSD kernel that you are now running.
Update your sysinstall program files
Do not do this step until you have succeeded with the previous steps and your system appears to be working properly.
# cd /usr/src/release/sysinstall # make clean # make all install clean
If something goes wrong during the buildworld process
Make sure your /etc/group file has not had necessary groups removed. The solution is to examine /usr/src/etc/group and compare its list of groups with your own. If they are any groups in the new file that are not in your file then copy them over. Similarly, you should rename any groups in /etc/group which have the same GID but a different name to those in /usr/src/etc/group. The same procedure applies to the master.passwd file, but here you need to run "vipw" as root on one screen to edit the passwd file, while examining /usr/src/etc/master.passwd in another screen.
Generally, when you have a buildworld failure run your cvsup again, then go back to the "Before every buildworld" step and repeat the procedure.
If something goes wrong during the buildkernel process
Is your /usr/src/sys/i386/conf/YOURKERNEL file correct?, you can use GENERIC and LINT to get examples and information about a correct kernel configuration.
If you are just building a new kernel and did not clean out the /usr/obj directory, then cd to /usr/obj/usr/src/sys and rm -rf the directory YOURKERNEL. Also check for a directory called /usr/src/sys/compile/YOURKERNEL and delete it before trying to buildkernel again.
If something goes wrong during the installworld process
Make sure you are not running in multiuser mode, or that "securelevel" is not enabled, to make sure securelevels are disabled edit your /etc/rc.conf file and add this line:
If it is already set to "YES" than edit it to "NO" and perform a standard shutdown/restart before continuing with the installworld process. Secure levels are a good thing and you may want to investigate, and enable them, after you have your system updated.
Have you changed your mount options for the /tmp directory?, if so, remove any options like "nodev" and "nosuid" from the /etc/fstab entry for /tmp. The only option in /etc/fstab for /tmp should be "rw" after fixing this unmount and remount /tmp and try the installworld again. Reapply your mount options changes to /etc/fstab when done if so desired.
My kernel won't boot!
If your new kernel is incorrect and will not boot, or runs improperly, then shutdown if possible, then reboot and press the space bar to interrupt the boot loader. At the ok prompt enter:
unload boot kernel.old
To restart with your backup kernel created by the last new kernel install. This file will be overwritten every time you do a "make installkernel" so making a backup named kernel copy is a good thing.
Or if you made a named kernel copy:
unload boot kernel.XXX
Or as a last resort:
unload boot kernel.GENERIC
Some things to check if you still have problems:
Did you check your /etc/make.conf, and that the /etc/defaults/make.conf are correct. All your local edits are done to the /etc/make.conf file. The /etc/defaults/make.conf file is a system installed file and should not be edited. Example source for the /etc/defaults/make.conf is located at /usr/src/etc/defaults/make.conf.
Is your computers date set correctly? if not, correct it.
Do you have incorrect dates on files in your /usr/src directory tree? they could be set to a point in the future.
As a last resort you can delete your /usr/src directory and cvsup a fresh copy. This can be a long process on slow internet connections. Make sure you copy your custom kernel files from the /usr/src/sys/i386/conf/ directory to another location before deleting the /usr/src directory.
If you still have problems, record the errors and search the freebsd-STABLE and freebsd-questions lists before asking for help. Good background information, detailed error messages, and an appropriate subject line, will produce the best results from the mailing lists.
The FreeBSD Mailing Lists at FreeBSD.org
Thanks to Jim Conner (SnafuX/NOTJames) for help with the shell scripts.
Thanks to Kevin Oberman for help with this document.
Thanks to David Wolfskill for input on the sintr.sh script
Corrections? / Additions? / Suggestions? / Links?
Please email any and all such to: