System Configuration

Files Paths

Fatbuildr is installed with a vendor configuration file located at /usr/share/fatbuildr/fatbuildr.ini. This configuration file must not be modified as changes would be lost on upgrades.

Parameters can be overriden in site configuration file /etc/fatbuildr/fatbuildr.ini. This file is empty by default. All parameters declared in this file take precedence over the vendor file.

Parameters can be defined with interpolation using Python extended interpolation syntax.

Parameters

The configuration files have the INI file format, with sections and parameters.

All sections with their parameters are described in the following sub-sections.

`dirs`

This section controls paths of main directories used by Fatbuildr. It includes the following parameters:

instances: Absolute path to directory with instances definitions files.
registry: Absolute path to directory for managed artifact registries.
cache: Absolute path to directory for cached artifacts.
tmp: Absolute path to temporary directory.

`daemon`

This section controls Fatbuildr daemon generic runtime parameters. It includes the following parameters:

debug: Boolean to control fatbuildrd daemon debug mode
fulldebug: Boolean to control fatbuildrd daemon full debug mode. In this mode, logs from external libraries are included in daemon logs. When disabled, logs from external libraries are filtered out. Enabling fulldebug implies debug enabled.

`web`

This section controls Fatbuildrweb service specific settings. It includes the following parameters:

debug: Boolean to control Fatbuildrweb service debug mode.
host: Host IP address to which Fatbuildrweb network socket is binded. Special value 0.0.0.0 means all host network interfaces.
port: TCP port listened by Fatbuildrweb service.
instance: The name of Fatbuildr instance served by Fatbuildrweb service. Special value all means all defined instances.

debug, host, port and instance parameters are valid for Fatbuildrweb running as autonomous service only. These parameters are ignored when Fatbuildrweb runs as WSGI application.

listing: Boolean to control if listing of files and browsing in registries folders is allowed.
vendor_templates: Absolute path to directory of vendor HTML pages templates.
templates: Absolute path to directory of site HTML pages templates.
static: Absolute path to directory of static web assets.
vendor_policy: Absolute path to the vendor policy file which defines the default permissions to access Fatbuildrweb REST API and HTML endpoints.
policy: Absolute path to the side policy file which defines the alternative permissions to access Fatbuildrweb REST API and HTML endpoints.

By default, the file pointed by policy parameter does not exist. In this case, Fatbuildrweb loads the policy pointed by vendor_policy. If the file pointed by the policy parameter is created by an administrator, Fatbuildrweb loads this site policy and the vendor_policy is completely ignored.

Please refer to Fatbuildrweb policy management section for more details the access policy and the underlying permissions.

`images`

This section controls container images settings. It includes the following parameters:

storage: Absolute path to directory for container images.
defs: Absolute path to directory with container images definition files and utilities.
formats: Comma-separated list of artifacts format supported by this Fatbuildr installation. This can be used to restrict the list of supported formats to a subset of all formats natively supported by Fatbuildr.
create_cmd: Command used to create container images.

`containers`

This section controls container instances settings. It includes the following parameters:

exec: Absolute path to executable for running containers.
init_opts: Command options passed to container instanciation executable for updating images, creating and update build environments. These options are not used when running commands for other types of tasks (ex: builds)
opts: Command options passed to container instanciation executable, for all commands.
seccomp: Boolean to control whether Linux seccomp feature is used to filter the syscalls available to containers.

`tasks`

workspaces: Absolute path to directory for tasks working directories.
purge: Purge policy of tasks workspaces with its limit. This is a string with the name of the selected policy and the limit value separated by a colon (:) (ex: older:7d).

Please refer to Tasks History Purge page for more details about this configuration parameter and the available purge policies.

hook: Path to executable script or binary that is executed before and after tasks are run.

Please refer to Tasks Hooks page for more details about this configuration parameter.

`registry`

This section controls managed artifact registries settings. It includes the following parameters:

conf: Absolute path to directory for managed artifact registries.

`keyring`

This section controls the cryptographic signing keyring settings. It includes the following parameters:

storage: Absolute path to directory for cryptographic signing keyrings.
type: Algorithm used to generate the keys
size: Integer size of keys in bits
expires: Duration of keys validity. Special value 0 means the keys never expires. The value can be suffixed with units w (weeks), m (months) or y (years). The default unit is days.
seeder: Path to utility used to seed the internal cache of a running gpg-agent with keyring passphrase.

`tokens`

