bbot-agent(1)

NAME
bbot-agent - build bot agent

SYNOPSIS

bbot-agent --help
bbot-agent --version
bbot-agent [options] [priority=]url...

DESCRIPTION

bbot-agent @@ TODO.

The controller URL priority is a four or five-digit decimal value. If it is absent, then 0 (lowest priority) is assumed. URLs with equal priority are queried at random.

The priority value has the [F]DCBA form which encodes four priority levels (DCBA) each occupying one decimal digit (so there are 10 distinct priorities in each level) plus the optional boost flag (F). These levels offer different trade-offs between the speed of completing a higher priority task and potentially discarding work that has already been done.

The first priority level (A) is a simple preference: among the URLs with equal values for other levels (DCB), those with higher first level priorities are queried first.

The second priority level (B) has the semantics of the first level plus it prevents URLs with lower second priority level from being queried until the task with a higher second priority level has completed, effectively conserving the resources for the higher priority task.

The third priority level (C) has the semantics of the second level plus it may interrupt one lower third priority level task in order to perform the higher third priority task (the interrupt is necessary if the desired machine is used by the lower priority task or the number of tasks already being performed is the maximum allowed to be performed concurrently; see --instance-max).

Finally, the fourth priority level (D) has the semantics of the third level except that not one but all the lower fourth priority level tasks are interrupting, effectively dedicating all the available resources to the higher priority task. This level can also be combined with the boost flag F. If this flag is 1 then the higher priority task's CPU number (--cpu) is boosted to the full number of available hardware threads (or, to view it another way, the fourth priority level has 20 possible values, not 10, with the first 0-9 being without the boost while the last 10-19 being with the boost). Note that this boosting semantics may not be accurate if the agent is executed with CPU affinity. Also note that there is no corresponding RAM boosting and it's possible that in some configurations the amount of RAM will be insufficient for the boosted CPU count.

Note that the priority levels are hierarchical in a sense that within a given higher level URLs can be further prioritized using the lower levels. As an example, consider a deployment with three controller URLs: background package rebuilds (pkg.example.org), user-initiated CI (ci.example.org), and user-initiated interactive CI (ici.example.org). Given the following priorities:

0000=https://pkg.example.org
0100=https://ci.example.org
0101=https://ici.example.org

Both types of CI tasks will interrupt one background rebuild task if necessary while the interactive CI tasks will be merely preferred over non-interactive.

Note that on termination bbot-agent may leave behind a machine lock and working machine snapshot. It is expected that the caller (normally Build OS monitor) cleans them up before restarting the agent.

OPTIONS

--help
    Print usage information and exit.

--version
    Print version and exit.

--verbose level
    Set the diagnostics verbosity to level between 0 and 6 with level 1 being the default.

--systemd-daemon
    Run as a simple systemd daemon.

--toolchain-name str
    Toolchain name, default by default.

--toolchain-num num
    Toolchain number, 1 by default. If agents are running for several toolchains, then each of them should have a unique toolchain number between 1 and 9. This number is used as an offset for network ports, interfaces, etc.

--toolchain-lock path
    Absolute path to the global toolchain lock file. If unspecified, then /var/lock/bbot-agent-toolchain-name.lock is used by default. If empty path is specified then no global locking is performed. If one of the --fake-* options is specified, then no locking is performed by default.

--toolchain-ver stdver
    Toolchain version. If unspecified, then the agent's version will be used (which will be imprecise for snapshot versions).

--toolchain-id str
    Toolchain id. If unspecified or empty, then no re-bootstrapping on toolchain changes will be performed (which is primarily useful for testing).

--interactive mode
    Interactive build support. Valid values for this option are false (only non-interactive), true (only interactive), and both. If this option is not specified, then only non-interactive builds are supported.

--instance num
    Instance number, 1 by default. If several instances of an agent are running for the same toolchain, then each of them should have a unique instance number between 1 and 99. This number is used as an offset for network ports, interfaces, etc.

