Go to file
lars 3252f23c04 fixed some unittests
small layout improvements
added german translations for data and disks plugins
remove leading empty lines in html output to fix tidy warnings
2006-12-14 13:19:37 +00:00
bin fixed some ssl detection stuff 2006-12-14 00:23:10 +00:00
bin-perl-old moved pythonrewrite branch to trunk 2006-11-06 16:05:00 +00:00
conf-examples fixed some ssl detection stuff 2006-12-14 00:23:10 +00:00
debian improved some minor layout stuff 2006-12-14 01:34:07 +00:00
design -logfile checks 2006-12-06 01:16:26 +00:00
doc/html updated translation 2006-11-30 14:50:28 +00:00
event-scripts samba stuff 2006-12-12 19:42:19 +00:00
intl 'log' plugin: show warning if no log file is used 2006-12-12 13:34:05 +00:00
lang language page stays after change 2006-12-08 00:49:32 +00:00
man added manpages for CryptoBoxRootActions and CryptoBoxWebserver 2006-11-24 11:03:34 +00:00
plugins fixed some unittests 2006-12-14 13:19:37 +00:00
scripts fixed some ssl detection stuff 2006-12-14 00:23:10 +00:00
src fixed some unittests 2006-12-14 13:19:37 +00:00
stuff samba stuff 2006-12-12 19:42:19 +00:00
templates fixed some unittests 2006-12-14 13:19:37 +00:00
www-data added some exception catching for writing setting files 2006-12-13 10:01:58 +00:00
LICENSE debianisation finished 2005-11-30 01:10:32 +00:00
MANIFEST.in fixed some ssl detection stuff 2006-12-14 00:23:10 +00:00
README fixed some unittests 2006-12-14 13:19:37 +00:00
README.davfs constant width of the main screen (works for mozilla/ff and ie55/60 2006-12-07 12:20:43 +00:00
README.proxy fixed some ssl detection stuff 2006-12-14 00:23:10 +00:00
README.samba added minor parts of slovene translation 2006-12-11 14:16:10 +00:00
README.ssl fixed some ssl detection stuff 2006-12-14 00:23:10 +00:00
changelog added manpages for CryptoBoxRootActions and CryptoBoxWebserver 2006-11-24 11:03:34 +00:00
copyright moved some more stuff around 2006-11-23 20:52:30 +00:00
package.exclude added manpages for CryptoBoxRootActions and CryptoBoxWebserver 2006-11-24 11:03:34 +00:00
setup.py improved code style of setup script 2006-12-14 00:21:08 +00:00

README

********************************************
*          CryptoBox v0.2.99               *
********************************************

$Id$

This file describes the webserver CryptoBox.
The CryptoBox enables you to control the plaintext or encrypted harddisks of
your server via a webinterface.
Read on if you want to install the CryptoBox-server package on your computer.

For more information, see the website:
	http://cryptobox.org

Table of contents:
	1) Requirements
	2) Installation
	3) Setup
	4) Usage
	5) Development
	6) Acknowledgements
	7) Licence

--------------------------------------------

1) Requirements
	- Linux 2.6
	- super (to selectively gain root privileges)
	- Python 2.4
	- some python packages:
		clearsilver 0.10 for python
		python-configobj 4.x
		cherrypy 2.x


2) Installation
For Debian, Ubuntu and other derivates you should use the debian package:
	see http://systemausfall.org/toolforge/debian/

There are currently no official rpm packages of the CryptoBox.

For source installation follow these steps:
	Get the source:
		http://cryptobox.org/download

	Extract tarball and change to the new directory:
		tar xzf cryptobox-0.?.?.tar.gz

	Install the program:
		python setup.by install

The installed files can be found in your local python installation directory.
The default location should be:
	/usr/lib/python2.4/site-packages/cryptobox

Adapt the directories given in /etc/cryptobox-server/cryptobox.conf to your
local installation. The paths below /usr/share should be below your python
directoy instead (see above) - sorry for this inconvenience!

The CryptoBox webserver daemon that is given in /etc/init.d/cryptobox-server
may have to be changed to /usr/bin instead of /usr/sbin.

As some actions of the cryptobox require root privileges, you have to add the
following line to /etc/super.tab:
	CryptoBoxRootActions	/usr/bin/CryptoBoxRootActions	cryptobox
