|
1 | | -=============== |
2 | | -Tips and Tricks |
3 | | -=============== |
4 | | - |
5 | | -Creating URL Overrides to Open a Connection |
6 | | -=========================================== |
7 | | - |
8 | | -Having lots of SSH keys loaded in KeeAgent can be a problem for many servers. |
9 | | -To work around this, many ssh programs allow you to specify an identity file when |
10 | | -connecting so that it knows which key to use instead of having to try all the |
11 | | -keys that are loaded. |
12 | | - |
13 | | -Since SSH keys in KeeAgent are usually saved as attachments embedded in the |
14 | | -database, there is an option in the *Entry Settings* to save the key to an actual |
15 | | -file on disk when the key is loaded in KeeAgent. |
16 | | - |
17 | | -.. figure:: images/win10-keepass-entry-keeagent-tab-private-key-file-location.png |
18 | | - :alt: Screenshot of Private Key File Location with "Save attachments to |
19 | | - temporary file when key is loaded" checked |
20 | | - |
21 | | -Once you have selected this option, there will be two placeholders available for |
22 | | -use in KeePass. |
23 | | - |
24 | | -- ``{KEEAGENT:KEYFILEPATH}`` returns the full path. e.g. ``C:\path\to\keyfile.ppk`` |
25 | | -- ``{KEEAGENT:IDENTFILEOPT}`` returns the identity file command line option |
26 | | - that is used by both PuTTY.exe and ssh. e.g. ``-i "C:\path\to\keyfile.ppk"`` |
27 | | - |
28 | | -You can use these placeholders to create URL overrides. Global overrides are at |
29 | | -*Tools > Options > Integration (tab) > URL Scheme Overrides...* or they can be |
30 | | -specified per-entry on the *Properties* tab of *Entry Settings*. |
31 | | - |
32 | | -.. note:: The placeholders also work with the *External File* location in |
33 | | - addition to attachments. |
34 | | - |
35 | | -Example: |
36 | | - |
37 | | - Open an ssh connection using PuTTY with the username and host specified in |
38 | | - the database entry. The entry must have the Username and URL fields filled |
39 | | - out for this to work. |
40 | | - :: |
41 | | - |
42 | | - cmd://"C:\Program Files (x86)\PuTTY\PuTTY.exe" -ssh {USERNAME}@{URL:RMVSCM} {KEEAGENT:IDENTFILEOPT} |
43 | | - |
44 | | -.. tip:: Read more about the PuTTY command line `here`__. For example, the |
45 | | - ``-load`` option is useful to load a saved session associated with the key. |
46 | | - |
47 | | -.. __: http://the.earth.li/~sgtatham/putty/latest/htmldoc/Chapter3.html#using-cmdline |
48 | | - |
49 | | - |
50 | | -Using KeeAgent on Windows |
51 | | -========================= |
52 | | - |
53 | | - |
54 | | -Client mode with Pageant |
55 | | ------------------------- |
56 | | - |
57 | | -KeeAgent (in Agent Mode) is designed to work much like ``ssh-agent`` on Linux/BSD/etc... |
58 | | -Pageant is very similar, but there are some notable differences. Because of the |
59 | | -more limited features of Pageant, it is recommended to run in Agent mode on |
60 | | -Windows instead of using Pageant. However, if you have a good reason to run |
61 | | -KeeAgent in Client Mode along with Pageant, here are some things to be aware of: |
62 | | - |
63 | | -- Pageant does not support locking. |
64 | | -- Pageant does not support constraints. |
65 | | -- Pageant does not support ECDSA or Ed25519 keys (except in the development version). |
66 | | - |
67 | | - |
68 | | -Cygwin and MSYS |
69 | | ---------------- |
70 | | - |
71 | | -KeeAgent can natively communicate with ssh programs running in Cygwin and |
72 | | -MSYS. It is enabled in the :ref:`global-options` dialog. |
73 | | - |
74 | | -There are two implementations of sockets that are found in the various versions |
75 | | -of Cygwin and MSYS. MSYS is really just a fork of Cygwin, so it depends on which |
76 | | -fork the code is based on. So, unless you are using msysGit, try the "Cygwin |
77 | | -socket file" first and if that does not work, try the "msysGit socket file". |
78 | | -In some cases, you may need both enabled to support multiple versions of |
79 | | -Cygwin/MSYS. |
| 1 | +=============== |
| 2 | +Tips and Tricks |
| 3 | +=============== |
| 4 | + |
| 5 | +Creating URL Overrides to Open a Connection |
| 6 | +=========================================== |
| 7 | + |
| 8 | +Having lots of SSH keys loaded in KeeAgent can be a problem for many servers. |
| 9 | +To work around this, many ssh programs allow you to specify an identity file when |
| 10 | +connecting so that it knows which key to use instead of having to try all the |
| 11 | +keys that are loaded. |
| 12 | + |
| 13 | +Since SSH keys in KeeAgent are usually saved as attachments embedded in the |
| 14 | +database, there is an option in the *Entry Settings* to save the key to an actual |
| 15 | +file on disk when the key is loaded in KeeAgent. |
| 16 | + |
| 17 | +.. figure:: images/win10-keepass-entry-keeagent-tab-private-key-file-location.png |
| 18 | + :alt: Screenshot of Private Key File Location with "Save attachments to |
| 19 | + temporary file when key is loaded" checked |
| 20 | + |
| 21 | +Once you have selected this option, there will be two placeholders available for |
| 22 | +use in KeePass. |
| 23 | + |
| 24 | +- ``{KEEAGENT:KEYFILEPATH}`` returns the full path. e.g. ``C:\path\to\keyfile.ppk`` |
| 25 | +- ``{KEEAGENT:IDENTFILEOPT}`` returns the identity file command line option |
| 26 | + that is used by both PuTTY.exe and ssh. e.g. ``-i "C:\path\to\keyfile.ppk"`` |
| 27 | + |
| 28 | +You can use these placeholders to create URL overrides. Global overrides are at |
| 29 | +*Tools > Options > Integration (tab) > URL Scheme Overrides...* or they can be |
| 30 | +specified per-entry on the *Properties* tab of *Entry Settings*. |
| 31 | + |
| 32 | +.. note:: The placeholders also work with the *External File* location in |
| 33 | + addition to attachments. |
| 34 | + |
| 35 | +Example: |
| 36 | + |
| 37 | + Open an ssh connection using PuTTY with the username and host specified in |
| 38 | + the database entry. The entry must have the Username and URL fields filled |
| 39 | + out for this to work. |
| 40 | + :: |
| 41 | + |
| 42 | + cmd://"C:\Program Files (x86)\PuTTY\PuTTY.exe" -ssh {USERNAME}@{URL:RMVSCM} {KEEAGENT:IDENTFILEOPT} |
| 43 | + |
| 44 | +.. tip:: Read more about the PuTTY command line `here`__. For example, the |
| 45 | + ``-load`` option is useful to load a saved session associated with the key. |
| 46 | + |
| 47 | +.. __: http://the.earth.li/~sgtatham/putty/latest/htmldoc/Chapter3.html#using-cmdline |
| 48 | + |
| 49 | + |
| 50 | +Using KeeAgent on Windows |
| 51 | +========================= |
| 52 | + |
| 53 | + |
| 54 | +Client mode with Pageant |
| 55 | +------------------------ |
| 56 | + |
| 57 | +KeeAgent (in Agent Mode) is designed to work much like ``ssh-agent`` on Linux/BSD/etc... |
| 58 | +Pageant is very similar, but there are some notable differences. Because of the |
| 59 | +more limited features of Pageant, it is recommended to run in Agent mode on |
| 60 | +Windows instead of using Pageant. However, if you have a good reason to run |
| 61 | +KeeAgent in Client Mode along with Pageant, here are some things to be aware of: |
| 62 | + |
| 63 | +- Pageant does not support locking. |
| 64 | +- Pageant does not support constraints. |
| 65 | +- Pageant does not support ECDSA or Ed25519 keys (except in the development version). |
| 66 | + |
| 67 | + |
| 68 | +Cygwin and MSYS |
| 69 | +--------------- |
| 70 | + |
| 71 | +KeeAgent can natively communicate with ssh programs running in Cygwin and |
| 72 | +MSYS. It is enabled in the :ref:`global-options` dialog. |
| 73 | + |
| 74 | +There are two implementations of sockets that are found in the various versions |
| 75 | +of Cygwin and MSYS. MSYS is really just a fork of Cygwin, so it depends on which |
| 76 | +fork the code is based on. So, unless you are using msysGit, try the "Cygwin |
| 77 | +socket file" first and if that does not work, try the "msysGit socket file". |
| 78 | +In some cases, you may need both enabled to support multiple versions of |
| 79 | +Cygwin/MSYS. |
| 80 | + |
| 81 | + |
| 82 | +Windows OpenSSH |
| 83 | +--------------- |
| 84 | + |
| 85 | +Although recent versions of Windows ship with OpenSSH out of the box, the |
| 86 | +included version is quite out of date. Consider installing the latest version |
| 87 | +with ``winget`` or ``choco`` instead or get them straight from the source from the |
| 88 | +`GitHub releases <https://github.com/PowerShell/Win32-OpenSSH/releases>`_ page. |
| 89 | + |
| 90 | +These tools are compatible with KeeAgent when **Enable agent for Windows OpenSSH** |
| 91 | +is selected in the :ref:`global-options`. |
| 92 | + |
| 93 | + |
| 94 | +Windows Subsystem for Linux (WSL) |
| 95 | +--------------------------------- |
| 96 | + |
| 97 | +KeeAgent can be used with `WSL <https://learn.microsoft.com/en-us/windows/wsl/>`_. |
| 98 | + |
| 99 | +For WSL1, simply select **Create WSL1 compatible socket file** in the |
| 100 | +:ref:`global-options` and set the ``SSH_AUTH_SOCK`` environment variable |
| 101 | +in your WSL1 shell to match. |
| 102 | + |
| 103 | +For WSL2, the environment is more isolated from Windows, so it is not possible |
| 104 | +to use the WSL1 socket. Instead, you can use the Windows OpenSSH programs |
| 105 | +from inside a WSL2 shell by running ``ssh.exe`` instead of ``ssh``. |
| 106 | + |
| 107 | +.. tip:: You can make a bash alias or symlink to make ``ssh`` an alias for |
| 108 | + ``ssh.exe``. For example:: |
| 109 | + |
| 110 | + sudo ln -s $(which ssh.exe) /usr/local/bin/ |
| 111 | + |
| 112 | +Alternately, there are a number of 3rd party solutions for providing a socket |
| 113 | +bridge to connect programs inside of WSL2 to an external SSH agent. |
0 commit comments