NAME

       plainbox-trusted-launcher-1 - execute job command as another user

SYNOPSIS

          plainbox-trusted-launcher-1 [-h] (-w | -t CHECKSUM)
                                      [-T NAME=VALUE [NAME=VALUE ...]] [-g CHECKSUM]
                                      [-G NAME=VALUE [NAME=VALUE ...]]

DESCRIPTION

       Security elevation mechanism for plainbox

       This command is a part of the implementation of plainbox. It is not intended to be invoked
       directly and the command line arguments and behavior may freely change between versions.

       Technically this program is used to run a command associated  with  a  job  definition  as
       another  user  (typically  as root). The existing technologies such as sudo (8) and pkexec
       (1) don't have enough granularity to still  restrict  arbitrary  commands  but  allow  the
       commands  that  are  inside  system-wide  installed locations (thus safe as one needs root
       access to install those in the first place).  One  additional  restriction  is  that  some
       commands are themselves generated by other jobs.

   Execution
   Warm-up Mode
       If  the  --warmup  option  is  specified  then nothing more happens and the program exists
       immediately.   This   is    intended    to    'warm-up'    the    tool    that    executes
       plainbox-trusted-launcher-1 itself (typically pkexec or sudo)

   Normal Execution
       In  normal  execution  mode,  the launcher looks up the job with the checksum specified by
       --target  and   executes   the   command   embedded   inside.   Environment   passed   via
       --target-environment  is  appended  to the environment variables inherited from the parent
       process.

       Standard output, standard error and exit code of plainbox-trusted-launcher-1 is exactly as
       the values from the commands embedded into the selected job itself.

   Indirect Execution
       In  indirect  execution  mode,  the  launcher  first  looks  up  the job with the checksum
       specified by --generator, executes it, discarding stderr and re-interpreting stdout  as  a
       set  of  job  definitions.  Environment passed via the --generator-environment is appended
       (but just to the generator job, the --target job has independent environment). All of  the
       additional job definitions are added to the global pool of jobs the launcher knows about.

       After  that  the  launcher  continues as with normal execution, returning the same stdout,
       stderr and exit code.

OPTIONS

       Optional arguments:

       -w, --warmup
              return immediately, only useful when used with pkexec(1)

       -t, --target
              run a job with this checksum

       -T, --target-environment
              environment passed to the target job

       -g, --generator
              also run a job with this checksum (assuming it is a local job)

       -G, --generator-environment
              environment passed to the generator job

ENVIRONMENT VARIABLES

       The following environment variables DO NOT affect plainbox-trusted-launcher-1

       PROVIDERPATH
                 For plainbox this would affect the set of directories where Plainbox  looks  for
                 provider  definitions. The trusted launcher has a fixed list of directories that
                 cannot be extended.

                 The fixed list is composed of two system-wide locations:

                 • /usr/local/share/plainbox-providers-1

                 • /usr/share/plainbox-providers-1

              All the other environment variables mentioned in plainbox work the same way.

BUGS

       Currently it is impossible to use plainbox-trusted-launcher-1 with a local  job  needs  to
       run  as  root, that generates another local job that needs to run as root, to generate any
       additional jobs that also need to  run  as  root.  In  other  words,  only  one-level  job
       generation is supported.

       The  launcher is somewhat inefficient, in that it has to re-run all of the dependencies of
       the local job over and over. Ideally those would be cached, per-session,  but  that  would
       significantly increase the complexity of the code running as root.

SEE ALSO

       plainbox

AUTHOR

       Zygmunt Krynicki & Checkbox Contributors

COPYRIGHT

       2012-2014 Canonical Ltd