This section controls the JWT tokens settings for HTTP REST API authentication. It includes the following parameters:

storage: Absolute path to directory for storing the JWT tokens encoding keys.
duration: The numbers of days for which the generated token are valid before expiration.
algorithm: The cryptographic algorithm used for signing generated JWT tokens and verifying client tokens. Supported algorithms are HS256, HS384 and HS512.

For more details, please refer to PyJWT library algorithms documentation.

audience: The name of the audience claimed in the payload of generated and accepted JWT tokens.

`format:*`

All artifacts supported by Fatbuildr have their dedicated section prefixed by format:. They contain all parameters to manage the content of container images specialized for the formats including the build environments (when applicable).

Formats sections include both common and specific parameters. The specific parameters are detailed in following dedicated subsections. The common parameters shared by all formats are the following:

builder: Path to artifact builder command in container.
img_update_cmds: Command used in container to upgrade image software.
img_create_use_sysusersd: Boolean to determine if fatbuildr system user is created with sysusers.d configuration file during image bootstrap. If not, the user is create with raw seeds of /etc/passwd, /etc/group and /etc/gshadow.

`format:deb`

env_path: Absolute path to the build environment in the container image.
init_cmds: Command used in container to create build environment.
shell_cmd: Command used in container to launch an interactive shell in build environment.
exec_cmd: Command used in container to execute command in build environment.
exec_tmpfile: Boolean to contrat if command to execute in build environment is provided in a temporary file or directly as executable arguments.
env_update_cmds: Command used in container to upgrade build environment software.
env_as_root: Boolean to control if commands to manage build environments (creation and update) are run as root, instead the user running fatbuildrd daemon.
env_default_mirror: URL of APT mirror used by default to create deb build environments, unless overridden in instance pipelines definitions.
env_default_components: Space separated list of APT repository components used by default to create deb build environments, unless overridden in instance pipelines definitions.
prescript_deps: Space-separated list of packages installed in build environment before prescripts are run.

`format:rpm`

env_path: Absolute path to the build environment in the container image.
init_cmds: Command used in container to create build environment.
shell_cmd: Command used in container to launch an interactive shell in build environment.
exec_cmd: Command used in container to execute command in build environment.
exec_tmpfile: Boolean to contrat if command to execute in build environment is provided in a temporary file or directly as executable arguments.
env_update_cmds: Command used in container to upgrade build environment software.
env_as_root: Boolean to control if commands to manage build environments (creation and update) are run as root, instead the user running fatbuildrd daemon.
env_default_modules: Space separated list of DNF modules to enable by default in Mock build environments, unless overridden in instance pipelines definitions. By default, this parameter is not defined and no DNF module is enabled.
prescript_deps: Space-separated list of packages installed in build environment before prescripts are run.

`format:osi`

containerized: Boolean to control if OSI images are built in container, or directly on fatbuildrd daemon host instead. Disabling this parameter help to support more OSI formats such as raw or squashfs images for which mkosi utility require access to loop devices.

To build OSI images directly on host, in addition to containerized parameter with a negative value, it is recommended to change builder parameter value in the same section to run mkosi setuid wrapper as well:

[format:osi]
builder = /usr/libexec/fatbuildr/u-mkosi
containerized = no

For various reasons, mkosi utility requires the root user permissions. This wrapper gives fatbuildr system user the expected permissions for mkosi executable.

Default Values

This is the content of the vendor configuration file with all parameters default values:

# This is the vendor configuration file of Fatbuildr. Do not modify! To change
# Fatbuildr configuration parameters, please override these parameters in
# /etc/fatbuildr/fatbuildr.ini

[dirs]
instances = /etc/fatbuildr/instances.d
registry = /var/lib/fatbuildr/registry
cache = /var/cache/fatbuildr
tmp = /var/tmp

[daemon]
debug = no
# When disabled, fatbuildr external libs logs are filtered out. This can be
# enabled to debug or understand behavior of external libs. Enabling fulldebug
# implies debug enabled.
fulldebug = no

[web]
debug = no
# Bind address of the web application. By default, it only listens for incoming
# connections from localhost.
host = localhost
port = 5000
# By default, serve all defined instances
instance = all
# Allow file listing and directory browsing in registries
listing = yes
vendor_templates = /usr/share/fatbuildr/web/templates
templates = /etc/fatbuildr/web/templates
static = /usr/share/fatbuildr/web/static
vendor_policy = /usr/share/fatbuildr/web/policy.acl
policy = /etc/fatbuildr/web/policy.acl

