How to Integrate mkcert CA with Linux Trust Stores (update-ca-trust/update-ca-certificates)

Running mkcert -install automatically detects your Linux distribution and executes the appropriate trust store update command (update-ca-trust, update-ca-certificates, or trust extract-compat) to integrate the local CA system-wide.

Integrating mkcert's locally generated root CA with Linux system trust stores allows browsers, curl, and other applications to automatically trust certificates issued by mkcert. The FiloSottile/mkcert repository implements platform-specific logic in truststore_linux.go to handle the various Linux distribution trust store mechanisms without manual configuration.

How mkcert Detects Linux Trust Store Locations

The detection logic resides in the init() function of truststore_linux.go (lines 27-48). During package initialization, mkcert probes for the existence of specific anchor directories to determine which trust store management command to use:

• /etc/pki/ca-trust/source/anchors/ → Uses update-ca-trust extract (Fedora, RHEL, CentOS)
• /usr/local/share/ca-certificates/ → Uses update-ca-certificates (Debian, Ubuntu)
• /etc/ca-certificates/trust-source/anchors/ → Uses trust extract-compat (Arch Linux)
• /usr/share/pki/trust/anchors → Uses update-ca-certificates

When a matching directory is found, mkcert sets the package-level variables SystemTrustFilename (the destination path template) and SystemTrustCommand (the refresh command slice). If no known location is detected, the installation gracefully falls back to a warning rather than failing.

Installing the mkcert CA into Linux System Trust Stores

Automatic Installation with mkcert -install

The installPlatform() method (lines 55-74 in truststore_linux.go) handles the actual installation. When you execute:

mkcert -install

The tool performs three operations:

1. Copies the root CA from $CAROOT/rootCA.pem to the detected anchors directory using tee with sudo privileges (via the commandWithSudo helper in main.go, lines 80-92).

2. Refreshes the system trust store by executing the detected command (e.g., sudo update-ca-certificates or sudo update-ca-trust extract).

3. Confirms success by printing "The local CA is now installed in the system trust store! ⚡️".

Manual Installation Steps

If you prefer to integrate the mkcert CA manually without using mkcert -install:

# 1. Determine your CAROOT path

export CAROOT=$(mkcert -CAROOT)

# 2. Copy the root CA to the appropriate anchors directory

# For Debian/Ubuntu:

sudo cp "$CAROOT/rootCA.pem" /usr/local/share/ca-certificates/mkcert_rootCA.crt

# For Fedora/RHEL/CentOS:

sudo cp "$CAROOT/rootCA.pem" /etc/pki/ca-trust/source/anchors/mkcert_rootCA.pem

# 3. Update the trust store

# For Debian/Ubuntu:

sudo update-ca-certificates

# For Fedora/RHEL/CentOS:

sudo update-ca-trust extract

Uninstalling the mkcert CA from Linux Trust Stores

The uninstallPlatform() method (lines 77-98) reverses the installation process. Running:

mkcert -uninstall

Removes the CA file from the anchors directory using rm -f (with sudo via commandWithSudo) and then re-runs the trust store refresh command to update the system-wide certificate database.

Verifying mkcert CA Integration

To confirm the mkcert CA is properly integrated into your Linux trust store:

# Check if the CA is listed in the system trust store

trust list | grep -i mkcert

# Or for systems using update-ca-certificates

ls -la /etc/ssl/certs/ | grep mkcert

# Test certificate validation against a local mkcert-issued cert

curl -v https://localhost:8443 2>&1 | grep "SSL certificate verify ok"

Summary

• Automatic detection: mkcert probes /etc/pki/ca-trust/source/anchors/, /usr/local/share/ca-certificates/, and other standard paths in truststore_linux.go to determine whether to use update-ca-trust or update-ca-certificates.
• Installation flow: mkcert -install copies rootCA.pem to the detected anchors directory and executes the distribution-specific refresh command with sudo privileges.
• Manual control: You can manually copy the CA from $CAROOT to the appropriate anchors folder and run the refresh command if you prefer not to use the automatic installer.
• Clean removal: mkcert -uninstall removes the CA file and refreshes the trust store, ensuring no orphaned certificates remain.

Frequently Asked Questions

Where does mkcert store the root CA certificate on Linux?

mkcert stores the root CA certificate as rootCA.pem in the directory specified by the CAROOT environment variable. You can locate this directory by running mkcert -CAROOT. By default, this is usually ~/.local/share/mkcert or $HOME/.mkcert, depending on your system configuration.

What command does mkcert use to update the trust store on Fedora and RHEL systems?

On Fedora, RHEL, and CentOS systems, mkcert detects the /etc/pki/ca-trust/source/anchors/ directory and uses the command update-ca-trust extract to refresh the system trust store. This command processes the certificates in the source anchors directory and updates the consolidated trust database used by system applications.

How can I manually remove the mkcert CA without using mkcert -uninstall?

To manually remove the mkcert CA, first identify your distribution's anchors directory (e.g., /usr/local/share/ca-certificates/ for Debian/Ubuntu or /etc/pki/ca-trust/source/anchors/ for Fedora/RHEL). Remove the mkcert CA file (typically named mkcert_rootCA.pem or similar), then run the appropriate refresh command (sudo update-ca-certificates or sudo update-ca-trust extract) to update the system trust store.

Does mkcert require root privileges to install the CA into Linux trust stores?

Yes, installing the CA into system-wide trust stores requires root privileges because the anchor directories (such as /usr/local/share/ca-certificates/ and /etc/pki/ca-trust/source/anchors/) are protected system directories. The commandWithSudo helper function in mkcert's main.go automatically prefixes commands with sudo when the current user is not root, prompting for a password if necessary.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}