.\" Man page generated from reStructuredText.
.
.TH "PLAINBOX-TRUSTED-LAUNCHER-1" "1" "January 05, 2016" "0.25" "Plainbox"
.SH NAME
plainbox-trusted-launcher-1 \- execute job command as another user
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
plainbox\-trusted\-launcher\-1 [\-h] (\-w | \-t CHECKSUM)
                            [\-T NAME=VALUE [NAME=VALUE ...]] [\-g CHECKSUM]
                            [\-G NAME=VALUE [NAME=VALUE ...]]
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
Security elevation mechanism for plainbox
.sp
This command is a part of the implementation of \fBplainbox\fP\&. It is not
intended to be invoked directly and the command line arguments and behavior
may freely change between versions.
.sp
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 \fBsudo\fP (8) and \fBpkexec\fP (1) don\(aqt 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.
.SS Execution
.SS Warm\-up Mode
.sp
If the \fB\-\-warmup\fP option is specified then nothing more happens and the
program exists immediately. This is intended to \(aqwarm\-up\(aq the tool that
executes \fBplainbox\-trusted\-launcher\-1\fP itself (typically \fBpkexec\fP or
\fBsudo\fP)
.SS Normal Execution
.sp
In normal execution mode, the launcher looks up the job with the checksum
specified by \fB\-\-target\fP and executes the command embedded inside. Environment
passed via \fB\-\-target\-environment\fP is appended to the environment variables
inherited from the parent process.
.sp
Standard output, standard error and exit code of
\fBplainbox\-trusted\-launcher\-1\fP is exactly as the values from the commands
embedded into the selected job itself.
.SS Indirect Execution
.sp
In indirect execution mode, the launcher first looks up the job with the
checksum specified by \fB\-\-generator\fP, executes it, discarding stderr and
re\-interpreting stdout as a set of job definitions. Environment passed via the
\fB\-\-generator\-environment\fP is appended (but just to the generator job, the
\fB\-\-target\fP job has independent environment). All of the additional job
definitions are added to the global pool of jobs the launcher knows about.
.sp
After that the launcher continues as with normal execution, returning the same
stdout, stderr and exit code.
.SH OPTIONS
.sp

\fBOptional arguments:\fP
.PP
.INDENT 0.0
.TP
.B \-w\fP,\fB  \-\-warmup
return immediately, only useful when used with pkexec(1)
.TP
.B \-t\fP,\fB  \-\-target
run a job with this checksum
.TP
.B \-T\fP,\fB  \-\-target\-environment
environment passed to the target job
.TP
.B \-g\fP,\fB  \-\-generator
also run a job with this checksum (assuming it is a local job)
.TP
.B \-G\fP,\fB  \-\-generator\-environment
environment passed to the generator job
.UNINDENT
.SH ENVIRONMENT VARIABLES
.sp
The following environment variables \fIDO NOT\fP affect \fBplainbox\-trusted\-launcher\-1\fP
.INDENT 0.0
.TP
.B \fBPROVIDERPATH\fP
.INDENT 7.0
.INDENT 3.5
For \fBplainbox\fP 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.
.sp
The fixed list is composed of two system\-wide locations:
.INDENT 0.0
.IP \(bu 2
\fB/usr/local/share/plainbox\-providers\-1\fP
.IP \(bu 2
\fB/usr/share/plainbox\-providers\-1\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
All the other environment variables mentioned in \fBplainbox\fP work the
same way.
.UNINDENT
.SH BUGS
.sp
Currently it is impossible to use \fBplainbox\-trusted\-launcher\-1\fP with a
\fBlocal\fP job needs to run as root, that generates another \fBlocal\fP 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.
.sp
The launcher is somewhat inefficient, in that it has to re\-run all of the
dependencies of the \fBlocal\fP job over and over. Ideally those would be cached,
per\-session, but that would significantly increase the complexity of the code
running as root.
.SH SEE ALSO
.sp
\fBplainbox\fP
.SH AUTHOR
Zygmunt Krynicki & Checkbox Contributors
.SH COPYRIGHT
2012-2014 Canonical Ltd
.\" Generated by docutils manpage writer.
.