ConfigDump Tool

ENTERPRISE This is an EJBCA Enterprise feature.

The EJBCA ConfigDump tool allows you to export and import configurations in a human-readable (YAML) format. Exporting the current state of your installation is useful for auditing purposes and comparing configuration changes made in EJBCA. The import functionality allows you to import a complete configuration, or a configuration containing, for example a set of profiles, CAs, or any other previously exported object into EJBCA.

Since the configuration dump itself is human-readable, you can edit the fields in each object (for example, change the subject DN of an end entity profile) before import.

The following sections provide a short comparison between the ConfigDump tool, and our earlier Statedump configuration management tool, followed by information about how to build and run ConfigDump, and the commands to use for export and import.

    Comparison Between ConfigDump and Statedump

    ConfigDump serves as a partial replacement for the Statedump configuration management tool.

    Statedump allows exporting and importing full EJBCA configurations on new instances using the export format XML that is not meant to be human-readable and thus makes it poorly suited as an audit tool.

    The new ConfigDump tool instead produces a human-readable YAML output, which allows you to hand-modify exports.

    The following provides a high-level comparison between ConfigDump and Statedump.

    Functionality

    ConfigDump

    Statedump

    Output format

    YAML

    XML

    Can be easily edited

    Yes

    No

    Export

    Yes

    Yes

    Import

    Yes

    Yes

    Ability to add comments to output files

    Yes

    No

    Folder Structure and Output

    Each EJBCA object is exported into its own file. Objects of different types will be put in different folders.

    The following displays an example of a directory structure created by ConfigDump:

    Directory structure
    > tree
    .
    ├── certification-authorities
    │ ├── PrimeKey TestNet.yml
    ├── validators
    │ ├── My CAA Validator.yml
    │ ├── My RSA Key Validator.yml

    The following displays an example output from ConfigDump:

    Configdump output example
    'Type': 'PARTITIONED_APPROVAL'
    'Name': 'Partitioned approval profile test'
    'Approval expiration period': '1d'
    'Request expiration period': '2d'
    'Max extension time': '3d'
    'Allow self-approved request editing': !!bool 'true'
    'Steps':
    - 'Partitions':
    - 'Title': 'Partition 1'
    'Can approve':
    - 'Super Administrator'
    - 'RA Administrator 1'
    'Can view':
    - 'Super Administrator'
    - 'CA Administrator'
    - 'RA Administrator 1'
    - 'RA Administrator 2'
    - 'Supervisor'
    'Components':
    - 'Type': 'Text field'
    'Label': 'Text test'
    'Content': 'This is a multiline string.'
    - 'Type': 'Checkbox'
    'Label': 'Checkbox test'
    'Is checked?': !!bool 'true'
    - 'Type': 'Radio group'
    'Label': 'Radio test'
    'Selected choice': 'Blue'
    'Possible choices':
    - 'Green'
    - 'Blue'
    - 'Red'
    - 'Title': 'Partition 2'
    'Can approve':
    - 'Super Administrator'
    - 'RA Administrator 2'
    'Can view':
    - 'Anybody'
    'Administrator notification':
    'Sender': 'no-reply@admin.notification'
    'Recipients':
    - 'recipient1@admin.com'
    - 'recipient2.admin.com'
    'Subject': 'Admin notification subject'
    'Body': 'Admin notification body'
    'User notification':
    'Sender': 'no-reply@user.notification'
    'Subject': 'User notification subject'
    'Body': 'User notification body'
    'Components':
    - 'Type': 'Number'
    'Label': 'Integer test'
    'Value': !!int '42'
    - 'Type': 'Big number'
    'Label': 'Long test'
    'Value': !!int '9223372036854775807'

    As we can see, this YAML file corresponds to a partitioned approval profile with one step and two partitions. Partition 1 contains a text field, a checkbox and a radio group with three radio buttons. Partition 2 contains a user notification, an administrator notification, and two number fields.

    Exportable Object Types

    The following lists available object types that can be exported using ConfigDump:

    • acme-config

    • admin-preferences

    • admin-roles

    • approval-profiles

    • available-protocols

    • certificate-profiles

    • certification-authorities

    • cmp-config

    • crypto-tokens

    • ct-logs

    • custom-certificate-extensions

    • end-entity-profiles

    • est-config

    • extended-key-usage

    • internal-key-bindings

    • oauth-key-configuration

    • ocsp-configuration

    • peer-connectors

    • publishers

    • scep-config

    • services

    • trusted-oauth-providers

    • validators


    Import and export requires /system_functionality/edit_systemconfiguration access rule permission. Import of available-protocols requires superadmin permission. For more information on permissions, see Roles and Access Rules.

    Building

    To build and run the ConfigDump tool from the command line, using the following build argument:

    $ ant configdump

    This results in a standalone JAR library deployed to dist/configdump/configdump.jar. To run it, use the following command:

    $ ./dist/configdump/configdump.sh

    Export

    The following lists sub-commands for the export command.

    To see the full manual file for the export command, run:

    $ ./dist/configdump/configdump.sh export --help

    The export command produces a complete YAML-based export of an EJBCA installation, meant to be human-readable. Thus, ID references for objects will be replaced with their proper names. Certificates and end entity information will not be included in this export.

    Mandatory Parameters

    Switch

    Description

    -l (may be omitted if this value is added first)

    The output directory where YAML files will be written. It will be created automatically if non-existent. Provide absolute path to the directory e.g. /home/user/configdumpresult etc. Any existing dump files will be overwritten.

    Optional Parameters

    Switch

    Description

    --exclude

    Names of items/types to exclude in the export, separated by a semicolon. Type and name are separated by a colon, and wildcards "*" are allowed. Both are case-insensitive. E.g. --exclude "*:Example CA; cryptotoken:Example*; systemconfiguration:*"

    Supported types are: ACMECONFIG, CA, CRYPTOTOKEN, PUBLISHER, APPROVALPROFILE, CERTPROFILE, EEPROFILE, SERVICE, ROLE, KEYBINDING, ENDENTITY, SYSCONFIG, ADMINPREFS, CMPCONFIG, OCSPCONFIG, PEERCONNECTOR, PEERCONFIG, SCEPCONFIG, ESTCONFIG, VALIDATOR, CTLOG, EXTENDEDKEYUSAGE, CERTEXTENSION, AVAILABLEPROTOCOLS

    --ignore-errors

    Print a warning instead of aborting and throwing an exception on errors.

    --ignore-warnings

    No warnings will be printed in the CLI output.

    --include

    Names of items/types to include in the export. The syntax is identical to that of --exclude. For items of types that aren't listed, everything is included.

    --include-external-cas

    Enables export of external CAs (i.e. CAs where there's only a certificate and nothing else).

    --with-defaults

    Also include fields having the default value.

    An example usage of the include filter to only export CMP configuration to the directory dump would look like:

    ./configdump.sh export --exclude "*:*" --include "CMPCONFIG:*" -l dump

    Or exporting a specific EST Alias:

    ./configdump.sh export --exclude "*:*" --include "ESTCONFIG:myAliasName*" -l dump

    Export of Passwords and Secrets

    Several configuration items have passwords or secrets stored, which are usually encrypted in the database. An example is the CMP RA Mode authentication secret. Secrets like these are replaced with the string placeholder during export.

    When constructing configuration dump files for import, search and replace secrets set with placeholder with the values to be used for import, or edit it afterward using the EJBCA UI or the CLI.

    The following shows an example output for a SCEP Alias with Intune configuration containing Azure Application API Secret and Intune EJBCA Proxy Password. 

    Object Type: SCEP Configuration
Version: 2
Name: Intune
Operational Mode: RA
Authenticate through Microsoft Intune: 'true'
RA CA Name: IntuneCA
RA Authentication Password: placeholder
Azure Application ID: IntuneID
Azure Application API Secret: placeholder
Intune Tenant: My tennant
Intune EJBCA Proxy Password: placeholder

    Import

    The following lists sub-commands for the import command.

    To see the full manual file for the import command, run:

    $ ./dist/configdump/configdump.sh import --help

    The import command reads from a YAML-based export of an EJBCA installation, or YAML files created following the same structure as an export.

    Mandatory Parameters

    Switch

    Description

    -l

    The input directory to read dump YAML files from.

    This must point to the root directory of the YAML files. Specific sub-directories cannot be targeted.

    Optional Parameters

    Switch

    Description

    --ignore-errors

    Print a warning instead of aborting and throwing an exception on errors.

    --ignore-warnings

    No warnings will be printed in the CLI output.

    --initialize

    Generate initial certificate for CAs on import.

    --non-interactive

    Set non-interactive mode. Mode must be one of: <continue> or <abort>

    --overwrite

    Don't prompt for overwrite. Mode must be one of: <update> or <skip>. When an object from the YAML file already exists in the database, this object should be skipped from import or be updated.

    --resolve-reference

    Don't prompt for reference problem. Mode must be one of: <default> or <skip>. When an object to be imported is referencing a missing object, this object should get a default value for the missing object or be skipped from import.

    Known Limitations

    The following objects are available for ConfigDump export, though not yet importable in version 7.5.

    • admin-preferences

    • msae-config

    ConfigDump REST Interface

    Import and export are supported in the EJBCA REST Interface. For more information, see EJBCA REST Interface.

    To allow automation via the REST interface, superadmins can access the REST interface without enabling it beforehand. By enabling ConfigDump or other protocols, the superadmin can support further operations without access to the CLI or UI. To update the protocol and/or interface configuration, superadmins need to import the available-protocol object with overwrite parameter set to true.

    Troubleshooting

    If EJBCA is running as a different user than ConfigDump (which may happen whenever you log in as foo but EJBCA is running as e.g. wildfly) you may run into the following problem when exporting:

    Exporting to directory: /home/foo/configdump
    java.nio.file.AccessDeniedException: /home/foo/configdump
    [....]

    The solution is to create the folder manually with the proper group ownership, according to the following example:

    mkdir ~/configdump
    sudo chown foo:wildfly ~/configdump