Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
Box Backup Certificates and Accounts Management
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, Box Backup includes a script to do most of the work in a way which is good enough for most deployments.
IMPORTANT NOTE: The certificate authority directory is intended to be stored on another server. It should not be kept on the backup server to limit the impact of a server compromise. The instructions and the script assume that it will be kept elsewhere, so will ask you to copy files to and from the CA.
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.
Setting Up the Certificate Authority
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 the following:
/usr/local/sbin/bbstored-certs ca init
(See OpenSSLNotes 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 the following:
/usr/local/sbin/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 the following:
/usr/local/sbin/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 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 the above example, the account is allocated 4Gb (assuming you use 2048 byte blocks as per the 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 the following command:
/usr/local/sbin/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 the following command:
/usr/local/sbin/bbstoreaccounts info 75AB23C
To adjust the soft and hard limits on an account, use the following:
/usr/local/sbin/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 the following command:
/usr/local/sbin/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 the following commands:
/usr/local/sbin/bbstoreaccounts check 75AB23C /usr/local/sbin/bbstoreaccounts check 75AB23C fix
The second command will fix any errors it finds, the first will merely report them.
Append quiet to reduce the amount of output, although errors are always reported.
See FixingCorruption for more information.