mirror of
https://github.com/germondai/trawl.git
synced 2026-08-17 12:11:23 +02:00
139 lines
3.6 KiB
Markdown
139 lines
3.6 KiB
Markdown
---
|
|
title: Install the Proxy CA
|
|
description: 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:
|
|
|
|
```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. 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.
|