Note: This installation method will be deprecated by the end of 2022. The current recommended method for installing Turbinia is here.
Turbinia Quick Installation Instructions
Overview
Turbinia can be run on the Google Cloud Platform, on local machines, or in a hybrid mode. See the “how it works” documentation for more details on what the architecture looks like for each of these installation types. This doc covers the recommended quick installation instructions for Cloud installations. This uses terraform configs that are part of the Forseti Security repository to automate deployment of Turbinia into an existing GCP Project. for details.
Installation
The following steps can be performed on any Linux machine (Ubuntu 18.0.4 recommended), and Cloud Shell is one easy way to get a shell with access to your GCP resources.
GCP Project Setup
Create or select a Google Cloud Platform project in the Google Cloud Console.
Determine which GCP zone and region that you wish to deploy Turbinia into. Note that one of the GCP dependencies is Cloud Functions, and that only works in certain regions, so you will need to deploy in one of the supported regions.
Install google-cloud-sdk.
Note: If you are doing this from cloud shell you shouldn’t need this step.
Run
gcloud auth login
to authenticate. This may require you to copy/paste url to browser.Run
gcloud auth application-default login
Deploy Turbinia
Download the Terraform CLI from here.
Clone the Forseti Security repository and change to the path containing the configs
git clone https://github.com/forseti-security/osdfir-infrastructure/
cd osdfir-infrastructure
Configuration
By default this will create one Turbinia server instance and one worker instance. If you want to change the number of workers, edit the
modules/turbinia/variables.tf
file and set theturbinia_worker_count
variable to the number of workers you want to deploy.To adjust the GCP zone and region you want to run Turbinia in, edit the
modules/turbinia/variables.tf
file and change thegcp_zone
andgcp_region
variables as appropriate to reflect your GCP project’s zone and region.If you want to use docker to run Turbinia tasks, please follow the instructions here to enable docker.
Running the following commands will leave some state information under the current directory, so if you wish to continue to manage the number of workers via Terraform you should keep this directory for later use. Alternatively, if you wish to store this information in GCS instead, you can edit
main.tf
and change thebucket
parameter to the GCS bucket you wish to keep this state information in. See the Terraform documentation for more information.The current configuration does not enable alert notifications by default. Please see here for the instructions
If you are running multiple workers on a given host and within containers, ensure that you are mapping the host
OUTPUT_DIR
path specified in the configuration file.turbiniarc
to the containers so that they can properly update theRESOURCE_STATE_FILE
.
Initialize terraform and apply the configuration
./deploy.sh --no-timesketch
If the
--no-timesketch
parameter is not supplied, Terraform will also create a Timesketch instance in the same project, and this can be configured to ingest Turbinia timeline output and report data. See the Documentation on this for more details.When prompted for the project name, enter the project you selected during setup.
This should result in the appropriate cloud services being enabled and
configured and GCE instances for the server and the worker(s) being started and
configured. The Turbinia configuration file will be deployed on these instances
as etc/turbinia/turbinia.conf
. If you later want to increase the number of
workers, you can edit the turbinia/variables.tf
file mentioned above and
re-run terraform apply
To use Turbinia you can use the virtual environment that was setup by
the deploy.sh
script.To activate the virtual environment, run the following
command source ~/turbinia/bin/activate
and then use turbiniactl
. For more
information on how to use Turbinia please visit the user manual.
Client configuration (optional)
If you want to use the command line tool, you can SSH into the server and run
turbiniactl
from there. The turbiniactl
command can be used to submit
Evidence for processing or see the status of existing and previous processing
requests. If you’d prefer to use turbiniactl on a different machine, follow the
following instructions to configure the client. The instructions are based on
using Ubuntu 18.04, though other versions of Linux should be compatible.
Follow the steps from GCP Project setup above to install the SDK and authenticate with gcloud.
Install some python tooling:
apt-get install python3-pip python3-wheel
Install the Turbinia client.
If running on the same machine you deployed Turbinia from, you can generate the config with terraform
terraform output turbinia-config > ~/.turbiniarc
Otherwise, if you are running from a different machine you’ll need to copy the Turbinia config from the original machine, or from the Turbinia server from
/etc/turbinia/turbinia.conf
.
Grafana SMTP Setup
If you want to receive alert notifications from Grafana, you’ll need to setup a SMTP server for Grafana. To configure a SMTP server, you need to add the following environment variables to Grafana
env
section in osdfir-infrastructure/modules/monitoring/main.tf
{
name = "GF_SMTP_ENABLED"
value = "true"
}, {
name = "GF_SMTP_HOST"
value = "smtp.gmail.com:465" # Replace this if you're not using gmail
}, {
name = "GF_SMTP_USER"
value = "<EMAIL ADDRESS HERE>"
}, {
name = "GF_SMTP_PASSWORD"
value = "<PASSWORD>"
}, {
name = "GF_SMTP_SKIP_VERIFY"
value = "true"
}, {
name = "GF_SMTP_FROM_ADDRESS"
value = "<EMAIL ADDRESS THAT SHOWS AS THE SENDER>"
}
NOTE
By default Gmail does not allow less secure apps to authenticate and send emails. For that reason, you’ll need to allow less secure apps to access the provided Gmail account.
Once completed:
login to the Grafana Dashboard.
Select Alerting and choose “Notification channels”.
Fill the required fields and add the email addresses that will receive notification.
Click “Test” to test your SMTP setup.
Once everything is working, click “Save” to save the notification channel.