| Warden® |
THIS PAGE IS CHANGING IN 9.1 AND IS STILL BEING UPDATED. UNLESS YOU ARE BETA TESTING 9.1, YOU SHOULD INSTEAD REFER TO THE PUBLISHED VERSION OF THE USERS HANDBOOK THAT MATCHES YOUR PC-BSD VERSION
Warden® is an easy to use, graphical jail management program. Using Warden®, it is possible to create multiple, isolated virtual instances of FreeBSD which can be used to run services such as Apache, PHP, or MySQL in a secure manner. Each jail is considered to be a unique FreeBSD operating system and whatever happens in that jail will not affect your operating system or other jails running on the PC-BSD system.
Warden® has been redesigned for PC-BSD 9.1, and is now part of Control Panel. A command line version is also available for those who prefer to work from the command line or to script their jail management.
Some of the new features in Warden® include:
- ability to create both traditional FreeBSD jails for running network services and (a less secure) ports jail for safely installing and running FreeBSD ports/packages from your PC-BSD system
- ability to create multiple traditional and ports jails
- ability to create IPv4, IPv4/IPv6, and IPv6-only jails
- ability to set multiple IPv4 and IPv6 addresses per jail
- ability to quickly install meta packages of common network server applications on a per-jail basis
- ability to use Update Manager for installed meta packages on a per-jail basis
- ability to use User Manager to manage user accounts on a per-jail basis
Creating a Jail using Warden®
Warden® can be started by clicking on its icon in Control Panel or by typing pc-su warden gui from the command line. You will be prompted for the adminstrative password as only the superuser can create and manage jails.
The first time you start Warden®, you will be presented with the main window, seen in Figure 7.10a. It will indicate that no jail is selected as none have been created yet.
Figure 7.10a: Initial Warden® Screen
To create your first jail, click the + button or go to File ➜ New Jail. A jail creation wizard, seen in Figure 7.10b, will launch.
Figure 7.10b: Creating the New Jail
The first screen in the jail creation wizard will prompt you for the following information:
IP Address: this is the IPv4 or IPv6 address you will use to ssh into the jail and access its contents. Choose an address on your network that is not already in use by another computer or jail.
Hostname: you can change the default of "Jailbird" to another value. The hostname must be unique on your network. You should use a hostname that reminds you of the type of jail and your reason for creating it.
When finished, click Next to select the type of jail, as shown in Figure 7.10c:
Figure 7.10c: Select the Type of Jail
There are two types of jails supported by Warden®:
- Traditional Jail: select this type if you are creating the jail in order to install and run network services. For example, this type of jail is appropriate if you wish to run a web server or a database which is accessible to other systems on a network or over the Internet. This is the most secure type of jail as it is separate from the PC-BSD host and any other jails that you create using Warden®.
- Ports Jail: select this type of jail if your intention is to install software using FreeBSD packages and ports and you wish to have access to that software from your PC-BSD system. This type of jail is less secure then a traditional jail as applications are shared between the jail and the PC-BSD system. This means that you should not use this type of jail to install services that will be available to other machines over a network. More information about using FreeBSD ports and packages is available in the Using a Jail section of the Guide.
If you select the "Traditional Jail" and click Next, you will be prompted to set the root password as seen in Figure 7.10d.
Figure 7.10d: Setting the Traditional Jail's Root Password
Input and confirm the password to see the screen shown in Figure 7.10e. If you instead select to create a "Ports Jail", you will go directly to Figure 7.10e once you click Next.
Figure 7.10e: Select the Jail Options
This screen allows you to install the following options:
Include system source: if you check this box, /usr/src/ will be populated with FreeBSD source. Some ports require source in order to build. Source can also be used to rebuild the jail's world or a new driver. Note that while you can compile a kernel within a jail, it will not use it as a jail uses the host system's kernel (i.e. the kernel running on your PC-BSD system).
Include ports tree: if you check this box, the ports tree will be installed into /usr/ports/. This will allow you to compile FreeBSD ports within this jail.
Start jail at system bootup: if this box is checked, the jail will be started (become available) whenever you boot your main system. If the box is not checked, you can manually start the jail whenever you wish to access it using Warden®.
Once you have made your selections, click the Finish button to create the jail. Warden® will display a pop-up window containing status messages as it downloads fbsd-release.txz and creates and configures the new jail.
NOTE: this initial download only occurs the first time you create the jail and contains the FreeBSD operating system (world), source, and ports collection. Subsequent jails will reuse the downloaded tarball to obtain the files needed to create the new jail.
Once Warden® is finished creating the jail, a message should appear at the bottom of the pop-up window:
Success! Jail created at /usr/jails/192.168.2.150 Changing root password on: 192.168.2.150
Click the Close button to return to the main screen.
Managing Jails
Once the jail is created, it will be listed in the main screen and some information about that jail will appear in the Info tab. If you have created multiple jails, the currently highlighted jail will have its information shown in the Info tab. You can use the IP and Host buttons to toggle between viewing the list of jails either by IP address or by hostname. In the examples shown in Figure 7.10f and 7.10g, 2 jails have been created. The jail in Figure 7.10f is a traditional jail with its IP address highlighted. The jail in Figure 7.10g is a ports jail with its hostname highlighted.
Figure 7.10f: Viewing the Info of a Highlighted Jail
Figure 7.10g: Viewing the Info of Another Jail
The Info tab contains the following information:
Jail Type:
Size on Disk:
Start at boot:
Active Connections:
Additional IPs:
Listening on Ports:
Tools Tab
The tools tab, shown in Figure 7.10h, allows you to manage common configuration tasks within a jail.
NOTE: make sure that the desired jail is highlighted when using the Tools tab.
Figure 7.10h: Tools Tab for the Highlighted Jail
This tab provides the following buttons:
User Administrator:
Launch Terminal:
Check for Updates:
Export Jail:
Packages Tab
Right-Click Menu
A jail's right-click menu contains the following options:
Start or Stop this Jail: allows you to start a jail (if it is currently not running) or to stop a jail (if it is currently running). You will not be able to SSH into a jail until it has been started. The icon next to the jail will change to indicate the current status: a red X for a stopped jail and a blue arrow for a started jail.
Toggle Autostart: will toggle a jail's Autostart between Disabled (does not automatically start when the PC-BSD system is booted) and Enabled (will start the jail when the PC-BSD system is booted). The Info tab will be updated to indicate the new "Start at boot" status. Note that toggling autostart will not affect the running status of the jail (i.e. it does not start or stop the jail right now) as autostart is only used when the system boots.
Export jail to .wdn file: Exporting a jail allows you to save the jail (and all of its software, configuration, and files) as a .wdn file. This allows you to quickly clone a pre-configured jail to a new jail on either the same or another PC-BSD system. The exported jail will end with a .wdn extension and the filename will be the IP address of the jail. When exporting a jail, a pop-up window will prompt you to choose the directory in which to store the backup. A progress bar will indicate that the export is in progress. Creating the .wdn file may take some time, especially if you have installed src, ports, or software.
NOTE: you should close all network connections to the jail before exporting it as Warden® will need to stop the jail in order to back it up. If your jail is running services (e.g. a webserver), export the jail at a time that will least impact network connections to the jail.
Delete Jail: this will remove the jail and all of its contents from the PC-BSD system.
File Menu
To create a new jail using the .wdn backup, select File ➜ Import Jail. You will be prompted to browse to the location of the .wdn file. Once selected, you will be prompted whether or not to use the same IP address for the new jail. If you are creating a new jail on the same system that still has the original jail installed, select No and input the IP address for the new jail. However, if you have deleted the original jail or need to restore that same jail on another computer (for example, there was a hardware failure on the system containing the original jail), you can choose to use the same IP address. You will then be prompted whether or not to use the same hostname. Again, only say Yes if that hostname is no longer in use; otherwise, select No and input a unique hostname for the jail. Warden® will then recreate the jail with all of the original settings. Whether or not those settings include the original IP address and hostname depends upon your selections.
Jail Menu
Accessing the Jail
Before you can access a jail, make sure that it has been started (has a blue arrow icon) next to its IP address or hostname. If it is not started, right-click the jail and select Start Jail from the menu.
If you wish to configure the jail from your PC-BSD system, highlight the jail in Warden®, then go to Tools -> Launch Terminal. This will open up a root terminal so that you can configure the jail.
If you wish to configure the jail from another system that does not have Warden®, you can use the ssh command to login to the jail over a secure connection. Before you can do this, you will need to create a user account to use for login purposes. If you have created a ports jail, you will also need to set the root password so that you can perform administrative tasks within the jail.
To create the user account from Warden®, highlight the jail and click Tools -> User Administrator.
CAN ALREADY LOGIN BUT NO HOMEDIR ON JAIL
When using ssh, include the IP address of the jail that you wish to connect to. When prompted, input the The following example will login to the jail with the IP address of 192.168.2.102:
ssh 192.168.2.102
to its IP address using the username and password you configured for the jail. Once you have logged into the jail, you can do anything that you could do on a FreeBSD system. This is a good way to learn how to use FreeBSD without affecting your PC-BSD desktop. The FreeBSD Handbook is a handy reference for learning how to perform almost any task on a FreeBSD system.
Using the Command Line Version of Warden®
The Warden® GUI is based on a Bourne shell script. This script can be manually run from the command line on a PC-BSD server or by users who prefer using the command line. Advanced users can also refer to the command line version in their own scripts.
If you type warden at the command line, you will receive a summary of its usage:
warden Warden version 1.2 --------------------------------- Available commands Type in help <command> for information and usage about that command help - This help file gui - Launch the GUI menu auto - Toggles the autostart flag for a jail chroot - Launches chroot into a jail create - Creates a new jail details - Display usage details about a jail delete - Deletes a jail export - Exports a jail to a .wdn file import - Imports a jail from a .wdn file list - Lists the installed jails pkgs - Lists the installed packages in a jail start - Start a jail stop - Stops a jail set - Sets options for a jail type - Set the jail type (portjail/normal)
Each command has its own help text that describes its parameters and provides a usage example. For example, to receive help on how to use the warden create command, type:
warden help create Warden version 1.2 --------------------------------- Help create Creates a new jail, with options for system source, ports and autostarting. Available Flags: --src (Includes /usr/src system source) --ports (Includes the ports tree) --startauto (Start this jail at system boot) --portjail (Make this a portjail) Usage: warden create <IP> <HOSTNAME> <flags> Example: warden create 192.168.0.5 jailbird --src --ports --startauto
You do not need superuser access to use the view commands but will for any commands that create or manage a jail. The warden command will display an error message if a command requires superuser access and you currently are not the superuser. On PC-BSD, you can put pc-su at the beginning of the warden command to be prompted for the administrative password. On a PC-BSD server, you can type su to become superuser, then repeat the warden command.
Using a Jail
ADD NOTE ON HOW TO ACCESS JAIL AND DIFFERENT TYPES OF JAILS
A ports jail provides an environment where users who are new to FreeBSD packages and ports can safely experiment and learn how to use the FreeBSD software management command line tools without affecting the software that was installed with the operating system.
NOTE: advanced FreeBSD users can continue to use FreeBSD packages and ports on their PC-BSD installation without using ports jail. However, if you do not consider yourself to be an advanced FreeBSD user, you should experiment learning how to use ports and packages within the ports jail utility. That is, do not run the commands described in this section from a command prompt; only run these commands from within a ports jail console.
You can install system source using the "Fetch System Source" button in the Tasks tab of System Manager.
Once system source is installed, you'll see messages similar to the following if you press b:
As you can see from Figure 7.1a, ports jail opens in a console terminal:
Figure 7.1a: Ports Jail
The jail itself is like a self-contained FreeBSD installation. You can see what this means if you spend a few minutes comparing the outputs of commands such as ls /, pkg_info, and more /etc/rc.conf between the ports jail and a regular console. It should be noted that "self-contained" does impose limitations. For example, any ports you compile within the jail will not exist outside of the jail. However, you can still access any application installed into a jail by typing portjail run name_of_command. You can also use that command when creating a desktop icon or menu item for the installed application. (This only accepts the very first word after run which means more complex operations may need to be handled by a script written inside the portjail.) X11-based ports as described in this forum thread may need to be preceded by xhost + before attempting to invoke by portjail run <appname>
Installing FreeBSD Packages
A FreeBSD package is an installation file that contains an application as well as installation information useful to the operation system, such as a list of dependencies (other software required by the application). Packages have been pre-tested for FreeBSD, meaning that they should be fairly easy to install and should work once installed. There are over 23,000 FreeBSD packages to choose from. FreshPorts is an excellent place to browse for packages and to research the files that get installed with a FreeBSD package.
When dealing with FreeBSD packages, the following command line utilities are used:
pkg_add: used to install packages. If you have never used this command before, take the time to read man pkg_add to get an overview of how this command works.
pkg_delete: used to uninstall packages. If you have never used this command before, take the time to read man pkg_delete to get an overview of how this command works.
pkg_info: used to get more information about the packages that have been installed. This command provides many useful switches so it is well worth your time to read through man pkg_info and to experiment with various switches.
To install a package, become the superuser from within ports jail and use the remote (-r) switch to install the specified package from the FreeBSD packages repository. For example, this command will install the electric package:
pkg_add -r electric Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/amd64/packages-9-stable/Latest/electric.tbz... Done.
You should receive a message indicating that the package was successfully fetched, then your prompt back. Depending upon what is already installed in your ports jail, your messages may indicate that dependent packages were also fetched. Some packages include post-installation instructions that will be displayed in the message. Occasionally you will see a warning about a version mismatch; you can ignore these as they do not affect the installation of the package. Unless the message includes an error indicating that the system was unable to fetch or install the package, the installation was successful.
Since the command is issued from within Ports Jail, the installed package will not appear as a menu entry or as an icon on the desktop.
Most packages install their binary (executable) in /usr/local/bin and configuration files in /usr/local/etc/. You can find out exactly what was installed using the -L (list) switch. If you include -x, you will not have to type in the entire name and version of the package as pkg_info will match any installed packages containing your query string.
pkg_info -Lx electric | more Information for electric-7.0.0_4: Files: /usr/local/bin/electric /usr/local/share/electric/lib/.cadrc /usr/local/share/electric/lib/ALS.help /usr/local/share/electric/lib/AllDialogs.c <snip rest of output>
The pkg_delete command can be used to uninstall either a package or a port from within ports jail. If you include the -x switch, you do not have to give the full name and version of the software. Be sure to give enough of a name so that you do not inadvertently uninstall other software matching the name:
pkg_delete -x electric
If you just get the command prompt back, the delete was successful. You can verify this by checking that the package no longer exists in the package database:
pkg_info | grep electric
You will just get your prompt back if no installed software matches that name.
If the software has other applications that depend upon it, pkg_delete will refuse to uninstall it. If you wish to override this setting, you can use the -xf switch to force the delete. However, use the force switch with caution as forcibly removing software can adversely affect the applications that required it as a dependency.
Compiling FreeBSD Ports
A FreeBSD port is a set of instructions (contained within a Makefile) for successfully compiling the source code for an application on a FreeBSD system. The FreeBSD ports collection has been arranged into a series of software categories; each category contains a subdirectory for each application in that category. The application's directory contains the application's Makefile as well as any other files needed to compile and install the application. If you click on the CVSWeb link of an application at FreshPorts, you can read the port's Makefile. Figure 7.1b shows the CVSweb info for the electric port. To navigate to this page in your browser, go to FreshPorts, search for "electric", then click the link for electric 7.0.0_4, then click on CVSWeb.
Figure 7.1b Viewing a Port's Information at FreshPorts
If you click the link for Makefile, you can read the commit messages for every version of the Makefile; this can give you a good idea of how long the port has been available, how often it is updated, and any major changes that have occurred. Alternately, to view the current Makefile, click on the Rev. number--in this case, 1.24. The distinfo contains the checksums for the source files; again, you can either read the current revision or scroll through the list of commits. The pkg-descr contains a description of the software; if you read the revision, it will begin with the commit message. The pkg-plist contains a list of what is installed (i.e. it is the equivalent of running pkg_info -Lx as described in the FreeBSD packages section). When reading this list, mentally replace anything between %% markers with /usr/local/.
If you wish to learn how to compile ports, you will need to first install the ports collection into the ports jail. There are several ways to accomplish this so you should select one of the following methods. You will know that you have the ports collection when /usr/ports/ is populated with many subdirectories, each representing a category of software.
Method 1: Go to Control Panel ➜ System Manager. After inputting the administrative password, click on the Tasks tab, seen in Figure 7.1c:
Figure 7.1c: Installing the Ports Collection using the Tasks Tab of System Manager
In the "Ports Console" section, click "Fetch Ports Tree" and a pop-up window will indicate that it is fetching ports and that it may take a while. Be patient, as it is downloading and installing a tarball that is about 50MB in size. Note that you do not want to select the option to "Fetch System Ports Tree" as this will install ports onto the main system rather than into the ports jail.
Method 2: Make sure that you are in the ports jail, become the superuser using the su command, then issue these commands:
cd /usr fetch ftp://ftp.freebsd.org/pub/FreeBSD/ports/ports/ports.tar.gz tar xzvf ports.tar.gz
Method 3: Make sure that you are in the ports jail, become the superuser using the su command, then issue this command:
portsnap fetch extract
Once you have the ports collection installed into your ports jail, change to the subdirectory of the application you wish to install, for instance /usr/ports/cad/electric, and issue the command to make and install the application:
cd /usr/ports/cad/electric make install clean
How long this command will take can range from a few minutes to many hours, depending upon the size of the application and the speed of your system. The make command will spit out many messages, most of which you can ignore as they are simply indications of what source is currently being compiled. Occasionally a menu will appear asking you to select from a list of options. When in doubt, keep the default options. If you understand the options, you can use your arrow and enter keys to toggle an option on or off. When finished, use the tab key to navigate to OK and press enter to continue the compilation process. Occasionally, make will encounter an error and will stop with an error message. If the solution for the error is not obvious to you, try a web search for the keywords in the error message. Keep in mind that this is a learning exercise and that you may be forced to learn some things along the way.
Note: Sometimes a port will require a file to be downloaded seperately from the make process and also instructs that it be placed into the /usr/ports/distfiles/ directory. The proper location to copy the downloaded file, so that the portsjail can find it is /usr/jails/portjail/usr/ports/distfiles/. Copying or moving the file requires root permissions. One port that requires this action is jdk16.
Keeping the Jail and its Software Up-to-Date
Any software that you install using the Packages tab within Warden® can be kept up-to-date using Update Manager. Simply highlight the jail and go to Tools -> Check for Updates.
However, you will need to manually upgrade any software that you installed using pkg_add or any ports that you compiled yourself. In order to do this, you will need:
- to create a sup file to keep your ports tree in sync with the latest version
- to install a utility to upgrade FreeBSD ports
- to read /usr/ports/UPDATING so you're aware of any gotchas before you attempt to upgrade your software
Note: this entire section assumes that you are the superuser.
Create a sup file
PC-BSD provides some sample sup files in /usr/share/examples/cvsup/. They are well commented, making it easy to edit them to meet your needs. You should copy one of the sup files, edit it, and save it to either your regular user's home directory or the root user's home directory; in other words, save it to a location that you regularly backup and which isn't likely to be overwritten by a system upgrade. Once edited, your supfile will look something like this:
*default host=cvsup.ca.freebsd.org *default base=/usr/local/etc/cvsup *default prefix=/usr *default tag=RELENG_9 *default release=cvs delete use-rel-suffix compress src-all ports-all tag=.
Let's look at each line in more detail:
1. this line is mandatory and you should modify it to choose a mirror that is geographically close. You'll find the list of mirrors here.
2. this line is mandatory and the directory must be created if it does not exist. Be sure to choose a directory on a partition with plenty of available disk space--for example, /usr usually has more disk space than /var.
3. this line is mandatory and should point to /usr.
4. this line is mandatory and you should modify it to contain the tag for your operating system. You'll find the list of tags here. If you're running PC-BSD 9.1, use RELENG_9 if you want to receive all src changes (e.g. new drivers and features) or use RELENG_9_1 if you are only interested in receiving security fixes. You can only have one tag so you must pick one or the other.
5. this line is mandatory and should be left as-is.
6. include this line if you wish to keep your source up-to-date. Source is needed if you wish to recompile your kernel, update the operating system by rebuilding world, or to recompile the latest version of a driver. Source will be put into /usr/src and takes up about 600MB of disk space.
7. include this line if you wish to keep your installed ports/packages up-to-date. Ports will be put into /usr/ports/ and take up about 1.2GB of space. That amount of disk space will grow as you upgrade your ports since downloaded source files for the software will be added to /usr/ports/distfiles/.
Once you have a supfile, you can sync your src and/or ports using the following command. If the command is successful, you'll see messages indicating that you are connected and can watch the progress as new and modified files are downloaded:
csup -L2 /pathto/supfile Parsing supfile "cvs-supfile" Connecting to cvsup.ca.freebsd.org Connected to 206.75.218.52 Server software version: SNAP_16_1h Negotiating file attribute support Exchanging collection information Establishing multiplexed-mode data connection Running Updating collection src-all/cvs Edit src/bin/ps/extern.h Add delta 1.39.2.2 2010.10.25.15.01.40 attilio Edit src/bin/ps/keyword.c <snip a lot of output> Edit ports/x11-toolkits/phat/Makefile Add delta 1.10 2010.10.25.20.09.06 trasz Shutting down connection to server Finished successfully
If your messages instead indicate a problem with the connection, check that your Internet connection is active. If it is, try using a different mirror in your sup file.
Install an Upgrading Utility
The ports-mgmt section of the FreeBSD ports collection contains many utilities for managing ports. Popular utilities for upgrading ports include:
- portupgrade: easy to use and effective, but requires the Berkeley DB as a backend and the ruby programming language. If you are upgrading a lot of ports, you may find it inconvenient for the process to pause while it waits for you to notice that you must attend to a configuration option screen.
- portmaster: offers the advantage of not requiring a database or another programming language as a dependency. It also displays all of the configuration option screens at the beginning of the process so you don't have to worry about them pausing the upgrade.
- port maintenance tools: installs a selection of utilities.
- porteasy: allows you to upgrade your ports without downloading the entire ports tree.
If you don't already have a favourite upgrade utility, spend some time perusing the ports-mgmt section and experiment with the utilities that interest you. You'll also find utilities that allow you to save disk space, check for security vulnerabilities, remove unneeded dependencies, and other useful tasks dealing with ports management.
Read /usr/ports/UPDATING
Before upgrading any ports, always read through /usr/ports/UPDATING first. This file contains any gotchas or special instructions that are needed to upgrade certain ports. Ports maintainers add to this file as new gotchas are discovered. However, you will want to start reading the file at the entry that is closest to the date that your version of PC-BSD was released (if you have not upgraded anything yet) or the date you last upgraded, and read your way up to the top of the file. There is a handy entry to look for:
20110224: AFFECTS: Nobody AUTHOR: wxs@FreeBSD.org FreeBSD 8.2 and 7.4 released.
But for earlier versions such as PC-BSD 8.1 which was released on July 20. You will want to start reading at this entry:
20100715: AFFECTS: users of lang/perl* AUTHOR: skv@FreeBSD.org lang/perl5.12 is out. If you want to switch to it from, for example lang/perl5.10, that is:
as it is for the 15th of July of 2010, the first entry nearest to July 20. As you read through the entries from that date up to the last entry at the beginning of the file, make note of any entries that match the software you have installed. If you are unsure of what software is installed, this command will tell you:
pkg_info | more
Occasionally, a software upgrade (e.g. perl, kde, gnome) will affect many applications. If you come across such entries that affect your installed software, follow the instructions carefully.
Note: if there have been major changes or there are a lot of entries that affect you, you should decide if it is worth your time to upgrade or if you prefer to wait until the next version of PC-BSD is released (as each release contains the most updated software as of the release date). The more software there is to update, the longer the time required to complete the upgrade process.
If your ports are already up-to-date and you prefer to be notified as new entries are added to /usr/ports/UPDATING, consider subscribing to its RSS feed.
Perform the Upgrade
After using the csup command to update your ports and reading /usr/ports/UPDATING, you are ready to upgrade your installed software.
If you are using portupgrade, you need to first update the ports database and check to see which ports need updating. Note that the following commands are installed for you when you install portupgrade:
portsdb -Fu /usr/ports/INDEX-8.bz2 100% of 1421 kB 114 kBps 00m00s done [Updating the portsdb <format:bdb_btree> in /usr/ports ... - 22250 port entries found ........1000.........2000.........3000.........4000.........5000.........6000.........7000.........8000 .........9000....10000.......11000.........12000.........13000.........14000.........15000.........16000 .........17000.........18000.........19000.........20000.........21000.........22000.. ..... done] portversion -l "<" linkchecker < mpg123 < p5-Object-InsideOut < tomcat <
In this example, 4 ports are out-of-date. You can then upgrade the desired port using the following command:
portupgrade -rR tomcat
It is important to include -rR switches as this will make sure all of the ports dependencies and any ports that depend on this port are also upgraded. If you don't do this, you may find that dependency problems will start to creep up overtime. If you are concerned that the upgrade may fail or that you may not like the new version of the port, include -b which will create a package of the current port. If something happens, you can uninstall the new version and reinstall the old version using the created package. portupgrade supports many switches so it is recommended that you take the time to read through man portupgrade to see which switches are of interest to you.
If you are using portmaster, this command will look for out-dated ports and offer to upgrade them for you:
portmaster -a
===>>> Gathering distinfo list for installed ports
===>>> Starting check of installed ports for available updates
<snip some output>
===>>> The following actions will be taken if you choose to proceed:
Upgrade mpg123-1.12.3 to mpg123-1.12.5
Upgrade p5-Object-InsideOut-3.69 to p5-Object-InsideOut-3.72
Upgrade linkchecker-5.3 to linkchecker-5.4
Upgrade tomcat-6.0.29 to tomcat-6.0.29_1
===>>> Proceed? y/n [y]
If you press enter to accept the default of yes, the upgrade will begin. If any of the ports have configuration options, you will be presented with some menus to make your selections. As each upgrade completes, you will be asked if you want to delete the tar.gz of the source for the old version of the software (which can save disk space); you can include -D or -d if you don't want to see this prompt. There are many switches available for portmaster so it is a good idea to man portmaster to see which ones interest you.
Once all of your ports are up-to-date, consider scheduling your upgrade process. The csup command works nicely as a cron job; you can then run the portmaster command at your leisure. Some portupgrade users create a simple script to run the csup, portsdb and portversion commands and to have the results emailed to the root user account. They can then run portupgrade manually as ports need to be upgraded.
Rebuilding the Jail's World
If you csup src, as demonstrated in Keeping Ports Up-to-date, you can choose to rebuild the jail's world (operating system) without waiting for the next version of the operating system to be released. This process can be desirable if a hardware driver you use is fixed or given new features or if new functionality is added to the operating system and you want to start using it right away.
How do you know what changes have been made to the src of your operating system? One way is to read /usr/src/UPDATING or to subscribe to its RSS feed. If this is your first time reading this file, scroll down to the COMMON ITEMS section towards the end of the file as it contains useful advice. Similar to /usr/ports/UPDATING, you want to skim through this file from the most recent entry down to the date closest to when you installed or last upgraded the operating system to see if any entries affect you. If so, be sure to follow the instructions. Another way to find changes in src is to get in the habit of reviewing the messages csup displays in order to see which src files are added or modified.
If you are only interested in updating one driver or system binary, you may or may not have to rebuild your world, depending upon if the driver or binary depends on any changes that have been made to the operating system source. The safest (but longer) way is to always rebuild world; however, you can try just recompiling the driver or binary to see if it works. If you receive an error indicating that your "userland and kernel are out of sync", this means that you must go through the build world process in order for the new functionality to work.
To build just the driver or binary, cd into its location in src. In this example, we'll rebuild the kdump utility:
cd /usr/src/usr.bin/kdump
make && make install
To rebuild the operating system, you will issue the following commands as the superuser. If you have built world or your kernel before on this system, you should first clean out the obj directory:
rm -Rf /usr/obj/*
You can now build the world. This process will take some time, depending upon the speed of your processor.
cd /usr/src
make buildworld
When that is finished, you will want to make sure to incorporate the PC-BSD kernel options into the new kernel. If your system is 32-bit:
cp /usr/local/share/pcbsd/conf/PCBSD /usr/src/sys/i386/conf
or, if your system is 64-bit:
cp /usr/local/share/pcbsd/conf/PCBSD /usr/src/sys/amd64/conf
Then, build and install the kernel, install the built world, and reboot into the upgraded operating system:
make buildkernel KERNCONF=PCBSD
make installkernel KERNCONF=PCBSD
make installworld
reboot
Should you be unable to boot into the new kernel, review the If Something Goes Wrong section of the FreeBSD Handbook. It will show you how to boot into the previously working kernel so that you can access PC-BSD and figure out why the new kernel failed.
