1. Introduction

This howto explains how to set up a full Peerfuse network and works for Peerfuse-net and Peerfuse-lan. If you just want to try Peerfuse, you can follow a shorter howto to join the Peerfuse.net network (http://peerfuse.net/howto.html). Peerfuse is really new and doesn't fully work yet. This howto is more meant for people wanting to try Peerfuse or develop on it, than for administrators looking for a full featured distributed filesystem.

Don't store any file under the Peerfuse mountpoint if you don't have a copy of it somewhere else.

If you find a bug in this howto, or have questions, you can contact us using the Peerfuse mailing list at peerfuse@peerfuse.org, or on irc at #peerfuse@irc.freenode.net.

  1. Getting Peerfuse / Installing Peerfuse

Everything is explained on the Peerfuse website, in the download section at http://peerfuse.org/download.html .

  1. Generating keys and certificates

Peerfuse uses public key cryptography (http://en.wikipedia.org/wiki/Public_key) to encrypt communications and to authenticate users. In order to authorize a peer to connect, a certificate authority (CA - http://en.wikipedia.org/wiki/Certificate_authority) has to generate a certificate based on the public key of the peer. On Peerfuse-net, you'll need to create one key/certificate per user joining the network. On Peerfuse-lan, you'll need one for each computer.

To take care of their creation Peerfuse provides some scripts (loosely copied from the excellent OpenVPN project : http://www.openvpn.net), but you can use any PKI tool like TinyCA (http://tinyca.sm-zone.net/) to generate them.

3.1 CA generation

The first thing to do is to set up the PKI:

$ cd peerfuse/tools/pf-pki/

Edit the vars and the openssl.cnf configuration files to suit your needs. You can let them untouched, if you don't know their syntax, the default values are generally good. Next, you need to set the environment:

$ source vars

Clean the certificate generation folder, and generate the CA:

$ ./clean-all
$ ./build-ca

You will then be prompted about the data to be stored in the CA (those informations will be public). Once it's done, you'll find files created in the keys/ folder. The ca.key file is confidential and allows to generate certificate, the administrator of the network have to keep it secret from other people. The ca.crt is public and will allow other peer to check whether incoming connections have been signed be your ca.key file. You'll have to distribute the ca.crt file with the certificate you signs.

3.2 Generating a key and a certificate

As said before, you will have to generate a key and a certificate for each peer in the network. The key is the private part of the authentication/encryption mechanisms, it has to be kept secret from other people. The certificate (the public part) is signed by the CA and provides enough information to other peers to determine if they can trust it or not.

There are two ways to generate a certificate:

  • The first method is to generate the private key on the peer that will use it, then a certificate signing request (CSR) is sent to the CA that sends back a certificate. This method has the advantage of being really safe. The private key is only known by the peer that will use it.
  • With the second method, the key and the certificate are generated by the CA. They are then sent to the peer using you preferred means of communication. This has the advantage to be faster, but it is less safe as the key has to be moved...

3.2.1 Generating a key, a certificate request and a certificate

The peer generates a private key and a certificate request using those commands:

$ cd tools/pf-pki/
$ source vars
$ ./clean-all
$ ./build-req <peer_name>

When prompted for a password, leave it blank. Peerfuse don't handle passwords yet. In the keys/ folder you'll find a peer_name.key, this is the private of the user (to keep secret), and a peer_name.csr (can be public) that have to be sent to the CA.

On the CA, the certificate can be generated using the CSR:

$ cd tools/pf-pki/
$ source vars
$ cp /path/to/peer_name.csr keys/
$ ./sign-req <peer_name>

The keys/ folder of the CA will then contain a file peer_name.crt than can be sent back to the peer.

3.2.2 Generating a key and a certificate on the CA

Just start those commands:

$ cd tools/pf-pki/
$ source vars
$ ./build-key <peer_name>

The resulting key and certificate are also in the keys/ directory.

3.3 Managing a certificate revocation list

The certificate revocation list (CRL) is a list of revoked certificate generated be the CA, it is read by peers to tell whether they should connect to an other peer. For testing purpose the CRL can be disabled, but you won't be able to "ban" users with bad behaviour (on Peerfuse-net) or shutdown the access to compromised hosts (on Peerfuse-lan). CRls are only valid during a limited time for security reason, that's why you'll need to regenerate it frequently. As of Peerfuse 0.0, CRL are only refreshed at start by clients. You can modify the refresh rate of your CRL by modifying the default_crl_hours options of the openssl.cnf. This parameter have to be chosen carefully, any peer with an outdated CRL won't connect to an other peer.

In order to refresh the CRL frequently, you need a wrapper script to regenerate the CRL:

#!/bin/bash
cd /path/to/peerfuse/tools/pf-pki
source vars
./gen-crl

The resulting CRL is stored in keys/crl.pem. Since the CRL needs to be refreshed regularly, you should set up a cron job:

$ crontab -e
(man crontab, to get more informations on the syntax)
15 1 \* \* \* /path/to/the_wrapper_script.sh

Now make sure the crl.pem is available through a web server (distribution of the CRL through Peerfuse may be implemented later...).

  1. Configuration of the peer

Edit the pfnet.conf or pflan.conf file in the root folder of Peerfuse, to correct the various paths it contains. Create the folder pointed by the hdd/root and the hdd/workdir options.

You can now run Peerfuse using the commands described on the download section of the Peerfuse website : http://peerfuse.org/download.html .

  1. Revoking certificate

If you activated the CRL option, you can revoke the certificate of a peer that behaves badly. Other peers using the CRL won't accept connections from peers with a revoked certificate, and won't connect to them. If a peer is misconfigured (disabled the CRL check), it'll still accept peers with a revoked certificate and let them read and modify files. On Peerfuse-net, this point is particularly important, as each peer is configured by a different person. To ban someone from the network, the CA administrator of a Peerfuse-net network will have to revoke the certificate of a badly behaving person and the certificate of all peers that don't handle the CRL (if any). To revoke a certificate, on the CA, run:

$ cd tools/pf-pki/
$ source vars
$ ./revoke-full <peer_name>

The CRL is automatically refreshed to take into account the new revocation.


© 2008 Laurent Defert, Romain Bignon
Valid XHTML 1.1 and CSS.
Thanks to axestech.net for this website.