Overview
In order to use a GPG key that has a passphrase, an external gpg-agent must be running and seeded with your passphrase. This feature is enabled with the following configuration directive in /etc/packagecloud/packagecloud.rb
:
Prerequisites
- gpg-agent 2.0.x
- gpg-connect-agent (might be a separate package for your system)
Setup
1) Start gpg-agent
gpg-agent --homedir /etc/packagecloud/gpgkey --allow-preset-passphrase --max-cache-ttl 31622400 --daemon --sh --write-env-file /etc/packagecloud/gpgkey/gpg_socket.env
The --write-env-file
argument writes the gpg-agent's socket information into a file (henceforth referred to as the 'socket environment file') and it is how the application can locate and communicate with the gpg-agent. The example command above uses the default packagecloud_gpg['key_directory']
of "/etc/packagecloud/gpgkey"
. The application will look for a `gpg_socket.env` file inside of the configured packagecloud_gpg['key_directory']
.
2) Seeding the agent with your passphrase
Once the gpg-agent is running, you can set your passphrase by issuing the PRESET_PASSPHRASE instruction to gpg-agent using the gpg-connect-agent
command. This instruction takes the full key fingerprint and a hexencoded passphrase as arguments. For example:
echo "PRESET_PASSPHRASE $GPG_FINGERPRINT -1 $GPG_PASSPHRASE_HEX" | gpg-connect-agent --homedir /etc/packagecloud/gpgkey
Where the variables $GPG_FINGERPRINT and $GPG_PASSPHRASE_HEX are set to the full fingerprint (without colons) and the hexencoded passphrase, respectively. Example implementations using the Bash shell are provided below:
2.1) Getting the $GPG_FINGERPRINT
GPG_FINGERPRINT=`gpg --homedir /etc/packagecloud/gpgkey --fingerprint user@email.com | grep fingerprint | awk -F= '{print $2}' | sed -e 's/[[:blank:]]//g'` env | grep GPG
2.2) Getting the $GPG_PASSPHRASE_HEX
GPG_PASSPHRASE_HEX=`cat /path/to/passphrase | tr -d '\n' | hexdump -v -e '/1 "%02X"'`
Monitoring
Once enabled, the application will rely solely on gpg-agent running in order to sign repository metadata, so it's important that it is always available, and restarted in the event that it stops working. Otherwise repository updates might stop working unexpectedly.
Max Cache TTL
After you seed your passphrase, it will eventually expire according to the max-cache-ttl
setting used when starting up the agent. If this is desired, you'll need to use a periodic process, like a cron job to continually reseed the passphrase before it expires, or alternatively, you can set it to a year (31622400 seconds).
Common Errors
When using the Indexer Status area, you might see recently failed jobs with the following errors:
Error | Description | Troubleshooting Tips |
---|---|---|
NoSocketEnvironmentFile | The socket environment file cannot be located. | Is the |
SocketEnvironmentFileUnreadable | The socket environment file is unreadable. | Are the permissions of the socket environment file readable by the packagecloud user? |
CannotParseSocketEnvironmentFile | The socket file is malformed and cannot be parsed. | Contact support@packagecloud.io with the contents of the socket environment file. |