You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
frisco a26dca8068 Added script and related configuration to browse all of CryptoNAS' Python code in one browser 10 years ago
bin Added script and related configuration to browse all of CryptoNAS' Python code in one browser 10 years ago
conf-examples * floppy disks are now unsupported 14 years ago
debian Build requires python-setuptools 10 years ago
design Added src image for splash screen. Fixed error in r1151. 13 years ago
doc Added script and related configuration to browse all of CryptoNAS' Python code in one browser 10 years ago
event-scripts * new loge & name in webfrontend 14 years ago
intl update translations from Pootle server (translation branch v0.3.x) 13 years ago
man CryptoBoxRootActions 14 years ago
plugins Minor code cleanup 10 years ago
scripts Major updates to scripts for unit tests and pydoc 12 years ago
src * use caching for "debian_live" check 12 years ago
stuff tags/v0.3.5: Merged translations from branches/translation-base-v0.4 12 years ago
templates * added more specific information to a log message 12 years ago
www-data * added new logo to webfrontend 14 years ago
.htaccess Added script and related configuration to browse all of CryptoNAS' Python code in one browser 10 years ago
LICENSE debianisation finished 16 years ago fixed some ssl detection stuff 15 years ago
README synchronized changelog and README 14 years ago
README.davfs constant width of the main screen (works for mozilla/ff and ie55/60 15 years ago
README.proxy fixed wrong apache module name in README.ssl 14 years ago
README.samba some hints 15 years ago
README.ssl * removed lighthttpd until someone asks for 15 years ago
changelog synchronized changelog and README 14 years ago
copyright added license information for vector graphic files 15 years ago removed obsolete creative-commons logo 15 years ago
package.exclude added exclusion file for packaging 15 years ago Added `--use-fuzzy' to msgfmt call, fixing undesired German messages in English locale. 13 years ago


* CryptoBox v0.3.xx *


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:

Table of contents:
1) Requirements
2) Installation
3) Setup
4) Usage
5) Data access
6) Development
7) Acknowledgements
8) 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:

Please follow the /usr/share/doc/cryptobox-server/README.Debian for
any special steps regarding Debian.

There are currently no official rpm or other packages of the CryptoBox.
Use the source installation on non-deb based distributions.

For source installation follow these steps:
Get the source:

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

Install the program:
python install

Fulfil the requirements:
read more in the user documentation

The installed pyhton modules can be found in your local python installation directory.
The default location should be:
The data files are (by default) installed to:

As some actions of the cryptobox require root privileges, you have to add the
following line to /etc/
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 bootup.

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

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
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.

5) Data access
Before you can access your plaintext or encrypted data on a volume, you have to
open it. To accomplish this, you have to go to the webinterface, select the
appropriate volume and click on "Open volume" in the "Activation" tab.

If you are running the CryptoBox locally, then you can access all open volumes
below the 'MountDir' as specified in the configuration file
(/etc/cryptobox-server/cryptobox.conf). The default mount location is

If the CryptoBox package is running on a networking server, then you have to
configure your favourite fileserver (e.g. samba, webdav, nfs, ftp, ...) to
publish the subdirectories of the 'MountDir' (see above).
If you want to customize the publishing of volumes, then you may use the
event script feature fo the CryptoBox. See event-scripts/README for details.

6) Development
bug reports: please use our issue tracker


The CryptoBox project is mainly driven by sense.lab (

7) Acknowledgements
Besides the core development team, these people helped a lot:
Clavdia Horvat, Tadej Brce & Dušan Rebolj - Slovenian translation
rike - French translation
Fabrizio Tarizzo - Italian translation
kinneko - Japanese translation
Andrzej S. Kaznowski - Polish translation
Fadrique - Spanish translation
Michiel van Dijk - Dutch translation
Raimar - the blender dragon
Gilles Accad - French translation
ASpr - Russian translation

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

8) License
The code is licensed under the GPL v2.0 or above.
The documentation and all graphics are licenced under "Creative Commons Attribution
Share-Alike 2.5" (
See the file 'copyright' for details.