Table Of Contents

Previous topic

Features

Next topic

Architecture

This Page

Installation instructions

Warning

Before you start, you should install the client on some computer from where you’re going to connect to the SFLvault server. This is because the client must be ready for when the server is setup: you have 15 minutes to set up the admin account after a certain point.

Production setup

Installing from your distribution’s package manager

This section will be added soon. In the meantime the preferred way to install SFLvault is from PyPI.

Installing from PyPI

Warning

The instructions in this wiki are for the latest version of SFLvault (0.8) that has not yet been released on the Python package index. It will be updated shortly. In the meantime please refer to:

Install system dependencies

Note

These instructions assume you are installing on Ubuntu 10.04 or newer. Specific package manager related commands and package names may vary.

SFLvault requires Python 2.6 or higher.

SFLvault requires the python headers to compile the crypto libraries. These instructions assume you are installing SFLvault inside a virtual environment.

$ sudo apt-get install python-virtualenv python-pip python-dev autoconf

Make a directory where the application will live:

$ mkdir SFLvault
$ cd SFLvault

Note

If you want this installation to become production installation, make sure you create a user and a group for that purpose, and that you issues those commands as that user.

Configure your virtual environment

$ virtualenv --distribute env
$ . env/bin/activate
(env)$ pip install -r requirements.freeze

Client installation first

To properly setup your server (with user-setup), you’ll need SFLVault’s client installed. It has the same dependencies as the server, so once you have them, you can install a client with a simple:

(env)$ pip install SFLVault-client

Install SFLvault

(env)$ pip install SFLvault-server

Note

If you get some permission denied, make sure you have activated your environment with . env/bin/activate (do not forget the dot!)

Run SFLvault

At this point it is possible to run SFLvault with the default configuration:

python -m sflvault.server

Warning

The default configuration does not enable SSL and is therefore insecure. It is recommended to generate a SSL key and certificate and configure SFLvault to use it. The following configuration file provides instructions to configure SSL on your installation.

To provide a configuration file to your SFLvault instance, please use the following file. Options are detailed in the Section sflvault section.

#
# SFLvault - Pylons development environment configuration
#
# The %(here)s variable will be replaced with the parent directory of this file
#
[sflvault]
sflvault.vault.session_timeout = 90
sflvault.vault.setup_timeout = 300
sflvault.vault.session_trust = true
sqlalchemy.url = sqlite:///%(here)s/sflvault.sqlite
sflvault.keyfile = /path/to/ssl/keyfile
sflvault.certfile = /path/to/ssl/certfile

# Logging configuration
[loggers]
keys = root, sflvault, sqlalchemy

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = INFO
handlers = console

[logger_sflvault]
level = DEBUG
handlers = console
qualname = sflvault

# SQLAlchemy logging from within paster shell
[logger_sqlalchemy]
# INFO or DEBUG for all SQL statements.
level = INFO
handlers =
qualname = sqlalchemy.engine

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(asctime)s,%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S

sflvault.keyfile and sflvault.certfile are the paths to your keyfile and certfile. You can use OpenSSl to generate these:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days XXX

Once you have created your configuration file, you can run tell SFLvault to use it by calling the following:

python -m sflvault.server /path/to/config

The first time you run the server, it will initialize a new database with a new ‘admin’ user. From this moment, you have 15 minutes to setup your admin account.

Create the admin account

Warning

If you’re too late, and you notice that you’ve expired the timer, don’t worry! Please go to Recreating the admin account

On your other computer (or on the same), run:

$ sflvault user-setup admin https://localhost:5000/vault/rpc

This will generate a new keypair, and store the public key in the vault. The admin account is setup, and you may start using the vault.

You should see something like:

...
Enter passphrase (to secure your private key):
Enter passphrase again:
Vault says: User setup complete for admin
Saving settings...

Congratulations! You now have running instance of SFLvault! For information on how to use it, please refer to the user manual.

Development setup

Installing from source

Get the latest version from git:

$ git clone http://git.sflvault.org/sflvault.git SFLvault

This will create a SFLvault directory where the application will live.

Before continuing, make sure to Install system dependencies and Configure your virtual environment

You can now install the required SFLvault packages:

$ cd common
$ python setup.py develop
$ cd ../server
$ python setup.py develop
$ cd ../client
$ python setup.py develop

At this point you can Run SFLvault and Create the admin account!

Run the tests

To run the tests you need to install further dependencies:

$ pip install -r requirements.tests.freeze

Which will let you run the vault’s test suite:

$ nosetests -w server --cover-package=sflvault.server

Additional information

Configuration parameters

Section sflvault

sflvault.host
The address at which we host the server. localhost is the default and results in a local-only server. If you want to serve externally, you can set this to 0.0.0.0.
sflvault.port
The port to listen to. Default is 5000.
sflvault.vault.session_timeout

Determines how long the user can wait, in seconds, before issuing two commands to SFLvault.

Default value is 60 seconds.

sflvault.vault.setup_timeout

Determines how long a user has, in seconds, to issue a user-setup command and configure his account after it has been created.

Default value is 300 seconds.

sflvault.vault.session_trust

Determines if a user’s session can be cached and used for login later in time. This parameter is deprecated and will be removed in 0.9.0

Default value is false.

sflvault.keyfile

sflvault.certfile

Paths to a key file and certificate file to use the SSL mode. When both configurations are set, the server is started in SSL mode, otherwise, it’s started in plain HTTP mode.
sqlalchemy.url (default value: sqlite://%(here)s/sflvault.sqlite)
Where SFLVault’s database is. It’s a SQLAlchemy URL, about which you can have more information at http://docs.sqlalchemy.org/en/rel_0_8/core/engines.html

Section loggers, handlers and formatters

Logging in SFLvault is done with the standard logging module. For further information, please refer to the official python documentation:

Recreating the admin account

If you get an error from the Vault because you waited more than 15 minutes between the setup-app and the call to user-setup, then you need to start with a new vault:

  1. Stop your server.
  2. Delete your database.
  3. Start your server.

SSL and password safety

Running the server over SSL is required to ensure password safety. The show command sends passwords in an encrypted form, but service-add and service-passwd do not. Someone listening to the communications between the client and the server could very easily get these passwords.

Make SFLvault a system service

To run as a server, you’ll need to have an eggcache directory, so go to where you created the config file:

$ cd SFLvault
$ mkdir eggcache

and install this file in /etc/init.d/sflvault (tweak as needed):

 #!/bin/sh -e

 APPDIR="/home/MyUser/SFLvault"
 cd $APPDIR
 export PYTHON_EGG_CACHE="$APPDIR/eggcache"
 PIDFILE="$APPDIR/paster.pid"
 LOGFILE="$APPDIR/paster.log"
 COMMAND="$APPDIR/env/bin/python -m sflvault.server /path/to/configuration --user=MyUser --group=MyUser --pid-file=$PIDFILE --log-file=$LOGFILE"

case "$1" in
  start)
    $COMMAND start
    ;;
  stop)
    $COMMAND stop
    ;;
  restart)
    $COMMAND restart
    ;;
  *)
    echo $"Usage: $0 {start|stop|restart}"
    exit 1
esac

exit 0

Then run:

chmod +x /etc/init.d/sflvault