key-manager.conf File Format

CommunityEnterprise

To use the Master Key feature, you must configure it in the key-manager.conf file located in /opt/bacula/etc. This file is automatically populated with a single master key by the install-key-manager.sh script found in the bacula-enterprise-storage-key-manager package. By default, this Master Key applies to all volumes.

If you do not use a Master Key, this file is not required, but it allows to select different encryption algorithms for different volumes when needed.

Here is an example of the key-manager.conf file that is generated by using the install-key-manager.sh script. The file holds numerous comments designed to assist you in managing the gpg-agent, for example, in how to securely load the passphrase if necessary. The comments have been omitted here for clarity, refer to the full content below.

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

[0378FB9C839FF9F207834D89DB856A1A513B7AB4]
# keygrip=2786B044C9994C73F92B5DF80F2386CC20B40CAA
# uid=bacula@localhost
volume_regex=.*
cipher=AES_256_XTS
passphrase=CgcEdvt87U4SsCRd
masterkey=on
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. If your section is not related to a Master Key, you can use any valid name.

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. Do not confuse this with the directory of your key files, which is set by default to /opt/bacula/etc/keydir.

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.

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

# sudo -u bacula gpg --homedir /opt/bacula/etc/gnupg -k --with-keygrip
/opt/bacula/etc/gnupg/pubring.kbx
-----------------------------------------------------
pub   rsa2048 2025-08-07 [SCEAR]
      0378FB9C839FF9F207834D89DB856A1A513B7AB4
      Keygrip = E80B516DC479790C81E09B0A0A0F0B1059E28EF1
uid           [ultimate] Bacula <bacula@localhost>
sub   rsa2048 2025-08-07 [SEA]
      Keygrip = 2786B044C9994C73F92B5DF80F2386CC20B40CAA

Notice that the public key has a subkey that performs the encryption. This is the [SEA] 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 uses the Master Key to encrypt the symmetric keys for the Volumes that match the regular expression specified here.

The volume_regex values of each sections are checked sequentially. The first regex that matches the Volume name provided to key-manager.py will select the section applied for the Volume. By default, the volume_regex of the preset Master Key is set to .* to match any Volume name.

cipher: The cipher is the encryption algorithm used to encrypt the data. AES_256_XTS uses a 256-bit key while AES_128_XTS uses a 128-bit key.
passphrase: This is the passphrase of the private key.

If the passphrase of the public/private key is not set in the key-manager.conf file but is required by the key-manager.py script, then the script relies on the gpg-agent to supply it. When the public/private key is generated by install-key-manager.sh, this is the only location where the key is stored. Be sure to keep a copy before removing it from the configuration file.

masterkey: If the section is related to a Master Key, then this field must be set to on to activate the encryption and decryption of the symmetric key. When set to on and the stealth mode is used, the key-manager.py script stores only the encrypted version of the symmetric keys in the KEYDIR directory.
stealth: When set to on, the key-manager.py does not keep the symmetric keys in clear text in the KEYDIR directory. When on, it is recommended 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 key-manager.conf configuration file to decrypt the symmetric key coming from the Volume, or use the clear version of the symmetric key stored locally in the KEYDIR directory.
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 loaded or is still in the cache of the gpg-agent, allowing GnuPG to decrypt the symmetric key. You are not supposed to provide the passphrase in the configuration file when stealth is used.
- Bacula waits until a user provides the passphrase. The Director and the Storage Daemon report the passphrase request in their status, and it is also reported in the job log. The key-manager.conf configuration file contains some helpful commands on how to load the passphrase using either the gpg-preset-passphrase or the gpg-connect-agent programs.

The keygrip and uid are added as comments by the install-key-manager.sh script to help the user to identify the Master Key when Bacula asks for the passphrase. These lines are just comments and are not used by the key-manager.py script.

Here is the full version of the keymanager.conf file. Notice the gpg commands that allow the user to load the passphrase for the gpg-agent.

[DEFAULT]
# This file has been generated by /opt/bacula/scripts/install-key-manager.sh version 1.1
# Here are the default values for ALL the sections
# You can overwrite these values inside the sections
gnupghome="/opt/bacula/etc/gnupg"
#cipher=AES_128_XTS
#stealth=off
#masterkey=on


[0378FB9C839FF9F207834D89DB856A1A513B7AB4]
# The name of this section is the master-key fingerprint,
# below are the uid and keygrip of this master-key
#
# keygrip=2786B044C9994C73F92B5DF80F2386CC20B40CAA
# uid=bacula@localhost
#
# Options in this section applies to volumes matching the "volume_regex" below
# A typical regex looks like : "volume_regex=Accounting[0-9]+|HumanResources[0-9]+"
# Be careful these are real regex and not wildcard patterns,
# you must use "Volume.*" and not "Volume*"
# A section without "volume_regex" field is ignored.
# The first matching section is used. Be careful at the order.
#
# When using a masterkey and stealth=off, you can preload the passphrase in the
# gpg-agent using one of the commands below:
# Notice that the KEYGRIP of the KEY is used instead of the MASTERKEY itself
# $ echo <PASSPHRASE> | sudo -u bacula /usr/lib/gnupg/gpg-preset-passphrase --homedir /opt/bacula/etc/gnupg --preset 6EEACFAE035AAC8772B50E6C9A3C683B596F4186
# or
# $ sudo -u bacula /usr/lib/gnupg/gpg-preset-passphrase --homedir /opt/bacula/etc/gnupg --preset -P <PASSPHRASE> 6EEACFAE035AAC8772B50E6C9A3C683B596F4186
# Without the "echo <PASSPHRASE>" or the "-P <PASSPHRASE>", the command will
# wait for the input of the passphrase that you can validate with ENTER
#
# If you want to script the command above and avoid the use of the <PASSPHRASE>
# on the command line (to not reveal the passphrase via the "ps" command), use:
#
# sudo -u bacula /usr/lib/gnupg/gpg-preset-passphrase --homedir /opt/bacula/etc/gnupg --preset 6EEACFAE035AAC8772B50E6C9A3C683B596F4186 <<EOF
# <PASSPHRASE>
# EOF
#
# If the gpg-preset-passphrase is not installed on you platform, you can use
# gpg-connect-agent instead:
#
# $ hex="$(printf '%s' "<PASSPHRASE>" | xxd -p -u)"
# $ sudo -u bacula gpg-connect-agent --homedir /opt/bacula/etc/gnupg <<EOF
# PRESET_PASSPHRASE  -1 $hex
# EOF
#
# To test your passphrase you can try to sign any file
# $ echo test > /tmp/testfile.txt
# $ sudo -u bacula gpg --homedir /opt/bacula/etc/gnupg --dry-run --local-user 20B22AB0BD882A6CE91452CCE7CAB24CED714865 --output /dev/null --sign /tmp/testfile.txt
# GnuPG will ask you for a passphrase and tell you if it was able to unlock your key
# If GnuPG don't ask you for a passphrase, this is because the agent is already
# running and know your passphrase, you can kill your agent using
# $ sudo -u bacula gpg-connect-agent --homedir /opt/bacula/etc/gnupg killagent /bye
#

volume_regex=.*
cipher=AES_256_XTS
passphrase=CgcEdvt87U4SsCRd
masterkey=on
stealth=off