trawl/apps/docs/proxy/ca-installation.md

title, description

title	description
Install the Proxy CA	Trust TRAWL's generated root CA on operating systems, browsers, Java, and containers.

Install the proxy CA

TRAWL decrypts proxied HTTPS connections to detect challenge pages. On first proxy startup it creates:

• ca.crt — the root certificate clients install;
• ca.key — the private signing key, which must remain secret.

Both files live in MITM_PROXY_CA_DIR. Per-host certificates are generated in memory and signed by this root. Persist the directory so clients only need to install the root once.

::: danger Anyone with ca.key can issue certificates trusted by clients that installed this CA. Keep the directory private, do not publish it, and never distribute ca.key. :::

Download the certificate

The route is available when the proxy is enabled:

curl http://<trawl-host>:8191/proxy-ca.crt -o trawl-ca.crt

From the TRAWL container:

docker cp trawl:/data/proxy-ca/ca.crt ./trawl-ca.crt

macOS

Install into the system keychain:

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ./trawl-ca.crt

Verify or remove it:

security find-certificate -c "TRAWL MITM Proxy CA"
sudo security delete-certificate -c "TRAWL MITM Proxy CA" \
  /Library/Keychains/System.keychain

Debian and Ubuntu

sudo cp trawl-ca.crt /usr/local/share/ca-certificates/trawl-ca.crt
sudo update-ca-certificates

RHEL, Fedora, and Amazon Linux

sudo cp trawl-ca.crt /etc/pki/ca-trust/source/anchors/trawl-ca.crt
sudo update-ca-trust

Windows

Run PowerShell as Administrator:

Import-Certificate -FilePath .\trawl-ca.crt `
  -CertStoreLocation Cert:\LocalMachine\Root

Remove it later:

Get-ChildItem Cert:\LocalMachine\Root |
  Where-Object { $_.Subject -like "*TRAWL MITM*" } |
  Remove-Item

Firefox and NSS stores

Firefox installations that do not use the operating-system roots need an NSS import:

certutil -A -n "TRAWL MITM" -t "CT,C,C" -i trawl-ca.crt \
  -d sql:$HOME/.mozilla/firefox/<profile-directory>

Alternatively use Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import.

Java and JDownloader

Java applications use their own cacerts store:

keytool -importcert -noprompt -trustcacerts \
  -alias trawl-mitm-ca \
  -file trawl-ca.crt \
  -keystore "<java-home>/lib/security/cacerts" \
  -storepass changeit

JDownloader bundles a JRE. Locate its active Java path in JDownloader's advanced settings, import the certificate into that JRE's lib/security/cacerts, and restart JDownloader.

Prowlarr, Sonarr, and Radarr are .NET applications. Their containers normally use the Linux system trust store, not Java cacerts.

Docker clients

Mount the certificate into the client container and install it during container initialization. For Debian-based images:

cp /config/trawl-ca.crt /usr/local/share/ca-certificates/trawl-ca.crt
update-ca-certificates

The exact startup-hook directory depends on the image. LinuxServer images support /custom-cont-init.d/; other images may require a derived Dockerfile.

Rotation and recovery

Do not delete or replace ca.crt or ca.key during normal upgrades. If either is lost, TRAWL generates a new root on the next startup and every client must install the new certificate.

To intentionally rotate the CA:

1. stop TRAWL;
2. back up and remove both CA files;
3. start TRAWL and download the new ca.crt;
4. remove the old root from every client;
5. install the new root.