fatbuildrctl command

This section explains all fatbuildrctl command available options, with many examples and descriptions of its behaviours. The content of the page is also available in fatbuildrctl(1) manpage after installation.

Synopsis

fatbuildrctl [GENERAL OPTIONS] COMMAND [COMMAND OPTIONS]

General Options

-h, --help

Show this help message and exit.

-v, --version

Show Fatbuildr version number and exit.

--debug

Enable debug mode with more messages in output.

--fulldebug

Enable debug mode in external libraries used by Fatbuildr. You should probably not need this option, as it is designed for Fatbuildr developers.

--preferences=PREFERENCES

Path to user preference file (default: ~/.config/fatbuildr.ini). Please refer to PREFERENCES FILE section for details about this file.

--uri=URI

URI of Fatbuildr server (default: dbus://system/default or $FATBUILDR_URI environment variable if defined). Accepted schemes are dbus, when interacting with local fatbuildrd service on D-Bus, or http(s) when interacting with potentially remote fatbuildrweb proxy (ex: http://build.host/prod).

When connecting to fatbuildrweb started in mono-instance mode, the URI does not contain the fatbuildrd instance name. In this case, the URI can be as simple as http://build.host.

Commands

All commands accept -h, --help option to get details about available option for this particular command (ex: fatbuildrctl images --help). Commands are listed in lexicographical order.

build

Submit artifact build tasks.

This command accepts the following options:

-a, --artifact=ARTIFACT

Artifact to build.

-d, --distribution=DISTRIBUTION

Targeted distribution name for the built artifact. The format of the resulting artifact is deduced from this distribution, based on instance pipelines definitions.

-f, --format=FORMAT

Format of the resulting artifact. This is an alternative way to specify the targeted distribution. It can be used when only one distribution is declared for the given format in instance pipelines definitions. When multiple distributions are declared for the given format, the command fails with an error. When both -f, --format and -d, --distribution are specified but distribution format and the given format do not match, the command also fails with an error.

--derivative=DERIVATIVE

Name of distribution derivative (default: main)

-b, --basedir=BASEDIR

Artifacts definitions base directory. The BASEDIR is used in combination with SUBDIR to define location of artifact definition. This parameter is required unless it is defined in user preferences files (see PREFERENCES FILE for more details).

-s, --subdir=SUBDIR

Artifact definition subdirectory. Eventually, fatbuildrctl searches for the artifact definition under the path composed by BASEDIR concatenated with SUBDIR. By default, SUBDIR is the artifact name.

--sources=[SOURCE_ID#][SOURCE_VERSION@]SOURCE_DIR

Generate artifact source using the source code in a local SOURCE_DIR directory instead of using the source tarball from the URL declared in artifact definition. See LOCAL SOURCES section for more details.

--include-git-untracked

Include in artifact source archive generated from local source directory files that are untracked in git repository. This option only has effect with --sources option. See LOCAL SOURCES section for more details.

-n, --name=NAME

User name for artifact build changelog entry. This option is required, unless the user name is defined in user preferences file (see PREFERENCES FILE for more details).

-e, --email=EMAIL

User email for artifact build changelog entry. This option is required, unless the user email is defined in user preferences file (see PREFERENCES FILE for more details).

-m, --msg=MSG

Build message to set in artifact build changelog entry. This option is required, unless a default build message is defined in user preferences file (see PREFERENCES FILE for more details).

--batch

Submit task in background.

-i, --interactive

Submit build in interactive mode. In this mode, users drop into an interactive shell inside the build environment in case of build failure. By launching commands in this interactive shell, users can more easily diagnose the cause of the build issue and eventually find solution. When this option is used, --batch option is ignored. This mode is available only when the Fatbuildr server is accessed locally on D-Bus.

-n, --name, -e, --email and -m, --msg options are not actually used for osi format artifacts as this format does not contain changelogs.

Examples:

$ fatbuildrctl build --artifact foo --distribution bar

Submit task to build artifact foo for distribution bar (using main default derivative). The format of the artifact is deduced from the distribution, based on instance pipelines definitions. The base directory, the default build message, the user name and email must be defined in user preferences file. The artifact definition must be present in foo/ subdirectory of the base directory.

$ fatbuildrctl build --artifact foo --format rpm

Submit task to build artifact foo to RPM format. The distribution is deduced from the format. This works when only one distribution is declared for the rpm format in instance pipelines definitions.

$ fatbuildrctl build --artifact foo --distribution bar --msg 'build foo for bar'

Submit task to build artifact foo for distribution bar with given message in artifact changelog. The base directory, the user name and email must be defined in user preferences file.

$ fatbuildrctl build --artifact foo --distribution bar --basedir ~/path/to/basedir --subdir pkg

Submit task to build artifact foo for distribution bar using artifact definition located in pkg/ subdirectory of ~/path/to/basedir directory. The default build message, the user name and email must be defined in user preferences file.

$ fatbuildrctl build --artifact foo --distribution bar --derivative baz

Submit task to build artifact foo for derivative baz of distribution bar. The baz derivate must be declared in instance pipelines definitions and artifact.yml file of artifact definition directory.

$ fatbuildrctl build --artifact foo --distribution bar --batch

Submit task to build artifact foo for distribution bar in background.

$ fatbuildrctl build --artifact foo --distribution bar --interactive

Submit task to build artifact foo for distribution bar, then wait for the build task to start and print its output until it is over. Launch an interactive shell in the build environment in case of build failure.

$ fatbuildrctl build --artifact foo --distribution bar --sources 1.2.3@~/path/to/sources

Generate source tarball of artifact foo with files located in directory ~/path/to/sources tagged with version 1.2.3, then submit task to build this artifact for distribution bar.

history

Manage tasks history.

This command accepts the following subcommands:

list

List last 10 terminated tasks in history with all their parameters. This is the default subcommand.

purge

Submit task to purge tasks history with their workspaces according to the policy defined on server side.

The command accepts the following options:

--batch

Submit task in background.

Examples:

$ fatbuildrctl history
$ fatbuildrctl history list

List last 10 terminated tasks in history with all their parameters.

$ fatbuildrctl history purge

Submit task to purge tasks history with their workspaces according to the policy defined on server side.

$ fatbuildrctl history purge --batch

Submit task to purge tasks history in background.

images

Manage container images and build environments. One operation among the available subcommands must be specified.

The images subcommand accepts the following subcommands:

create

Submit tasks to create container images. Unless -f, --format filter is used, all images for all formats declared in instance pipelines are created. One task per image (or format) is submitted on server side.

The create subcommand accepts the following options:

-f, --format=FORMAT

Create container image specific to format FORMAT.

--force

Force creation of container images even if already existing. Without this option, creating container image that already exists gives an error.

--batch

Submit task in background.

update

Submit tasks to update OS packages of container images. Unless -f, --format filter is used, all images for all formats declared in instance pipelines are updated. One task per image is submitted on server side.

The update subcommand accepts the following options:

-f, --format=FORMAT

Update container image specific to format FORMAT.

--batch

Submit task in background.

shell

Submit a task to launch an interactive shell or execute a command as root in a container image. Unless only one format is declared in the instance pipelines, it is necessary to select the image with -f, --format filter. The task is terminated when the shell is exited.

The shell subcommand accepts the following options:

-f, --format=FORMAT

Select container image specific to format FORMAT.

command

Command to execute in container image. Without this option, an interative shell is launched.

command

Command to execute in container image. Without this option, an interative shell is launched.

env-create

Submit tasks to create the build environments in the container images. Unless -f, --format, -d, --distribution or -a, --architecture filters are used, all build environments for all formats and architectures declared in instance pipelines are created. One task per build environment is submitted on server side.

The env-create subcommand accepts the following options:

-f, --format=FORMAT

Create build environments for format FORMAT.

-d, --distribution=DISTRIBUTION

Create build environments for distribution DISTRIBUTION.

-a, --architecture=ARCHITECTURE

Create build environments for the hardware architecture ARCHITECTURE.

--batch

Submit task in background.

env-update

Submit tasks to update the build environments in the container images. Unless -f, --format, -d, --distribution or -a, --architecture filters are used, all build environments for all formats and architectures declared in instance pipelines are updated. One task per build environment is submitted on server side.

The env-update subcommand accepts the following options:

-f, --format=FORMAT

Update build environments for format FORMAT.

-d, --distribution=DISTRIBUTION

Update build environments for distribution DISTRIBUTION.

-a, --architecture=ARCHITECTURE

Update build environments for the hardware architecture ARCHITECTURE.

--batch

Submit task in background.

env-shell

Submit a task to launch an interactive shell or execute command as root in a build environment. The build environment must be selected with -f, --format, -d, --distribution and -a, --architecture filters. The task is terminated when the shell is exited.

The env-shell subcommand accepts the following options:

-f, --format=FORMAT

Select build environment for format FORMAT.

-d, --distribution=DISTRIBUTION

Select build environment for distribution DISTRIBUTION.

-a, --architecture=ARCHITECTURE

Select build environment for the hardware architecture ARCHITECTURE.

command

Command to execute in build environment. Without this option, an interative shell is launched.

Examples:

$ fatbuildrctl images create

Submit tasks to create container images for all formats declared in instance pipelines.

$ fatbuildrctl images update --format rpm --batch

Submit tasks to update container image for RPM format in background.

$ fatbuildrctl images shell --format rpm

Submit tasks to open an interactive shell in an instance of a container running the image for RPM format.

$ fatbuildrctl images shell --format deb -- dpkg -l

Submit tasks to execute dpkg -l command in an instance of a container running the image for Deb format.

$ fatbuildrctl images env-create --format deb --batch

Submit tasks to create all build environments declared in instance pipelines for Deb format in background.

$ fatbuildrctl images env-update --distribution el8

Submit tasks to update the build environments declared in instances pipelines for the el8 distribution, for all supported architectures.

$ fatbuildrctl images env-update --distribution sid --architecture x86_64

Submit a task to update the build environments declared in instances pipelines for the sid distribution for x86_64 hardware architecture only.

$ fatbuildrctl images env-shell --distribution el8 --architecture arm64

Submit a task to open an interactive shell in the build environment declared in instances pipelines for the el8 distribution for arm64 hardware architecture.

$ fatbuildrctl images env-shell --distribution sid -- apt show curl

Submit a task to execute command apt show curl in the build environment declared in instances pipelines for the sid distribution.

keyring

Manage keyring.

The keyrings managed by Fatbuildr are created with a masterkey and a signing subkey. This subkey is actually used to sign the artifacts and registries. The masterkey is only used to sign the subkey.
The keyring keys are encrypted on disks using a randomly generated passphrase. Fatbuildr users and administrators are not expected to know or manipulate this passphrase, it is managed transparently by Fatbuildr.

This command accepts the following subcommands:

show

Print the keyring information including its subject, format, size, fingerprint, expiration, etc. This is the default subcommand.

export

Print keyring public key in armoured format.

create

Submit keyring creation task. The key is created using the parameters defined in Fatbuildr server configuration file. If the keyring already exists, it is overwritten.

renew

Submit keyring renewal task. The new key expiry date is set using --duration option.

The renew subcommand accepts the following options:

--duration=DURATION

The validity duration of the renewed keyring. The duration accepts the following time units: w for weeks, m for months, y for years. The default unit is a number of days. The special value 0 indicates no expirary date. This option is required with renew subcommand. It is silently ignored with other subcommands.

--batch

Submit task in background.

Examples:

$ fatbuildrctl keyring
$ fatbuildrctl keyring show

Print keyring information, or report an error if the keyring does not exist.

$ fatbuildrctl keyring export

Print keyring public key in armoured format.

$ fatbuildrctl keyring create

Submit task to create the keyring.

$ fatbuildrctl keyring renew --duration 10

Submit task to set keyring expiry in 10 days from now.

$ fatbuildrctl keyring renew --duration 2y

Submit task to set keyring expiry in 2 years from now.

$ fatbuildrctl keyring renew --duration 0

Submit task to remove keyring expiry.

list

List currently running and pending tasks with their parameters. This commands does not accept any option.

patches

Manage artifact patch queue. This downloads artifact source code tarball, selecting the version intended for the given derivative. Then, it creates a temporary Git repository initialized with artifact source code in initial commit and existing artifact patches into successive commits. After the Git repository is initialized, a subshell is launched into it. You can then modify existing patches by editing commit history, or add additional patches with new commits. When the subshell is exited, the commit log is exported into a set of patches for the artifact, and the temporary Git repository is destroyed.

The downloaded source code tarball is saved in user cache directory. If environment variable $XDG_CACHE_HOME is defined, it is honoured. Otherwise, the default user cache directory ~/.cache is selected. Fatbuildr creates a dedicated fatbuildr subdirectory in this user cache directory where all source code tarballs are placed. If the downloaded source code tarball is already present in cache, it is used directly and additional download is avoided.

This command accepts the following options:

-a, --artifact=ARTIFACT

Edit ARTIFACT patch queue.

--derivative=DERIVATIVE

Select artifact source version intended for DERIVATIVE (default: main).

-b, --basedir=BASEDIR

Artifacts definitions base directory. The BASEDIR is used in combination with SUBDIR to define location of artifact definition. This parameter is required unless it is defined in user preferences files (see PREFERENCES FILE for more details).

-s, --subdir=SUBDIR

Artifact definition subdirectory. Eventually, fatbuildrctl searches for the artifact definition under the path composed by BASEDIR concatenated with SUBDIR. By default, SUBDIR is the artifact name.

--sources=[SOURCE_ID#][SOURCE_VERSION@]SOURCE_DIR

Generate artifact source using the source code in a local SOURCE_DIR directory instead of using the source tarball from the URL declared in artifact definition. See LOCAL SOURCES section for more details.

--include-git-untracked

Include in artifact source archive generated from local source directory files that are untracked in git repository. This option only has effect with --sources option. See LOCAL SOURCES section for more details.

-n, --name=NAME

User name for temporary Git repository initial commit author and commiter. This option is required, unless the user name is defined in user preferences file (see PREFERENCES FILE for more details).

-e, --email=EMAIL

User email for temporary Git repository initial commit author and commiter. This option is required, unless the user email is defined in user preferences file (see PREFERENCES FILE for more details).

Examples:

$ fatbuildrctl patches --artifact foo

Edit patch queue of artifact foo (using version intended main default derivative). The base directory, the default build message, the user name and email must be defined in user preferences file. The artifact definition must be present in foo/ subdirectory of the base directory.

$ fatbuildrctl patches --artifact foo --derivative bar

Edit patch queue of artifact foo using version intended for bar derivative.

$ fatbuildrctl patches --artifact foo --basedir ~/path/to/basedir --subdir pkg

Edit patch queue of artifact foo using artifact definition located in pkg/ subdirectory of ~/path/to/basedir directory.

$ fatbuildrctl patches --artifact foo --name 'John Doe' --email john@doe.org

Edit patch queue of artifact foo. This initial commit of temporary Git repository will created using John Doe <john@doe.org> identity as author and commiter.

$ fatbuildrctl patches --artifact foo --sources 1.2.3@~/path/to/sources

Edit patch queue of artifact foo based on a generated source tarball with files located in directory ~/path/to/sources tagged with version 1.2.3.

registry

Query and manage artifacts in registries.

This command accepts the following subcommands:

list

List artifacts matching given filters.

delete

Remove artifacts matching given filters from registry.

The command accepts the following options:

-d, --distribution=DISTRIBUTION

Registry distribution name. This parameter is required. The format of the artifact is deduced from the distribution, based on instance pipelines definitions.

--derivative=DERIVATIVE

Registry distribution derivative name (default: main).

-a, --artifact=ARTIFACT

Part of artifact name. All artifacts whose name contains ARTIFACT are selected. By default, all artifacts are selected.

Examples:

$ fatbuildrctl registry --distribution foo
$ fatbuildrctl registry --distribution foo list

List all artifacts found in distribution foo (in main default derivative).

$ fatbuildrctl registry --distribution foo --derivative bar

List all artifacts found in bar derivative of distribution foo.

$ fatbuildrctl registry --distribution foo --artifact baz

List all artifacts whose in name contains baz in distribution foo.

$ fatbuildrctl registry --distribution foo --artifact baz delete

Remove all artifacts whose in name contains baz from distribution foo (in main default derivative).

tokens

Manage tokens for authentication to HTTP REST API. See <<tokens,API TOKENS> > section for more details.

This command accepts the following subcommands:

list

Print the list of JWT tokens available in the tokens directory defined in the user preferences file with all their details (path, associated URI, expiration date, etc). See PREFERENCES FILE section for more details. This is the default subcommand.

generate

Generate a token. This subcommand only works for local instance through DBus interface.

save

Reads a token on standard input and saves it to a local file. The --uri option is required to determine the file name. The file is saved in the tokens directory defined in the user’s preferences file. See PREFERENCES FILE section for more details.

The command accepts the following options:

--uri=URI

The URI associated to the save token. This parameter is required when using the save subcommand, it is ignored otherwise.

Examples:

$ fatbuildrctl tokens
$ fatbuildrctl tokens list

Print the list of JWT tokens available in the tokens directory.

$ fatbuildrctl tokens generate

Generates a JWT token for remote authentification on the local instance. The token is printed on standard output.

$ fatbuildrctl tokens save --uri https://build.server

Reads a token on standard input and saves it to a local file associated to the given remote instance URI.

watch

Get output of running and archived tasks.

This command accepts the following argument:

TASK

Get output of task TASK. By default, currently running task is selected. When the selected task is running, its output is streamed until its end. If TASK is not found in pending, running and archived tasks, an error is reported. If the argument is not given and no task is currently running, an error is also reported. If TASK is pending, the command waits for the task to start.

Examples:

$ fatbuildrctl watch

Get output of currently running task until its end.

$ fatbuildrctl watch a97737c0-5ecd-41d7-ba3a-ed46e03a2eb0

Get output of task a97737c0-5ecd-41d7-ba3a-ed46e03a2eb0.

Local Sources

Some fatbuildrctl commands (build, patches) provide the possibility to generate an artifact source tarball with the content of a local source tree using --sources option.

The value of this option has the following format: [SOURCE_ID#][SOURCE_VERSION@]SOURCE_DIR [[SOURCE_ID#][SOURCE_VERSION@]SOURCE_DIR]

The local directory which contains the source tree is specified with SOURCE_DIR.

By default, the ID associated to the source is the artifact name. It is considered by Fatbuildr as the main source for the artifact. For artifact with multiple sources, it is possible to generate a tarball for a supplementary source by specifying SOURCE_ID followed by #. Specifying a SOURCE_ID not declared as a supplementary source in artifact definition file results in an error.

By default, the version number declared for this source in artifact definition file is used in generated tarball filename. It is possible to prefix the source directory with an alternate version SOURCE_VERSION followed by @.

The --sources option accepts multiple values for artifact defined with multiple sources. An error is reported when a source ID is specified more than once.

Examples:

fatbuildrctl […] --sources ~/path/to/code

Generate archive for artifact main source with the content of directory ~/path/to/code (using the version number defined in artifact definition file).

fatbuildrctl […] --sources 1.2.3@~/path/to/code

Generate archive for artifact main source with the content of directory ~/path/to/code and version 1.2.3.

fatbuildrctl […] --sources other#~/path/to/other-code

Generate archive for artifact other source with the content of directory ~/path/to/other-code (using the version number defined for other source in artifact definition file).

fatbuildrctl […] --sources other#4.5.6@~/path/to/other-code

Generate archive for artifact other source with the content of directory ~/path/to/other-code and version 4.5.6.

fatbuildrctl […] --sources 1.2.3@~/path/to/code other#4.5.6@~/path/to/other-code

Generate archive for artifact main source with the content of directory ~/path/to/code and version 1.2.3, and generate archive for artifact other source with the content of directory ~/path/to/other-code and version 4.5.6.

Some files are automatically excluded by Fatbuildr from the generated archives:

  • All files whose name start by .git (ex: .gitignore and .git/ folder),

  • The debian/ subdirectory recursively,

  • If the source tree is an initialized Git repository, all files referenced as untracked in this repository (typically in .gitignore). This can be disabled with --include-git-untracked option.

Preferences file

To avoid specifying some options to fatbuildrctl, it is possible to define a preferences file with some defaults user settings.

The path to this file can be provided to fatbuildrctl using --preferences=PREFERENCES general option. By default, fatbuildrctl checks if $XDG_CONFIG_HOME environment variable is defined with an existing directory and search for a file named fatbuildr.ini inside this directory. If the environment variable is not defined, fatbuildrctl tries to load file ~/.config/fatbuildrctl.ini.

The preferences file is formatted as an INI file. It can contains two sections:

[user]

This section can contain the following parameters:

name

User real name. When defined, it is used as default value for -n, --name=NAME option of build and patches commands.

email

User emame. When defined, it is used as default value for -e, --email=EMAIL option of build and patches commands.

[prefs]

This section can contain the following parameters:

uri

URI of Fatbuildr instance. When defined, it is used as default value for --uri=URI general option.

basedir

Path to artifact definition repository. When defined, it is used as default value for -b, --basedir=BASEDIR option of build and patches commands.

message

Default build message. When defined, it is used as default value for -m, --msg=MSG option of build command.

tokens

The path to the directory where fatbuildrctl saves and load JWT tokens for remote authentication to the REST API. The default value is ~/.local/share/fatbuildr or $XDG_DATA_HOME/fatbuildr if the environment variable is defined.

commit_template

The path to the git commit message template file used to preformat the messages of new git commits when using fatbuildrctl patches command. Default value is /usr/share/fatbuildr/commit-message-template.

This is a full example of a user preferences file:

[user]
name = John Doe
email = joe@doe.com

[prefs]
uri = http://build.host/dev
basedir = /home/john/path/to/basedir
message = Artifact maintenance build

Environment Variables

To avoid specifying some options to fatbuildrctl, it is possible to define the following environment variables:

FATBUILDR_URI

When defined, this environment variable overrides the instance URI defined in user preferences file. When --uri option is set, this environment variable is ignored.

API Tokens

Authentication to Fatbuildr REST API is realized with JSON WEB Tokens (JWT). Depending on the policy, users must have a valid token prior to calling some API endpoints. To obtain a valid token, users can run this command:

$ fatbuildrctl tokens generate
<secret personal token>

This command requests fatbuildrd daemon to generate and sign a valid token for the current user. The token provided by the server is printed on standard output.

The tokens generate command only works with local Fatbuildr instance through DBus interface. For remote authentication, users are expected to connect to the remote host (eg. with SSH) to generate the token and provide it to the tokens save command to save it on the client host. For example:

$ ssh john@build.server fatbuildrctl --uri dbus://system/default tokens generate | \
  fatbuildrctl tokens save --uri https://build.server/default
token saved in file /home/john/.local/share/fatbuildr/aHR0cHM6Ly9idWlsZC5zZXJ2ZXIvZGVmYXVsdA==.token

This command generates a token on default instance of build.server remote host for user john and saves this token in a file associated to the URI of this remote instance, in local john tokens directory.

The path to this tokens directory is defined in user’s preference file. See PREFERENCES FILE section for more details. The filename of the token is the URI of the associated remote instance encoded in base64 and the .token extension. This naming convention notably guarantees uniqueness of token files for each remote instance.

All tokens available locally can be listed with this command:

$ fatbuildrctl tokens
token:
  path: /home/john/.local/share/fatbuildr/aHR0cHM6Ly9idWlsZC5zZXJ2ZXIvZGVmYXVsdA==.token
  uri: https://build.server/default
  user: john
  issued at: 1970-01-01T00:00:00
  expiration: 2099-12-31T23:59:59
  audience: fatbuildr

When a token associated to a remote instance is available locally, it is automatically loaded and sent by fatbuildrctl for authentication to this instance.

Exit status

0

fatbuildrctl has processed command with success.

1

fatbuildrctl encountered an error.