.\" Man page generated from reStructuredText.
.
.TH "PLAINBOX-TRUSTED-LAUNCHER-1" "1" "April 14, 2014" "0.5" "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
.TP
.B usage: plainbox\-trusted\-launcher\-1 [\-h] (\-w | \-t CHECKSUM)
[\-T NAME=VALUE [NAME=VALUE ...]]
[\-g CHECKSUM]
[\-G NAME=VALUE [NAME=VALUE ...]]
.UNINDENT
.SH DESCRIPTION
.sp
This command is a part of the implementation of plainbox(1). 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 sudo(8) and pkexec(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.
.SH EXECUTION
.SS Warm\-up Mode
.sp
If the \-\-warmup option is specified then nothing more happens and the program
exists immediately. This is intended to \(aqwarm\-up\(aq the tool that executes
plainbox\-trusted\-launcher\-1 itself (typically pkexec or sudo)
.SS Normal Execution
.sp
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.
.sp
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.
.SS Indirect Execution
.sp
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.
.sp
After that the launcher continues as with normal execution, returning the same
stdout, stderr and exit code.
.SH OPTIONS
.SS Optional Arguments
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B \-w\fP,\fB  \-\-warmup
return immediately, only useful when used with
pkexec(1)
.UNINDENT
.UNINDENT
.UNINDENT
.SS Target job specification
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.BI \-t \ CHECKSUM\fP,\fB \ \-\-target \ CHECKSUM
run a job with this checksum
.UNINDENT
.INDENT 0.0
.TP
.B \-T NAME=VALUE [NAME=VALUE ...], \-\-target\-environment NAME=VALUE [NAME=VALUE ...]
environment passed to the target job
.UNINDENT
.UNINDENT
.UNINDENT
.SS Generator job specification
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.BI \-g \ CHECKSUM\fP,\fB \ \-\-generator \ CHECKSUM
also run a job with this checksum (assuming it is a
local job)
.UNINDENT
.INDENT 0.0
.TP
.B \-G NAME=VALUE [NAME=VALUE ...], \-\-generator\-environment NAME=VALUE [NAME=VALUE ...]
environment passed to the generator job
.UNINDENT
.UNINDENT
.UNINDENT
.SH ENVIRONMENT VARIABLES
.sp
The following environment variables \fIDO NOT\fP affect plainbox\-trusted\-launcher\-1
.INDENT 0.0
.TP
.B \fBPROVIDERPATH\fP
For plainbox(1) 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 7.0
.IP \(bu 2
\fB/usr/local/share/plainbox\-providers\-1\fP
.IP \(bu 2
\fB/usr/share/plainbox\-providers\-1\fP
.UNINDENT
.UNINDENT
.sp
All the other environment variables mentioned in plainbox(1) work the same way.
.SH AUTHOR
Zygmunt Krynicki
.SH COPYRIGHT
2012-2014 Canonical Ltd
.\" Generated by docutils manpage writer.
.