TRAWL

Appearance

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

Upgrading an existing CA ​

On the first startup after upgrading to a version containing the fix for issue #113, TRAWL checks the persisted root certificate. If it lacks a Subject Key Identifier, TRAWL updates ca.crt once and logs the certificate path. The subject, serial number, validity period, and CA key stay the same; ca.key is not changed. TRAWL refuses to migrate if the certificate and private key do not match or an existing Subject Key Identifier is invalid, rather than silently creating a new CA identity. Initialization is serialized with a short-lived .ca.lock file so multiple instances sharing the same CA volume cannot race to create different identities. If a process is forcibly terminated during initialization, remove a stale lock only after confirming no other instance is starting.

Adding the extension changes the certificate fingerprint. Clients that pin the exact certificate, including strict TLS clients, must download the updated ca.crt, remove the previously installed TRAWL root, and import the updated certificate using the relevant instructions below. Restart the client afterward if it caches its trust store. Clients that identify trust anchors by their public key and subject may continue to work without re-importing, but updating every trust store is the safest deployment procedure.

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:

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

From the TRAWL container:

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

macOS ​

Install into the system keychain:

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

Verify or remove it:

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

Debian and Ubuntu ​

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

RHEL, Fedora, and Amazon Linux ​

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

Windows ​

Run PowerShell as Administrator:

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

Remove it later:

powershell
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:

bash
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:

bash
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:

bash
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. TRAWL only generates a new root when both files are absent. If just one file is missing, startup fails to prevent an accidental identity change. If both are 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.