Running jobs as root

Plainbox is started without any privilege. But several tests need to start commands requiring privileges.

Such tests will call a trusted launcher, a standalone script which does not depend on the Plainbox core modules. polkit will control access to system resources. The trusted launcher has to be started using pkexec so that the related policy file works as expected.

To avoid a security hole that allows anyone to run anything as root, the launcher can only run jobs installed in a system-wide directory. This way we are not weaken the trust system as root access is required to install both components (the trusted runner and jobs). The Plainbox process will send an identifier which is matched by a well-known list in the trusted launcher. This identifier is the job hash:

$ pkexec plainbox-trusted-launcher-1 --hash JOB-HASH

See for details about job hashes.

Using Polkit

Available authentication methods


Only applicable to the package version of Plainbox

Plainbox comes with two authentication methods but both aim to retain the granted privileges for the life of the Plainbox process.

  • The first method will ask the password only once and show the following agent on desktop systems (a text-based agent is available for servers):

    | [X]                            Authenticate                                 |
    |                                                                             |
    | [Icon] Please enter your password. Some tests require root access to run    |
    |        properly. Your password will never be stored and will never be       |
    |        submitted with test results.                                         |
    |                                                                             |
    |        An application is attempting to perform an action that requires      |
    |        privileges.                                                          |
    |        Authentication as the super user is required to perform this action. |
    |                                                                             |
    |        Password: [________________________________________________________] |
    |                                                                             |
    | [V] Details:                                                                |
    |  Action:                  |
    |  Vendor: Plainbox                                                           |
    |                                                                             |
    |                                                     [Cancel] [Authenticate] |

    The following policy file has to be installed in /usr/share/polkit-1/actions/ on Ubuntu systems. Asking the password just one time and keeps the authentication for forthcoming calls is provided by the allow_active element and the auth_admin_keep value.

    Check the polkit actions documentation for details about the other parameters.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE policyconfig PUBLIC
     "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
      <action id="">
        <description>Run Job command</description>
        <message>Authentication is required to run a job command.</message>
        <annotate key="org.freedesktop.policykit.exec.path">/usr/bin/plainbox-trusted-launcher-1</annotate>
        <annotate key="org.freedesktop.policykit.exec.allow_gui">TRUE</annotate>
  • The second method is only intended to be used in headless mode (like SRU). The only difference with the above method is that allow_active will be set to yes.


The two policy files are available in the Plainbox contrib/ directory.

Environment settings with pkexec

pkexec allows an authorized user to execute a command as another user. But the environment that command will run it, will be set to a minimal known and safe environment in order to avoid injecting code through LD_LIBRARY_PATH or similar mechanisms.

However, some jobs commands require specific enviroment variables such as the name of an access point for a wireless test. Those kind of variables must be available to the trusted launcher. To do so, the enviromment mapping is sent to the launcher like key/value pairs are sent to the env(1) command:

$ pkexec trusted-launcher JOB-HASH [NAME=VALUE [NAME=VALUE ...]]

Each NAME will be set to VALUE in the environment given that they are known and defined in the JobDefinition.environ parameter.


The trusted launcher is the minimal code needed to be able to run a Checkbox job command.

Internally the checkbox trusted launcher looks for jobs in the system locations defined in which defaults to /usr/share/plainbox-trusted-launcher-1/*.provider.


plainbox-trusted-launcher-1 [-h] (--hash HASH | --warmup)
                          [--via GENERATOR-JOB-HASH]
                          [NAME=VALUE [NAME=VALUE ...]]

positional arguments:
  NAME=VALUE            Set each NAME to VALUE in the string environment

optional arguments:
  -h, --help            show this help message and exit
  --hash HASH           job hash to match
  --warmup              Return immediately, only useful when used with
  --via GENERATOR-JOB-HASH  Generator job hash to use to match the generated job


Check all job hashes with plainbox special -J

As stated in the polkit chapter, only a trusted subset of the environment mapping will be set using to run the command. Only the variables defined in the job environ property are allowed to avoid compromising the root environment. Needed modifications like adding CHECKBOX_SHARE and new paths to scripts are managed by the plainbox-trusted-launcher-1.

Authentication on Plainbox startup

To avoid prompting the password at the first test requiring privileges, Plainbox will call the plainbox-trusted-launcher-1 with the --warmup option. It’s like a NOOP and it will return immediately, but thanks to the installed policy file the authentication will be kept.


When running the development version from a branch, the usual polkit authentication agent will pop up to ask the password each and every time. This is the only difference.

Special case of jobs using the Checkbox local plugin

For jobs generated from resources jobs (e.g. disk/read_performance.*) the trusted launcher is started with --via meaning that we have to first eval a generator job to find a hash match. Once a match is found, the job command is executed.

$ pkexec plainbox-trusted-launcher-1 --hash JOB-HASH --via GENERATOR-JOB-HASH
comments powered by Disqus