From a7ecdc8874fc39e6af9b8eccbbe68126c965e7c7 Mon Sep 17 00:00:00 2001 From: Didi Hoffmann Date: Mon, 27 Apr 2026 16:14:22 +0200 Subject: [PATCH 1/3] Adds the documenation for ssh keys --- content/en/docs/cluster/ssh-keys.md | 118 ++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 content/en/docs/cluster/ssh-keys.md diff --git a/content/en/docs/cluster/ssh-keys.md b/content/en/docs/cluster/ssh-keys.md new file mode 100644 index 0000000..1676957 --- /dev/null +++ b/content/en/docs/cluster/ssh-keys.md @@ -0,0 +1,118 @@ +--- +title: "SSH Keys" +description: "Configure user supplied SSH keys for private repository measurements" +date: 2026-04-27T00:00:00+00:00 +weight: 1006 +--- + +GMT can use SSH keys submitted by users through the Dashboard or the command line when measuring private Git repositories in a cluster setup. + +There are two different key types involved, and they are used on different machines: + +- The GMT web/API server uses an RSA PEM public key configured in `config.yml` to encrypt user supplied SSH keys before storing them. +- Each runner or cluster machine that executes measurements uses the matching RSA PEM private key configured in `config.yml` to decrypt the stored SSH key before cloning a repository. +- The user submits an OpenSSH private key through the Dashboard or command line. This is the key used by Git, through ssh, when cloning the measured repository. + +We do this so that when the GMT Web machine or the database is leaked we do not expose any SSH keys. + +Do not mix these formats. The encryption keys configured in `config.yml` must be RSA PEM files. The user supplied SSH key submitted through the Dashboard or passed on the command line must be an OpenSSH private key block. + +## Configure the web server to accept SSH keys from users + +On the GMT web/API server, configure an RSA PEM-format public key in `config.yml`: + +```yml +security: + encryption_public_key_file: ./.rsa/public_key.pem +``` + +Create the RSA key pair with: + +```bash +# Generate private key (2048-bit) +openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048 + +# Extract public key +openssl rsa -pubout -in private_key.pem -out public_key.pem +``` + +Recommended placement on the web/API server: + +```bash +mkdir -p ./.rsa +mv public_key.pem ./.rsa/public_key.pem +chmod 755 ./.rsa/public_key.pem +``` + +The file must be readable by the GMT API process. In the default container setup the Gunicorn container runs as root, and a restrictive mode such as `400` can make the mounted file unreadable inside the container. Use `755` for the public key file. + +## Configure runners to use submitted SSH keys + +On each runner that needs to execute jobs with user supplied SSH keys, configure the matching RSA PEM-format private key in `config.yml`: + +```yml +security: + encryption_private_key_file: ./.rsa/private_key.pem +``` + +The private key must match the public key configured as `security.encryption_public_key_file` on the GMT web/API server. Keep this private key available only to runner or cluster machines that execute measurements and to administrators who need runner access. + +## Allow users to save SSH keys + +To submit an SSH key through the Dashboard, the user must be allowed to update the `ssh_private_key` setting. This is controlled through the user's `capabilities` JSON: + +```json +{ + "user": { + "updateable_settings": [ + "ssh_private_key" + ] + } +} +``` + +The Dashboard also needs access to the settings API routes: + +```json +{ + "api": { + "routes": [ + "/v1/user/setting", + "/v1/user/settings" + ] + } +} +``` + +The default seeded user includes this capability. For existing or restricted users, add `ssh_private_key` to `user.updateable_settings`; otherwise the Dashboard will reject the setting update. + +## Submit a user SSH key through the Dashboard + +Users can add their repository SSH key in the Dashboard under: + +```text +/settings.html +``` + +Paste an OpenSSH private key block into the SSH private key setting. This key is used by the runner for Git clone operations. + +The Dashboard key should look like: + +```text +-----BEGIN OPENSSH PRIVATE KEY----- +... +-----END OPENSSH PRIVATE KEY----- +``` + +After saving the setting, new measurements for private Git repositories can use the stored SSH key. + +## Use an SSH key from the command line + +When running a measurement directly with `runner.py`, pass the OpenSSH private key file with `--ssh-private-key`: + +```bash +python3 runner.py \ + --uri git@github.com:example/private-repository.git \ + --filename usage_scenario.yml \ + --ssh-private-key ~/.ssh/id_ed25519 +``` From 7146c61466bdf1f7b1634138615914cf9646b3cb Mon Sep 17 00:00:00 2001 From: Didi Hoffmann Date: Tue, 12 May 2026 09:04:57 +0200 Subject: [PATCH 2/3] Arne Feedback --- .../{ssh-keys.md => private-repositories.md} | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) rename content/en/docs/cluster/{ssh-keys.md => private-repositories.md} (79%) diff --git a/content/en/docs/cluster/ssh-keys.md b/content/en/docs/cluster/private-repositories.md similarity index 79% rename from content/en/docs/cluster/ssh-keys.md rename to content/en/docs/cluster/private-repositories.md index 1676957..f7b442c 100644 --- a/content/en/docs/cluster/ssh-keys.md +++ b/content/en/docs/cluster/private-repositories.md @@ -1,5 +1,5 @@ --- -title: "SSH Keys" +title: "Private repositories" description: "Configure user supplied SSH keys for private repository measurements" date: 2026-04-27T00:00:00+00:00 weight: 1006 @@ -9,21 +9,21 @@ GMT can use SSH keys submitted by users through the Dashboard or the command lin There are two different key types involved, and they are used on different machines: -- The GMT web/API server uses an RSA PEM public key configured in `config.yml` to encrypt user supplied SSH keys before storing them. +- The GMT Dashboard server uses an RSA PEM public key configured in `config.yml` to encrypt user supplied SSH keys before storing them. - Each runner or cluster machine that executes measurements uses the matching RSA PEM private key configured in `config.yml` to decrypt the stored SSH key before cloning a repository. - The user submits an OpenSSH private key through the Dashboard or command line. This is the key used by Git, through ssh, when cloning the measured repository. -We do this so that when the GMT Web machine or the database is leaked we do not expose any SSH keys. +We do this so that when the Dashboard machine or the database is leaked we do not expose any SSH keys. Do not mix these formats. The encryption keys configured in `config.yml` must be RSA PEM files. The user supplied SSH key submitted through the Dashboard or passed on the command line must be an OpenSSH private key block. ## Configure the web server to accept SSH keys from users -On the GMT web/API server, configure an RSA PEM-format public key in `config.yml`: +On the GMT Dashboard server, configure an RSA PEM-format public key in `config.yml`: ```yml security: - encryption_public_key_file: ./.rsa/public_key.pem + encryption_public_key_file: /var/www/rsa/public_key.pem ``` Create the RSA key pair with: @@ -36,12 +36,12 @@ openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:204 openssl rsa -pubout -in private_key.pem -out public_key.pem ``` -Recommended placement on the web/API server: +Recommended placement on the Dashboard server: ```bash -mkdir -p ./.rsa -mv public_key.pem ./.rsa/public_key.pem -chmod 755 ./.rsa/public_key.pem +mkdir -p /var/www/rsa +mv public_key.pem /var/www/rsa/public_key.pem +chmod 755 /var/www/rsa/public_key.pem ``` The file must be readable by the GMT API process. In the default container setup the Gunicorn container runs as root, and a restrictive mode such as `400` can make the mounted file unreadable inside the container. Use `755` for the public key file. @@ -52,10 +52,10 @@ On each runner that needs to execute jobs with user supplied SSH keys, configure ```yml security: - encryption_private_key_file: ./.rsa/private_key.pem + encryption_private_key_file: /path/to/repo/rsa/private_key.pem ``` -The private key must match the public key configured as `security.encryption_public_key_file` on the GMT web/API server. Keep this private key available only to runner or cluster machines that execute measurements and to administrators who need runner access. +The private key must match the public key configured as `security.encryption_public_key_file` on the GMT Dashboard server. Keep this private key available only to runner or cluster machines that execute measurements and to administrators who need runner access. ## Allow users to save SSH keys From 9ebcf9c7d8472d7054fe8ee879204e8ce1e5b28c Mon Sep 17 00:00:00 2001 From: Didi Hoffmann Date: Wed, 13 May 2026 10:16:32 +0200 Subject: [PATCH 3/3] new path --- content/en/docs/cluster/private-repositories.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/docs/cluster/private-repositories.md b/content/en/docs/cluster/private-repositories.md index f7b442c..8b465eb 100644 --- a/content/en/docs/cluster/private-repositories.md +++ b/content/en/docs/cluster/private-repositories.md @@ -23,7 +23,7 @@ On the GMT Dashboard server, configure an RSA PEM-format public key in `config.y ```yml security: - encryption_public_key_file: /var/www/rsa/public_key.pem + encryption_public_key_file: /var/www/green-metrics-tool/.rsa/public_key.pem ``` Create the RSA key pair with: @@ -39,9 +39,9 @@ openssl rsa -pubout -in private_key.pem -out public_key.pem Recommended placement on the Dashboard server: ```bash -mkdir -p /var/www/rsa -mv public_key.pem /var/www/rsa/public_key.pem -chmod 755 /var/www/rsa/public_key.pem +mkdir -p /var/www/green-metrics-tool/.rsa/ +mv public_key.pem /var/www/green-metrics-tool/.rsa/public_key.pem +chmod 755 /var/www/green-metrics-tool/.rsa/public_key.pem ``` The file must be readable by the GMT API process. In the default container setup the Gunicorn container runs as root, and a restrictive mode such as `400` can make the mounted file unreadable inside the container. Use `755` for the public key file.