|
| 1 | +# Secret Service in headless Linux sessions |
| 2 | + |
| 3 | +Git Credential Manager (GCM) can use Secret Service without a graphical |
| 4 | +desktop, provided a provider is available and the required keyrings are |
| 5 | +unlocked. |
| 6 | + |
| 7 | +## How Secret Service fits together |
| 8 | + |
| 9 | +Secret Service is a standard API for storing and retrieving secrets. |
| 10 | +A **provider** implements that API, stores the secrets, and controls access |
| 11 | +to them. Example providers include [GNOME Keyring][gnome-keyring], |
| 12 | +[KWallet][kwallet], and [oo7][oo7]. |
| 13 | + |
| 14 | +[D-Bus][dbus] carries messages between applications and the provider; it |
| 15 | +does not store the secrets itself. GCM's `secretservice` credential store |
| 16 | +uses the `libsecret` library to communicate with the provider over the user's |
| 17 | +D-Bus session bus. |
| 18 | + |
| 19 | +```mermaid |
| 20 | +flowchart LR |
| 21 | + subgraph gcm["Git Credential Manager"] |
| 22 | + direction TB |
| 23 | + libsecret("libsecret") |
| 24 | + end |
| 25 | + libsecret <--> dbus[/"D-Bus<br/>session"/] |
| 26 | + apps("Other<br/>applications") <--> dbus |
| 27 | + dbus <--> provider("Secret Service<br/> provider") |
| 28 | + keyrings[("Secret<br/>Collections")] <--> provider |
| 29 | +``` |
| 30 | + |
| 31 | +For GCM to use this store, it needs: |
| 32 | + |
| 33 | +- Access to a user/session bus. |
| 34 | +- A Secret Service provider running, or able to start on demand, on that bus. |
| 35 | +- A default collection for storing credentials, with the required collections |
| 36 | + unlocked. GNOME Keyring and oo7 call these **keyrings**; KWallet calls them |
| 37 | + **wallets**. |
| 38 | + |
| 39 | +> [!NOTE] |
| 40 | +> On systems with [systemd][systemd], the user D-Bus session bus and installed |
| 41 | +> Secret Service providers are typically started automatically. Providers may be |
| 42 | +> started on demand through D-Bus activation when an application requests them. |
| 43 | +
|
| 44 | +## Unlocking without a desktop |
| 45 | + |
| 46 | +Secret Service allows applications to request that a collection be unlocked, |
| 47 | +but the provider controls authentication and prompting. On a desktop, this |
| 48 | +often means a graphical password prompt. The standard API does not let GCM |
| 49 | +supply the collection's password or choose a terminal prompt such as pinentry. |
| 50 | + |
| 51 | +In a headless session, the collection must already be unlocked, or the |
| 52 | +provider must offer a way to unlock it without a graphical prompt. Available |
| 53 | +options depend on the provider and may include command-line tools or login |
| 54 | +integration, such as PAM. Installing a terminal pinentry program alone does |
| 55 | +not make a provider's graphical prompts work headlessly. |
| 56 | + |
| 57 | +**Starting the bus or provider is not the same as unlocking a collection.** |
| 58 | +An unlocked collection needs no further input. After a reboot or provider |
| 59 | +restart, it must be unlocked again, either through configured automatic |
| 60 | +unlocking or user interaction. Unattended workloads need a setup that does |
| 61 | +not depend on an interactive password prompt. |
| 62 | + |
| 63 | +## Setup Guides |
| 64 | + |
| 65 | +### Ubuntu Server + GNOME Keyring |
| 66 | + |
| 67 | +These instructions use Ubuntu Server 24.04 to create a password-protected |
| 68 | +keyring and reuse it on future logins. Ubuntu's packages provide automatic service |
| 69 | +startup; no custom systemd configuration is needed. |
| 70 | + |
| 71 | +Run these steps as the user who runs Git. Use `sudo` only where shown. |
| 72 | + |
| 73 | +#### 1. Set up the keyring |
| 74 | + |
| 75 | +##### Install the dependencies |
| 76 | + |
| 77 | +```shell |
| 78 | +sudo apt-get update |
| 79 | +sudo apt-get install --no-install-recommends \ |
| 80 | + dbus dbus-user-session gnome-keyring libsecret-tools |
| 81 | +``` |
| 82 | + |
| 83 | +##### Check the D-Bus session |
| 84 | + |
| 85 | +```shell |
| 86 | +busctl --user list |
| 87 | +``` |
| 88 | + |
| 89 | +On a standard Ubuntu Server login, the user bus is already available. |
| 90 | +If the command lists services, continue in the same shell. |
| 91 | + |
| 92 | +If no user bus is available, start a temporary session: |
| 93 | + |
| 94 | +```shell |
| 95 | +dbus-run-session -- bash |
| 96 | +``` |
| 97 | + |
| 98 | +Run the remaining keyring setup commands inside this new shell. |
| 99 | + |
| 100 | +##### Create an unlock command |
| 101 | + |
| 102 | +Create this small helper so you do not have to repeat the password-handling |
| 103 | +commands each time. The helper **does not store your password**. |
| 104 | + |
| 105 | +```shell |
| 106 | +mkdir -p "$HOME/.local/bin" |
| 107 | +cat > "$HOME/.local/bin/unlock-keyring" <<'EOF' |
| 108 | +#!/usr/bin/env bash |
| 109 | +set -euo pipefail |
| 110 | +set +x |
| 111 | +
|
| 112 | +if ! IFS= read -r -s -p 'Keyring password: ' password </dev/tty; then |
| 113 | + printf '\nCould not read the keyring password.\n' >&2 |
| 114 | + exit 1 |
| 115 | +fi |
| 116 | +printf '\n' >/dev/tty |
| 117 | +if [[ -z "$password" ]]; then |
| 118 | + printf 'Use a non-empty keyring password.\n' >&2 |
| 119 | + exit 1 |
| 120 | +fi |
| 121 | +
|
| 122 | +printf '%s' "$password" | |
| 123 | + gnome-keyring-daemon --daemonize --replace --unlock --components=secrets |
| 124 | +EOF |
| 125 | +chmod 700 "$HOME/.local/bin/unlock-keyring" |
| 126 | +``` |
| 127 | + |
| 128 | +Start the daemon and create or unlock the login keyring: |
| 129 | + |
| 130 | +```shell |
| 131 | +~/.local/bin/unlock-keyring |
| 132 | +``` |
| 133 | + |
| 134 | +On first use, choose a non-empty keyring password. On later uses, enter |
| 135 | +that same password. This is the **keyring password**, not a Git access token. |
| 136 | +The encrypted keyring is saved in your home directory. |
| 137 | + |
| 138 | +The command replaces any GNOME Keyring daemon it discovers, so it may |
| 139 | +interrupt other applications using that daemon. |
| 140 | + |
| 141 | +##### Select the credential store |
| 142 | + |
| 143 | +```shell |
| 144 | +git config --global credential.credentialStore secretservice |
| 145 | +``` |
| 146 | + |
| 147 | +GCM can now use the keyring. To check that it is unlocked: |
| 148 | + |
| 149 | +```shell |
| 150 | +busctl --user get-property org.freedesktop.secrets \ |
| 151 | + /org/freedesktop/secrets/collection/login \ |
| 152 | + org.freedesktop.Secret.Collection Locked |
| 153 | +``` |
| 154 | + |
| 155 | +The expected output is `b false`. |
| 156 | + |
| 157 | +#### 2. Use the keyring on future logins |
| 158 | + |
| 159 | +On a standard Ubuntu Server login, the user bus starts automatically. |
| 160 | +Installing GNOME Keyring also installs its D-Bus activation configuration: |
| 161 | +the bus can start the provider when an application requests it. |
| 162 | + |
| 163 | +You can see this with: |
| 164 | + |
| 165 | +```shell |
| 166 | +busctl --user list | grep org.freedesktop.secrets |
| 167 | +``` |
| 168 | + |
| 169 | +An `(activatable)` entry means the provider can start on demand. A PID means |
| 170 | +it is already running. You do not need to enable additional systemd units |
| 171 | +or change `.bashrc` for this setup. |
| 172 | + |
| 173 | +After a reboot, or whenever the keyring is locked, unlock it before using GCM: |
| 174 | + |
| 175 | +```shell |
| 176 | +~/.local/bin/unlock-keyring |
| 177 | +``` |
| 178 | + |
| 179 | +Use the password you chose in part 1, then use Git normally. If the collection |
| 180 | +is already unlocked, no unlock command is needed. |
| 181 | + |
| 182 | +If you used a temporary `dbus-run-session` shell, its bus ends when you leave |
| 183 | +that shell. Start another session as described in part 1 when needed. |
| 184 | + |
| 185 | +## Troubleshooting |
| 186 | + |
| 187 | +Read the complete error, including any native error printed after GCM's |
| 188 | +message. For example, `Failed to open the Secret Service session` can mean |
| 189 | +a collection could not be loaded, not just that the provider is missing. |
| 190 | + |
| 191 | +Symptom|What to check |
| 192 | +-|- |
| 193 | +`No credential store has been selected`|Select the store with `git config --global credential.credentialStore secretservice`. |
| 194 | +`Failed to connect to the D-Bus session bus` or `Cannot autolaunch D-Bus without X11 $DISPLAY`|Run `busctl --user list` as the user who runs Git, without `sudo`. If no user bus is available, follow the [D-Bus session setup](#check-the-d-bus-session). |
| 195 | +`ServiceUnknown` or `NameHasNoOwner`|A required D-Bus service is unavailable. Check whether `org.freedesktop.secrets` is running or activatable in `busctl --user list`. If it is, the error may refer to another component, such as the provider's prompter; check the service named in the error. |
| 196 | +`No such secret collection at path: ...` or `Object does not exist` for a collection path|The collection may be missing or the provider's state may be inconsistent. Check the default collection as described below. |
| 197 | +`Cannot get secret of a locked object`, `Failed to unlock the secret item`, or a prompt that cannot open a display|Unlock the collection using the provider's headless unlocking method, then retry. Starting the provider or installing pinentry alone does not unlock it. |
| 198 | +`secret-tool lookup` returns no output and exits with `1`|No accessible matching secret was returned. This can mean either no matching entry or an unsuccessful unlock. Unlock the collection and retry with a known existing entry. |
| 199 | +`libsecret-1.so.0` cannot be loaded|Check that the libsecret runtime is installed for the architecture GCM is running on. On Ubuntu, the package is `libsecret-1-0`. |
| 200 | + |
| 201 | +### Check the default collection |
| 202 | + |
| 203 | +The default collection is an alias, not necessarily a collection named |
| 204 | +`login`. Ask the provider where it points: |
| 205 | + |
| 206 | +```shell |
| 207 | +busctl --user call org.freedesktop.secrets \ |
| 208 | + /org/freedesktop/secrets org.freedesktop.Secret.Service \ |
| 209 | + ReadAlias s default |
| 210 | +``` |
| 211 | + |
| 212 | +An output of `o "/"` means no default collection is assigned. Use the |
| 213 | +provider's tools to create or select one. Otherwise, inspect the returned |
| 214 | +collection path rather than assuming it is the GNOME `login` keyring. |
| 215 | + |
| 216 | +If the provider advertises a collection but cannot return its properties, |
| 217 | +restarting it may resolve inconsistent state. With GNOME Keyring, this can |
| 218 | +occur when independently started daemons create or unlock the keyring while |
| 219 | +another daemon serves D-Bus. The [unlock helper](#create-an-unlock-command) |
| 220 | +replaces the daemon it discovers, but may interrupt other applications. |
| 221 | +Do not delete keyring files to resolve a missing-object error. |
| 222 | + |
| 223 | +[dbus]: https://www.freedesktop.org/wiki/Software/dbus/ |
| 224 | +[gnome-keyring]: https://wiki.gnome.org/Projects/GnomeKeyring |
| 225 | +[kwallet]: https://invent.kde.org/frameworks/kwallet |
| 226 | +[oo7]: https://github.com/linux-credentials/oo7 |
| 227 | +[systemd]: https://systemd.io/ |
0 commit comments