The script /usr/bin/CryptoBoxRootActions is used to execute all actions
requiring root privileges. Please check it to make sure, that your system will
not get compromised.


3) Setup

 a) Start at bootup
	Set NO_START in /etc/default/cryptobox-server to "0".
	The CryptoBox webserver will get started by its runlevel control script
	after during booting.

 b) Define managed devices
	You may restrict which blockdevices should be accessible to the CryptoBox.
	Simply set [Main]->AllowedDevices in /etc/cryptobox-server/cryptobox.conf
	to a comma separated list of device prefixes: e.g. /dev/sd gives access to
	all SCSI devices, while /dev/hda3 restricts it to this single partition.
	The user executing the webserver (by default: 'cryptobox') must have write
	access to these devices. Usually the cryptobox user is member of the 'disk'
	group. This gives control over most devices.
	Be careful with this setting, as you may expose important data to public
	read and write access.

 c) Listening port and interface
	By default, the CryptoBox webserver listens to tcp port 8080 on all network
	interfaces. You can change this setting in /etc/default/cryptobox-server.
	Also take a look at your firewall settings.

 d) Disable plugins
	The CryptoBox contains a lot of plugins. As some of them could expose
	unwanted features to your users, you should carefully select which plugins
	to disable.
	Quite likely candidates for disabling are:
		- shutdown: poweroff or reboot the computer
		- network: change IP, gateway or dns settings of the server
		- partition: partition blockdevices
		- volume_format_fs: format a disk/partition (plaintext/encrypted)
	Take a look at /usr/share/cryptobox-server/plugins for the list of
	other plugins.
	The setting [Main]->DisabledPlugins in /etc/cryptobox-server/cryptobox.conf
	is a comma separated list of plugin names. Capitalization is important!

 e) Separate configuration partition
	The CryptoBox webserver requires a writeable directory for proper
	operation. If your root filesystem is not writeable (e.g. booting from a
	cdrom, read-only mounted flash memory, ...) you may use a seperated
	partition to store runtime settings. The CryptoBox will automatically
	creates it, when you use partition one of your disks with its interface.
	The setting [Main]->UseConfigPartition (see
	/etc/cryptobox-server/cryptobox.conf) defines, whether you want to use a
	separate partition (value "1") or if you want to store your runtime
	settings in the root filesystem (typically below
	/var/cache/cryptobox-server).

 f) Samba/WebDAV/NFS/??? integration (aka. event script handling)
	The CryptoBox allows you to add event handling scripts for most of the
	interesting events: bootup/shutdown of the webserver and mount/umount
	of single volumes.
	If you want to automatically publish your mounted volumes with samba
	or similar fileservers, then you should take a closer look at the
	example scripts for samba and apache-webdav in
	/usr/share/doc/cryptobox-server/event-scripts.
	You may also just publish the mount directory of the CryptoBox. This
	will expose all mounted volumes very easily. Review the configuration
	file for the setting [Locations]->MountParentDir.

 g) Take a close look at the configuration file to check all other options
	before you start the CryptoBox webserver.


4) Usage
Use your favourite web browser to go to http://localhost:8080 and browse the
webinterface of the CryptoBox.
Some parts of the interface are restricted to administrative access. The
default access combination is the user 'admin' and the password 'admin'. Please
change this setting immediately.
The plugin 'user_manager' allows you to add users and to change passwords.
The plugin 'plugin_manager' lets you configure, which plugins require
administrative authentication.

The user manual (available via the 'help' plugin) should give you exhaustive
usage information.
The current version of the online manual is available at:
	https://systemausfall.org/trac/cryptobox/wiki/CryptoBoxUser


5) Development
bug reports: please use our issue tracker
	https://systemausfall.org/trac/cryptobox/newticket

email:
	cryptobox@systemausfall.org

The CryptoBox project is mainly driven by sense.lab (http://senselab.org).


6) Acknowledgements
Besides the core development team, these people helped a lot:
Clavdia Horvat, Tadej Brce & Dušan Rebolj - slovenian translation
rike - french translation

We also want to thank the numerous developers of the Free Software, the
CryptoBox depends on and that was used in development.


7) Licence
All scripts are GPL code (v2.0 or above).
The documentation is licenced under "Creative Commons 2.5 share-alike" (http://creativecommons.org/licenses/by-sa/2.5/).