From 0f6fb13923751e387c0d5c3befcc09896cd0c4b0 Mon Sep 17 00:00:00 2001
From: Susanne Westphal <swestphal@google.com>
Date: Mon, 17 Jun 2024 12:34:28 +0000
Subject: [PATCH] Add documentation for configuration files

---
 .../via-docker-compose.md                     | 32 +++++++++++++++++--
 installing-and-running-grr/via-docker.md      | 23 +++++++++++++
 2 files changed, 53 insertions(+), 2 deletions(-)

diff --git a/installing-and-running-grr/via-docker-compose.md b/installing-and-running-grr/via-docker-compose.md
index 777aeb3..ffa4747 100644
--- a/installing-and-running-grr/via-docker-compose.md
+++ b/installing-and-running-grr/via-docker-compose.md
@@ -1,5 +1,10 @@
 # Running GRR in a Docker Compose Stack (Recommended)
 
+- [Setup the ennviroment](#setup-the-environment)
+- [Run the GRR Docker Compose Stack](#run-the-grr-docker-compose-stack)
+- [Repacking Client Installers](#repacking-client-installers)
+- [Setting up your own MySQL database](#setting-up-your-own-mysql-database)
+
 Running GRR via Docker Compose will start every [GRR component](<overview.md>) in a separate Docker container. 
 All that is needed is install Docker, Docker Compose and git, then get the code, generate certificates and start the stack.
 Follow the instructions below!
@@ -90,6 +95,28 @@ The stack uses mounted volumes to persist state , to also delete these run:
 docker compose down --volumes
 ```
 
+### Configuring the stack
+
+See [configuration files](<../via-docker#configuration-files>) for general information.
+In the GRR Docker Compose Stack the default configuration with a minimal set of
+configuration options are mounted at `/configs/(server|client|testing)`, see the
+`compose.yaml` file for reference.
+
+After updating the configuration restart the components to apply the changes.
+
+To run any GRR binary that requires a configuration, e.g. the `grr_config_updater`
+binary, the config file need to be passed via a command line option.
+
+For example to show available users you can run:
+```bash
+# Start the stack.
+$ docker compose up --wait
+# Connect to the GRR admin ui container.
+$ docker exec -it grr-admin-ui /bin/bash
+# Run GRR config updater inside the container, set the `--config` option.
+$ root@admin-ui:/usr/src/grr# grr_config_updater --config /configs/server/grr.server.yaml show_user
+```
+
 ### Debugging
 
 - You can access the **logs** via:
@@ -118,11 +145,12 @@ docker compose down --volumes
   Username, password and DB name for the mysql database can also be found in
    `docker_config_files/mysql/.env`.
 
+
 ## Repacking Client Installers
 
-The client templates need to be repacked into installer to be installed on a
+The client templates need to be repacked into installers to be installed on a
 client. The repacking adds some configuration to the templates that is
-provided by the GRR server and needs to be available before startup.
+provided by the GRR server.
 
 In the Docker Compose stack, the templates are
 [repacked](https://github.com/google/grr/blob/master/docker_config_files/server/repack_clients.sh)
diff --git a/installing-and-running-grr/via-docker.md b/installing-and-running-grr/via-docker.md
index e11702e..2a9f2e4 100644
--- a/installing-and-running-grr/via-docker.md
+++ b/installing-and-running-grr/via-docker.md
@@ -18,6 +18,29 @@ Binaries to start the different GRR components, create new certificates, repack
 are included in the GRR Docker image.
 All available binaries are in the `$PATH` in the Docker container and can also be found
 inside the container in `/usr/share/grr-server/bin`.
+Most binaries require a [configuration file](#configuration-files), which can be set with the
+`-config / --config` command line argument. Also see examples in [How to use the image](#how-to-use-the-image).
+
+##### Configuration files
+
+GRR uses [GrrConfigManager](https://github.com/google/grr/blob/v3.4.7.2/grr/core/grr_response_core/lib/config_lib.py#L445)
+which is based on [configparser](https://docs.python.org/3/library/configparser.html) to configure GRR components and binaries.
+A basic configuration for [server](https://github.com/google/grr/blob/v3.4.7.4-release/docker_config_files/server/grr.server.yaml),
+[client](https://github.com/google/grr/blob/v3.4.7.4-release/docker_config_files/client/grr.client.yaml) and
+[e2e testing](https://github.com/google/grr/blob/v3.4.7.4-release/docker_config_files/testing/grr.testing.yaml) are provided.
+They can be mounted in the container:
+```bash
+$ docker run -it \
+    --entrypoint /bin/bash \  # open a shell
+    -v $(pwd)/docker_config_files:/configs \  # mount the docker_config_files folder to /configs
+    ghcr.io/google/grr:latest
+```
+Additional configuration options can be added, i.e. additional options for the server configuration can be found
+[here](https://github.com/google/grr/blob/v3.4.7.4-release/grr/core/grr_response_core/config/server.py) for the
+server or [here](https://github.com/google/grr/blob/v3.4.7.4-release/grr/core/grr_response_core/config/client.py)
+for the client.
+(We are working on a better documentation for the available config options.)
+
 
 ### Fleetspeak Docker Image