Skip to content

Commit

Permalink
Updated the "Using Docker for Job execution" documentation (google#1415)
Browse files Browse the repository at this point in the history
* Updated the "Using Docker for Job execution" documentation

The documentation article "Using Docker for Job execution" was updated so it reflects the code in `turbinia/turbinia/lib/docker_manager.py`.
  • Loading branch information
HelferDCSO authored and jleaniz committed Mar 18, 2024
1 parent a3e3b51 commit e8cf771
Showing 1 changed file with 12 additions and 11 deletions.
23 changes: 12 additions & 11 deletions docs/user/using-docker.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,34 +5,35 @@ Turbinia supports the use of Docker by allowing a Task to execute its command th

## Enabling Docker usage
In order to enable this feature, please take the following steps.
1. Install the Docker daemon on the Worker's host machine. Please visit the Docker website for the [Installation Guide](https://docs.docker.com/install/).
2. In the `.turbiniarc` configuration file, set the `DOCKER_ENABLED` flag to `True` to enable the usage of Docker.
3. Review the `DEPENDENCIES` flag in the `.turbiniarc` configuration file and identify which Job you would like to execute a Docker container for. Once identified, replace the value for `docker_image` with the `image_id` of the Docker image.
4. Save the `.turbiniarc` configuration file then restart all Workers for the changes to take into effect.
5. When the Workers start, they will perform dependency checks to ensure that the binaries required by the Job are installed in the Container, and if that check passes, it will execute those in the configured Docker Container.
6. If you no longer would like to use the Docker image, set the `docker_image` value back to `None`.
1. In the `turbinia.conf` configuration file, set the `DOCKER_ENABLED` flag to `True` to enable the usage of Docker.
2. Review the `DEPENDENCIES` flag in the `turbinia.conf` configuration file and identify which Job you would like to execute a Docker container for. Once identified, replace the value for `docker_image` with the name of the Docker image.
3. Save the `turbinia.conf` configuration file then restart all Workers for the changes to take into effect.
4. When the Workers start, they will perform dependency checks to ensure that the binaries required by the Job are installed in the Container, and if that check passes, it will execute those in the configured Docker Container.
5. If you no longer would like to use the Docker image, set the `docker_image` value back to `None`.

## Example using Plaso
The following section provides an example of the steps mentioned above for the Plaso Job by using the Docker CLI to retrieve the required information.
1. Retrieve the latest Plaso Docker image either locally or through a preconfigured registry containing the image.
* ` docker pull log2timeline/plaso`
2. Identify the `image_id` for the retrieved image.
2. Identify the name for the retrieved image.
* `docker image ls`

Then copy the value listed under the column `IMAGE ID`.
Then copy the value listed under the column `REPOSITORY`.
```
REPOSITORY TAG IMAGE ID CREATED SIZE
log2timeline/plaso latest 9c22665bff50 4 days ago 314MB
```
3. Open up the `.turbiniarc` configuration file then set the attribute `DOCKER_ENABLED` to `True`.
4. Identify the `DEPENDENCIES` attribute and look for the Job `PlasoJob`, then replace the `docker_image` value with the identified `IMAGE ID`.
3. Open up the `turbinia.conf` configuration file then set the attribute `DOCKER_ENABLED` to `True`.
4. Identify the `DEPENDENCIES` attribute and look for the Job `PlasoJob`, then replace the `docker_image` value with the identified `REPOSITORY`.
```python
{
'job': 'PlasoJob'
'programs': ['log2timeline.py'],
'docker_image': '9c22665bff50'
'docker_image': 'log2timeline/plaso'
}
```
> **Note:** You can also provide the docker image name with a tag to pin the programs used in jobs to a certain version. In the example above `log2timeline/plaso` can also be specified as `log2timeline/plaso:latest`. This way the tools can be updated and after that the tag is changed in the configuration file which eliminates the need for redeploying or re-installing anything.
5. Save the configuration file, then restart the turbinia Worker.
* `sudo systemctl restart turbinia@psqworker.service`
6. If the dependency check succeeds, once a Worker receives a Docker configured Task, the Task will execute its external command through the Docker Container instead and pass the associated data back to the Worker for further processing.

0 comments on commit e8cf771

Please sign in to comment.