Transmission first install¶
Transmission runs in a container behind a PIA VPN tunnel. app-setup/podman-transmission-setup.sh creates a Podman virtual machine named transmission-vm for the operator account, starts the transmission-vpn container from the haugene/transmission-openvpn image, and adds the LaunchAgents that keep both running. All container traffic goes through the OpenVPN tunnel to PIA. This page covers the first install. For credentials, port forwarding and regions after that, see PIA VPN.
Before you start¶
- A PIA account in 1Password. Make a 1Password item with
usernameandpasswordfields for your PIA account. SetONEPASSWORD_PIA_ITEMto the item name before you runprep-airdrop.sh. The script readsop://<vault>/<item>/usernameandop://<vault>/<item>/passwordand stores them as oneusername:passwordentry, with the service namepia-account-<hostname>, in the package keychain. First boot imports that keychain. The setup script reads the entry from theadminkeychain and stops with an error when it is missing. -
The config keys. Set these in
config/config.conf. See Configuration keys.Key Default What it does ONEPASSWORD_PIA_ITEM(empty) The 1Password item that holds the PIA credentials. PIA_VPN_REGIONca_vancouverThe PIA region. Use the file name stem from the image's /etc/openvpn/pia/folder, not the PIA API region id. The region must serve port forwarding.LAN_SUBNET192.168.1.0/24Your LAN, in CIDR form, for example 192.168.20.0/22. The container gets it asLOCAL_NETWORK.TRANSMISSION_HOST_PORT9091The host port for the Transmission web UI and RPC. It is bound to 127.0.0.1only.NAS_HOSTNAME,NAS_SHARE_NAME(none) Required. The script stops when either one is empty, or has characters other than letters, digits, .,-and_.MONITORING_EMAILyour-email@example.comNeeded for the two watchdogs. See step 4. -
The NAS mount for
operator. The container's/datafolder is/Users/operator/.local/mnt/<NAS_SHARE_NAME>, passed through from the host over VirtioFS.plex-setup.shadds themount-nas-mediaLaunchAgent that mounts it whenoperatorlogs in. When the share is not mounted, the script skips its mount test with a warning. The supervisor waits up to 120 seconds for the mount at each start. - Alert email, if you want the watchdogs. Set up Alert email with msmtp first. Without
MONITORING_EMAILand/Users/operator/.config/msmtp/config, the script skips the PIA port watchdog and the stall watchdog.
Warning
The Caddyfile proxies /transmission/ to 127.0.0.1:9091, a fixed value. If you change TRANSMISSION_HOST_PORT, the web UI through Caddy stops working until you change the Caddyfile too.
Set it up¶
-
Optional, but do it before the first container start: set up stable signing. On the server, as
admin(the script refuses to run as root), run:first-boot.shdoes not run this script. It installs/usr/local/bin/<hostname>-stable-sign.sh, creates a local code signing identity, and makes signed copies of Homebrew'spodman,coreutilsandbashunder/usr/local/stable/. It also sets up the daily Homebrew upgrade, which signs the copies again after each upgrade. See Stable signing for why this is needed. -
As
admin, go to the app setup folder and run the Transmission script: -
Enter the
adminpassword whensudoasks for it. -
Restart the server, or log out and log in as
operator, so the LaunchAgents start. - Watch the operator desktop. macOS can show a prompt that a program "would like to access files on a network volume". Click Allow. The prompt names the program that macOS holds responsible for the VirtioFS access. With stable signing, it names a path under
/usr/local/stable/, and the grant then survives Homebrew upgrades. Without stable signing, the prompt can come back after each upgrade, and the supervisor waits until someone answers it.
What the script creates¶
The script does these things, in order:
- It installs Podman with Homebrew if it is missing, and stops when the version is older than 4.7.0.
- It creates the
transmission-vmmachine asoperator, rootful, with 2 CPUs, 2 GB of memory and a 20 GB disk, unless it already exists. It makestransmission-vmthe default connection and starts the machine. - It creates
/Users/operator/containers/transmission/with theconfig,scriptsandwatchfolders. - It reads the PIA entry from the keychain and writes
/Users/operator/containers/transmission/.env, mode 600. The container gets the credentials from this file through--env-file, so they do not show inpsoutput. - It copies the container-side scripts to
containers/transmission/scripts/:transmission-post-done.sh, the port forwarding managerpia-port-guard.shwithtransmission-post-start.sh, and the region probepia-pf-probe.sh. The image's own port updater is turned off withDISABLE_PORT_UPDATER=true. - It writes these scripts to
/Users/operator/.local/bin/:transmission-trigger-watcher.sh,pending-move-cleanup.sh,podman-machine-start.sh(the supervisor), and, when alert email is set up,pia-port-watchdog.shandstall-watchdog.shwith~/.local/lib/alert-lib.sh. -
It writes the operator LaunchAgents. See LaunchAgents.
LaunchAgent What it does com.<hostname>.podman-transmission-vmRuns the supervisor at login, always kept alive. com.<hostname>.transmission-trigger-watcherWatches for finished downloads and runs FileBot processing. com.<hostname>.pending-move-cleanupRuns every hour. com.<hostname>.pia-port-watchdogRuns every 15 minutes, only with alert email. com.<hostname>.stall-watchdogRuns every 2 minutes, only with alert email. -
When the NAS share is mounted, it runs a test
alpinecontainer that lists the share through VirtioFS. - When there were no errors and
.envwas written, it starts thetransmission-vpncontainer withpodman run. - It builds
/Users/operator/Applications/TransmissionMagnetHandler.appand registers it as the handler formagnet:links. See Catch.
The script does not load the LaunchAgents. They start at the next operator login. The supervisor then checks the machine and the container every 300 seconds, and starts or creates them again when they are not running. When the container cannot read /data three times in a row, the supervisor restarts the VM. The supervisor never exits, because launchd stops the VM helper about 5 seconds after the agent's script exits.
Note
The log of the setup script says that curl -s ifconfig.io "should return Panama PIA exit IP". That text is old. The default region is now ca_vancouver, and Panama serves no port forwarding. The exit IP belongs to the region that you set.
Check¶
Run these checks as admin, after operator has logged in.
-
The container is up and healthy:
The
STATUScolumn showsUpand, after the 120-second start period,(healthy). -
Traffic leaves through PIA. This command prints the exit IP address, which must not be your home IP address:
-
Port forwarding works. Ask Transmission for its listen port from inside the container:
sudo -iu operator podman exec transmission-vpn transmission-remote localhost:9091 -si | grep -i 'listen port'A port number other than 0 means port forwarding works.
Listen port: 0means it failed. See Diagnosing "torrents won't start". -
The PIA credentials were not rejected. A wrong password shows up as
AUTH_FAILEDin the container log, so this command must print nothing. An empty result does not prove the tunnel is up; check 3 does that: -
The supervisor is running its loop. The log shows
entering supervision loop: -
If you set up stable signing, every signed copy is current. The command exits 0:
-
The web UI opens at
https://macmini.local/transmission/from the LAN, once Caddy is set up. Port 9091 answers on127.0.0.1only.
Replace macmini with your server name in lower case. The setup script's own log is ~/.local/state/macmini-apps.log. Lines from this script contain [podman-transmission].
Related¶
- PIA VPN: the credential chain, password rotation, port forwarding and region choice.
- Stable signing: the network-volume privacy grant and the
/usr/local/stablecopies. - Transmission and FileBot: what happens after a download finishes.
- Monitoring: the PIA port watchdog and the stall watchdog.
- Alert email with msmtp
- Catch
- Storage and VirtioFS
- Configuration keys
- LaunchAgents
- Logs
- Ports