view FreeBSD/ @ 13:8970cbf95e7e default tip @

FreeBSD: add mkdir command in
author David Demelier <>
date Fri, 08 Sep 2017 09:35:44 +0200
parents 56b6b50c0d7e
line wrap: on
line source

FreeBSD poudriere howto

What is poudriere?

In short, poudriere is a tool for building packages into clean jails to make
predictible and secure installation/upgrades.


### From packages

    pkg install poudriere
    pkg install dialog4ports

### From ports

    make -C /usr/ports/ports-mgmt/poudriere install clean
    make -C /usr/ports/ports-mgmt/dialog4ports install clean

Initial configuration

This guide assumes that you use ZFS.

### poudriere.conf

The /usr/local/etc/poudriere.conf file does not require much information, the
following options are required:



  - **ZPOOL**: your zfs pool name,
  - **ZROOTFS**: zfs dataset to use,
  - **BASEFS**: base directory for jails and ports,
  - **POUDRIERE**: directory for packages, logs and such,
  - **DISTFILES_CACHE**: directory where to store distfiles,
  - **RESOLV_CONF**: file for DNS resolver.

This means that:

  - any jail created by poudriere will be stored in /poudriere/jails,
  - result of builds will be kept in dedicated /poudriere/data directories.

Create the zfs datasets for poudriere:

    zfs create zroot/poudriere

warning: you may need to use `-o mountpoint=/poudriere` if you root dataset
         is not parent of poudriere.

    zfs create zroot/poudriere/distfiles

Jail creation

Before building package, you need to create a jail. The easiest way is to use
the FTP method (default) which simply fetch release tarballs and extract them.

Let's create a poudriere jail named **FreeBSD-11-1**.

### Using FTP

    poudriere jail -c -j FreeBSD-11-1 -v 11.1-RELEASE

Ports fetching

You also need to have a ports tree to build ports from, you have several way to
fetch them such as svn, portsnap and git. The default is portsnap and available
directly from FreeBSD so use it.

Let's create a default poudriere ports tree.

    poudriere ports -c

Building options

What's really interesting in building ports is to customize every options of

For example, on a server you don't want to have desktop software and all of
useless things like X.Org, dbus, avahi, pulseaudio and such.

Poudriere uses different files for customizing options in the following order:

  - /usr/local/etc/poudriere.d/make.conf
  - /usr/local/etc/poudriere.d/<setname>-make.conf
  - /usr/local/etc/poudriere.d/<tree>-make.conf
  - /usr/local/etc/poudriere.d/<jailname>-make.conf
  - /usr/local/etc/poudriere.d/<jailname>-<tree>-make.conf
  - /usr/local/etc/poudriere.d/<jailname>-<setname>-make.conf
  - /usr/local/etc/poudriere.d/<jailname>-<tree>-<setname>-make.conf

For example, in our case we can basically customize our options by creating the
file **/usr/local/etc/poudriere.d/FreeBSD-11-1-make.conf**.

### Disabling desktop options

On a server, we may disable the following options using the `OPTIONS_UNSET`

Note: we use the `+=` assignment to avoid resetting it.

    # /usr/local/etc/poudriere.d/FreeBSD-11-1-make.conf

Configuring per-port options

It's also possible to edit port options in individual manner, for that purpose,
we use the `poudriere options` command.

Let's configure vim to remove options we don't care:

    poudriere options -j FreeBSD-11-1 -c editors/vim

If you defined the **OPTIONS_UNSET** described above, the **NLS** option should
be disabled by default, now select **CONSOLE** as User interface option.

Note: it's recommended to use `-c` option because it forces the edition of

Building ports

Now that we have prepared our poudriere environment, let's build a port using
the `poudriere bulk` command.

    poudriere bulk -j FreeBSD-11-1 editors/vim

Since we will probably build a high number of ports, we can use a file instead
using the `-f` option.

    # /etc/packages.conf

    poudriere bulk -j FreeBSD-11-1 -f /etc/packages.conf

Using your repository

Once you have built some packages, you may use it directly from `pkg` command
because poudriere build a custom repository.

In our case, the package repository is located into

### Disable FreeBSD official repository

If you want to completely disable the official FreeBSD repository, create the
following file:

    # /etc/pkg/no-FreeBSD.conf
    FreeBSD: {
      enabled: no

### Enable our own package repository

Create the following file:

    # /etc/pkg/local.conf
    local: {
      url: "file:///poudriere/data/packages/FreeBSD-11-1-default"

Note: the **local** name can be replaced with anything.

Update pkg repository and upgrade:

    pkg update -f
    pkg upgrade

Then install our own packages:

    pkg install vim zsh

### Enable repository in your jails (optional)

If you have followed the **** howto, you may want to use your package
repository in your own jails.

This chapter assumes that you have built your jails in **/jails** and we will
use the **template** jail.

#### Mount package repository

First, we need to mount the packages as read-only, we will use **/usr/packages**
as destination.

    mkdir /jails/template/usr/packages

Edit your **/etc/jail.conf** to update your jail, you need to do this for each
of your jails:

    # /etc/jail.conf
    template {

And create **/etc/fstab.template**:

    # /etc/fstab.template
    /poudriere/data/packages/FreeBSD-11-1-default /jails/template/usr/packages nullfs ro 0 0

If your jail is **running**, you can mount using:

    mount -t nullfs -r /poudriere/data/packages/FreeBSD-11-1-default /jails/template/usr/packages

Otherwise, it will be mounted using:

    service jail start template

#### Create repository file

Now create the repository file in the jail:

    # /jails/template/etc/pkg/local.conf
    local: {
      url: "file:///usr/packages"

You can now use `pkg` in your jail!

    pkg -j template update -f
    pkg -j template upgrade
    pkg -j template install your_packages