Chapter 5. Using pkgsrc
Prev | Part I. The pkgsrc user's guide | Next

## Chapter 5. Using pkgsrc

Basically, there are two ways of using pkgsrc. The first is to only install the package tools and to use binary packages that someone else has prepared. This is the “pkg” in pkgsrc. The second way is to install the “src” of pkgsrc, too. Then you are able to build your own packages, and you can still use binary packages from someone else.

## 5.1. Using binary packages

On the cdn.NetBSD.org site and mirrors, there are collections of binary packages, ready to be installed. These binary packages have been built using the default settings for the directories, that is:

- `/usr/pkg` for `LOCALBASE`, where most of the files are installed,

- `/usr/pkg/etc` for configuration files,

- `/var` for `VARBASE`, where those files are installed that may change after installation.

If you cannot use these directories for whatever reasons (maybe because you're not root), you cannot use these binary packages, but have to build the packages yourself, which is explained in Section 4.2, “Bootstrapping pkgsrc”.

### 5.1.1. Finding binary packages

To install binary packages, you first need to know from where to get them. The first place where you should look is on the main pkgsrc CDN in the directory `/pub/pkgsrc/packages`.

This directory contains binary packages for multiple platforms. First, select your operating system. (Ignore the directories with version numbers attached to it, they just exist for legacy reasons.) Then, select your hardware architecture, and in the third step, the OS version and the “version” of pkgsrc.

In this directory, you often find a file called `bootstrap.tar.gz` which contains the package management tools. If the file is missing, it is likely that your operating system already provides those tools. Download the file and extract it in the `/` directory. It will create the directories `/usr/pkg` (containing the tools for managing binary packages and the database of installed packages).

### 5.1.2. Installing binary packages

In the directory from the last section, there is a subdirectory called `All/`, which contains all the binary packages that are available for the platform, excluding those that may not be distributed via HTTP or FTP.

To install packages directly from an FTP or HTTP server, run the following commands in a Bourne-compatible shell (be sure to su to root first):

    # PATH="/usr/pkg/sbin:/usr/pkg/bin:$PATH"
    # PKG_PATH="https://cdn.NetBSD.org/pub/pkgsrc/packages"
    # PKG_PATH="$PKG_PATH/OPSYS/ARCH/VERSIONS/All/"
    # export PATH PKG_PATH
    # pkg_add pkgin

Instead of URLs, you can also use local paths, for example if you are installing from a set of CDROMs, DVDs or an NFS-mounted repository. If you want to install packages from multiple sources, you can separate them by a semicolon in `PKG_PATH`.

After these preparations, installing a package is very easy:

    # pkgin search nginx
    nginx-1.19.6         Lightweight HTTP server and mail proxy server
    nginx-1.18.0nb8      Lightweight HTTP server and mail proxy server
    # pkgin install zsh nginx-1.19.6 vim

Note that pkgin is a user-friendly frontend to the pkg_* tools.

Any prerequisite packages needed to run the package in question will be installed, too, assuming they are present in the repository.

After you've installed packages, be sure to have `/usr/pkg/bin` and `/usr/pkg/sbin` in your `PATH` so you can actually start the just installed program.

### 5.1.3. Updating packages

To update binary packages, it is recommended that you use pkgin upgrade. This will compare the remote package repository to your locally installed packages and safely replace any older packages.

Note that pkgsrc is released as quarterly branches. If you are updating to a newer quarterly branch of pkgsrc, you may need to adjust the repository in `/usr/pkg/etc/pkgin/repositories.conf`.

### 5.1.4. Deinstalling packages

To deinstall a package, it does not matter whether it was installed from source code or from a binary package. Neither the pkgin or the pkg_delete command need to know.

To delete a package, you can just run pkgin remove `package-name`. The package name can be given with or without version number.

### 5.1.5. Getting information about installed packages

The pkg_info shows information about installed packages or binary package files. As with other management tools, it works with packages installed from source or binaries.

### 5.1.6. Checking for security vulnerabilities in installed packages

The pkgsrc Security Team and Packages Groups maintain a list of known vulnerabilities to packages which are (or have been) included in pkgsrc. The list is available from the NetBSD CDN at https://cdn.NetBSD.org/pub/NetBSD/packages/vulns/pkg-vulnerabilities.

Please note that not every "vulnerability" with a CVE assignment is exploitable in every configuration. Some bugs are marked as active simply because an fix was not marked as such. Operating system specific hardening and mitigation features may also reduce the impact of bugs.

Through pkg_admin fetch-pkg-vulnerabilities, this list can be downloaded automatically, and a security audit of all packages installed on a system can take place.

There are two components to auditing. The first step, pkg_admin fetch-pkg-vulnerabilities, is for downloading the list of vulnerabilities from the NetBSD FTP site. The second step, pkg_admin audit, checks to see if any of your installed packages are vulnerable. If a package is vulnerable, you will see output similar to the following:

    Package samba-2.0.9 has a local-root-shell vulnerability, see
        https://www.samba.org/samba/whatsnew/macroexploit.html

You may wish to have the vulnerabilities file downloaded daily so that it remains current. This may be done by adding an appropriate entry to the root users crontab(5) entry. For example the entry

    # Download vulnerabilities file
    0 3 * * * /usr/pkg/sbin/pkg_admin fetch-pkg-vulnerabilities >/dev/null 2>&1
    # Audit the installed packages and email results to root
    9 3 * * * /usr/pkg/sbin/pkg_admin audit |mail -s "Installed package audit result" \
    	    root >/dev/null 2>&1

will update the vulnerability list every day at 3AM, followed by an audit at 3:09AM. The result of the audit are then emailed to root. On NetBSD this may be accomplished instead by adding the following line to `/etc/daily.conf`:

    fetch_pkg_vulnerabilities=YES

to fetch the vulnerability list from the daily security script. The system is set to audit the packages by default but can be set explicitly, if desired (not required), by adding the following line to `/etc/security.conf`:

    check_pkg_vulnerabilities=YES

see daily.conf(5) and security.conf(5) for more details.

### 5.1.7. Finding if newer versions of your installed packages are in pkgsrc

Install `pkgtools/lintpkgsrc` and run lintpkgsrc with the “-i” argument to check if any packages are stale, e.g.

    % lintpkgsrc -i
    ...
    Version mismatch: 'tcsh' 6.09.00 vs 6.10.00

### 5.1.8. Other administrative functions

The pkg_admin executes various administrative functions on the package system.

## 5.2. Building packages from source

After obtaining pkgsrc, the `pkgsrc` directory now contains a set of packages, organized into categories. You can browse the online index of packages, or run make readme from the `pkgsrc` directory to build local `README.html` files for all packages, viewable with any web browser such as `www/lynx` or `www/firefox`.

The default prefix for installed packages is `/usr/pkg`. If you wish to change this, you should do so by setting `LOCALBASE` in `mk.conf`. You should not try to use multiple different `LOCALBASE` definitions on the same system (inside a chroot is an exception).

The rest of this chapter assumes that the package is already in pkgsrc. If it is not, see Part II, “The pkgsrc developer's guide” for instructions how to create your own packages.

### 5.2.1. Requirements

To build packages from source, you need a working C compiler. On NetBSD, you need to install the “comp” and the “text” distribution sets. If you want to build X11-related packages, the “xbase” and “xcomp” distribution sets are required, too.

### 5.2.2. Fetching distfiles

The first step for building a package is downloading the distfiles (i.e. the unmodified source). If they have not yet been downloaded, pkgsrc will fetch them automatically.

If you have all files that you need in the `distfiles` directory, you don't need to connect. If the distfiles are on CD-ROM, you can mount the CD-ROM on `/cdrom` and add:

    DISTDIR=/cdrom/pkgsrc/distfiles

to your `mk.conf`.

By default a list of distribution sites will be randomly intermixed to prevent huge load on servers which holding popular packages (for example, SourceForge.net mirrors). Thus, every time when you need to fetch yet another distfile all the mirrors will be tried in new (random) order. You can turn this feature off by setting `MASTER_SORT_RANDOM=NO` (for `PKG_DEVELOPER`s it's already disabled).

You can overwrite some of the major distribution sites to fit to sites that are close to your own. By setting one or two variables you can modify the order in which the master sites are accessed. `MASTER_SORT` contains a whitespace delimited list of domain suffixes. `MASTER_SORT_REGEX` is even more flexible, it contains a whitespace delimited list of regular expressions. It has higher priority than `MASTER_SORT`. Have a look at `pkgsrc/mk/defaults/mk.conf` to find some examples. This may save some of your bandwidth and time.

You can change these settings either in your shell's environment, or, if you want to keep the settings, by editing the `mk.conf` file, and adding the definitions there.

If a package depends on many other packages (such as `meta-pkgs/kde4`), the build process may alternate between periods of downloading source, and compiling. To ensure you have all the source downloaded initially you can run the command:

    % make fetch-list | sh

which will output and run a set of shell commands to fetch the necessary files into the `distfiles` directory. You can also choose to download the files manually.

### 5.2.3. How to build and install

Once the software has downloaded, any patches will be applied, then it will be compiled for you. This may take some time depending on your computer, and how many other packages the software depends on and their compile time.

### Note

If using bootstrap or pkgsrc on a non-NetBSD system, use the pkgsrc bmake command instead of “make” in the examples in this guide.

For example, type

    % cd misc/figlet
    % make

at the shell prompt to build the various components of the package.

The next stage is to actually install the newly compiled program onto your system. Do this by entering:

    % make install

while you are still in the directory for whatever package you are installing.

Installing the package on your system may require you to be root. However, pkgsrc has a just-in-time-su feature, which allows you to only become root for the actual installation step.

That's it, the software should now be installed and setup for use. You can now enter:

    % make clean

to remove the compiled files in the work directory, as you shouldn't need them any more. If other packages were also added to your system (dependencies) to allow your program to compile, you can tidy these up also with the command:

    % make clean-depends

Taking the figlet utility as an example, we can install it on our system by building as shown in Appendix C, Build logs.

The program is installed under the default root of the packages tree - `/usr/pkg`. Should this not conform to your tastes, set the `LOCALBASE` variable in your environment, and it will use that value as the root of your packages tree. So, to use `/usr/local`, set `LOCALBASE=/usr/local` in your environment. Please note that you should use a directory which is dedicated to packages and not shared with other programs (i.e., do not try and use `LOCALBASE=/usr`). Also, you should not try to add any of your own files or directories (such as `src/`, `obj/`, or `pkgsrc/`) below the `LOCALBASE` tree. This is to prevent possible conflicts between programs and other files installed by the package system and whatever else may have been installed there.

Some packages look in `mk.conf` to alter some configuration options at build time. Have a look at `pkgsrc/mk/defaults/mk.conf` to get an overview of what will be set there by default. Environment variables such as `LOCALBASE` can be set in `mk.conf` to save having to remember to set them each time you want to use pkgsrc.

Occasionally, people want to “look under the covers” to see what is going on when a package is building or being installed. This may be for debugging purposes, or out of simple curiosity. A number of utility values have been added to help with this.

1. If you invoke the make(1) command with `PKG_DEBUG_LEVEL=2`, then a huge amount of information will be displayed. For example,

       make patch PKG_DEBUG_LEVEL=2

   will show all the commands that are invoked, up to and including the “patch” stage.

2. If you want to know the value of a certain make(1) definition, then the `VARNAME` definition should be used, in conjunction with the show-var target. e.g. to show the expansion of the make(1) variable `LOCALBASE`:

       % make show-var VARNAME=LOCALBASE
       /usr/pkg
       %

If you want to install a binary package that you've either created yourself (see next section), that you put into pkgsrc/packages manually or that is located on a remote FTP server, you can use the "bin-install" target. This target will install a binary package - if available - via pkg_add(1), else do a make package. The list of remote FTP sites searched is kept in the variable `BINPKG_SITES`, which defaults to ftp.NetBSD.org. Any flags that should be added to pkg_add(1) can be put into `BIN_INSTALL_FLAGS`. See `pkgsrc/mk/defaults/mk.conf` for more details.

A final word of warning: If you set up a system that has a non-standard setting for `LOCALBASE`, be sure to set that before any packages are installed, as you cannot use several directories for the same purpose. Doing so will result in pkgsrc not being able to properly detect your installed packages, and fail miserably. Note also that precompiled binary packages are usually built with the default `LOCALBASE` of `/usr/pkg`, and that you should not install any if you use a non-standard `LOCALBASE`.

Prev | Up | Next
Chapter 4. Using pkgsrc on systems other than NetBSD | Home | Chapter 6. Configuring pkgsrc