Using the Ports Collection

The Ports Collection is essentially a set of Makefiles, patches, and description files placed in /usr/ports.

The first thing that should be explained when it comes to the Ports Collection is what is actually meant by a ``skeleton''. In a nutshell, a port skeleton is a minimal set of files that tell your FreeBSD system how to cleanly compile and install a program. Each port skeleton includes:

Some ports have other files, such as pkg-message. The ports system uses these files to handle special situations.

The port includes instructions on how to build source code, but does not include the actual source code. You can get the source code from a CD-ROM or from the Internet. Source code is distributed in whatever manner the software author desires. Frequently this is a tarred and gzipped file, but it might be compressed with some other tool or even uncompressed. The program source code, whatever form it comes in, is called a ``distfile''

Note: You must be logged in as root to install ports.
Warning: Before installing any port, you should be sure to have an up-to-date Ports Collection and you should check http://vuxml.freebsd.org/ for security issues related to your port.
A security vulnerabilities check can be automatically done by portaudit before any new application installation. This tool can be found in the Ports Collection (security/portaudit). Consider running portaudit -F before installing a new port, to fetch the current vulnerabilities database. A security audit and an update of the database will be performed during the daily security system check.



When installing your FreeBSD system, sysinstall asked if you would like to install the Ports Collection. We chose yes and thus we have the ports collection installed. However if you chose no, you can still install the ports collection using sysinstall and installing them from CD or cvsup.

UPDATING YOUR PORTS COLLECTION USING CVSUP

The alternative method to obtain and keep your ports collection up to date is by using CVSup. Look at the ports CVSup file, /usr/share/examples/cvsup/ports-supfile.

This is a quick method for getting the Ports Collection using CVSup.

  1. Install the net/cvsup port. We did this yesterday and we installed cvsup-without-gui.

  2. As root, edit /usr/share/examples/cvsup/ports-supfile

  3. Change CHANGE_THIS.FreeBSD.org to a CVSup server near you. In our case this will be noc.e0.ws.afnog.org

  4. Run cvsup:

    # cvsup -g -L 2 /usr/share/examples/cvsup/ports-supfile

  5. It is wise to do this regularly in order to ensure that you install the latest version of a port each time you use ports for installation.

Installing Ports



To begin, change to the directory for the port you want to install:

# cd /usr/ports/sysutils/lsof

In some rare cases, users may need to acquire the tarballs from a site other than the MASTER_SITES (the location where files are downloaded from). In our case, we are doing this so that we may download the package form our local ftp server rather than form the internet. You can override the MASTER_SITES option with the following command:

# cd /usr/ports/sysutils/lsof (this should be changed to the particular port you're installing at the time)
# make MASTER_SITE_OVERRIDE= \
ftp://noc.e0.ws.afnog.org/pub/FreeBSD/ports/distfiles/

In this example we change the MASTER_SITES option to noc.e0.ws.afnog.org/pub/FreeBSD/ports/distfiles/.

Once inside the lsof directory, you will see the port skeleton. The next step is to compile, or ``build'', the port. This is done by simply typing make at the prompt. Once you have done so, you should see something like this:

noc# make
===>  Vulnerability check disabled, database not found
=> lsof_4.75C.freebsd.tar.bz2 doesn't seem to exist in /usr/ports/distfiles/.
=> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
fetch: ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/lsof_4.75C.freebsd.tar.bz2: File unavailable (e.g., file not found, no access)
=> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/NEW/.
lsof_4.75C.freebsd.tar.bz2                    100% of  437 kB 1429  Bps 00m00s
===>  Extracting for lsof-4.74.2
=> Checksum OK for lsof_4.75C.freebsd.tar.bz2.
===>  Patching for lsof-4.74.2
===>  Applying FreeBSD patches for lsof-4.74.2
===>  Configuring for lsof-4.74.2


(compilation output snipped)

Notice that once the compile is complete you are returned to your prompt. The next step is to install the port. In order to install it, you simply need to tack one word onto the make command, and that word is install:

