FreeBSD/poudriere.md

Mon, 28 Aug 2017 09:04:46 +0200

author
David Demelier <markand@malikania.fr>
date
Mon, 28 Aug 2017 09:04:46 +0200
changeset 5
435b53af6b96
parent 4
49956537f483
child 8
49a3a8c3c7ec
permissions
-rw-r--r--

FreeBSD: fix incorrect jail naming in poudriere.md

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.

Installation
------------

### 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=zroot
    ZROOTFS=/poudriere  
    BASEFS=/poudriere
    POUDRIERE_DATA=${BASEFS}/data
    DISTFILES_CACHE=/poudriere/distfiles
    RESOLV_CONF=/etc/resolv.conf

Options:

  - **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
    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
them.

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`
variable.

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

    # /usr/local/etc/poudriere.d/FreeBSD-11-1-make.conf
    OPTIONS_UNSET+= DBUS NLS X11

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
options.

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
    editors/vim
    shells/zsh

    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
**/poudriere/data/packages/FreeBSD-11-1-default**

### 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

mercurial