From 1c1c8b80d3de6005e4a4146570151742bad17ae1 Mon Sep 17 00:00:00 2001 From: Jack Harper Date: Mon, 1 Sep 2025 13:12:43 +0100 Subject: [PATCH 1/4] add docs on using keeper for ssh key management --- doc/tools/SSH-keys.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/doc/tools/SSH-keys.md b/doc/tools/SSH-keys.md index 9693516d0..e8862946c 100644 --- a/doc/tools/SSH-keys.md +++ b/doc/tools/SSH-keys.md @@ -30,7 +30,20 @@ example, by being copied onto instruments). Do not share your **private** key. T is additionally encrypted using your selected password. ::: -## Setting up SSH agent +{#keeper_ssh} +## Keeper + +To avoid having to copy and paste your passphrase every time, you can use [Keeper](https://ukri.sharepoint.com/sites/thesource/SitePages/Keeper-Password-Manager.aspx) to store your passwords. + +If you want to use Keeper (you'll need the desktop client for this, _not_ the browser plugin) for storing your SSH keys, and not have local plaintext copies on your machine, you can do so. + +This is done by adding your newly-generated key to keeper (with the `SSH key` record type) with your public key, private key and passphrase filled in. + +In `Settings -> Developer`, enable the "SSH Agent" which will add your keys, without needing to enter the passphrases, when the keeper vault is unlocked. + +Ignore the section below as you don't need to manually set up an SSH agent. + +## Manually Setting up SSH agent In a powershell window, run the following commands: ```powershell @@ -59,7 +72,7 @@ To connect via SSH to an instrument, use: ssh spudulike@NDXINST ``` -This will prompt you on each connection for the passphrase to unlock your SSH key, this is the +(If you aren't [using Keeper](#keeper_ssh)) This will prompt you on each connection for the passphrase to unlock your SSH key, this is the password you set earlier for your personal SSH key. You will not be prompted for an account password; your key is sufficient to grant you access. @@ -72,7 +85,7 @@ run a command as a privileged user. ::: Typing the password to unlock your SSH key for each instrument would be tedious. -To avoid this, we can **temporarily** add the key to the SSH agent: +To avoid this, we can either [use Keeper](#keeper_ssh), or **temporarily** add the key to the SSH agent: ``` ssh-add From 01c97ac0ef70531fc75f1834b8d43e27aa56389b Mon Sep 17 00:00:00 2001 From: Jack Harper Date: Mon, 1 Sep 2025 13:38:33 +0100 Subject: [PATCH 2/4] more --- doc/tools/SSH-keys.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/doc/tools/SSH-keys.md b/doc/tools/SSH-keys.md index e8862946c..db5371ee6 100644 --- a/doc/tools/SSH-keys.md +++ b/doc/tools/SSH-keys.md @@ -37,11 +37,21 @@ To avoid having to copy and paste your passphrase every time, you can use [Keepe If you want to use Keeper (you'll need the desktop client for this, _not_ the browser plugin) for storing your SSH keys, and not have local plaintext copies on your machine, you can do so. -This is done by adding your newly-generated key to keeper (with the `SSH key` record type) with your public key, private key and passphrase filled in. +This is done by following [this guide](https://docs.keeper.io/en/keeperpam/privileged-access-manager/ssh-agent#activating-the-ssh-agent) with your public key, private key and passphrase filled in. In `Settings -> Developer`, enable the "SSH Agent" which will add your keys, without needing to enter the passphrases, when the keeper vault is unlocked. -Ignore the section below as you don't need to manually set up an SSH agent. +Ignore the section below as you don't need to manually set up an SSH agent. + +You may need to [turn the `OpenSSH` agent off](https://docs.keeper.io/en/keeperpam/privileged-access-manager/ssh-agent#windows-note-on-ssh-agent-conflicts) if it's on your machine - see if `ssh-agent` is running in your services in task manager. + +### Troubleshooting + +#### SSH works and prompts to use passphrase, but git doesn't show the prompt + If `ssh git@github.com` works fine, your SSH key has been added to Github, so that's a good start. + +You may need to set the `GIT_SSH` environment variable to wherever your git installation is as git might try and use its own ssh executable which doesn't seem to work with Keeper. `where ssh` will tell you where this is. + ## Manually Setting up SSH agent From 427adb922a82430601951134ee86ac4697004cb4 Mon Sep 17 00:00:00 2001 From: Jack Harper Date: Mon, 1 Sep 2025 13:47:11 +0100 Subject: [PATCH 3/4] add admonition for using keeper when setting up manual ssh agent --- doc/tools/SSH-keys.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/doc/tools/SSH-keys.md b/doc/tools/SSH-keys.md index db5371ee6..c9958e281 100644 --- a/doc/tools/SSH-keys.md +++ b/doc/tools/SSH-keys.md @@ -39,22 +39,20 @@ If you want to use Keeper (you'll need the desktop client for this, _not_ the br This is done by following [this guide](https://docs.keeper.io/en/keeperpam/privileged-access-manager/ssh-agent#activating-the-ssh-agent) with your public key, private key and passphrase filled in. -In `Settings -> Developer`, enable the "SSH Agent" which will add your keys, without needing to enter the passphrases, when the keeper vault is unlocked. - -Ignore the section below as you don't need to manually set up an SSH agent. - You may need to [turn the `OpenSSH` agent off](https://docs.keeper.io/en/keeperpam/privileged-access-manager/ssh-agent#windows-note-on-ssh-agent-conflicts) if it's on your machine - see if `ssh-agent` is running in your services in task manager. -### Troubleshooting - -#### SSH works and prompts to use passphrase, but git doesn't show the prompt - If `ssh git@github.com` works fine, your SSH key has been added to Github, so that's a good start. - -You may need to set the `GIT_SSH` environment variable to wherever your git installation is as git might try and use its own ssh executable which doesn't seem to work with Keeper. `where ssh` will tell you where this is. +### SSH works and prompts to use passphrase, but git doesn't show the prompt + If `ssh git@github.com` works fine, your SSH key has been added to Github and `ssh` is using it. +You may need to set the `GIT_SSH` environment variable to wherever your ssh executable is, as git might try and use its own ssh executable which doesn't seem to work with Keeper. `where ssh` will tell you where this is. +{#manual_ssh_agent} ## Manually Setting up SSH agent +```{note} +Ignore this section if you followed {ref}`the section on setting up keeper as your ssh agent`. +``` + In a powershell window, run the following commands: ```powershell Get-Service ssh-agent | Set-Service -StartupType Automatic From 8a434fe2ccf6b5104239eac771bf5e6910da7138 Mon Sep 17 00:00:00 2001 From: Jack Harper Date: Mon, 1 Sep 2025 13:52:14 +0100 Subject: [PATCH 4/4] review comments --- doc/tools/SSH-keys.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/tools/SSH-keys.md b/doc/tools/SSH-keys.md index c9958e281..2987fc09c 100644 --- a/doc/tools/SSH-keys.md +++ b/doc/tools/SSH-keys.md @@ -33,14 +33,16 @@ is additionally encrypted using your selected password. {#keeper_ssh} ## Keeper -To avoid having to copy and paste your passphrase every time, you can use [Keeper](https://ukri.sharepoint.com/sites/thesource/SitePages/Keeper-Password-Manager.aspx) to store your passwords. +To avoid having to copy and paste your passphrase every time, you can use [Keeper](https://ukri.sharepoint.com/sites/thesource/SitePages/Keeper-Password-Manager.aspx) to store your passwords and SSH keys. -If you want to use Keeper (you'll need the desktop client for this, _not_ the browser plugin) for storing your SSH keys, and not have local plaintext copies on your machine, you can do so. +If you want to use Keeper (you'll need the desktop client for this, _not_ the browser plugin) for storing your SSH keys, and not have local plain text copies on your machine, you can do so. This is done by following [this guide](https://docs.keeper.io/en/keeperpam/privileged-access-manager/ssh-agent#activating-the-ssh-agent) with your public key, private key and passphrase filled in. You may need to [turn the `OpenSSH` agent off](https://docs.keeper.io/en/keeperpam/privileged-access-manager/ssh-agent#windows-note-on-ssh-agent-conflicts) if it's on your machine - see if `ssh-agent` is running in your services in task manager. +It would also be a good idea to change the vault timeout to something relatively short to minimise scope of access for when the SSH keys are available. + ### SSH works and prompts to use passphrase, but git doesn't show the prompt If `ssh git@github.com` works fine, your SSH key has been added to Github and `ssh` is using it.