noc# make install
===>  Installing for lsof-4.74.2
===>   Generating temporary packing list
===>  Checking if sysutils/lsof already installed
install  -s -o root -m 2755 -g kmem /usr/ports/sysutils/lsof/work/lsof_4.75C.freebsd/lsof /usr/local/sbin
install  -o root -g wheel -m 444 /usr/ports/sysutils/lsof/work/lsof_4.75C.freebsd/lsof.8 /usr/local/man/man8/lsof.8
install  -o root -g wheel -m 555 /usr/ports/sysutils/lsof/work/lsof_4.75C.freebsd/scripts/* /usr/local/share/lsof
cd /usr/local &&  /usr/bin/find -s share/lsof -type f -o -type l >>/usr/ports/sysutils/lsof/work/.PLIST.mktmp ; /usr/bin/find -d share/lsof -type d  | /usr/bin/sed -e 's/^/@dirrm /g' >>/usr/ports/sysutils/lsof/work/.PLIST.mktmp
===>   Compressing manual pages for lsof-4.74.2
===>   Registering installation for lsof-4.74.2
===> SECURITY REPORT: 
      This port has installed the following binaries which execute with
      increased privileges.
/usr/local/sbin/lsof

      If there are vulnerabilities in these programs there may be a security
      risk to the system. FreeBSD makes no guarantee about the security of
      ports included in the Ports Collection. Please type 'make deinstall'
      to deinstall the port if this is a concern.

      For more information, and contact details about the security
      status of this software, see the following webpage: 
http://people.freebsd.org/~abe/





Once you are returned to your prompt, you should be able to run the
application you just installed. Since lsof is a program that
runs with increased privileges, a security warning is shown. During
the building and installation of ports, you should take heed of any
other warnings that may appear.


Note: You can save an extra step by just running
make install instead of make and make install
as two separate steps.


Note: Some shells keep a cache of the commands
that are available in the directories listed in the PATH
environment variable, to speed up lookup operations for the
executable file of these commands. If you are using one of these
shells, you might have to use the rehash command after
installing a port, before the newly installed commands can be used.
This command will work for shells like tcsh. Use the hash
-r command for shells like sh or bash.
Look at documentation for your shell for more information.








The ports system uses fetch
to download the files, which honors various environment
variables, including FTP_PASSIVE_MODE, FTP_PROXY,
and FTP_PASSWORD. You may need to set one or more of these
if you are behind a firewall, or need to use an FTP/HTTP proxy. 



For users which cannot be connected all the time, the make
fetch option is provided. Just run this command at the
top level directory (/usr/ports) and the required files will
be downloaded for you. This command will also work in the lower level
categories, for example: /usr/ports/net. Note that if a port
depends on libraries or other ports this will not fetch the
distfiles of those ports too. Replace fetch with
fetch-recursive if you want to fetch all the dependencies of
a port too.


Note: You can build all the ports in a category or
as a whole by running make in the top level directory, just
like the aforementioned make fetch method. This is
dangerous, however, as some ports cannot co-exist. In other cases,
some ports can install two different files with the same filename.








Overriding the Default Ports Directories


Sometimes it is useful (or mandatory) to use a different distfiles
and ports directory. The PORTSDIR and PREFIX
variables can override the default directories. For example:


# make PORTSDIR=/usr/home/example/ports install

will compile the port in /usr/home/example/ports and install
everything under /usr/local.


# make PREFIX=/usr/home/example/local install

will compile it in /usr/ports and install it in
/usr/home/example/local.


And of course,


# make PORTSDIR=../ports PREFIX=../local install

will combine the two (it is too long to completely write on this
page, but it should give you the general idea).


Alternatively, these variables can also be set as part of your
environment. 



4.5.3 Removing Installed Ports


Now that you know how to install ports, you are probably wondering
how to remove them, just in case you install one and later on decide
that you installed the wrong port. We will remove our previous
example (which was lsof for those of you not paying
attention). As with installing ports, the first thing you must do is
change to the port directory, /usr/ports/sysutils/lsof.
After you change directories, you are ready to uninstall lsof.
This is done with the make deinstall command:


# cd /usr/ports/sysutils/lsof
# make deinstall


That was easy enough. You have removed lsof from your
system. If you would like to reinstall it, you can do so by running
make reinstall from the /usr/ports/sysutils/lsof
directory.


The make deinstall and make reinstall sequence
does not work once you have run make clean. If you want to
deinstall a port after cleaning, use pkg_delete


Ports and Disk Space


Using the Ports Collection will use up disk space over time.
Because of this tendency of the ports tree to grow in size, after
building and installing software from the ports, you should always
remember to clean up the temporary work directories using
the make clean command. This will remove the work
directory after a port has been built and installed. You can also
remove the source distribution files from the distfiles
directory, and remove the installed ports if the need for them has
passed.


THE REFUSE FILE.


Some users choose to limit the available port categories by
placing an entry in the refuse file. This way, when they run
the CVSup application, it will not download the files in that
category.  You can find more information in the refuse file and how
to use it by reading /usr/share/examples/cvsup/refuse.README  There
is a sample refuse file in this directory as well.


Upgrading Ports


Note: Once you updated your Ports Collection,
before attempting a port upgrade, you should check the
/usr/ports/UPDATING file. This file describes various issues
and additional steps users may encounter and need to perform when
updating a port.


Keeping your ports up to date can be a tedious job. For instance,
to upgrade a port you would go to the ports directory, build the
port, deinstall the old port, install the new port, and then clean up
after the build. The sysutils/portupgrade
utility will do everything for you! Just install it like you would
any other port, using the make install clean
command.


    
	
  1. cd /usr/ports/sysutils/portupgrade
    



# cd /usr/ports/sysutils/lsof
# make MASTER_SITE_OVERRIDE=ftp://noc.e0.ws.afnog.org/pub/FreeBSD/ports/distfiles/
# make install 

Now create a database with the pkgdb -F command. This will
read the list of installed ports and create a database file in the
/var/db/pkg directory. 



#pkgdb -F


Now when you run portupgrade -a, it will read this and
the ports INDEX file. Finally, portupgrade will begin
to download, build, backup, install, and clean the ports which have
been updated. portupgrade comes with a lot of options for
different use cases, the most important ones will be presented below.


If you want to upgrade only a certain application, not the
complete database, use portupgrade pkgname,
include the flags -r if portupgrade should act on
all those packages depending on the given package as well, and -R
to act on all packages required by the given packages. Let 



To use packages instead of ports for installation, provide -P.
With this option portupgrade searches the local directories
listed in PKG_PATH, or fetches packages from remote site if
it is not found locally. If packages can not be found locally or
fetched remotely, portupgrade will use ports. To avoid using
ports, specify -PP.


To just fetch distfiles (or packages, if -P is
specified) without building or installing anything, use -F.



Note: It is important to regularly update the
package database using pkgdb -F to fix inconsistencies,
especially when portupgrade asks you to. Do not abort
portupgrade while it is updating the package database, this
will leave you an inconsistent database.


Other utilities exist which will do this, check out the
ports/sysutils directory and see what you come up with.


Post-installation Activities


After installing a new application you will normally want to read
any documentation it may have included, edit any configuration files
that are required, ensure that the application starts at boot time
(if it is a daemon), and so on.


The exact steps you need to take to configure each application
will obviously be different. However, if you have just installed a
new application and are wondering ``What now?'' these tips might
help: