cryptonas-branches/staging-v0.3.5/man/CryptoBoxRootActions.8

106 lines
3.8 KiB
Groff

.TH CryptoBoxRootActions 8 "August 02007" "CryptoBox" "CryptoBox-Server manual"
.SH NAME
CryptoBoxRootActions \- The CryptoBoxWebserver calls this script in order to
execute various programs which require root privileges.
.SH SYNOPSIS
.B CryptoBoxRootActions
check
.br
.B CryptoBoxRootActions
plugin \fIFEATURE_SCRIPT\fR [\fIARGS\fR]
.br
.B CryptoBoxRootActions
hook \fIEVENT_SCRIPT\fR [\fIARGS\fR]
.br
.B CryptoBoxRootActions
program \fIPROG\fR [\fIARGS\fR]
.SH DESCRIPTION
CryptoBoxRootActions is a script that is called by the
\fBCryptoBox\fR-Server to execute programs which require root privileges. You
will never call this program directly. This manpage should only be useful as a
reference for developers of the CryptoBox.
.PP
To let the CryptoBox-Server gain root permissions you need the program
\fBsuper\fR. It is configured properly if \fI/etc/super.tab\fR contains the
following line:
.RS
.PP
CryptoBoxRootActions /usr/sbin/CryptoBoxRootActions cryptobox
.RE
.PP
We assume that the CryptoBoxRootActions script is located at
\fI/usr/sbin/CryptoBoxRootActions\fR. Furthermore the user running the
CryptoBox-Server is assumed to be \fIcryptobox\fR. Otherwise you must change the
above line accordingly.
.SH CONFIGURATION CHECK
Call the CryptoBoxRootActions script with the argument \fIcheck\fR to test if
\fBsuper\fR is configured properly. Just type the following:
.RS
.PP
super CryptoBoxRootActions check; echo $?
.RE
.PP
This should output '0' for success. Any other value indicates a problem and
should be accompanied by a descriptive error message.
.SH FEATURE SCRIPTS
The CryptoBox can be easily extended with new features. Refer to the developer
documentation of the CryptoBox for more details.
.PP
If a feature needs root privileges to accomplish its function, then you have to
write a separate python script for these actions. This script must fulfill the
following conditions:
.TP
writable only for root
The script and all its parent directories may not be writable for anyone except
root.
.TP
must be executable
The execution permission bit of the script must be set.
.TP
required member
The script must contain a member called \fBPLUGIN_TYPE\fR with the string value
\fIcryptobox\fR. This prevents the execution of arbitrary scripts.
.SH EVENT SCRIPTS
The CryptoBox-Server calls all scripts within a given directory whenever
specific events occour. Possible events are mounting and unmounting of disks or
the bootup or shutdown of the CryptoBox-Server. Refer to
\fI/usr/share/doc/cryptobox-server/event-scripts/README\fR for further details.
.PP
An event script must fulfill the following conditions:
.TP
writable only for root
The script and all its parent directories must not be writable for anyone
except root.
.TP
must be executable
The execution permission bit of the script must be set.
.TP
directory must be marked
The directory of the script must also contain a file called
\fI_cryptobox_events_\fR to prevent the execution of arbitrary scripts.
.SH SELECTED PROGRAMS
Very few selected programs may be called via CryptoBoxRootActions. Examples
are \fBcryptsetup\fR and \fBmount\fR. Refer to the source of
CryptoBoxRootActions for details.
.SH EXIT CODES
The program can return the following exit codes:
.TP
\fI0\fR - the action finished successfully
.TP
\fI1\fR - the executed action returned a failure code (exit code > 0)
.TP
\fI100\fR - improper calling or misconfiguration (wrong arguments, wrong uid, ...)
.TP
\fI101\fR - failed to execute the given program (maybe it does not exist?)
.SH AUTHOR
Written by Lars Kruse
.SH REPORTING BUGS
Report bugs to <devel@sumpfralle.de>
.SH COPYRIGHT
Copyright \(co 02006-02007 Lars Kruse
.br
This is free software. You may redistribute copies of it under the terms of the
GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO
WARRANTY, to the extent permitted by law.