Checkbox configuration options

Checkbox configuration and launcher files use the INI format. Each option is listed below with its type and default value. An empty default means that the option is not set by default. For details about how Checkbox finds and combines configuration files, see Checkbox configs.

To get a default INI as a file run:

checkbox-cli config defaults

[launcher]

launcher_version

Type: integer

Default: 1

Version of the launcher syntax and semantics to use.

app_id

Type: string

Default: checkbox-cli

Identifier of the application creating the session.

app_version

Type: string

Default: empty

Version of the application creating the session.

stock_reports

Type: list

Default: text,certification,submission_files

Stock reports to generate after the session.

local_submission

Type: Boolean

Default: True

Generate and send the submission report locally when using Checkbox Remote.

session_title

Type: string

Default: session title

Title applied to sessions created with the launcher. Exporters can include it in generated reports.

session_desc

Type: string

Default: empty

Description applied to sessions created with the launcher. Use it to store contextual information about the session.

[test plan]

filter

Type: list

Default: ['*']

Glob patterns that limit the test plans offered for interactive selection.

unit

Type: string

Default: empty

Test plan identifier selected by default.

forced

Type: Boolean

Default: False

Prevent the user from changing the selected test plan.

[test selection]

forced

Type: Boolean

Default: False

Prevent the user from changing the job selection.

exclude

Type: list

Default: []

Patterns matching jobs to exclude from the run.

match

Type: list

Default: []

Patterns matching jobs to run. Dependencies of matching jobs are also run.

[features]

strict_template_expansion

Type: Boolean

Default: True

Use invalid units generated by templates and report them as failures.

systemd_based_job_runner

Type: Boolean or unset

Default: None (True in snaps)

Run Checkbox jobs as systemd units outside the snap sandbox. When unset, Checkbox selects the behaviour based on its runtime environment.

[ui]

type

Type: string

Default: interactive

User interface to use.

output

Type: string

Default: show

Controls whether command output is shown or suppressed.

dont_suppress_output

Type: Boolean

Default: False

Do not suppress output from resource and attachment jobs. This option is deprecated; use output instead.

verbosity

Type: string

Default: normal

Amount of information reported by Checkbox internals.

auto_retry

Type: Boolean

Default: False

Automatically retry failed jobs at the end of the session.

max_attempts

Type: integer

Default: 3

Maximum number of attempts for a job in automatic retry mode.

delay_before_retry

Type: integer

Default: 1

Number of seconds to wait before retrying failed jobs.

[agent]

normal_user

Type: string

Default: empty

User name to use for jobs that do not specify a user.

[restart]

strategy

Type: string

Default: empty

Alternative strategy to use when restarting Checkbox.

[config]

config_filename

Type: string

Default: checkbox.conf

Name of the configuration file to look for.

Report sections

Report, transport, and exporter sections are named sections. Replace the name in each heading with a name that is unique within the configuration file.

[report:report_name]

exporter

Type: string

Default: empty

Name of the exporter section to use.

transport

Type: string

Default: empty

Name of the transport section to use.

forced

Type: Boolean

Default: False

Generate the report without asking the user.

[transport:transport_name]

type

Type: string

Default: empty

Type of transport to use.

stream

Type: string

Default: stdout

Stream transport destination. Supported values are stdout and stderr.

path

Type: string

Default: empty

Path where the report is saved by a file transport.

secure_id

Type: string

Default: empty

Secure identifier used by a submission transport.

staging

Type: Boolean

Default: False

Submit to the staging certification service instead of the production service.

[exporter:exporter_name]

unit

Type: string

Default: empty

Identifier of the exporter unit to use.

options

Type: list

Default: []

Options passed to the exporter.

Free-form sections

[environment]

Each entry defines an environment variable made available to jobs. The option name is the environment variable name and the option value is its value.

[manifest]

Each entry provides a preset value for the corresponding manifest entry. These values take precedence over values stored in the manifest cache.