ConfigDump Export and Audit Tool

ENTERPRISE  This is an EJBCA Enterprise feature.

Overview

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.

Configdump is EJBCA version independent, unlike Statedump, where you can run into trouble if you do the export and import on different versions of EJBCA.

Configdump is still under construction, and the import functionality is still in development. In the meanwhile, the export functionality serves as an excellent auditing tool.

Comparison between Configdump and Statedump


ConfigdumpStatedump
Output formatYAMLXML
Can be easily editedYesNo
ExportYesYes
ImportNo, but on the roadmapYes
EJBCA version independentYesNo
Ability to add comments to output filesYesNo

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 the 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.

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.jarTo run it, use the following command:

$ java -jar dist/configdump/configdump.jar <command name>

Commands

Configdump is split into several subcommands, listed here. So far only the export command has been implemented. 

Export

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

$ java -jar dist/configdump/configdump.jar 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 

SwitchDescription
-l (may be omitted of 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

SwitchDescription

--exclude

Names of items/types to exclude in the export, separated by semicolon. Type and name is 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

--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).

Troubleshooting

If EJBCA is running as a different user than Configdump (which may happen whenever you login 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