[images]
storage = /var/lib/fatbuildr/images
defs = /usr/share/fatbuildr/images
# List of artifacts formats enabled on this Fatbuildr installation.
formats = rpm,deb,osi
create_cmd = /usr/libexec/fatbuildr/u-mkosi --include {{ definition }} --directory {{ definition.parent }} --output-dir {{ path.parent }} --output {{ path.name }} --cache-dir {{ path.parent }}/.cache-{{ format }} --skeleton-tree {{ skeleton }} --environment FATBUILDR_USER={{ user }} --environment FATBUILDR_GROUP={{ group }} --environment FATBUILDR_UID={{ uid }} --environment FATBUILDR_GID={{ gid }}

[registry]
conf = /usr/share/fatbuildr/registry

[tasks]
workspaces = /var/lib/fatbuildr/workspaces
# Purge policy of tasks history with their workspaces. Several policies are
# available (ex: older, last, each, size). The policy must be associated to a
# limit value separated by a colon (:).
purge = last:100
# Hook to execute before and after tasks are run. This must be the path to an
# executable script or binary.
#hook = /usr/local/bin/fatbuildr-hook

[containers]
# Absolute path to executable for running containers. By default, execute the
# wrapper restricted to fatbuildr system user with CAP_SET{UID,GID} to become
# root:root before launching systemd-nspawn.
exec = /usr/libexec/fatbuildr/u-nspawn
# systemd-nspawn command line options used on creation and update of build
# environments and interactive shell.
init_opts =
# systemd-nspawn command line options.
# Bind-mount stub-resolv.conf on host from systemd-resolved to /etc/resolv.conf
# in container for DNS resolution.
# Disable registration to systemd-machined as recommended in systemd-nspawn(1)
# for containers not running service manager. Also keep fatbuildrd unit scope
# so processes in containers get the resources allocated to fatbuildrd service.
opts = --quiet --resolv-conf=bind-stub --register=no --keep-unit
# Controls whether seccomp is used to filter the list of syscalls available to
# the containers.
seccomp = yes

[keyring]
storage = /var/lib/fatbuildr/keyring
type = rsa
size = 4096
expires = no
seeder = /usr/lib/gnupg/gpg-preset-passphrase

[tokens]
storage = /var/lib/fatbuildr/tokens
# Generated token expire after this duration number of days.
duration = 30
# The cryptographic algorithm used for signing JWT tokens. Supported algorithms
# are HS256, HS384 and HS512.
algorithm = HS256
# The audience claimed in the payload of generated and accepted JWT tokens.
audience = fatbuildr

#
# Formats specifics parameters
#
[format:deb]
builder = /usr/sbin/cowbuilder
env_path = /var/cache/pbuilder/{{ name }}
init_cmds = ${builder} --create --distribution {{ environment }} --mirror {{ mirror }} --components '{{ components }}' --extrapackages passwd --architecture {{ architecture }} --basepath {{ path }}
shell_cmd = ${builder} --login --distribution {{ environment }} --architecture {{ architecture }} --basepath {{ path }}
exec_cmd = ${builder} --execute --distribution {{ environment }} --architecture {{ architecture }} --basepath {{ path }}
exec_tmpfile = yes
img_update_cmds = apt-get update && apt-get --yes upgrade
img_create_use_sysusersd = yes
env_update_cmds = ${builder} --update --basepath {{ path }}
env_as_root = yes
env_default_mirror = http://deb.debian.org/debian
env_default_components = main contrib non-free
prescript_deps = wget ca-certificates

[format:rpm]
builder = /usr/bin/mock
env_path = /var/lib/mock/{{ name }}-bootstrap
init_cmds = /usr/bin/fatbuildr-setup-mockenv {{ name }} {{ base }} perl {{ modules|join(',') }} && ${builder} --init --root={{ name }}
shell_cmd = ${builder} --shell --root={{ name }}
exec_cmd = ${builder} --chroot --root={{ name }} --
exec_tmpfile = no
img_update_cmds = dnf upgrade --assumeyes
img_create_use_sysusersd = no
env_update_cmds = ${builder} --update --root={{ name }}
env_as_root = no
prescript_deps = wget

[format:osi]
builder = /usr/bin/mkosi
img_update_cmds = dnf upgrade --assumeyes
img_create_use_sysusersd = no
containerized = yes