diff --git a/README.md b/README.md index aa8f69e..64b00ce 100644 --- a/README.md +++ b/README.md @@ -7,3 +7,123 @@ This repository contains code which implements the Gravwell Cloud Archive server * `usertool` is a utility for managing a password database as used by the Cloud Archive server. * `configtool` is a small utility which attempts to generate a `gravwell.conf` for a set of archived shards. * `pkg` contains packages used by the Cloud Archive system. + +## Running a Cloud Archive server + +Until the Cloud Archive server is packaged officially, you can set it up manually. Make sure you have [Go](https://golang.org) installed, to build the programs. + +Before running the server, you'll need to set up the password database and the config file. For simplicity, we'll assume all cloud archive information will be kept in `/opt/cloudarchive`. + +### Initializing the Password Database + +Use the `usertool` command to set up the password database with an entry for your customer number: + +``` +cd usertool +go build +./usertool -action useradd -id -passfile /opt/cloudarchive/cloud.passwd +``` + +The tool will prompt for the passphrase to use for the specified customer number. + +Note: You can find your customer number on the License page of the Gravwell UI. + +### Configuration + +The following config file will make the server archive incoming data to `/opt/cloudarchive/storage`. It listens for clients on port 8886, using the specified TLS cert/key pair for encryption. The `Password-File` parameter points at the password database set up earlier. + +``` +[Global] +Listen-Address="0.0.0.0:8886" +Cert-File=/opt/cloudarchive/cert.pem +Key-File=/opt/cloudarchive/key.pem +Password-File=/opt/cloudarchive/cloud.passwd +Log-Level=INFO +Backend-Type=file +Storage-Directory=/opt/cloudarchive/storage +``` + +The following config archives incoming data shards to an FTP server instead of the local disk. Note the specification of the FTP-Server; the FTP-Username and FTP-Password fields should be for a valid account on that FTP server. + +``` +[Global] +Listen-Address="0.0.0.0:8886" +Cert-File=/opt/cloudarchive/cert.pem +Key-File=/opt/cloudarchive/key.pem +Password-File=/opt/cloudarchive/cloud.passwd +Log-Level=INFO +Backend-Type=ftp +Storage-Directory=/opt/cloudarchive/storage +FTP-Server=ftp.example.org:21 +FTP-Username=cloudarchiveuser +FTP-Password=ca_secret_password +``` + +### Build and install the binary + +Install the server binary into `/opt/cloudarchive`: + +``` +cd server +go build +cp server /opt/cloudarchive +``` + +### Create user / set ownership + +For security reasons, we'll create a system user to run the Cloud Archive service and give it ownership of `/opt/cloudarchive`: + +``` +adduser -S -h /opt/cloudarchive -H -D -g "Cloud Archive Daemon User" -G cloudarchive cloudarchive +chown -R cloudarchive:cloudarchive /opt/cloudarchive +``` + +### Run the server + +Now that everything is set up, we create a service file in `/etc/systemd/system/cloudarchive.service`: + + +``` +[Unit] +Description=Gravwell Cloud Archive Service +After=network-online.target + +[Service] +Type=simple +ExecStart=/opt/cloudarchive/server -config-file /opt/cloudarchive/server.conf +WorkingDirectory=/opt/cloudarchive +Restart=always +User=cloudarchive +Group=cloudarchive +StandardOutput=journal +StandardError=journal +LimitNPROC=infinity +LimitNOFILE=infinity +PIDFile=/var/run/gravwell_cloudarchive.pid +TimeoutStopSec=5 +KillMode=process +KillSignal=SIGINT +``` + +Then we enable & run it: + +``` +systemctl enable cloudarchive.service +systemctl start cloudarchive.service +``` + +### Configure Gravwell + +To make Gravwell send archived shards to the Cloud Archive server, add a `Cloud-Archive` stanza to `gravwell.conf`: + +``` +[Cloud-Archive] + Archive-Server=cloudarchive.example.org + Archive-Shared-Secret="mypassword" +``` + +(The `Archive-Shared-Secret` field should match the password you set for your customer number in the password database) + +Shards will not be archived unless the well has the `Archive-Deleted-Shards=true` and `Delete-Frozen-Data=true` parameters set. + +Refer to the [documentation for Cloud Archive](https://docs.gravwell.io/configuration/archive.html) for more information. \ No newline at end of file