# Box Backup certificates and accounts

There are two steps involved to create an account. You need to create the account on the server, and sign a certificate to give the client permission to connect to the server.

Running a Certification Authority for TLS (SSL) connections is not trivial. However, I have written a script to do most of the work in a way which is good enough for most deployments.

## Warning about clock times

SSL certificates contain validity dates, including a "valid from" time. If the clock on the machine which signs the certificates is not syncronised to the clocks of the machines using these certificates, you will probably get strange errors until the start time is reached on all machines.

If you get strange errors when attempting to use new certificates, check the clocks! You will probably just need to wait a while until the certificates become valid, rather than having to regenerate them.

## Set up CA

It's best to do this on a machine other than your server, probably without direct network access. The contents of this directory control who can access your backup store server.

To setup the basic key structure, do

    /usr/local/bin/bbstored-certs ca init

(See OpenSSL notes if you get an OpenSSL error)

This creates the directory 'ca' in the current directory, and initialises it with basic keys.

## Sign a server certificate

When you use the `bbstored-config` script to set up a config file for a server, it will generate a certificate request (CSR) for you. Transfer it to the machine with your CA, then do

    /usr/local/bin/bbstored-certs ca sign-server hostname-csr.pem

which signs the certificate for the server. Follow the instructions in the output on which files to install on the server. The CSR file is now no longer needed. Make sure you run this command from the directory above the directory 'ca'.

## Setting up an account.

Choose an account number for the user. This must be unique on the server, and is presented as a 31 bit number in hex greater than 0, for example, 1 or 75AB23C. Then on the backup store server, create the account with

    /usr/local/bin/bbstoreaccounts create 75AB23C 0 4096M 4505M

This looks complicated. The numbers are, in order...

- The account number allocated (hex)
- The RAID disc set (0 if you use raidfile-config and don't add a new set)
- Soft limit (size)
- Hard limit (size)

The sizes are are specified in Mb, Gb, or blocks, depending on the suffix. `1M` specifies 1 Mb, `1G` specifies 1 Gb, and `1B` specifies 1 block, the size of which depends on how you have configured the raidfile system with `raidfile-config`.

In this example, I have allocated 4Gb (assuming you use 2048 byte blocks as per my example) as the soft limit, and 4Gb + 10% as the hard limit.

NOTE The sizes specified here are pre-RAID. So if you are using userland RAID, you are actually allocating two-thirds of this amount. This means that, when you take compression into account, that if you allocate 2Gb on the server, it'll probably hold about 2Gb of backed up files (depending on the compressability of those files).

The backup client will (voluntarily) try not to upload more data than is allowed by the soft limit. The store server will refuse to accept a file if it would take it over the hard limit, and when doing housekeeping for this account, try and delete old versions and deleted files to reduce the space taken to below the soft limit.

This command will create some files on disc in the raid file directories (if you run as root, the utility will change to the user specified in the bbstored.conf file to write them) and update the accounts file. A server restart is not required.

NOTE If you get a message saying '`Exception: RaidFile (2/8)`', the directories you specified in the raidfile.conf are not writable by the _bbstored user -- fix it, and try again.

Finally, tell the user their account number, and the hostname of your server. They will use this to set up the backup client, and send you a CSR. This has the account number embedded in it, and you should be sure that it has the right account number in it.

Sign this CSR with

    /usr/local/bin/bbstored-certs ca sign 75AB23C-csr.pem

Don't forget to check that the embedded account number is correct! Then send the two files back to the user, as instructed by the script.

Please read the Troubleshooting page if you have problems.

## Finding disc space used, and changing limits.

To display the space used on the server for an account, use

      /usr/local/bin/bbstoreaccounts info 75AB23C

To adjust the soft and hard limits on an account, use

      /usr/local/bin/bbstoreaccounts setlimit 75AB23C new-soft-limit new-hard-limit

You do not need to restart the server if the limits are changed.

## Deleting an account

To remove an account, deleting all the stored files on the server and removing the account information which allows a client to log in, use

      /usr/local/bin/bbstoreaccounts delete 75AB23C

This will ask for confirmation. Append `yes` to the command to delete without confirmation.

## Verifying a store account

To check that a store account is not corrupt, and optionally fix any errors, use

      /usr/local/bin/bbstoreaccounts check 75AB23C
      /usr/local/bin/bbstoreaccounts check 75AB23C fix

The second command will fix errors it finds, the first will merely report them.

Append `quiet` to reduce the amount of output, although errors are always reported.

See fixing problems with corruption on the server for more information.

© Ben Summers, 2003, 2004