ACM Maintenance Operations

This section describes the options to upgrade, repair or uninstall the ACM and its components from the system.

1. Update Configurations and Component Images

If you need to update the configurations or Docker images of any component, please follow the process outlined below:

1.1 Updating Component Configurations or Environment Variables

All component configurations are managed through the env file.
If you wish to modify any configuration, update the env file on all nodes, and then execute the following command:
- sudo ./script.sh redeploy

1.2 Updating Component Docker Images

If there are updates to the Docker images, a new script.sh file will be provided. This script will include the updated image references required for deployment.
Along with the updated script, a folder containing the new Docker images will also be provided.
Follow the steps outlined in Section 5.3: Copy Images and Load to load the updated images into each node.
Once the updated script.sh file has been copied and the new Docker images have been loaded, execute the following command:
- sudo ./script.sh redeploy
This command will redeploy the cluster with the updated images while retaining the existing configurations from the current env file.

Note

Do not copy or overwrite the existing env file during an upgrade. Doing so will override your working configurations, potentially resulting in the loss of critical data required for proper cluster operation.

2. Full Uninstallation

Important

Critical Risk Warning: Before proceeding with Uninstallation, please be aware of the following critical risks:
Data Loss Risk: Uninstalling will result in permanent loss of all certificates, keys, metadata stored in MongoDB and Vault, and all configurations of MongoDB and Vault. Always ensure you have a verified backup of your data before making any changes.

We have created a base folder that contains all data for the installed services, such as:
- MongoDB
  - ./mongo/data: MongoDB persistent data for all databases and collections
  - ./mongo/config: MongoDB configuration data
- Vault
  - ./vault/data: Vault certificates created for users
  - ./vault/config: Vault configuration data
  - ./vault/tls: Vault TLS certificates used for communication over TLS
The uninstallation process will perform the following operations:
- Delete containers for the following services:
  - MongoDB
  - Vault
  - Accops Certificate Manager (ACM)
  - Certificate Cleanup Service
  - Authorizer
  - Tenant Management Service
- Delete all directories from the base directory, such as:
  - ./mongo
  - ./vault
  - ./images: may be created by the admin to store images
  - Any other directories created by the user
- Delete all files from the base directory, such as:
  - env file
  - docker-compose.yml: created by the script during installation, update, or redeployment
  - Any other files created by the admin in the base directory
Uninstallation Process
- Please execute below command for full uninstallations:
  - sudo ./script.sh full_cleanup
- Verify the if the all services are deleted using below command:
  - sudo docker ps

3. Add Intermediate CA in Vault

We have three independent Vault instances, and each Vault has its own CA certificate or key pair.
An Intermediate CA (or Sub CA) acts on behalf of another main CA. For example, if you have Microsoft CA configured in your environment as the main CA, and you want the user certificates generated from Vault to reflect the identity of the main CA, you can create a Sub CA in Vault for this purpose.
To add a Sub CA in Vault, below are the steps in brief:
- On Node 1, generate the CSR (Certificate Signing Request).
- Copy this CSR to a location where you can sign it using your main CA, and create a PEM bundle.
- Import the signed PEM bundle from your CA into Vault. The Sub CA will now be added to your Vault.
- Once the Sub CA is added, set it as the default so that certificates will be generated/signed using this Sub CA.
- Repeat the above steps on the other two nodes - Node 2 and Node 3.

Below is a deep-dive into Step #2-how Vault generates and returns your intermediate CSR, what each option does, and how you can extract and inspect that CSR before sending it off for signing.

3.1. Generate the Intermediate CSR in Vault

3.1.1. Ensure your environment is set up

On the machine where you have the Vault CLI installed, make sure you've exported:

export VAULT_ADDR=https://<Addressof Vault>:8200
export VAULT_CACERT=./vault/tls/ca.pem
export VAULT_TOKEN="s.yourRootOrMgmtToken"

These tell the vault command where to send requests and which token to use for authentication. Please make sure Yoy are executing this command from Base directory so CA certificate will be available at ./vault/tls/ca.pem. Vault is running over TLS, so it need CA Certificate in request.

3.1.2. Vault command

Vault's PKI engine provides a command: pki/intermediate/generate/internal that:

Creates a new private key inside Vault (it never leaves Vault's storage).
Builds a CSR (Certificate Signing Request) for that key, using the parameters you supply.
Returns the PEM-encoded CSR in the JSON response.

3.1.3. Common parameters

Parameter	Description	Example
`common_name`	Subject Common Name (CN) for the intermediate CA.	`"My Vault Sub-CA"`
`key_type`	Cryptographic algorithm (`rsa`, `ecdsa`).	`"rsa"` (default)
`key_bits`	RSA key size in bits (only for `rsa`).	`2048`
`exclude_cn_from_sans`	If `true`, Vault will omit the CN from the SubjectAltName extension (SAN).	`false` (default)
`alt_names`	Comma-separated list of additional SANs (DNS, IP, URIs).	`"vault-int.example.com,192.0.2.5"`
`ttl`	TTL for this intermediate certificate (ignored here; the real ttl is set by your root CA).	`87600h` (10 years)

3.1.4. Example command

Here's a more fully-featured example, generating a 4096-bit RSA key, excluding the CN from SANs, and adding an extra DNS SAN:

vault write -format=json pki/intermediate/generate/internal \
common_name="ACM Intermediate CA" \
key_type="rsa" \
key_bits=2048 \
exclude_cn_from_sans=true \
alt_names="<Vault VM Host name>" \
ttl="87600h" \ 
| tee /tmp/pki_csr.json

-format=json ensures the output is JSON, so it's easy to parse.
We pipe through tee so you keep a copy of the full JSON response in /tmp/pki_csr.json.

3.1.5. What the JSON looks like

If you inspect /tmp/pki_csr.json, you'll see something like:

{
  "request_id": "5f8c2a3a-1234-5678-9abc-def012345678",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...snip...\n-----END CERTIFICATE REQUEST-----",
    "private_key_type": "rsa",
    "private_key_format": "der"          # DER-encoded key inside Vault
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

.data.csr is the PEM CSR you'll submit to your main CA.
The private key never leaves Vault; it's held securely in the "pki_int" engine.

3.1.6. Extract just the CSR

To pull the CSR out into its own file:

jq -r '.data.csr' /tmp/pki_csr.json > intermediate.csr

Now you have a clean intermediate.csr you can hand to your main CA.

3.1.7. (Optional) Inspect the CSR with OpenSSL

Before submission, you can verify the contents:

openssl req -in intermediate.csr -noout -text

Key things to check in the output:

Subject: shows your Common Name
Subject Alternative Name: includes any DNS/IP you requested
Public Key Algorithm: confirms 2048

You'll see a block like:

Certificate Request:
    Data:
        Version: 1 (0x0)
        Subject: CN = My Vault Intermediate CA
        Subject Alternative Name:
            DNS: vault-int.example.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (2048 bit)
...

3.2 Submit the CSR to Main CA

Prepare PEM bundle by generating Sub CA certificate from your Certificate Authority using CSR generated in step# 2
intermediate_bundle.pem now contains:
1. -----BEGIN CERTIFICATE----- (your intermediate)
2. -----BEGIN CERTIFICATE----- (the root)

You're now ready to import that bundle back into Vault.

3.2.1 Example of obtaining a CSR signed by a Windows CA and generating PEM bundles

Get Intermediate CA from Windows CA Server: Get the CSR from the vault# 1, run the following command on Windows CA Server:

certreq -submit -attrib "CertificateTemplate:SubCA" intermediate.csr intermediate_from_win_ca.cer

Get Windows Root CA certificate: To get the Windows-CA certificate
1. Open Certificate Authority > Right click on root CA > Properties > General > In the CA certificates section > Click on listed certificate > View Certificate > Go to Details tab > Export to file > This will export the files in the .cer format.
Moving the certificates to ACM Copy both the certificate files to ACM Machine# 1
Get the Certificate bundle in PEM (Convert to PEM and make bundle)
Move files to ACM Machine
Convert file to PEM

mv intermediate_from_win_ca.cer intermediate_from_win_ca.pem

openssl x509 -in root_ca.cer -inform DER -out root_ca.pem

Merge PEM files

cat intermediate_from_win_ca.pem root_ca.pem > intermediate_bundle.pem

This certificate PEM bundle is ready to be imported back to Vault.

3.3. Import the Signed Intermediate Back into Vault

Once you have your PEM-encoded bundle (intermediate + root) on your Vault host-let's call it intermediate_bundle.pem-you'll load it into the pki mount so Vault can begin issuing certificates from this intermediate.

3.3.1. Verify your bundle

Before importing, confirm that intermediate_bundle.pem contains:

Your signed intermediate certificate first
The Issuing CA certificate second

3.3.2. Import via the Vault CLI

Use the set-signed endpoint under your intermediate mount:

vault write pki/intermediate/set-signed \ 
certificate=@intermediate_bundle.pem

This will give you response as below with id of imported certificate

Note

Please save this highlighted Id from your console, this will require to make this CA default for certificate generation.

Additionally, you can run the script below to enumerate all issuers/Certificate Authorities (CAs). It outputs each issuer's ID and Common Name (CN).

Copy list-ca.sh from the release folder to the ACM base directory and make it executable:

chmod +x list-ca.sh

Execute the script:

./list-ca.sh

Optional (if the you are executing it on RHEL and fails to run):

sed -i 's/\r$//' list-ca.sh

3.3.3 Make the Intermediate CA the Default

Promote the newly imported intermediate CA
- We need to configure Vault to use this intermediate CA as the default.
Check the current default CA
- Run:

vault read -field=default pki/config/issuers

This returns the ID of the current default CA, which will differ from the ID of the CA you just imported.

Set your intermediate CA as the default
- Replace <ID-of-imported-CA> with the UUID you captured when importing:

vault write pki/config/issuers \ 
default="<ID-of-imported-CA>"

# Example:   vault write pki/config/issuers default="19dc6c4d-0733-5e40-3aa2-eaab1cc21594"

Verify the change

vault read -field=default pki/config/issuers

It should now return the ID of your intermediate CA.

Confirm issuance behavior
- Any new certificates you generate will now use this intermediate CA by default.

4. Export CA certificate

Ensure your environment is set up
- On the machine where you have the Vault CLI installed, make sure you've exported:

export VAULT_ADDR=https://<Addressof Vault>:8200
export VAULT_CACERT=./vault/tls/ca.pem
export VAULT_TOKEN="s.yourRootOrMgmtToken"

These tell the vault command where to send requests and which token to use for authentication. Please make sure Yoy are executing this command from Base directory so CA certificate will be available at ./vault/tls/ca.pem. Vault is running over TLS, so it need CA Certificate in request.

Export Vault CA certificate

vault read -field=certificate pki/cert/ca > ca.crt

Get CA certificate file from directory where you are running commands