Refresh the Linux CA Store with update-ca-certificates

You will add a local PEM certificate to the machine trust store, refresh the generated files, and check that the result is usable. The workflow also covers disabling a distribution certificate and restoring that change.

The examples use update-ca-certificates from Debian's ca-certificates package, version 20260601~24.04.1 on the system used for this guide. Allow about fifteen minutes. You need a shell, the package installed, and a CA certificate that you are authorised to trust.

Most commands that change the system store need elevated privileges. The inspection commands do not.

1. Check the installed command

Start with a read-only check. This confirms the executable and records the package version without changing certificates:

$ command -v update-ca-certificates
/usr/sbin/update-ca-certificates
$ dpkg-query -W -f='${Package} ${Version}\n' ca-certificates
ca-certificates 20260601~24.04.1
$ update-ca-certificates --help
/usr/sbin/update-ca-certificates: [--verbose] [--fresh]

The installed help is shorter than the manual page. The options relevant here are --verbose, which prints the underlying openssl rehash output, and --fresh, which removes symlinks in /etc/ssl/certs before rebuilding them.

2. Understand which files control trust

The command combines two sources. Distribution certificates are under /usr/share/ca-certificates and are selected by /etc/ca-certificates.conf. A normal entry names a certificate below the distribution directory. A line beginning with ! deselects that certificate, while a line beginning with # is a comment.

Local certificates are handled separately. Every PEM certificate with a .crt extension below /usr/local/share/ca-certificates is included and implicitly trusted. Keep one certificate in each file. A file containing several certificates is outside the documented workflow and can produce confusing results.

The generated store has two useful forms:

• /etc/ssl/certs contains the individual certificates and rehash links;
• /etc/ssl/certs/ca-certificates.crt is one concatenated bundle containing the activated certificates.

Do not edit the generated directory or bundle by hand. Change the source certificate or configuration, then regenerate the outputs.

3. Add one local CA certificate

Use this for a certificate that belongs to your organisation or lab and that local applications should trust. First inspect the file as the account that owns it:

$ openssl x509 -in /path/to/company-root.crt -noout -subject -issuer -dates
subject=CN = Example Company Root CA
issuer=CN = Example Company Root CA
notBefore=...
notAfter=...

Check the subject and expiry before installing anything. The command above reads the file only. Replace the path with the actual certificate path; do not copy a server private key or a certificate downloaded from an untrusted source.

Copy the verified PEM file into the local certificate directory. This is the first state-changing command and needs elevated privileges:

$ sudo install -m 0644 /path/to/company-root.crt /usr/local/share/ca-certificates/company-root.crt

The destination must end in .crt. The documented format is PEM, and the file should contain one certificate. If you used the wrong file or name, remove that one file before refreshing:

$ sudo rm -- /usr/local/share/ca-certificates/company-root.crt

That removal is deliberate and limited to the example path. Do not use a broad wildcard in this directory.

4. Regenerate and verify the store

Run the normal update as root:

$ sudo update-ca-certificates
Updating certificates in /etc/ssl/certs...
1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

The exact counts and hook output depend on the machine. The useful signals are a successful exit status and an added certificate count when you installed a new local file. The command also invokes hooks in /etc/ca-certificates/update.d. Those hooks receive added certificate names prefixed with + and removed names prefixed with -, so a locally installed hook may perform additional work.

Verify the generated paths without changing them:

$ test -s /etc/ssl/certs/ca-certificates.crt && echo "bundle exists and is non-empty"
bundle exists and is non-empty
$ openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt /path/to/company-root.crt
/path/to/company-root.crt: OK

The second command verifies the CA certificate against the generated bundle. It does not test a particular server certificate. To test an application, use that application's documented connection check and its own certificate options.

5. Disable one distribution certificate carefully

Use this only when you have a documented reason to stop trusting a distribution-provided CA. First find the exact entry instead of guessing its path:

$ grep -n -- 'certificate-name.crt' /etc/ca-certificates.conf
42:mozilla/example/certificate-name.crt

Make a small backup before editing the configuration:

$ sudo cp -- /etc/ca-certificates.conf /etc/ca-certificates.conf.backup

Edit the matching line and add ! at its beginning. For the example entry, the result is:

!mozilla/example/certificate-name.crt

Run the update again:

$ sudo update-ca-certificates
Updating certificates in /etc/ssl/certs...
0 added, 1 removed; done.

Do not infer success solely from a count. Check that the intended certificate is no longer selected in the configuration and inspect the generated result with a known certificate or application test.

To undo this specific configuration change, restore the backup after checking that it is the backup you created:

$ sudo cp -- /etc/ca-certificates.conf.backup /etc/ca-certificates.conf
$ sudo update-ca-certificates

6. Use a fresh rebuild only when needed

The --fresh option removes symlinks in /etc/ssl/certs before rebuilding them. That is a repair or cleanup operation, not the normal update after adding a certificate. It can briefly leave the generated directory without those links while the command runs.

Use it when stale links are a known problem and you have a maintenance window:

$ sudo update-ca-certificates --fresh
Clearing symlinks in /etc/ssl/certs...
done.

Output varies by package release and by the number of certificates. If the command fails, do not delete more files by hand. Read the error, check the source directories and configuration, then run the ordinary update after correcting the specific problem. A failed refresh does not mean that an arbitrary certificate should be marked trusted.