--instance-max num
    Maximum number of instances that can perform tasks concurrently. If the number of instances that have been started is greater than this number (normally by just one), then when the maximum number of tasks is already being performed, the extra instances operate in the priority monitor mode: they only query controller URLs with priorities higher than of the existing tasks and can only perform a task by interrupting one of them. If the maximum number of instances is 0 (default), then it is assumed the number of instances started is the maximum number, essentially disabling the priority monitor functionality.

--cpu num
    Number of CPUs (threads) to use, 1 by default.

--build-ram num
    Amount of RAM (in KiB) to use for the build machine, 4GiB by default.

--auxiliary-ram num
    Amount of RAM (in KiB) to use for auxiliary machines. To disable running auxiliary machines, specify 0. If unspecified, then currently the behavior is the same as specifying 0 but this may change in the future (for example, to support a more dynamic allocation strategy).

--bridge iface
    Bridge interface to use for machine networking, br1 by default.

--auth-key file
    Private key for the public key-based agent authentication. If not specified, then the agent will not be able to request tasks from controllers that require authentication. The file is expected to contain a single PEM-encoded private key without a password. A suitable key can be generated using the following command:
    $ openssl genrsa 4096 >key.pem

--trust fingerprint
    Trust repository certificate with a SHA256 fingerprint.

--machines dir
    The location of the build machines, /build/machines/ by default.

--tftp dir
    The location of the TFTP server root, /build/tftp/ by default.

--tftp-port num
    TFTP server port base, 23400 by default. The actual port is calculated by adding an offset calculated based on the toolchain, instance, and machine numbers.

--bootstrap-startup sec
    Maximum number of seconds to wait for build machine bootstrap startup, 300 (5 minutes) by default.

--bootstrap-timeout sec
    Maximum number of seconds to wait for build machine bootstrap completion, 3600 (60 minutes) by default.

--bootstrap-auxiliary sec
    Maximum number of seconds to wait for auxiliary machine bootstrap completion, 900 (15 minutes) by default.

--bootstrap-retries num
    Number of times to retry a mis-booted bootstrap, 2 (3 attempts total) by default.

--build-startup sec
    Maximum number of seconds to wait for build startup, 240 (4 minutes) by default. This value is used for both build and auxiliary machines.

--build-timeout sec
    Maximum number of seconds to wait for build completion, 5400 (90 minutes) by default.

--build-retries num
    Number of times to retry a mis-booted build, 2 (3 attempts total) by default.

--intactive-timeout sec
    Maximum number of seconds to wait for interactive build completion, 10800 (3 hours) by default.

--connect-timeout sec
    Maximum number of seconds to wait for controller request connection, 60 (1 minute) by default.

--request-timeout sec
    Maximum number of seconds to wait for controller request completion, 300 (5 minutes) by default.

--request-retries num
    Number of times to retry a controller request, 4 (5 attempts total) by default. Note that both the total time for all retries as well as the time of each retry are limited by the same --request-timeout value. This means that a successful request may take up to twice as long if a connection was established at the end of the retry window and took just as long to complete.

--openssl path
    The openssl program to be used for crypto operations. You can also specify additional options that should be passed to the openssl program with --openssl-option. If the openssl program is not explicitly specified, then bbot-agent will use openssl by default.

--openssl-option opt
    Additional option to be passed to the openssl program (see --openssl for details). Repeat this option to specify multiple openssl options.

--dump-machines
    Dump the available machines to stdout, (re)-bootstrapping any if necessary, and exit.

--dump-task
    Dump the received build task to stdout and exit.

--dump-result
    Dump the obtained build result to stdout and exit.

--fake-bootstrap
    Fake the machine bootstrap process by creating the expected bootstrapped machine manifest.

--fake-build
    Fake the package building process by creating the aborted build result.

--fake-machine file
    Fake the machine enumeration process by reading the machine header manifest from file (or stdin if file is '-').

--fake-request file
    Fake the task request process by reading the task manifest from file (or stdin if file is '-').

EXIT STATUS

Non-zero exit status is returned in case of an error.

BUGS
Send bug reports to the users@build2.org mailing list.

COPYRIGHT
Copyright (c) 2014-2026 the build2 authors (see the AUTHORS file). Permission is granted to copy, distribute and/or modify this document under the terms of the MIT License.