key-manager.conf File Format

When using the Master Key feature, it is possible to configure your master keys in the key-manager.conf file located in /opt/bacula/etc. This file is automatically populated with a single master key at installation time. If you do not intend to use a master key, this file is not necessary.

This is an example of the key-manager.conf file generated at installation time:

[default]
gnupghome="/opt/bacula/etc/gnupg"

[0378FB9C839FF9F207834D89DB856A1A513B7AB4]
volume_regex=Volume[0-9]+|TestVolume[0-9]+
uid=bacula@localhost
passphrase=xm3ynBi7MfHTUovls4QV8OtBT5rfAnXwT8Wb7wjVRyCT
stealth=off

It is essential to define a section for each master key intended for use. The name of the section is the Key-ID of your public/private key. In the above example, there is one section for the Key-ID 0378FB9C839FF9F207834D89DB856A1A513B7AB4.

The supported fields are:

gnupghome: This is where GnuPG stores the public and private keys.

When the bacula-enterprise-storage-key-manager package is installed, the default gnupghome directory is set to /opt/bacula/etc/gnupg.

Thus, if you plan to use GnuPG commands in the Storage Daemon host, it is necessary to employ the --homedir option like: --homedir /opt/bacula/etc/gnupg, or set the GNUPGHOME environment variable to /opt/bacula/etc/gnupg:

export GNUPGHOME="/opt/bacula/etc/gnupg"

To properly configure the key-manager.conf file with the master key values, you can get the Key-ID values by listing your keys:

bacula $ GNUPGHOME=/opt/bacula/etc/gnupg gpg -k
/opt/bacula/etc/gnupg/pubring.kbx
-----------------------------------------------------
pub   rsa3072 2023-01-11 [SC]
      0378FB9C839FF9F207834D89DB856A1A513B7AB4
uid           [ultimate] Bacula <bacula@localhost>
sub   rsa3072 2023-01-11 [E]

Notice that the public key has a subkey that allows encryption. This is the [E] in the last line. If your public/private key does not own such a key, you cannot use it with the key-manager.py script.

volume_regex: The key-manager.py script will use the master key

to encrypt the symmetric keys for the Volumes that match the regular expression specified here.

The volume_regex values are checked sequentially. The first regex that matches the Volume name submitted to the key-manager.py script will be used even if another volume_regex matches the name of the Volume. By default, the volume_regex is commented out to disable the master key feature.

uid: The User ID of the key, which is simply the user name and

email address. The uid assists in identifying the key.

The uid serves only as a reference and is not used by the key-manager.py script.

passphrase: This is the passphrase of the key.

When the passphrase of the public/private key is not set but required by the key-manager.py script, it depends on the gpg-agent to provide the key.

stealth: When the stealth mode is used, the key-manager.py script stores the symmetric keys encrypted in the KEYDIR directory. The volume_regex option must be set when using the stealth mode.

When stealth is set to on, the key-manager.py does not keep the symmetric keys in clear text in the KEYDIR directory. When on, it is advisable not to specify a passphrase.

The following scenarios are possible:

stealth mode is not used: the key-manager.py script can use the passphrase of the private key that you have provided in the configuration file to decrypt the symmetric key coming from the Volume, or use the clear version of the symmetric key stored locally.
stealth mode is used: the key-manager.py script asks GnuPG to decrypt the symmetric key coming from the Volume.

In this case, there are two potential outcomes:
- The passphrase of the private key has been preset or is still in the cache of the gpg agent, allowing gpg to successfully decrypt the symmetric key.
- Bacula waits until the user provides the passphrase.

This is an example to use the same master key to all Volumes:

[default]
gnupghome="/opt/bacula/etc/gnupg"

[0378FB9C839FF9F207834D89DB856A1A513B7AB4]
volume_regex=.*
uid=bacula@localhost
passphrase=xm3ynBi7MfHTUovls4QV8OtBT5rfAnXwT8Wb7wjVRyCT
stealth=on