22 June 2010

FreeBSD --- Packages and Ports

Adding, Deleting,and Managing Software

With Solaris for example, if you want to add a new piece of the software to the system, you have to find a precompiled binary for your particular platform and install it yourself (usually without the aid of installers that help you put it in the right place), because Solaris typically doesn't come with gcc (the standard GNU C/C++ compiler).
    Other systems, such as IRIX and HP-UX, do come with gcc, but you still have to find the source code for the program you want to install and then run its configuration script, compile it (a step that's often much easier said than done), and install it.
    This configuration and installation process is fairly standardized, but it's still completely voluntary and controlled by each individual software developer, so there's no guarantee that one program's installation process will work the same as another's.
    Different flavors of Linux take this a step further with the concept of packages, which are essentially all-in-one bundles that contain the proper executable binary for your system as well as any required libraries, plus the necessary information about where to install everything as appropriate to the system's layout.
    The i.e. Red Hat Package Manager (RPM) system is a GNU-licensed packager that runs on many systems, including FreeBSD. Its popularity was a large part of what pushed Red Hat to the top of the Linux distributors, edging out the previous favorite, Slackware, which is now all but forgotten which should illustrate well how important a good packaging system can be.
    RPM allowed administrators to keep tabs on their installed software and to upgrade, uninstall, and add new packages with unprecedented ease.
    But FreeBSD takes things to yet another level of convenience. It has its own package management system, the pkg_* tools. Also has a supplementary system called the ports.
    Ports allow you to compile software from its original sources with one-command simplicity and as close to a guarantee of quality as you can get in the "other" open-source world.

Introduction to Packages
Jordan Hubbard, formerly one of the core developers of FreeBSD (now working at Apple as an architect of Mac OS X), is responsible for most of the initial work on the package system.
    FreeBSD's system has been adopted by NetBSD and other platforms and refined over the years, with the best of the independent development efforts being rolled back into FreeBSD.

By its simplest definition, a package system is a way of bundling up software (including config files, shared libraries, and documentation) and extracting it again onto another machine, in which its configuration will be valid enough that the software can run properly on the new machine.

Early package managers did little more than direct the bundling and extraction processes. RPM and FreeBSD's class packagers both have numerous additional features:

They maintain a database on your machine that shows which software and which version of each package are installed.
They can grab a remote installation file from an FTP site (generally, the primary distribution site).
They keep track of dependencies or any additional packages that must be installed for the one you're installing to run.
They can do upgrades and deinstallations as well as installations.

The major difference between the two packagers is related very closely to the different development philosophies of FreeBSD and Linux.
Linux

Linux has a number of different distributions, with different versions of glibc (a set of core shared libraries not relevant to FreeBSD) and a nearly infinite variety of hardware on which the operating system can run.
RPM package files are usually retrieved from any of thousands of developer sites all over the Web, not just a single central repository. RPM must necessarily be quite complex in order to handle all this diversity and indeed it is.
Its command-line interface is fairly arcane and requires a lot of documentation to be used properly.

FreeBSD

FreeBSD, however, benefits from a more centralized development model and a single supported hardware platform, so the package model can be much simpler, both in architecture and usage.

    As we know the /usr/local hierarchy is reserved for items that you install yourself, which refers specifically to software you install from the ports and packages. Table 16.1 shows the /usr/local directory structure (although your installation may vary slightly, especially if you've installed software already).

Table 16.1. Directory Structure Within /usr/local
Subdirectory    Purpose
bin                    Binaries (compiled programs)
etc                    Configuration files
include             C include files, used for building new software
info                   Various supporting types of data for building documentation
lib                     Shared libraries
libexec              Supporting binaries used by other programs
man                  Manual pages for installed software
sbin                  System binaries (programs that alter system behavior)
share                Platform-independent materials (data files, documentation, and so on)

In other words, /usr/local has the same basic hierarchy as the one found directly within /usr (with the exception that man pages are found at /usr/local/man rather than /usr/local/share/man, as you might expect). FreeBSD's package system keeps anything you install in the /usr/local tree and out of the /usr tree, thus maintaining the seamless but strict separation between base and user-installed software.

Shared Libraries and Dependencies
A shared library is a "centralized" file that provides precompiled function calls. Using a shared library, a program can access certain functions without having to have those functions built into itself. This technique, known as dynamic linking, reduces file size and redundancy in the executable binaries in comparison to static linking, which compiles all necessary functions into every program. Shared libraries exist on nearly all platforms, although they have different names for instance, Windows calls them Dynamic Link Libraries (DLLs).
    FreeBSD already has a large number of shared libraries installed in the base system enough to support all the software that's part of FreeBSD itself and provides hooks for software that you might install later. Nevertheless, you're almost certain to run across a program that needs a shared library that doesn't exist in the base FreeBSD.
    In FreeBSD, basic shared libraries are stored in /usr/lib, and any shared libraries that you install go into /usr/local/lib. All programs know automatically to look first in /usr/lib for the shared libraries they need, and they then look in /usr/local/lib (as well as a couple of other places). You can control this search path in /etc/rc.conf.
    Every package has a listing of dependencies (packages that must already be installed for the package in question to run) that includes both shared libraries and executables (programs).

If a dependency isn't already installed, the package system automatically hunts it down and installs it before proceeding with the installation. If you later remove some program or library (via the package tools) that is a dependency for some other installed package, the tools tell you about this and refuse to proceed.

Obtaining Information on Installed Packages

pkg_info tool
pkg_info(or at least ls /var/db/pkg) can be used to determine what packages you have already installed.
Chances are you've installed some packages as part of a custom installation (for example, if you chose to install X11 during the FreeBSD installation process). If not, don't worry the information here will be just as useful to you later.

# pkg_info 
ImageMagick-6.2.2.1  An X11 package for display and interactive manipulation of
analog-6.0           An extremely fast program for analyzing WWW logfiles
apache-1.3.34        The extremely popular Apache http server. Very fast, very
arc-5.21j            extract files from DOS .ARC files
aub-2.1.3            Assemble usenet binaries

Each one of package commands does pretty much what you would expect it to do;

One hallmark of FreeBSD's style is to use differently named programs rather than obscure switches and parameters on the same program.

Each of these tools interacts with a filesystem database at /var/db/pkg (which as i say earlier you can consult by simply using ls to take a quick glance at your system's package status).
    This repository has a directory for each installed package that includes information about the packing list (the manifest of files in the package) and the dependencies. pkg_info uses this database to print out the short descriptions of every package you currently have installed.
    You can also get lots of information on any single package by using its name as an argument, and even more information by adding the -v (verbose) switch.
    As with RPM, packages in FreeBSD have names with multiple parts separated by dashes the package name, followed by the version.However, RPM files tend to be geared toward multiple platforms, and often contain the name of the intended platform in the package name.
    Instead, because FreeBSD is almost exclusively used on x86 hardware, a FreeBSD package file simply takes the form name-version.tbz.

Packages are generally .tbz files (called tarballs), which is shorthand for .tar.bz2. Using tarballs is the traditional way of archiving a directory structure under UNIX you first pack the directory into one file using tar and then compress it using bzip. ---FreeBSD's packages have recently been changed over to .tbz format from the previous .tgz (.tar.gz) format because the bzip2 compressor achieves better results than the traditional gzip compressor.----

To use tools such as pkg_info -v(or pkg_info ), you need to specify the full package name, including the version. Alternatively use the -Lx (The x in -Lx tells pkg_info to look for a package with the specified name --- not given the version number of the port, just its name) switch to receive a list of what was installed, and filter your search using "| grep bin_name". This tells pkg_info that you’re interested only in the path to the binary (another name for the application’s executable). pkg_info will search for all versions of package and will let me know if multiple versions of package are installed.

# pkg_info -v sudo-1.6.8.6
  Information for sudo-1.6.8.6:
Comment:
 Allow others to run commands as root
Description:
This is the CU version of sudo.
Sudo is a program designed to allow a sysadmin to give limited root privileges
to users and log root activity. The basic philosophy is to give as few
privileges as possible but still allow people to get their work done.
MAILING LISTS:
Please send bugs, problems, comments, etc to sudo-bugs@courtesan.com
There is a mailing list that receives announcements whenever a new
version of sudo is released.  You can subscribe to it by sending a
message to "majordomo@courtesan.com" that includes the line
"subscribe sudo-announce".  There is also a list for people working
on sudo.  The command to add yourself is "subscribe sudo-workers".
WWW: http://www.courtesan.com/sudo/
Packing list:
        Comment: PKG_FORMAT_REVISION:1.1
        Package name: sudo-1.6.8.6
        Package origin: security/sudo
        CWD to /usr/local
File: man/man5/sudoers.5.gz
        Comment: MD5:b8c9db19cbac166acac39357b92eae94
File: man/man8/sudo.8.gz
        Comment: MD5:027194bc19812c6da4ca4ed666c7c5f6
File: man/man8/visudo.8.gz
        Comment: MD5:2febf0dc710522e936e92802be2df45d
File: man/man8/sudoedit.8.gz
        Comment: MD5:115a43c18fe748f57d99650bea1ac5ad
        UNEXEC 'rm -f %D/man/cat5/sudoers.5 %D/man/cat5/sudoers.5.gz'
        UNEXEC 'rm -f %D/man/cat8/sudo.8 %D/man/cat8/sudo.8.gz'
        UNEXEC 'rm -f %D/man/cat8/visudo.8 %D/man/cat8/visudo.8.gz'
        UNEXEC 'rm -f %D/man/cat8/sudoedit.8 %D/man/cat8/sudoedit.8.gz'
        UNEXEC 'if cmp -s %D/etc/sudoers %D/etc/sudoers.sample; then rm -f %D/etc/sudoers; fi'
File: bin/sudo
        Comment: MD5:87f016a5e538921843b48656498cff7a
File: bin/sudoedit
        Comment: MD5:87f016a5e538921843b48656498cff7a
File: etc/sudoers.sample
        Comment: MD5:f16c8ba08bf992bf3d068745395e89fd
File: libexec/sudo_noexec.so
        Comment: MD5:b618e152b00290cbcf7023dc6e58ee9e
File: sbin/visudo
        Comment: MD5:55d4f41123fb170700f5bd286af583a2
        UNEXEC 'if [ -f %D/info/dir ]; then if sed -e '1,/Menu:/d' %D/info/dir | grep -q
 '^[*] '; then true; else rm %D/info/dir; fi; fi'
Install script:
#!/bin/sh
if [ $2 != "POST-INSTALL" ]; then
  exit 0
fi
if [ -e ${PKG_PREFIX}/etc/sudoers ]; then
  echo "Will not overwrite existing ${PKG_PREFIX}/etc/sudoers file."
else
  cp -p ${PKG_PREFIX}/etc/sudoers.sample ${PKG_PREFIX}/etc/sudoers
  chmod 440 ${PKG_PREFIX}/etc/sudoers
fi

This listing tells you everything you need to know about the package from its long description, to its dependencies, to its packing list (with the MD5 "fingerprint" checksum for each file, listed in its Comment field), and even the install script that was used during its installation, to help you track down where its component files are. Not shown in this listing is the complete mtree file (a map of all directories containing components for the selected package).

The information in the packing list is more than a simple list of component files: it also contains UNEXEC commands that are used during the deinstallation process for any package, so that if you use pkg_delete to remove the package, it simply executes these commands to cleanly remove all appropriate files and directories. In this example(look at last UNEXEC line), the default sudoers.sample file in the /etc subdirectory of the script's working directory (/usr/local, represented by the token %D) is removed as part of the default packing list. Additionally, in an UNEXEC command, the /usr/local/etc/sudoers file is compared to the default sudoers.sample file in the same directory; if they match, you never made any changes to the sudoers file since installing it, and it is deleted as well. Otherwise, pkg_delete knows you've made your own changes to the file, and it leaves it alone.

As you can see, a well-written and well-behaved package (and just about all packages are well behaved) will erase cleanly off your system when removed, leaving nary a trace of itself behind, but leaving your locally changed files untouched(for a comparison think how behaves Windows registry system about programs deinstallation).

pkg_version tool
How do you know that this version of the package is current? You can determine this easily by using the pkg_version tool.

It works only if the ports collection has been installed(and it should be installed unless you're severely short on disk space).

All you need to know for understanding pkg_version is that:

the ports collection (if kept up to date) has a listing of the current version of every package.
The pkg_version tool compares the versions of every installed package to the version found in the ports collection, and it tells you whether your packages are up to date.

# pkg_version -v 
ImageMagick-6.1.6.8        <  needs updating (port has 6.2.2.1)
apache-1.3.34              <  needs updating (port has 1.3.34_2)
arc-5.21e.8                =  up-to-date with port
aub-2.0.5                  =  up-to-date with port
autoconf-2.13              =  up-to-date with port
bash-2.04                  *  multiple versions (port has 1.14.7,2.05b.007_4)

Without the -v option, pkg_version wouldn't print the third column; you'd just get the icon in the second column. The version string would also not be appended to the package names in the first column. Either way, this provides you with a quick, at-a-glance method for telling where your maintenance efforts are needed.

A Note on Version Branches   For now, however, you should become familiar with at least a few important bits of terminology that are crucial to the proper operation of the packages and ports.
    In the Options section of the Sysinstall program is a field to set the release name you'll be working with. Chances are you will be running a "release" version of FreeBSD (these are the versions that come on CDs-DVDs). If so, the Release Name field will be set correctly for the version you're running (for example, 8.0-RELEASE). However, if you've upgraded your system to an interim point on either the -STABLE or the -CURRENT branch, this field may be set to #.#-STABLE, where the hash marks (#) stand for major and minor version numbers. That value won't work when you try to open the Packages menu because it tries to access a directory on the server whose name is based on the version number pulled in directly from the output of the uname command, which reports information on the kernel version. The corresponding directory for the packages that match your system's version doesn't necessarily have the same name as what's specified in the Release Name field.
    Go to ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/ (and then into your appropriate platform subdirectory) to see the available release directories. If your version is 6.1-RELEASE, the release directory you want is i386/6.1-RELEASE. If your system has been rebuilt from STABLE sources, choose the most recent RELEASE directory.

What Is the Ports Collection?
The Internet contains literally hundreds of thousands of free applications. Many can be found at free software websites such as Sourceforge.net (which hosts more than 200,000 applications); others, such as openoffice.org and gimp.org, have their own websites.
Some are stable and well documented; others are buggy, and you have to guess how they work. With so much out there to choose from, how do you find the software you need and how do you know it will work on your FreeBSD system?
The FreeBSD Project maintains something known as the ports collection. This is a large collection of software that has been “ported” for FreeBSD.

In a nutshell, ported means that someone did a fair bit of work to make the necessary changes needed for the software to run on FreeBSD.

If you’re curious as to what is involved, the Porter’s Handbook contains the instructions for making a port.

The person who makes the port is known as the port’s maintainer.

To make sure that all the ports in the ports collection work, the FreeBSD Project uses a build farm known as pointyhat.

A build farm is a cluster of machines that constantly rebuilds the ports in the ports collection.

This is important because an application that is known to work can sometimes stop working (for example, if a software library it uses changes). Sometimes an application that works on one version of FreeBSD won’t work on a newer version of FreeBSD without some modification. Pointyhat system will e-mail the maintainer if there is a problem with the port until the maintainer fixes the problem.
The FreeBSD Project is also concerned about software security. It maintains a database of known vulnerabilities, known as VuXML, and provides tools(see portaudit command later) you can use to determine if any of your installed software is vulnerable. The ports collection is the collection of ported software.

After installing FreeBSD, you can install additional software using either Ports or Packages.

The FreeBSD ports collection approach lets you install(configure, compile ---or build--- the port yourself) software from source code. As of July, 2010, there are (more than) 22,000 applications in the FreeBSD ports collection.
The Packages approach lets you install applications that are pre-built (always trough Ports) into binaries pretested for you so that it can be easily installed and used. Think of a package as a command-line installer program that knows how to install the application, all its dependencies, and any documentation and configuration files associated with the application.

As a rule of thumb expert users tend to use the Ports system to get the latest software. New users might be more comfortable with Packages provided that bugs have been worked out in the build process.

For installing binaries, the sysinstall utility lets you select:

where to install from (CD, DVD, FTP, and so on),
then choose which packages to install.

If a package is already on your computer, you can use commands such as:

pkg_add
pkg_delete
pkg_info
pkg_update
pkg_version, and
pkg_create

to work with that package.
For building packages using the ports system, you use the make command (instead of the pkg_add command).

make build
make install
make clean

Packages or Ports?
If you’re wondering whether you should install the package or compile a port for a given piece of software, you probably want to install the package.

If you find yourself compiling ports without passing any particular make targets, you definitely should be installing the package instead of compiling the port.

Packages provide several advantages over ports:

They are quick to install. With the exception of very large packages such as KDE or GNOME, most packages install in under a few minutes. Depending on the number of dependencies and your hardware, the same port may take several hours to compile.

If you aren’t customizing the port, you will end up with the same binary as the package would have installed, meaning you needlessly waited longer to install the software on your system.

A lot of ports i.e. CVSup require huge dependency programs, which you might not need or want on your system, to be built and installed. For instance, building a simple graphics library can cause the entire X11 system to be downloaded, compiled, and installed without your foreknowledge. For this reason, you should lean towards using the packages rather than the ports.

However, at times you do want to install the port, when, for example, the following occur:

A package is not available.

You want to compile a binary with a known security vulnerability.

You want to override a license restriction. For example, the license may allow you to compile the binary for personal use but does not allow the FreeBSD project (an organization) to distribute the binary package.

You need to customize the options that are compiled into the binary; this is often done with server applications such as Apache or PostgreSQL.

Finding Software

At any time, you can find out what software is available with FreeBSD Ports system using the FreeBSD Ports Search page. Type the term(s) to search for, the description area to search, and the particular category of software. You will see a listing of results by category and package name.
The easiest way to find FreeBSD packages is to point a web browser to FreshPorts. FreshPorts provides an easy-to-use web-interface to the information available within the FreeBSD ports collection. If you’re wondering what software is available to install on your FreeBSD FreshPorts is the place to go! If you use the Firefox web browser, you can access this website quickly using a FreshPorts search plugin. While in Firefox, go to that website and click the I to install the plugin(There are two Is to choose from. The first one will use the default search engine icon, and the second one will install the Beastie icon). To search for an application using the plugin, simply type the name of the software into the FreshPorts search bar and it will show you the results from FreshPorts.org. FreshPorts provides a lot of useful information that can assist you in deciding which software to install(a skull icon, indicating that software has had a known security vulnerability in VuXML. If that vulnerability has not been fixed yet, a package will not be available. You can click the skull icon to read details about the vulnerability). If you have no idea where to start and want to get a feel for what software is available, click the Categories hyperlink (located about halfway down the page in the right frame). This will show you a view of all available software divided into categories. Click a category to browse all its applications.
If you know a component (command, system call, file format, and so on), but don’t know what package it is in, you can search man pages from the FreeBSD site.To read about available commands, file formats and other things before you install them
You can also use pkg_info to get information about software that is already installed(without switches you get comment and description sections). You can check whether a package is already installed and list information about installed packages using the pkg_info command. (Depending on your shell, you may need to wrap wildcard characters(like under csh) in quotes, as in: pkg_info "cdrtools*").

# pkg_info | less   Show name/index line for all packages                 
# pkg_info -I "gnome*" | less  Show name/index line for matching packages
# pkg_info "cdrtools*" | less  Show info for installed package cdrtools
# pkg_info -d "cdrtools*" | less  Show long description of package
# pkg_info -c "cdrtools*" | less  Show comment line of package
# pkg_info -f "cdrtools*" | less  Show list of files in package
# pkg_info -L "cdrtools*" | less  Show list of full paths to files in package
# pkg_info -i "gnome-games*" | less   Show install script for package (if any)
# pkg_info -k "kdebase*" | less   Show de-install script for package (if any)

You can find out about package dependencies using the pkg_info command. Here are examples:

# pkg_info -R "cdrtools*" | less  Show packages "required by" installed package
# pkg_info -r "cdrtools*" | less   Show packages requested package depends on

Before you install the packages that interest you, there are other ways to get information about packages and categories as well.

If you installed the ports database(i.e. in OS install stage), you could simply search the /usr/ports directory, since packages are organized by directories named after each category and package name. For example:

# find /usr/ports -type d | grep quake | less  
Show ports with quake in the name

If you want to search your entire system for any sign of a particular package, command or file, you can use the locate command to search the entire file system.

That is, provided that you configured the locate database to include the entire contents of your file system.

Perhaps the most obvious way to browse through available groups and packages is to view the packages in the sysinstall utility.

Still about FreshPorts: Each FreshPorts entry contains the following information about the software:

Name: The name of the application, followed by its version number and category. Click the magnifier icon to determine whether any other software depends upon this application.
Maintained by: The e-mail address of the person responsible for making sure the software works on FreeBSD. Click the magnifier icon to see what other applications they are responsible for.
CVSWeb: Contains the complete history of the application since it first became available within the FreeBSD ports collection.
Sources: Shows the original source location of the software that was ported, as well as the checksums and size of the software source. Note that this is for informational purposes because the package system will fetch the software for you (that is, you shouldn’t download it yourself).
Main Web Site: This is the primary site of the application. This website often contains screenshots, documentation, and more information about the software.
Distfiles Availability: Shows the availability of the software source for that category.
PortsMon: Shows a report on the status of the FreeBSD port. See here for more information about the PortsMon project.
Installation instructions: Provides the commands used to install the software using the FreeBSD ports system and the FreeBSD packages system. In addition to the information about each port, the FreshPorts website contains lots of other useful information.
The Latest Vulnerabilities section (in the right frame) can be used to browse through software with known existing security vulnerabilities. The Ports section contains hyperlinks to the software categories, the list of deleted ports, and the FreshPorts RSS newsfeeds.
The Statistics section contains graphs; counts for the total number of ported applications; and the number of broken, deprecated, and vulnerable applications. It also contains hyperlinks to lists of software added within the last 24 or 48 hours, 7 days, fortnight, and month.
The FAQ in the This Site section includes explanations of packages and ports and descriptions of all the icons used on the website.

Installing Software Packages (binary)
Just about all the software available for Linux is also available for FreeBSD nearly every piece of open-source software in the world has been made into a native FreeBSD port, and even closed-source software distributed in binary form for Linux can be installed as well (because binary compatibility allows you to do anything up to and including playing back audio/video using Linux software).
You can install precompiled, binary packages that are ready to run using either:

a menu interface (sysinstall): offers an even more direct interface than case 2.
a command-line interface(CLI) (pkg_add): ---If you have the ports collection installed--- you can see a categorized view of all the available software by going to /usr/ports and just looking around at the filesystem. Each subdirectory represents a package category of the same name, and each port directory inside it represents a software package that might be available for installation using the command-line pkg_* tools. Not every port has a corresponding package available. If you try to install a package whose name you found in the ports directory, and it's not available in Sysinstall's menus, you'll want to build it from the ports instead.---

Both sysinstall and pkg_add will try to get and install the packages you request, along with any dependent packages your selected packages need to run.
After you have installed FreeBSD, you can run the sysinstall utility again to add more software packages.

As root user, type /usr/sbin/sysinstall (if type sysinstall and you get command not found type rehash--it's normally in root user PATH--) to display the sysinstall Main Menu.
Then select Configure ➪ Packages, and
Choose the medium you want to install from (CD/DVD, FTP, HTTP, and so on: choose CD/DVD if you have your FreeBSD DVD handy; if not, and you're on the Net, choose FTP.
After you get the package list from whichever medium you choose, you are presented with a menu. Scroll up and down to see the various categories, and press Enter to go into each one.
At the bottom of the screen you'll see the one-line "short description" of each package. When you see the package you want, press the spacebar to mark it with an x(If any of the packages you select are dependent on other packages that are not already installed, those dependent packages will be marked with a D and automatically installed with your selections.). Select(press tab key) Cancel (press the right arrow) to exit from the category. You can browse through all the available categories this way until you've selected a long list of the packages you want; when you're done, tab to the Install button at the bottom of the screen to install them all in one fell swoop. Note that selecting Install is the only way to exit from the Package menus. If you don't select any packages for installation, you still need to select Install (and accept its dialog about there being nothing to install) in order to exit to the main Sysinstall menu.
The program now goes through the list and downloads each package, one by one, unpacking it into /usr/tmp and installing it using the pkg_add program, the command line element to this phase of the FreeBSD package manager (which you can also use independently of Sysinstall).
If a package has any dependencies, Sysinstall first finds and installs them and then returns to installing the packages you selected.
Exit from Sysinstall using the Exit Install option at the bottom of the screen. Your new packages are now installed that's really all there is to it. The documentation (man pages) is all ready to use, config files are in /usr/local/etc, and the binaries are in /usr/local/bin. Type rehash to refresh the available programs(executables) that your current shell knows about (or log out and back in), and you'll be able to use the software.

Some programs need to be configured before they can be used. Go into /usr/local/etc and check for a config file (usually of the style program_name.conf or program_name.cfg, or at least containing the program name). If the file has .sample as extension, you need to copy the sample file to a real, "live" config file (without the .sample extension) and perform some additional modifications before the program can use it.

Open the file with your favorite text editor and do what needs to be done, as described in comments in the file itself or in the man page for the program.
After you have configured the first file, check inside the rc.d subdirectory for similarly named startup files and deal with them in the same way if necessary.

Use the pkg_add (better with -r option) command to add packages to your BSD system
Few options are available for the actual installation process in FreeBSD. Because executables, config files, and libraries are all kept in a standard centralized location, no dialog asks where you want to install a program or offers you any of the custom installation options you get in the desktop OS world.

These installation limitations are perfect examples of both the more "closed-box" approach of FreeBSD, as compared to that of Linux, and the centralized distribution model for all the open-source software available for the platform.

However, there are times when you need more control over a package than you can get within Sysinstall. Examples include

packages that have interactive preinstallation scripts (in which you can set options specific to that package) and
situations in which the automated installation in Sysinstall fails.

For times such as these, you need the pkg_add tool; it's used in every package installation, whether it's called directly or run by Sysinstall.
The pkg_add tool is designed to operate on a .tbz or .tgz file you've already downloaded (from the per-release distribution directory described earlier) or on a remote file specified by its URL. For instance, the following two procedures are roughly equivalent:

# fetch ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/6.0-RELEASE/packages/www/webstone-2.5.tbz
# pkg_add webstone-2.5.tbz

# pkg_add ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/6.0-RELEASE/packages/www/webstone-2.5.tbz

Of course, the latter method is much more convenient because not only does it eliminate the separate steps of downloading and installing the package, it also does all its work in /usr/tmp (or a similar temp directory) and cleans up after itself when it's done.
The former method, however, allows you to store your source tarballs in a local directory (such as ~/tarballs) so you can reinstall your software from them later without downloading them again.
pkg_add also keeps track of dependencies as if you were using it through Sysinstall. If you use pkg_add to add a package that has dependencies, it will automatically download and install the dependencies before proceeding. This ensures that you'll have a fully functional program after it's done working.
Use pkg_add -nv to do a "dry run" install. This shows you the steps pkg_add would take during the installation, without actually doing anything.

pkg_add warns you if the compiled package was built with a dependency on another package(but older in version than the one the package wants) that you have already installed:

pkg_add: warning: package 'xorg-libraries-6.8.2' requires 'pkgconfig-0.17.2', but 'pkgconfig-0.15.0' is installed
pkg_add: warning: package 'xorg-libraries-6.8.2' requires 'freetype2-2.1.10_1', but 'freetype2-2.1.5_1' is installed

If you receive warnings such as these, it's a good idea to upgrade the packages in question as soon as possible to avoid incompatibility issues.

An even more convenient way to install packages, one that does not involve your exploring through the FTP site at all, involves using the r option to pkg_add. This is the automated "remote fetching" feature, and it eliminates the need for you to know the current version number of the package you want, or even the version of your own operating system. The package manager will figure it out for you. Simply use the name of the package you want without the version number string, along with the r flag, and pkg_add will determine your platform type and release version and install the package in one step.

pkg_add Vs sysinstall Pros

Sometimes, a package installation finishes with a screen that gives you further instructions about how to complete the configuration. This is one benefit of installing packages from the command line rather than through Sysinstall.
Another is that Sysinstall provides no feedback about the file size of any package, so you pretty much have to just let it download with no progress feedback other than data rate. If you used a browser to find the package in its FTP directory, you'll find the package size there and at least know how far you have to go when downloading.

You can also specify multiple packages, run in verbose mode, and prevent pkg_add from running preinstallation or postinstallation scripts. You can even prevent it from recording that it has installed the package. These options and more can be found in the man pkg_add page.

Notes on Package Origins   The directory structure at the FreeBSD FTP site is such that each package is actually a symlink, so the file sizes aren't actually directly available if you reach them from the preceding URL. A little digging will get you the information, but it might not be worth your while.
    Note that pkg_add does work on .tbz files grabbed from any location, not just the FreeBSD site. However, beware of files from "suspect" locations; adding packages is an act of trust, allowing whoever wrote the package to specify files to be placed in user-executable locations, possibly overwriting other files. (This is why regular users are generally restricted from installing packages and ports.)
    Viruses and Trojan horses are very uncommon in the UNIX world, but a conscientious administrator should have these potential threats in mind at all times, and especially when installing packages!
    If you stick to Sysinstall, or at least to the .tbz files found at the FreeBSD FTP site, you can be assured that all the packages are approved for use and include an MD5 checksum to verify their authenticity, which you can usually do with the md5 tool:

# md5 webstone-2.5.tbz

You can compare the output string from this command to the contents of the checksum file, often provided along with the package, to make sure they match before installing it.

As i say the packages you request can be either in a local directory or in a remote(-r option) BSD software repository. Here are other examples:

# pkg_add -r freebsd-games Download/install freebsd-games from network
# pkg_add -r -K xmines  Download/install xmines, save pkg to local dir
# pkg_add -v lsof-4.79D.tbz  Install lsof in verbose mode
Requested space: 455200 bytes, free space: 1155635200 bytes
in /var/tmp/instmp.09jSIz
extract: Package name is lsof-4.79D
extract: CWD to /usr/local
extract /usr/local/sbin/lsof
...

To verify the contents of a package before installing it: you can use the -M (Master) option to pkg_add. With -M, instead of installing a package, the contents of the package are copied to a subdirectory of /var/tmp, where you can inspect them before installing. For example, with memdump-1.01.tbz in the local directory, type this:

# pkg_add -M memdump-1.01.tbz   Put package contents in /var/tmp to check

With the package extracted to the /var/tmp directory, you can now examine the contents of the package. Look for directories with names such as instmp.??????, where each ? is replaced by a letter or number. The -M option can be used in conjunction with the -S (Slave) mode.

What to Do if Something Fails
Packages usually work flawlessly by using the instructions in the previous section. But occasionally something goes wrong.

Sometimes pkg_add stops with a message saying that it can’t fetch the package.

Sometimes pkg_add complains that it can’t find a dependency and refuses to finish the installation without it

Sometimes the package installs, but you get an error message when you try to run the application.

If pkg_add tells you it can’t fetch the package, double-check that you are the superuser and that the pkg_add command FreshPorts told you to use was typed correctly into shell. If you see a typo, fix it and try again.

If it still won’t fetch, double-check that you’re connected to the Internet by pinging a website name. If it still won’t fetch or still refuses to install or run, you’ll have to do a bit of research to see what is going wrong.

Go back to that port’s entry in FreshPorts. Does it have a skull icon or a message indicating that it is broken, forbidden, or restricted? If so, there probably isn’t a package available. If you really want that version of the software, consider trying to build its port instead. Otherwise, try another version of the port or another application that provides similar functionality. You can also browse the FreeBSD ports mailing list archives to see if other users are experiencing the same problem.

Removing Software Packages (binary)
To remove previously installed software packages, you can use the pkg_delete command(Again, the -x indicates that you have not given the version number of the port, just its name).
    Here is no front end in Sysinstall for removing packages. You really don't need one because once a package is installed, you can specify its name directly using the command line package management tools.
    You can use pkg_info to see which packages you have installed, as you learned earlier. You can also simply look in /var/db/pkg; the directory names in there are the same as the package names. After you have the name of the package you want to delete, simply use pkg_delete to remove it.
    If the package has any dependencies, pkg_delete will detect them and refuse to proceed unless you've run it with the -f option to force deinstallation. It will also attempt to run any deinstallation scripts and evaluate any "require" statements; if these fail, pkg_delete will also fail (except if it's running with the -f option). As with pkg_add, you can use a number of other options, including verbose mode (-v) and "dry run" mode (-n). Here are some examples of pkg_delete for deleting a package:

# pkg_delete -n dbus-0.93_3   Check what would happen before deleting package
pkg_delete: package ‘dbus-0.93_3’ is required by these other packages and may not be deinstalled:
dbus-glib-0.71
avahi-0.6.14
policykit-0.1.20060514_2
hal-0.5.8.20060917_2
...
pkg_delete: 1 package deletion(s) failed

The -n option to pkg_delete shows you what would happen when you run the pkg_delete live, without actually running it.

Running pkg_delete -n before actually deleting the package is a good idea. This will tell you dependencies on the package, if there are any, but not actually delete the package. If there are no dependencies, it will show you the exact files that would be deleted, so you can see if there’s anything you would miss.

# pkg_delete "xmines*"  Delete package, using wildcard
# pkg_delete -i "akode*"  Delete set of packages, confirming each
delete akode-2.0.1,1? y...
# pkg_delete -v "xmines*"  Delete with verbose output
pkg_delete: no such package 'xmines*' installed
pkg_delete: 1 package deletion(s) failed

Think hard before you use any of the following options with pkg_delete.

The first example below forces the named package to be deleted, even if other packages are dependent on it.
In the second example, all installed packages are deleted, which I presume brings the system down to just the base system (I’m not going to try this myself, but mention it because the option is there):

# pkg_delete -f "metacity*" Forcibly remove package (no dependency checks)
# pkg_delete -a   Danger, Danger! This will remove all installed packages

Another option that’s a bit dangerous, but potentially useful is the -r option. Use this option if you want to remove a package, plus all packages that depend on it. Before you use this option, it is probably a good idea to do some non-destructive trials. For example:

# pkg_delete -n -r "gstreamer*" | less Non-destructive results of recursive delete
# pkg_delete -r gstreamer*   Danger! Recursively delete package and dependencies

If pkg_delete didn’t have any informational messages when it removed the package (sometimes happens) you can verify that the package did uninstall(by running pkg_info)

pkg_delete will not let you delete a package(package that installed with the interested package as a dependency) if another application needs it.

If you receive an error message that “no packages match pattern(s)”, double-check that you don’t have a typo in your pkg_delete command. If the command looks good, use pkg_info to double-check that the package you are trying to uninstall is indeed installed.

Upgrading Installed Packages
If you attempt to install a newer version of an already installed package, pkg_add will exit with the following error message:

# pkg_add pine-4.63.tbz
pkg_add: package 'pine-4.63' or its older version already installed

This means you need to delete the package in question before attempting to install a newer version.

First remove the package using pkg_delete (as described previously), and
then use pkg_add to install the latest version of the package, either from a downloaded tarball or using the -r option to automatically fetch the most recent package version.

Installing Software Using Ports (source code)

Introduction to Ports
You now know about packages and the tools FreeBSD provides for interacting with them. Ports offer another way for you to install software in FreeBSD. You use ports to compile software directly from the source code in an automated procedure that controls and safeguards the installation process as it allows you to grab the source directly from each program's distribution site.
As convenient as packages are, the traditional "UNIX way" of installing new software has always been to compile it yourself.

The administrator finds the distribution site (using either HTTP or FTP, or in an earlier era, a tool such as Gopher or Archie), downloads the source code bundled up in a .tar.gz or .tgz (or .tbz) file, and unpacks it into some temporary directory.
After reading the various README files for special instructions, the administrator usually runs a configure script that examines the system to check for a variety of function calls (these calls vary from platform to platform within the UNIX world) and generates an appropriate compilation script based on what calls are available for the program to use.
The next step is to compile the software by running make an encapsulated compiler-management tool that reads its build targets and the necessary steps from a file called Makefile within the main source directory.
After a (hopefully) clean compile, the administrator must then find the new, freshly baked executable and manually copy it into the publicly accessible location for binaries (/usr/local/bin, for example). In the best-case scenario, however, there is an "install" target in the makefile, so typing make install copies the proper files into (if he's lucky) the correct location.

This installation operation is (or rather, was) very inexact; sometimes it worked, sometimes it didn't. In the vast majority of cases it worked "sort of." Software distributed in source form usually worked fine in some systems; but trying to compile it on another platform usually resulted in at least a few minor disagreements about installation locations under the best of circumstances, or complete failures to compile in other cases. Maintenance was impossible, performance was unpredictable, and the reputation of UNIX for being arcane and difficult to use only grew stronger.
    Enter the FreeBSD ports. Ports provide a way for you to compile software directly from the source in a regimented, structured, automated procedure that ensures the safety and integrity of the software you're installing while allowing you to grab the source directly from each program's distribution site (or a backup location, such as the central FreeBSD server, if the initial source fails).
    This means you can stay on top of the very latest developments in a piece of software without having to wait for a precompiled binary package that might not run on a heavily customized system.
    Port installation also allows thousands of different pieces of software to install all their components into the proper locations in the FreeBSD filesystem without the developers even having to consider explicitly supporting FreeBSD's system structure. This is accomplished through a widespread system of port maintainers, volunteers in the FreeBSD user community who keep track of changes in their assigned ports and maintain scripts that patch a program's build and installation procedures to operate correctly with FreeBSD. When a developer updates his software, the port maintainer tries compiling it on FreeBSD and then makes whatever changes are necessary to the code patches and installation scripts that make it work smoothly with FreeBSD.
    A port, then, is simply these scripts and patches in a bundle, sitting in a particular spot on your FreeBSD machine, with a customized makefile that enables you to install the software simply by typing make install.
    No downloading; no configuring; no patching; no tweaking; no copying. All that work has been done for you.
    FreeBSD's port system has been so successful it has been adopted by various other systems, particularly OpenBSD and NetBSD, and has inspired similar systems on Gentoo Linux and Mac OS X/Darwin. Its success can be attributed to two things:

Its ability to keep UNIX administrators happy who prefer to compile their own software (either through security awareness or machismo), and
its ability to provide the simplicity of version tracking and maintenance that the package system boasts. It's truly the best of both worlds.

The FreeBSD Ports Tree
The BSD ports collection contains sets of make files, patches, and descriptive information needed to get, compile and install thousands of applications that have been ported to FreeBSD. When you install the ports collection, it is stored in the /usr/ports directory. Go into that directory now and take a look around. What you see should resemble listing below. You'll notice that every category you saw in the Sysinstall program is here as a directory. (The list may not be 100% accurate for you because categories are reorganized on a fairly regular basis)

# ls -sF /usr/ports/
total 7422
    2 .cvsignore         4 deskutils/         4 net-mgmt/
   34 CHANGES           38 devel/             2 news/
    2 COPYRIGHT          2 distfiles/         2 palm/
 6768 INDEX-6            2 dns/               2 picobsd/
    4 KNOBS              6 editors/           2 polish/
   32 LEGAL              4 emulators/         2 portuguese/
  106 MOVED              2 finance/           8 print/
    6 Makefile           2 french/            2 russian/
    2 Mk/                2 ftp/               2 science/
    2 README            16 games/            12 security/
    4 README.html        2 german/            2 shells/
    2 Templates/        14 graphics/         14 sysutils/
    2 Tools/             2 hebrew/           20 textproc/
   86 UPDATING           2 hungarian/         2 ukrainian/
    2 accessibility/     4 irc/               2 vietnamese/
    2 arabic/           10 japanese/         24 www/
    4 archivers/         4 java/              6 x11/
    2 astro/             2 korean/            2 x11-clocks/
   14 audio/             6 lang/              2 x11-fm/
    2 benchmarks/       14 mail/              2 x11-fonts/
    2 biology/           6 math/              2 x11-servers/
    2 cad/               2 mbone/             6 x11-themes/
    4 chinese/          12 misc/              6 x11-toolkits/
    4 comms/             6 multimedia/        4 x11-wm/
    2 converters/       22 net/
   10 databases/         2 net-im/

From there, you can run a few simple commands to build selected applications from source code and install them on your system.
In general, installing packages from the ports collection is generally preferred by more expert users. That’s because building from source code offers opportunities for checking the code, modifying it to work efficiently for your uses, and incorporating the latest patches.
When you first installed FreeBSD, you were given the opportunity to install the ports collection. If you chose not to do that at the time, you can install the ports collection later(i.e. trough sysinstall).

The contents of /usr/ports are by their nature independent of the branched development structure of the FreeBSD operating system. A newly released copy of the system will come with a snapshot of the ports created at the time the system was released, but it immediately becomes obsolete as soon as the ports within it are revised as new versions of the ported software come out. If you synchronize your ports tree to the central repository (as we will discuss later), it's always to whatever is current at the time you synchronize. There isn't a fixed state for the ports tree attached to each release as there is with the packages . Therefore, these sample directory listings are almost certain to differ somewhat from what is in your system. This also means that if you're trying to maintain multiple FreeBSD systems with identical software loadouts, you should avoid the ports system and use packages instead.

The first few directories in /usr/ports (the ones beginning with capital letters, taking advantage of the UNIX convention of alphabetizing capital and lowercase initial letters separately, in accordance with the ASCII character set) are structural elements of the ports system, adjuncts that make the system work.
You'll also find informative text files there, such as MOVED, which provides an up-to-date listing of recently moved or removed ports (including explanations for each of these changes).
The rest of the directories (beginning with lowercase letters) are categories of ports. Look inside one and you'll see as many as hundreds of different port directories, as demonstrated in the very partial Listing below.

# ls -sF /usr/ports/audio/
total 1206
 2 HVSC-Update/                       2 mp32ogg/
 2 Maaate/                            2 mp3_check/
16 Makefile                           2 mp3asm/
 2 abcde/                             2 mp3blaster/
 2 abcmidi/                           2 mp3burn/
 2 abcselect/                         2 mp3butler/
 2 ac3dec/                            2 mp3c/
 2 adpcm/                             2 mp3check/
 2 adplay/                            2 mp3ck/
 2 afsp/                              2 mp3encode/

Even though ports are sorted into categories by their intended functionality, their names aren't allowed to clash. A port in audio can't have the same name as a port in sysutils even though they're in different directories. This is because once your ports are installed, they're all stored in a single flat database (/var/db/pkg) with no category divisions. The categories are only there in /usr/ports for your convenience in finding ports by type.

Browsing the ports in this way is less than efficient, especially in the larger categories (in this example, /usr/ports/audio contains 883 ports at the time of this writing).

What if you know the name of a port you want to install, but you don't know what category it's in? You can use the locate command to find the port by name:

# locate uudeview
/usr/ports/converters/uudeview

However, until the locate database has been initially built (which might take a week after you first install FreeBSD), the command won't work. Use the /usr/libexec/locate.updatedb command to build the database manually so you can make use of locate.

What is Compiling a Port?
Software applications are created from source code, or text files written in a programming language. Those files are considered human readable, at least for those humans who understand the syntax of the programming language used.
The source code must be converted into a form that the computer understands by using a program known as a compiler; the end result is the binary executable of the program. When compiling a FreeBSD port, you use the following components:

The gcc compiler.

The make program to manage the dependencies that are needed when a binary is compiled.

A Makefile that contains all of the instructions needed to compile the FreeBSD port.

A directory structure, known as the ports tree, containing a subdirectory for each port. Each subdirectory includes the port’s Makefile, a working area, any needed patches, the post-installation message, the package description, and the checksums for the archive containing the source code.

gcc and make were installed with your freeBSD system. However, before you can compile any ports, you have to install the ports directory structure.

Getting the Ports Collection
There are several ways to get the ports collection for your FreeBSD system after the system is installed. Choices include

sysinstall,
portsnap, or
cvsup.

Of the three,the sysinstall method is probably the most intuitive, but each is pretty easy to use.

This first procedure either installs or updates your ports collection using portsnap:

Create the ports directory (if it doesn’t already exist):

# mkdir /usr/ports

install portsnap(If it is not already installed):

# pkg_add -r portsnap

Download ports collection(almost 60MB gzipped file) to /var/db/portsnap:

# portsnap fetch

If a ports tree has already been created in /usr/ports/ install a new /usr/ports (the first time you use portsnap):

# portsnap extract

Update an existing /usr/ports/ collection(Next time you use portsnap) :

# portsnap update

To use sysinstall to install the ports collection,

run the sysinstall command as root user.
Then select Configure ➪ Distributions ➪ ports.
With ports selected, select OK.
When prompted, select the location of the ports collection (CD, DVD, FTP site, etc.) and the ports collection will be extracted to the /usr/ports directory structure.

To use cvsup to install the ports collection, do the following:

Create the ports directory:

# mkdir /usr/ports

Install cvsup:

# pkg_add -r cvsup-without-gui

Run the cvsup command, replacing cvsup.FreeBSD.org with a FreeBSD mirror site nearer to your location and optionally copying and modifying the ports-supfile:

# cvsup -L 2 -h cvsup.FreeBSD.org/usr/share/examples/cvsup/ports-supfile

Regardless of which of the three procedures you used to get your FreeBSD ports collection,we must using the ports collection to install applications on our FreeBSD system.

Getting and Installing Applications with Ports
Applications in the ports collection are available via port skeletons. A port skeleton is represented by a directory in the /usr/ports directory structure that contains components needed to get the source code, compile it, and install the components.

Basically, the skeleton contains all the information needed to build an application from source code, without containing the source code itself. The source code itself is contained in a tarball referred to as a distfile. During the build process you get the distfile from a FreeBSD mirror site on the Internet or from a local disk.

Here’s how to see the port skeleton for the ftpcopy application:

# cd /usr/ports/ftp/ftpcopy Change to the ftpcopy directory in  ports 
# ls -CF Lists the contents of the ftpcopy directory
Makefile
distinfo
files/
pkg-descr
pkg-plist

The Makefile file is used by the make command to describe how the application is to be compiled. Contains certain variables used in the build process as well as contact information for the maintainer.
Makefile is the file that has the critical elements for

building
configuring
installing, and
maintaining

a port. Listing below shows you what's typically inside Makefile:

# New ports collection makefile for:    amp
# Date created:         Jun 23 1997
# Whom:                 Vanilla I. Shu 
#
# $FreeBSD: ports/audio/amp/Makefile,v 1.16 2005/04/17 15:19:40 novel Exp $
#
PORTNAME=       amp
PORTVERSION=    0.7.6
PORTEPOCH=      1
CATEGORIES=     audio
MASTER_SITES=   http://www-users.cs.umn.edu/~wburdick/ftp/
MAINTAINER=     delphus@gmail.com
COMMENT=        Another mp3 player
GNU_CONFIGURE=  yes
USE_GMAKE=      yes
MAN1=           amp.1
PLIST_FILES=    bin/amp
do-install:
        @ ${INSTALL_PROGRAM} ${WRKSRC}/amp ${PREFIX}/bin
        @ ${INSTALL_MAN} ${WRKSRC}/amp.1 ${PREFIX}/man/man1
.include

The list of shell-style variables tells you what you need to know about where the source for the port comes from, what version the makefile thinks is current, and how to reach the maintainer.
    The MAINTAINER is a volunteer, usually unaffiliated with whoever develops the actual software but a contributing member of the FreeBSD community, whose job is to make sure the port compiles and installs cleanly and that the most recent version of the software is reflected in the port.
     Most makefiles contain targets, such as clean, install, and all. Not all the makefiles in the ports have these targets explicitly defined, but what they do have is an included central makefile (bsd.port.mk, which lives in the /usr/ports/Mk directory along with other included files). This file is what contains the standardized build targets.
    The individual makefiles in each port serve as overrides or augmentations (much in the same way /etc/rc.conf relates to /etc/defaults/rc.conf), setting the necessary variables for the build and defining additional targets that will be used in the automated compile process.

README.html Contains the "short description" (or comment) for the port in HTML format.

The distinfo file contains the md5 and sha256 checksums needed to check the (authenticity of the) download files used to build the port, the size, and the name of the archive containing the source code that will be fetched from the Internet. For security reasons, the ports system will refuse to fetch an archive that doesn’t match the information in this file.

The files/ directory contains any patch files to the application(are applied to the source after it has been unpacked), such as those needed to get the application to run in FreeBSD(these vary greatly from port to port) or to fix a security problem(runme.sh patch-aa patch.ab)

pkg-comment The "short description" for the port.

The pkg-descr file contains a "long description" of the package(pkg_info -d can also be used to display the contents of this file) and usually a web site for the project that created the software.

The pkg-plist file identifies the files installed from the application and the locations in the local file system where to install them. /usr/local is assumed to be at the beginning of each path(as well as keywords telling the port system what to do when the port is deinstalled (for example, removing directories and unchanged files)). For example, if the file gives a location of bin/couchdb, the actual path is /usr/local/bin/couchdb.

pkg-install: Optional script used during the installation(pkg_info -i can also be used to display the contents of this file)

pkg-message: Optional message (usually containing post-installation configuration information) that will be displayed at the end of the installation. If you missed the message or wish to reread it, you can find it here(pkg_info -D can also be used to display the contents of this file).

Besides the executable commands (for example, ftpcp, ftpcopy, and ftpls), the file might also contain libraries, images, or documentation (such as ChangeLog, README or other documents).
So here(listing of /usr/ports/) exist files and directories contain the information needed for the ports collection to work

If you are interested in the inner workings of the FreeBSD ports process, read /usr/ports/Mk/bsd.port.mk (the master file used by the ports system). You will also find useful information in man ports.

The remainder is composed of directories that represent the same categories found at FreshPorts. If you list a directory, you’ll find that it contains subdirectories. Each subdirectory represents a port that can be compiled, and it contains all of the information needed to compile that port.
Note that FreshPorts contains the same files, enabling you to research your ports online before compiling them. CVSWeb has an added advantage in that it shows the entire history for each file. For example, if you click the Makefile link, you will see a history of the Makefile for every version of the port, along with the commit messages that indicate which changes were made and when. If you want to see only the current Makefile, click on the number in the Rev. (revision) column instead.

Doing a Quick Build
For the most basic type of application installation with ports, all you need to do is run a few make commands. Continuing with the example of the ftpcopy application, here’s how you can install an application using a ports collection:

# cd /usr/ports/ftp/ftpcopy Change to the ftpcopy directory in ports
#  make build Download and build ftpcopy application
=>  ftpcopy-0.6.7.tar.gz doesn’t seem to exist in /usr/ports/distfiles/.
=>  Attempting to fetch from http://www.ohse.de/uwe/ftpcopy/.
===>  Extracting for ftpcopy-0.6.7
=> MD5 Checksum OK for  ftpcopy-0.6.7.tar.gz.
=> SHA256 Checksum OK for  ftpcopy-0.6.7.tar.gz.
===>
ftpcopy-0.6.7 depends on  file: /usr/local/bin/perl5.8.8 - found
===> Patching for  ftpcopy-0.6.7
===>
ftpcopy-0.6.7 depends on file:  /usr/local/bin/perl5.8.8 - found
 ===> Applying FreeBSD patches  for ftpcopy-0.6.7
===>
ftpcopy-0.6.7 depends on file: /usr/local/bin/perl5.8.8 - found
===> Configuring for ftpcopy-0.6.7
===> Building for ftpcopy-0.6.7 
...# make install  Install ftpcopy binaries and documents
===> Installing for ftpcopy-0.6.7
===>
Generating temporary packing list
===> Checking if ftp/ftpcopy already installed
cd /usr/ports/ftp/ftpcopy/work/web/ftpcopy-0.6.7/compile &&  install -s -o root
-g wheel -m 555 ftpcopy ftpls /usr/local/bin && install -o root  -g wheel -m
444 ftpcopy.1 ftpcp.1 ftpls.1 /usr/local/man/man1 && install -o  root -g wheel
-m 555 ftpcp /usr/local/bin
/bin/mkdir -p /usr/local/share/doc/ftpcopy && cd
/usr/ports/ftp/ftpcopy/work/web/ftpcopy-0.6.7/compile && install  -o root -g
wheel -m 444 ChangeLog NEWS README THANKS ftpcopy.html ftpls.html
/usr/local/share/doc/ftpcopy
===>
Compressing manual pages for ftpcopy-0.6.7
===>
Registering installation for ftpcopy-0.6.7# make clean  Clean up files left behind from build
===> Cleaning for perl-5.8.8
===> Cleaning for ftpcopy-0.6.7
# pkg_info ftpcopy*  Check that ftpcopy package was installed
ftpcopy-0.6.7
Command line ftp tools for listing and mirroring
# pkg_info -L ftpcopy*  List files from ftpcopy package
Information for ftpcopy-0.6.7:
Files:
/usr/local/man/man1/ftpcopy.1.gz
/usr/local/man/man1/ftpcp.1.gz
/usr/local/man/man1/ftpls.1.gz
/usr/local/bin/ftpcp
/usr/local/bin/ftpcopy
/usr/local/bin/ftpls
/usr/local/share/doc/ftpcopy/ChangeLog
/usr/local/share/doc/ftpcopy/NEWS
...

After changing to the directory representing the application you want to install, you run three make commands.

The make build command downloads the software package (source code distfile), runs checksums to check its validity, applies patches, fulfills dependencies, and builds the binaries (commands).
The make install command puts the application’s files where they need to go in the file system, compresses man pages, and registers the package as installed.
The make clean command cleans up temporary files left behind.
After a package is installed, you can use the pkg_info command to verify that the package is installed.
Then run pkg_info again with -L to list the contents(files) of the package.

make Targets
To compile a port, simply cd to its subdirectory and type make. Wait until the messages stop, and if all goes well, you’ll receive your prompt back without any errors.
To understand what actually happened and how you can customize what happens, you should know a bit about make targets.

Targets are the words that follow the make command.

The most commonly used targets(the complete list of targets is listed in /usr/ports/Mk/bsd.port.mk and man ports) are summarized in Table 10-1. Note that targets are optional but very useful. For example, if you just type make, the port will compile, but it won’t install unless you add the install target (that is, type make install). It's a simple process on the surface, but there's a lot that goes on under the hood. The make command actually executes a series of sequential make targets (described in Table 16.3). Each one depends on all the previous targets completing successfully. You can specify any of these targets directly; this will build all prerequisite targets up to and including the one you specify.

checksum Verifies the authenticity of the tarball using the MD5 checksum
exTRact Unpacks the tarball into a work subdirectory
patch  Applies the patches from the files directory to the source
configure Runs the configure script, which prepares the source for building
build Compiles the source

Typing make extract, for example, will download the source file, match its MD5 checksum, and unpack it. Although there are other targets you won't need to use any of them under most circumstances.
    After each step in the process is complete (except for fetch and checksum), a file is created in the work subdirectory of the form .extract_done. This is how the system keeps track of which steps are completed. (To see whether the fetch step is done, it simply checks for the existence of the tarball in /usr/ports/distfiles.) The extract step runs the checksum step implicitly. After that, the steps are sequential and independent, and they check for prerequisite steps by looking for the appropriate .*_done files.
    If you need to make any changes to the source before compiling, you can run make patch, thus bringing the source up to a state where it's ready to compile, and then make whatever changes you like to the code in the work directory.
    Then, you can complete the process with make.
Dependencies are handled automatically by the ports, just as with the packages. Any dependencies are read from the makefile during the fetch or install phase and then downloaded, built, and installed. You will get feedback in the build output each time it encounters a dependency, regardless of whether that dependency is installed already.

If you run make config-recursive and don’t receive any menus, you might as well save yourself some time and install the package because there isn’t anything to customize for that port.

The TARGETS section of man ports indicates that some targets build upon each other in order. For example, make install is equivalent to make config fetch checksum depends extract patch configure build install. In other words, if you use a target within that ordered list, it will “automagically” include all of the targets that precede it. This means that if you type make config, make will only display the port’s options menu, if it exists. It will not fetch or build any source because those targets come after the config target. However, if you type make install, make will go through all of the targets, starting with config, then fetch, all the way up to install. You may have noticed that each category directory also has a Makefile. This means that you could (if you had a lot of time) install every port in that category by typing make install. For example, to build all www ports, issue the command

# cd /usr/ports/www && make install

make reads only the Makefile in the current directory. If there is no Makefile in your current directory, make will give the error “make: no target to make.” This means you should cd to the desired directory and try again.

There are make targets that are useful within a category directory or the /usr/ports/ directory itself. One is i.e. make readmes. You can click on each category to see a listing of its ports.

After a port is installed, an entry is made in the /var/db/pkg database; for all intents and purposes, it is now a package. You can use the pkg_* tools on it to gather information and compare its version, just as with packages installed from within Sysinstall.

Tip There is a deinstall target in the ports (make deinstall). This target is used when the installed port version is the same as the one in the makefile in essence, you're deinstalling exactly the same software package you installed.

If you update your ports so that the version of a port (in the makefile) is higher than the installed version, you can't use make deinstall to delete it. Instead you have to use pkg_delete, the same way as you would a package.

Using Other make Options
There are other options you can run with the make commands that let you do portions of what was done in the previous procedure separately. Remember that all these commands should be run from the directory associated with the port. To run checksums on the application’s distfile, type the following:

# make checksum  Run checksums on the application’s distfile
=> MD5 Checksum OK for ftpcopy-0.6.7.tar.gz.
=> SHA256 Checksum OK for ftpcopy-0.6.7.tar.gz.

To do the build up to the configure portion, run the following:

# make configure  To the make up to the configuration

To remove the package, type the following:

# make deinstall   Remove the package

If you have made changes to the source code, documents or other components of the package, you might want to repackage those changes into a new distfile.

The following result is that the package is installed and a new distfile tarball is created:

# make package  Create a new distfile tarball of application
===>  Installing for ftpcopy-0.6.7
...
Creating package  /usr/ports/ftp/ftpcopy/ftpcopy-0.6.7.tbz
Registering depends:.
Creating  bzip’d tar ball in ‘/usr/ports/ftp/ftpcopy/ftpcopy-0.6.7.tbz’

To just download the application’s distfile to the /usr/ports/distfiles directory, type the following:

# make fetch  Download the distfile but don’t install it
=> ftpcopy-0.6.7.tar.gz doesn’t seem to exist in /usr/ports/distfiles/.
=> Attempting to fetch from http://www.ohse.de/uwe/ftpcopy/.
ftpcopy-0.6.7.tar.gz
100% of 131 kB 44kBps

To download the selected distfile, plus any dependent distfiles, as follows:

# make fetch-recursive Download the distfile, plus dependencies

While we are on the subject of using make to make cool stuff, here is something useful if you are interested in README files. By running the following commands, in the /usr/ports directory, you can create a README.html file for every package and consolidate those files in a /usr/ports/README.html file (creates a local HTML copy of the specified ports structure). Here’s an example:

# cd /usr/ports
# make readmes  Create lots of README.html  files in /usr/ports

Another useful target to use from /usr/ports/ is search. The first time you run make search, you may be asked to run make fetchindex first.

# cd /usr/ports 
# make search name=youtube | more

The name= keyword (If you are interested in seeing only the Port, Path, and Info sections, use make quicksearch name= instead) in this command tells make to search for port names matching your search pattern. The search results will show the following:

Port: The name and version of the port
Path: The port’s location within the ports directory
Info: A one-line description of the port
Maint: The e-mail address of the port’s maintainer
B-deps: The names and version numbers of the dependencies required to build the port
R-deps: The names and version numbers of the dependencies required to run the application compiled by the port
WWW: The URL to the website for the software

Troubleshooting Errors
Like packages, ports have been pretested for you and should compile on your system without errors.
Occasionally you will receive an error message indicating that the port did not compile. If you receive the error almost immediately, one of the variables in Table 10-2 is probably set in the port’s Makefile.

Of course, you can remove the offending variable from the Makefile to force the port to compile, but that won’t change the underlying reason for including the variable.
If you receive a “Couldn’t fetch it - please try to retrieve this port manually into /usr/ports/distfiles/ and try again” error, double-check your Internet connection and try again.

shell assumes you are running the default pf firewall. If you have disabled pf, you will have to type pfctl -ef /etc/pf.conf in order to have Internet connectivity.

If your error does not seem to be connected with the Makefile or Internet connectivity, try googling the error message to see if there is a known fix. Or try installing another version of the port. If you’re still not having any luck, send an e-mail to the FreeBSD ports mailing list (If this is your first e-mail to the list, be sure to read How to Get Best Results from the FreeBSD-Questions Mailing List first as the information it contains applies to all of the FreeBSD mailing lists).

Checking Packages and Ports
FreeBSD comes with a lot of tools for making sure that the software you install is both safe and up-to-date. There are also tools for comparing installed packages to see if they match what is in the latest ports and to update your ports collection to the latest versions.

Checking Installed Packages Against Ports
You can use the pkg_version command to find out if one or more just installed packages is up-to-date with the latest version available from the ports collection. For example, to check if packages with a given string in their name is up-to-date, try using the -s option as follows:

# pkg_version -v   Check if all packages are up-to-date (verbose)
# pkg_version -v -s ftp   Check if ftp packages are up-to-date with ports
ftpcopy-0.6.7
lftp-3.5.4_1
= up-to-date with port
= up-to-date with port

The ports collection index file is stored in /usr/ports/INDEX-"freebsd release number(actually 8)", by default. When you run the pkg_version command, packages are checked against that file. To check against a different INDEX file, for example one from an earlier or later release, add the name of that INDEX file (either locally or on the Internet) to the end of the command line as follows:

# pkg_version /tmp/INDEX   Check packages against a local INDEX file

Keeping the Ports Tree(Collection) Updated
Just like FreeBSD itself, the Ports Collection is continually updated with new versions of software. Part of upgrading your system includes updating installed ports. The ports collection is constantly being updated, with new ports being added daily, broken ports being fixed (and sometimes working ports becoming broken), and ports being updated to newer versions of the software. Remember that add-on software can have security problems just as the main system software can, and the best defense against intrusion is to keep your software up to date. Upgrading installed software has two steps:

first, updating the Ports Collection to the latest version, and
then updating the installed software to the version supported in the latest Ports Collection.

If you update your system with csup(1), adding the statement ports tag=. to your supfile seamlessly updates your Ports Collection.
If you’re tracking an errata branch, however, you probably upgrade your system with freebsd-update.
Or perhaps you don’t want to update your entire system, just the Ports Collection. That’s where portsnap(8) comes in handy.

Keeping Ports tree Up to Date with portsnap

portsnap(8) downloads and installs compressed snapshots and updates of the Ports Collection, helping system administrators keep their installed software up to date.

Every hour or so, the central FreeBSD portsnap server gathers together all the changes that have occurred in the Ports Collection since the last time it checked. These changes are collected into a patch set.

When you run portsnap(8), you get all of the updates that have accumulated
since the last time you updated your ports tree. portsnap(8) applies those changes to your local Ports Collection, giving you the very latest ports.

PORTSNAP VS .CSUP
Use either portsnap(8) or(but not both) csup(1) to update the Ports Collection. The two tools are incompatible. csup is most useful if you are tracking -stable or -current, while portsnap is best for production systems where you use binary updates. You can make either csup(1) or portsnap(8) work in either situation, but you must pick one and stick with it!

Configuring portsnap
The file /etc/portsnap.conf tells portsnap(8) how to handle its updates. While
very few people must reconfigure portsnap(8), here are the options you’ll most likely want to touch.

You might notice that the configuration for portsnap(8) looks much like the configuration for freebsd-update(8). The same person wrote both tools, and they use similar underlying technologies to perform similar tasks.

The /etc/portsnap.conf file contains keywords with values assigned to them.

SERVERNAME=portsnap.freebsd.org This is the name of your desired portsnap server. The machine portsnap .freebsd.org is actually a pool of machines. It’s possible that the FreeBSD Project will establish regional or national portsnap servers to distribute the load more sensibly, but for now this is the only available portsnap server.
KEYPRINT=9b5... The keyprint is the cryptographic key for the portsnap server. portsnap(8) cryptographically signs updates to guarantee authenticity and integrity. Do not change this.
REFUSE arabic korean The REFUSE variable lets you tell portsnap(8) to not update certain categories of software. This example prevents updates to the arabic or korean categories, much as a csup(1) refuse file does. Just as with csup(1), be careful with what you refuse; the Ports Collection is an integrated whole, and you can wind up with an inconsistent system if you arbitrarily refuse large parts of the tree.

Using portsnap(8)
The first time you run portsnap(8), use the fetch extract command:

# portsnap fetch extract

This tells portsnap to download the portsnap server’s latest snapshot of
the Ports Collection and extracts it under /usr/ports. Only use fetch extract

once, to initialize portsnap(8) into a known state.

For subsequent updates, use the fetch update command:

# portsnap fetch update

This downloads all the changes since the last time you ran portsnap(8) and installs those updates in the Ports Collection.

If you wish to schedule a regular portsnap run via cron(1), it’s best to use the cron update command instead of fetch update. This helps distribute the load on the FreeBSD portsnap server. Schedule a 5 AM portsnap run in root’s crontab with an entry like this:

0  5  *  *  *  /usr/sbin/portsnap cron update

This kicks off the actual update at a random time between 5 AM and 6 AM, which is much more effective than every portsnap(8) user hitting the download
server simultaneously at 5 AM.
That’s really everything you need to know to use portsnap(8) which is an excellent way to get the latest FreeBSD applications without using csup(1) or updating your entire source tree.

The only thing you must do now is get your installed software updated to the version in the Ports Collection.

Keeping Ports Up to Date with CVSup
The csup utility enables you to sync with the current version of the ports tree whenever you wish. In order to use csup, you need a configuration file. A well-commented configuration file is located in /usr/share/examples/cvsup/ports-supfile. If this is your first time using csup, take the time to read through the comments in the example file because they explain the meaning of each line in the file.

Figure 10-8 demonstrates a customized configuration file saved as /root/cvs-supfile, as well as the csup command used to connect to the specified mirror (in this case, cvsup.FreeBSD.org) to sync the local ports tree with the latest release version (RELENG_8) of the ports tree.
Once connected, csup will compare the files on the mirror with your local copy of the ports collection and will download only the files that have changed or are missing.

Power users who would like to keep their ports tree updated on a regular basis should consider adding that csup -L2 command to their crontab.

To keep your ports synchronized, one good tool for the job is CVSup. Because CVSup is an essential tool for working efficiently with ports, it's important that you know some of its simplest uses and there really isn't much to it.
First, install the cvsup package, either by using the package system or by building it from the ports.

In fact, it's better to use the package version because CVSup is a tool written in Modula-3, meaning that building it from source involves building several large Modula-3 dependencies, which takes forever and installs a ton of libraries that you'll probably never need for anything else. Use the package installation to get past that for now.

The next step is to create a CVSup config file, known as a supfile. The purpose of this task is to update your ports, so call the file ports-supfile. As with other configuration files that you create for tasks that aren't part of the basic system, it's best to put this file in /usr/local/etc.
Listing below shows the contents of a suitable supfile for updating your ports:

*default  host=cvsup12.FreeBSD.org
*default  base=/usr
*default  prefix=/usr
*default  release=cvs
*default  tag=.
*default  delete use-rel-suffix
ports-all

The supfile has a number of tunable options. For now, the only one you need to worry about is the *default host= line, which should point to one of the central FreeBSD CVSup servers. There are 18 of these servers, named cvsup1 through cvsup18, each one an alias for a source repository host located at some discrete location in the world. It's difficult to know where each host is without doing a host lookup (host cvsup12.freebsd.org) to see if the hostname to which it resolves gives a clue to its location, but it might be worth it to you to use this technique to examine each of the CVSup hosts to find the one nearest to you.
Now, run the CVSup update:

# /usr/local/bin/cvsup -L 2 /usr/local/etc/ports-supfile

CVSup connects to the selected CVSup server and begins synchronizing your ports collection. Because of the -L 2 option (specifying the highest level of verbosity), you will see all changes between your installed version and the current one scroll by.

CVSup operates by updating only files that have changed and then by updating only the changed pieces (by using diff patches). This allows you to update the entire ports collection while transferring only a minimum of data and using a minimal amount of bandwidth. A CVSup update can be done efficiently and quickly even over a very small network link.

If you're running CVSup within an X11 session, it will use a GUI client interface in a separate window, giving you statistics about the update process as it runs. You can disable this behavior and force CVSup to remain in CLI mode by adding the -g option to the command line.
After the synchronization is complete, your ports collection is current and "up to the minute." You can now run pkg_version -v to see which ports or packages you need to update.
You will probably want to make this synchronization process a part of your system's daily routine so that your ports will never be more than 24 hours out of date. To do this, add the preceding CVSup command to your daily periodic files.
If it doesn't exist already, create a directory called periodic in /usr/local/etc and then another directory called daily underneath that. Inside the daily directory, create a file called something such as 100.cvsup-ports and put these lines in it:

#!/bin/sh
/usr/local/bin/cvsup -g -L 2 /usr/local/etc/cvsupfile

Now, every night when the daily periodic script is executed, your ports collection will be synchronized. The output of CVSup is mailed to you in your daily system status update. If you prefer not to get an email after every night's regular CVSup run, you can suppress its output using the -L 0 option instead of -L 2; that way, the only conditions under which you'll get an email is if errors occurred.

Notes on Forbidden Ports
Sometimes a port is present in the ports collection but the system doesn't allow you to build it. This is controlled by the FORBIDDEN variable in the makefile. If this variable is present, whatever text string it is set to is displayed when you try to build the port, and the build process is cancelled:

# cd /usr/ports/databases/gnats
# make
===>  gnats-3.113.1_12 
is forbidden: Security issues.

A port can be marked "forbidden" for many reasons.

In this example, it's because the program in question has some intractable security problems that make it dangerous to install it.
In other cases, a port might be forbidden because it has been made a part of the core system, and building it from the ports would be redundant and possibly ruin the system's operation.

In either case, this is a good illustration of the need to keep your ports synchronized to the CVSup server as regularly as possible. It's seldom a good idea to force the installation of a forbidden port, but it's possible to do so by simply removing the FORBIDDEN line from the makefile.
Some forbidden ports do provide a built-in way to override the block by setting an environment variable, such as in this example of the security/ssh port (which no longer has this behavior, but other ports might still work this way):

# cd /usr/ports/security/ssh
# make
===>  ssh-1.2.27_3 is forbidden: OpenSSH is a superior version of SSH which has been included in the FreeBSD base system since 4.0-RELEASE. This port is now deprecated and will be removed at some point in the future. To override this
warning set the REALLY_WANT_SSH environment variable and rebuild.

As the instructions say, set the indicated environment variable and try again. Here's how if you're using csh or tcsh:

# setenv REALLY_WANT_SSH yes

And here's how if you're using bash:

# REALLY_WANT_SSH=yes

After setting the variable, run make again. The port should build cleanly.

Reclaiming Hard Disk Space Used by the Port-Building Process
After you're done building and installing a port, the work directory is still sitting there, filled with the unpacked tree of source code and compiled binary objects. This can take up a fair amount of disk space. It's always advisable to clean this directory out after installation returning the port to its original pristine state by running one more make command, this time with the clean target:

# make clean

This deletes the work directory and everything in it.
It also cleans out the port directory for each dependency listed. However, it does not remove the tarball files from /usr/ports/distfiles; you'll have to remove these files yourself.

Unless you really need the disk space, you might want to leave the tarballs intact in the /usr/ports/distfiles directory. You can save a lot of time this way if you should ever need to rebuild or reinstall a port, the system can use the file it already has, instead of having to download it again.

The beauty of ports is that if a security hole or critical bug is fixed in a port that you have installed, the ports collection might solve it by placing a patch file in the files directory of the port, not by bumping the revision number of the entire distribution file (and causing you to have to download a new tarball). A simple rebuild allows you to incorporate the new patch into your old sources.

Periodically, you may want to issue a top-level recursive make clean on the entire ports collection. There's a makefile at both the /usr/ports level and in each directory in the category level below it that enables you to do odd tasks such as building all the ports in a category at once (for example, building every www port by running make from inside /usr/ports/www). More usefully, it lets you clean every port at once, in one very long recursive process. You do this simply by going to /usr/ports and entering make clean. Like cleaning an oven, this process will be worthwhile but usually takes forever.

When a Port Will Not Build: Searching for Solutions
As convenient as the ports collection is, it's not perfect and with the amount of change that goes on in the tree, especially with so many ports (such as the ones related to GNOME and KDE) interrelated and constantly evolving, chances are that you'll run into some stumbling blocks now and then. The general failure behavior is for the compile process to exit abruptly with "*** Error code 1" or a similar message. When this happens, you can try a number of things.

First, make sure you're starting from a clean port. If there is a pre-existing work directory, it's possible that you've mixed new sources with old, resulting in an unbuildable port. Run make clean to start over from a clean slate.
It's also important to make sure you have the very latest ports tree available. If a port doesn't build, it's possible that it's a temporary condition that will have affected many other FreeBSD users besides yourself. A new version of the ported software might have been released since the version your ports refer to, for example, or perhaps your ports refer to a version that was newly released at the time your ports tree was installed, and some of the patches (written for a previous version) might have inadvertently become incompatible. If your ports tree is even a few days out of date, the chances are good that the port has been fixed in the meantime. Synchronize your ports tree as discussed earlier and try building the port again (make sure you run make clean first).
If this doesn't work, it's time to seek outside assistance. Head to the FreeBSD website at http://www.freebsd.org and go to the Mailing Lists link, where you can search the mailing list archives for information about the port you're trying to build. Make sure you select the Ports check box as one of the search criteria. Then perform the search on the name of your port and some of the relevant text in the last few lines of the compiler output. If there's anything commonly failing that other people have noticed, you'll probably find something useful this way.
Still no luck? There's one more good recourse: the port maintainer. Look in the port's Makefile for the MAINTAINER variable, which is set to the email address of the maintainer. Send off a politely worded, undemanding email containing the last (relevant) part of the compiler output, as well as information about your system (the output of uname -a, for instance). The maintainer is usually a very overworked, underappreciated individual, so be sure to express your gratitude for any help!

Upgrading Ports

There are nearly 22,000 ports in the collection, and each one of them is undergoing development (some at much faster rates than others).

A fact of system administration is that you can't install or upgrade software fast enough to keep up with the rate of (individual port) development.

The best you can hope to do is keep your ports collection up to date and use the built-in tools, such as pkg_version, to keep track of what needs to be upgraded.

If you regularly build software from the ports, you should be in the habit of reading the regularly updated /usr/ports/UPDATING file and skimming it for changes to ports that pertain to you. Pay special attention to the AFFECTS: line in each update, as it describes the particular users of various ports that will need to know about special upgrading instructions or important security notices.

If you use csup to update your ports tree, anything you install from now on will be the latest version. But what about update your previously installed applications to their latest versions?
    FreeBSD tracks all sorts of dependency information between add-on packages, and often updating one program will impact dozens of others. This is a royal pain to manage. Wouldn’t it be nice to just say, “Update my Apache install,” and have FreeBSD manage the dependencies for you? FreeBSD provides two different tools for handling this issue, portupgrade(8) and portmaster(8).
    portupgrade is the original updating tool for FreeBSD ports. Written in Ruby, portupgrade maintains databases from the information in the ports tree.
    portmaster is a shell script that handles the most common software maintenance tasks without invoking any extra software or databases, but does not cover all possible edge cases. We cover portmaster; while it’s not as all-
encompassing as portupgrade, it’s far simpler, so there’s less that can go wrong with it.

    In this section, you’ll create a notification script and then learn how to use portupgrade and alternativelly portmaster. First, you should install some useful packages by using pkg_add:

portaudit: Used to compare your installed software to the VuXML database of software vulnerabilities.
portupgrade(or portmaster): Used to upgrade both your installed ports and packages to their latest versions.

The easiest way to upgrade to a newer version of a package is to remove the old one first; then use pkg_add to install the new version.

Power users can also use the portupgrade (/usr/local/sbin/portupgrade command) to upgrade all or some of their FreeBSD software (keep their ports collection up to date) at once.
Once portupgrade is installed(the first cmd in the example), you can use it to either update ports, individual packages or update the entire ports collection(-a option). Here’s an example of updating an individual package in the ports collection:

# pkg_add -r portupgrade
# portupgrade -R konqueror   Update Konqueror software, if it’s installed
[Rebuilding the pkgdb  in /usr/ports ...
15918 port entries found.....................................

If you've updated your ports tree (as described in the previous section) and the version of a port has changed, you can simply use make install to install it over the old version. This can be a bad idea, however, because most of the installed files will be the same from one version to another, so if you try to delete (using pkg_delete) an older version of the same port or package while a newer one is installed over it, you will end up deleting most of the newer version as well.

If you have pkg_version output like the following, you're stuck with the earlier versions in your package database, unless you're willing to deinstall all versions of the package and then reinstall the current version:

apache-1.3.12            <  needs updating (port has 1.3.34)
apache-1.3.14            <  needs updating (port has 1.3.34)
apache-1.3.17            <  needs updating (port has 1.3.34)
apache-1.3.19            =  up-to-date with port

To avoid this situation, always check for a previous version of a port before installing a new one. Use pkg_info, pkg_version, or the /var/db/pkg structure to see what's there already. If there's an earlier version, remove it, like so:

# pkg_delete apache-1.3.12

You shouldn't have to worry about customized config files for the port. In the apache port, for example, the pkg-plist file contains @unexec commands, which compare the configuration files with the default ones installed by the port and delete them only if they match (they correspond to the UNEXEC commands you saw earlier when we looked at package information with pkg_info). Even so, it's a good idea to back up important config files before removing a package or port, just in case.
It's not the end of the world to leave your old versions installed, though. This provides an audit trail so you can view your system's upgrade history, and it doesn't hurt anything to have the old versions around (except that if a port's component files are reorganized, the outdated files on your system will continue to hang around uselessly taking up space, and potentially confusing any other hapless administrator with whom you might be sharing duties).

Using portupgrade
To make your ports even easier to maintain and upgrade, you might want to install Portupgrade, a utility written by members of the FreeBSD team to further support the ports system. Using Portupgrade (which can be installed from the sysutils category), you can upgrade an installed port to a newer version with a single command no need

to research the current version,
deinstall the old version, or any such trivial tasks.

However, Portupgrade should be used with caution its ease of use comes at the expense of some of the safeguards and consistency checks that make building from the ports the safest way to install software.
For example, Portupgrade doesn't automatically upgrade all dependency packages or packages that depend on the one you're upgrading; you have to provide special command-line switches to make it do that (see man portupgrade for details).

Portupgrade is intended as an expert's tool, letting you update large groups of related ports (or all your ports at once, using the -a option) with a single command, but only if you're fully aware of the dangerous implications of such a momentous action.

First update your ports, using CVSup. This ensures that the makefiles in the ports tree all have the most recent versions of all the ports, so you can determine which ports need to be upgraded and to what versions. Use pkg_version to do this: # pkg_version -v
If the port needs to be upgraded rather than going into /usr/ports/ and typing make, make install, and make clean (and deinstalling the old version to replace it with the new one), you can simply issue the following command to perform all these steps at once: # portupgrade .
Notice at the beginning and end of the process that Portupgrade maintains its own database of installed packages, which it uses to compare against the available ports. This database provides the ability for you to look up any given file and find out what package it came from: # pkgdb /usr/local/bin/pdfopt
[Updating the pkgdb in /var/db/pkg ... - 195 packages found (-0 +0) done]
ghostscript-gnu-7.07_11
After the process is done, use pkg_version again to verify that the port has been upgraded successfully:# pkg_version -v
pine-4.64 = up-to-date with port

Tip You can use the portinstall command to install a new port without manually building it with the make command. portinstall is really just an alias for an install-only mode of portupgrade.

If you have software that needs updating, you can use portupgrade to upgrade it.

It doesn’t matter whether you installed the software from a package or compiled it from a port—it can still be upgraded.

Table 10-3 shows the most common switches used with portupgrade. See man portupgrade for a description of all available switches.

portupgrade switches can be stacked, and order does not matter unless the switch requires that it is followed by a variable (add those switches and their variables individually after your stacked switches). For example, you can type portupgrade -an instead of portupgrade -a -n.
It is recommended that you always include -rR to make sure all dependent software is also upgraded. If you don’t, over time you may run into dependency issues.
It is also recommended that you include -b just in case something goes wrong. If you have problems with the new software, use pkg_delete to uninstall the new version and pkg_add to install the backed-up package of the original software.

Never upgrade a port without first reading /usr/ports/UPDATING to see if there are any known gotchas or upgrade hints for that software. Always follow any instructions in this file that apply to the software you are trying to upgrade.

The upgrade process usually goes like this:

Use your notification script to get the latest version of the ports tree and ports index and to determine which software is vulnerable or has a newer version.
Decide whether you want to upgrade all of your outdated software or only a specific application.
Read /usr/ports/UPDATING to see whether there are any special instructions for the software you wish to upgrade.
If you have customized configuration files for the software being updated (for example, a customized httpd.conf for Apache), make sure you have a backup of those files.
Run a command such as portupgrade -abrR to upgrade all software, or portupgrade -brR name_of_software to upgrade only the specified software.

Your software upgrade should “just work.” If you run across an error, double-check your Internet connectivity, check that you didn’t miss anything in /usr/ports/UPDATING, or try googling the error.
You can also try waiting a day or so and rerunning csup because sometimes a missing patch will be added to the ports tree. On the off chance that the new version doesn’t work, you’ll be glad that you saved a backup package of the old version. This last scenario is rare, but it is always best to be safe rather than sorry!

Another tool for upgrading installed ports is portmanager(/usr/local/sbin/portmanager). After installing portmanager, you can upgrade port skeletons for whatever ports you choose. Here are some examples:

# cd /usr/ports/ports-mgmt/portmanager
# make install clean   Compile and install portmanager.
# portmanager -u       Upgrade all ports
# portmanager -ui      get asked for confirmation of every step Portmanager will perform
# portmanager math/gnumeric   Upgrade selected ports

Initial portmaster Setup
Look for portmaster in /usr/ports/ports-mgmt/portmaster. The usual make install clean shuffle installs it. After your install, run portmaster -L to see what it has to say about your installed ports. This can take a few minutes to run, so I
suggest capturing the output in a file for leisurely analysis. (You could also use
portmaster -l instead; this runs faster and provides the dependency information, but does not note obsolete ports.)

# portmaster -L > portmaster.out

portmaster categorizes ports by their relationships to one another, taking into account which other software each package requires to work properly. For example, to work correctly OpenOffice requires the X Window System, assorted graphics programs, security libraries, miscellaneous fonts, and a kitchen sink with a garbage disposal of 5.5 horsepower or greater. None of these programs are part of the FreeBSD base system, and if they’re not installed, OOo will not run. OOo therefore lists all of these programs as dependencies. In return, all those programs list OOo as a dependent program. These relationships allow portmaster to build a relationship tree between the ports, and portmaster uses tree terminology when referring to ports.

portmaster starts with root ports, which do not have dependencies and are not depended on by any other program. For example, portmaster itself requires no software other than itself, and no other program on my system requires portmaster. A few other programs, such as bash, sudo, and zip, are commonly installed root ports.
The trunk ports have no dependencies, but are required by other programs. Many shared libraries for graphics, encryption, and mathematics fall into this category, as do a variety of scripting and programming languages. If you use Perl, for example, the base Perl install would almost certainly be a trunk port.
Further up the tree we have branch ports, which both require other ports and are required by other ports. Common branch ports include Java, the X Window System, and web browser rendering engines.
Leaf ports are the tips of the tree; they have dependencies, but no programs depend on them. Typical leaf ports include text editors, oversized office suites, web browsers, chat clients, and so on.

When updating ports, it’s entirely possible that a change to a trunk or branch port will affect leaf ports. If you upgrade a graphics library to a new version that is incompatible with the old version, don’t be surprised if all the graphics programs using that library will no longer function.

Identifying Unneeded Software
Many of us have systems where we install software ad-hoc, play with it for a while, and then forget to remove it when we decide to not use it. When upgrade time comes, it makes sense to remove these software packages rather than spend the time to upgrade them. That’s where portmaster’s list of root and leaf ports is especially valuable.
    portmaster(8) starts its printout with the root ports. Go through the list and identify any programs you no longer want or require. If you’re not sure where a package came from, run whereis packagename to see where the port lives.
    Check the package description in the port to jog your memory and, if you still don’t recognize the program, or remember it and don’t want it, feel free to uninstall it. If it turns out to be something vital, you can always reinstall it later. Do the same with the leaf ports at the end of the list. Why upgrade what you don’t need?
    portmaster’s -e flag uninstalls a port and its dependencies, if those dependencies are not required by other ports. For example, were I to uninstall OpenOffice.org, I would have many ports I no longer need. Running portmaster -e openoffice.org-2.2.0 would remove OOo and all ports required by nothing else but OOo.

Identifying and Upgrading Software
Upgrade candidates appear in portmaster(8) output like this:

===>>> linux_base-fc-4_8
          ===>>> New version available: linux_base-fc-4_9

My laptop currently has linux_base version 4_8 installed, and 4_9 is available. Is it worth going through an upgrade for a minor point release like that? Maybe, maybe not. You can always check the FreeBSD CVSWeb history for the port to see what changes took place. If it’s a critical security issue, you almost certainly want to update, but if not there’s no real rush. It is up to you.
If you want to update, just give portmaster the name of the port you want to upgrade. You can use the port name, the full path to the package database for the port, or use a few other methods shown in portmaster(8).

# portmaster linux_base-fc-4_8

portmaster first searches for any dependencies that need to be upgraded as part of this upgrade and kicks off jobs to upgrade those ports. It also starts fetching distfiles for the upgrade target and the dependencies.

portmaster also front-loads the parts of the port build process that require user interaction. It tries to get all of the information it requires from you right up front, so that you can walk away and be assured that your upgrade won’t be hung up waiting for you to press ENTER halfway through.

There’s always a risk that the upgrade will fail. As uninstalling the old version is a necessary prerequisite to installing the upgrade, there’s a window
where a failure might leave you without either the old or the new versions of
the software. portmaster doesn’t just uninstall the port, however;
    it also creates a backup package of the old version of the software. This backup is deleted once the upgrade succeeds, but you can retain it with the -b flag. The backups are kept in /usr/ports/packages/All.
    What’s more, if you’re upgrading a whole chain of packages, portmaster retains the backups of all dependent packages until the entire upgrade is complete. If I try to upgrade OpenOffice.org with portmaster and the build fails, I’ll need the older versions of my OpenOffice.org dependencies to use the older version of the software. portmaster tries hard to not leave you with an unusable mix of old and new software.
    I like to keep backup packages around until I know that the new version works exactly the way I like, but some of you are much smarter than I am and don’t require such a safety belt.

Forcing a Rebuild
portmaster can’t identify every reason why a port would need an upgrade or reinstall. For example, my test server has the latest version of sudo(8) on it. If we check the shared libraries that program requires, we’ll see something interesting:

# ldd `which sudo`
/usr/local/bin/sudo:
libutil.so.5=> /lib/libutil.so.5 (0x28093000)
libpam.so.3 => /usr/lib/libpam.so.3 (0x2809f000)
libopie.so.4 => /usr/lib/libopie.so.4 (0x280a6000)
libc.so.6=> /lib/libc.so.6 (0x280af000)
libmd.so.3 => /lib/libmd.so.3 (0x28193000)

when i.e. libutil.so.5 and libc.so.6 showed up as obsolete if I had blindly erased them, my sudo would no longer work. Instead, I’m now hunting for all the programs that require those libraries. portmaster doesn’t see that sudo requires an upgrade, but I see that it requires a reinstall. I could go into the port directory and do a make deinstall && make reinstall, or I could just do:

# portmaster sudo

This forces portmaster to rebuild sudo(8). The process of building sudo automatically links it against the most recent library, removing one dependency on that obsolete file. If I need to do this with a leaf port, I can use -f to tell portmaster(8) to rebuild all dependencies whether needed or not.

Rebuilding Upward Dependencies
portmaster automatically updates programs required by a program you want to update, but it can also be told to upgrade everything that depends on the program you’re updating. This can quickly cover large numbers of ports if you’re updating a critical library.

Use the -r flag to tell portmaster to check all the upward as well as downward dependencies.

CAUTION IS FOR THE WEAK! FULL SPEED AHEAD!
If you use the -a flag, portmaster tries to update everything it thinks needs an update. Use -af, and portmaster will rebuild all of your ports.

Changing Dependencies
One important but less frequently needed change is replacing one port with another . For example, suppose I wanted to replace my Emacs 20 install with Emacs 21. portmaster can handle that for us easily with the -o argument. You’ll need to specify the new port and the old installed port, in that order:

# portmaster -o editors/emacs20 editors/emacs21

This isn’t common, mind you, but after surviving several major changes in software over the years I’m very grateful the capability exists!

Ignoring Ports
Occasionally, you really don’t want to update a port even if you specify recursion. For example, when I build a new OpenOffice.org, my laptop is tied up for a day. I really don’t want to update OpenOffice.org as part of another update; I want to choose exactly when that update happens.
portmaster checks each package database directory for a file called +IGNOREME. If that file exists, portmaster will not update that package as
part of an update of other dependencies.

# cd /var/db/pkg/openoffice.org-2.0.20060818
# touch +IGNOREME

Even if I update a library that OpenOffice.org depends on and tell portmaster to update every program that depends on that library, portmaster will not update OOo itself. OOo might break as a result of that dependency update, but that’s a risk I take when choosing this path.

Other portmaster Features
I highly recommend reading portmaster(8) to see what functions it includes that will help solve your problems. You can resume failed builds, see what portmaster would do if you let it upgrade the system, save packages in your package repository, and so on. If you have a port upgrade problem, portmaster(8) probably has your solution.

Reducing the Size of the Ports Tree
The ports tree grows over time. Part of this growth is good, as new ports are added to the tree. Part of this growth is a necessary evil, such as temporary retention of older versions of software you’ve just upgraded. The rest of this growth is an unnecessary evil, as files that were once important but are now
obsolete are never removed from the system. For example, now that I’ve updated my Linux package to Fedora Core 4, those distfiles for Fedora Core 3
are no longer useful. Finding and removing old files can save gigabytes of disk
space, and that space is not (yet) infinite.

While portmaster offers to delete unused distfiles for you, it’s still worthwhile to perform global checks for unnecessary distfiles.

portmaster can check for stale distfiles. If you run portmaster --clean-distfiles, portmaster(8) will identify each unnecessary distfile and ask if you want to delete it. If you run portmaster --clean-distfiles-all, portmaster deletes the old distfiles without asking.
    Another common problem is not running make clean after installing a
port. Often, I want source code easily at hand while first learning a program,
so I don’t clean my own ports. Eventually I forget about them, and they lounge around filling up disk space. I found that I had neglected to clean up after building OpenOffice.org the last time; no wonder my disk looked bloated! FreeBSD ports are easy enough to clean en masse; just go to /usr/ports and type make clean NOCLEANDEPENDS=yes.
    This recourses through the ports tree and does a make clean for every port,
methodically removing every work directory.
With these tools, you can keep your system as up to date as you like. Now
let’s switch from the basics of FreeBSD administration to some of the things
you can do with FreeBSD.

Uninstalling a Port
To uninstall a port, cd into its directory and type make deinstall. FreshPorts or pkg_info -ox will tell you the port’s location in the ports tree.
    Alternately, you can delete the port by using pkg_delete. Either way, you can then use pkg_info to verify that the software has been uninstalled.

Caution The pkg_delete command will not let you uninstall software that is required by other applications. However, make deinstall will. If you’re worried about inadvertently uninstalling dependencies, use pkg_delete instead.

Automatic Notifications with FreshPorts
When newer versions of FreeBSD packages become available, you can configure FreshPorts to send you an e-mail when changes are made to your installed ports.

To do so, you’ll have to first create an account with FreshPorts. Once you have activated your account and are logged in, a Watch Lists section will appear in the right frame of the FreshPorts website.
Click the Upload hyperlink, which will open the page
From shell, type pkg_info -qoa|more. This will create a list of the ports you have installed. Depending on what you have installed, this list may be several pages long. Cut/paste the list of ports you see in shell into the Paste box seen in step 2. Then, return to shell and press the spacebar to go to the next page so you can copy/paste its ports. Repeat until you get your prompt back in shell.
When finished, double-check that your pasted list contains only ports (e.g., not the word More); then click the Upload button. You should receive a message that your watch list has been updated. You can then configure how often you want to be notified by going back to Watch Lists ➤ Report Subscriptions.

Check the box next to Watch List Notification. If you don’t want to receive a daily e-mail, click Day to choose another selection from the drop-down menu. When finished, press the update button at the bottom of the page. You’ll now receive an e-mail regarding any changes to your ports at the frequency that you configured.

Don’t forget to update your watch list whenever you add new packages. You can choose to replace or append (add to) your list.

Auditing Installed Packages
The portaudit(/usr/local/sbin/portaudit) command (pkg_add -r portaudit to install it) lets you check your installed packages for known security vulnerabilities (like nessus for other OSs). Regardless of whether or not your FreeBSD system is using the latest ports collection, you can use portaudit to check your installed packages against a database of security advisories.
The portaudit database is kept in the /usr/local/etc/periodic/security directory. The portaudit package contains a script in that directory for updating the security advisories as they become available.

Those advisories are updated by the FreeBSD security team, as well as by those who commit ports to the ports collection.

You can run portaudit to get the latest ports security database:

# portaudit -Fda   Download the ports security database
auditfile.tbz 100% of 47 kB 26 kBps
New database installed.

Next you can check all installed packages against the ports security database by typing the following:

# portaudit -a  Check all installed packages against security  database
Affected package: libxine-1.1.2_2
Type of  problem: libxine -- buffer overflow vulnerability.
Reference:
http://www.FreeBSD.org/ports/portaudit/6ecd0b42-ce77-11dc-89b1-000e35248ad7.html
Affected package: xorg-server-6.9.0_5
Type of problem: xorg -- multiple vulnerabilities.Reference:


http://www.FreeBSD.org/ports/portaudit/fe2b6597-c9a4-11dc-8da8-0008a18a9961.html

...
44 problem(s) in your installed packages found.
You are advised to update or deinstall the affected pacakge(s)  immediately.

Instead of waiting for packages to be installed, you can check a single package for vulnerabilities before it is installed using the -f option:

# portaudit -f /usr/ports/distfiles/ftpcopy*  Check a package for  vulnerabilities
0 problem(s) found.

In the information produced by portaudit, security vulnerabilities are accompanied by links to descriptions of the vulnerabilities found. Then you can decide whether or not you want to update, patch, or remove the vulnerable software package.

Cleaning Up the Ports Collection
After each time you install a package from the ports system, it is usually best to run the make clean command to get rid of the temporary files created during the builds. If you forget to do that some time, a lot of unneeded files can fill your disk space.
You can clean out groups of unneeded files(work directories of files left behind) in your ports collection at once using the portsclean command (portsclean is in the portupgrade package: pkg_add -r portupgrade).
Although work files are cleaned out when you run the make clean command, the distfiles (source code tarballs) that are downloaded to /usr/ports/distfiles are
not cleaned out. Depending on how many ports you install, this directory can grow quite large. You can use the -D option to portsclean to remove ports that not are referenced by any ports any longer:

# portsclean -D   Remove unreferenced distfiles
Detecting  unreferenced distfiles...

Likewise, you can have portsclean check all distfiles and remove any distfiles that are not referenced by a port that is installed currently:

# portsclean -DD  Remove unreferenced distfiles of uninstalled  ports
Detecting unreferenced distfiles...
[Updating the  pkgdb  in /var/db/pkg ...
- 440 packages found (-0 +2) .. done]
Delete /usr/ports/distfiles/LPRng-3.8.28.tgz

You clean out all your ports work files at once using the -C option:

# portsclean -C    Remove ports work files
Cleaning out  /usr/ports/*/*/work...
Delete /usr/ports/ftp/ftpcopy/work
Delete  /usr/ports/net/samba-nmblookup/work
...

Packages that are not referenced by other packages (called leaf packages) can be cut interactively using the pkg_cutleaves command (as root user, type this: pkg_add -r pkg_cutleaves). To list unreferenced(not referenced by any other package) packages, type the following:

# pkg_cutleaves -lc    List unreferenced packages
3dm-2.04.00.018,1  - 3ware RAID controller monitoring daemon and web server
...

You can cut unreferenced packages as follows:

# pkg_cutleaves   Step through unreferenced packages list (keep or delete)
package 1 of 147
3dm-2.04.00.018,1 - 3ware RAID controller monitoring daemon and web server
3dm-2.04.00.018,1 - [keep]/(d)elete/(f)lush marked pkgs/(a)bort? d
3dm-2.04.00.018,1 - 3ware RAID controller monitoring daemon and web server
 Package 2 of 147:
44bsd-more-20000521 - The pager installed with FreeBSD before less(1) was
imported
44bsd-more-20000521 - [keep]/(d)elete/(f)lush marked pkgs/(a)bort? f
Deleting 3dm-2.04.00.018,1 (package 1 of 1).

Go on with new leaf packages ((y)es/[no])? no
** Deinstalled packages:
3dm-2.04.00.018,1
** Number of deinstalled packages: 1

As each unreferenced package is displayed, you can mark it

to keep (press Enter) or
delete (d) or
abort (a)

After you have marked some packages, you can flush them by typing f. You can quit at any time by typing a to abort.

Resources

BSD UNIX TOOLBOX 1000+ Commands for FreeBSD, OpenBSD, and NetBSD®Power Users (2008 by Wiley Publishing) by Christopher Negus, François Caen ISBN: 978-0-470-37603-4

FreeBSD Unleashed(2006 by Sams) By Brian Tiemann Sams ISBN: 978-0-672-32875-6

The Definitive Guide to PC-BSD(2010 Apress) by Dru Lavigne ISBN: 978-1-4302-2642-0

1 comment:

Gerald05 November, 2011 06:39
An amazing, clear, and useful dissertation. Thanks.
ReplyDelete
Replies

Add comment

Harrykar's Techies Blog

Total Pageviews

Search: This Blog, Linked From Here, The Web, My fav sites, My Blogroll

Translate

22 June 2010

FreeBSD --- Packages and Ports

Adding, Deleting,and Managing Software

Resources

1 comment: