Skip to content

Frequently asked questions

The container runs, but I can't access the web UI

TODO: Short explanation and link to networking

How do I enable authentication in the web UI

You can do this either by setting the appropriate fields in settings.json which is found in TRANSMISSION_HOME which defaults to /config/transmission-home so it will be available on your host where you mount the /config volume. Remember that Transmission overwrites the config when it shuts down, so do this when the container is not running.

Or you can set it using the convenience environment variables. They will then override the settings on every container startup. The environment variables you have to set are:

  • TRANSMISSION_RPC_USERNAME=username
  • TRANSMISSION_RPC_PASSWORD=password
  • TRANSMISSION_RPC_AUTHENTICATION_REQUIRED=true

PS: Be cautious of special characters in the username or password. We've had multiple errors with that and have not provided a fix yet. Escaping special characters could be an option, but the easiest solution is just to avoid them. Make the password longer instead ;) Or write it into settings.json manually as first described. Also, look up differences between how yaml special characters are escaped vs in docker run

Docker secrets are also supported for the rpc credentials. To use a secret, remove both the TRANSMISSION_RPC_USERNAME and TRANSMISSION_RPC_PASSWORD environment variables and add a secret named rpc_creds. The secret file must contain two lines, the first line is the username and the second line is the password. Then just add it as a secret to docker, and it will be picked up automatically. This is why the name of the secret is important.

How do I verify that my traffic is using VPN

There are many ways of doing this, and I welcome you to add to this list if you have any suggestions.

You can exec into the container and through the shell use curl to ask for your public IP. There are multiple endpoints for this but here are a few suggestions:

  • curl http://ipinfo.io/ip
  • curl http://ipecho.net/plain
  • curl icanhazip.com

Example command: docker exec <container-name> curl --silent "http://ipinfo.io/ip"

Or you could use a test torrent service to download a torrent file and then you can get the IP from that tracker.

  • http://ipmagnet.services.cbcdn.com/
  • https://torguard.net/checkmytorrentipaddress.php

TODO: Conflicting LOCAL_NETWORK values. Short explanation and link to networking

This can occur because you have specified an invalid subnet or possibly specified an IP Address in CIDR format instead of a subnet. Your LOCAL_NETWORK property must be aimed at a subnet and not at an IP Address.

A valid example would be

 ```
 LOCAL_NETWORK=10.80.0.0/24
 ```

but an invalid target route that would cause this error might be 

 ```
 #Invalid because the subnet for this range would be 10.20.30.0/24
 LOCAL_NETWORK=10.20.30.45/24
 ```

To check your value, you can use a subnet calculator. * Enter your IP Address - the portion before the mask, 10.20.30.45 here * Select the subnet that matches - the /24 portion here * Take the Network Address that is returned - 10.20.30.0 in this case

TUNSETIFF tun: Operation not permitted

This is usually a question of permissions. Have you set the NET_ADMIN capabilities to the container? What if you use docker run --privileged, do you still get that error?

This is an error where we haven't got too much information. If the hints above get you nowhere, create an issue.

Error resolving host address

This error can happen at multiple places in the scripts. The most common is that it happens with curl trying to download the latest .ovpn config bundle for those providers that have an update script, or that OpenVPN throws the error when trying to connect to the VPN server.

The curl error looks something like curl: (6) Could not resolve host: ... and OpenVPN says RESOLVE: Cannot resolve host address: .... Either way, the problem is that your container does not have a valid DNS setup. We have two recommended ways of addressing this.

The first solution is to use the dns option offered by Docker. This is available in Docker run as well as Docker Compose. You can add --dns 8.8.8.8 --dns 8.8.4.4 to use Google DNS servers. Or add the corresponding block in docker-compose.yml:

  dns:
    - 8.8.8.8
    - 8.8.4.4

You can of course use any DNS servers you want here. Google servers are popular. So is Cloudflare DNS.

The second approach is to use some environment variables to override /etc/resolv.conf in the container. Using the same DNS servers as in the previous approach you can set:

OVERRIDE_DNS_1=8.8.8.8
OVERRIDE_DNS_2=8.8.4.4

This will be read by the startup script and it will override the contents of /etc/resolv.conf accordingly. You can have one or more of these servers and they will be sorted alphabetically.

What is the difference between these solutions?

A good question as they both seem to override what DNS servers the container should use. However, they are not equal.

The first solution uses the dns flags from Docker. This will mean that we instruct Docker to use these DNS servers for the container, but the resolv.conf file in the container will still point to the Docker DNS service. Docker might have many reasons for this but one of them is at least for service discovery. If you're running your container as a part of a larger docker-compose file or custom docker network and you want to be able to lookup the other containers based on their service names then you need to use the Docker DNS service. By using the --dns flags you should have both control of what DNS servers are used for external requests as well as container DNS lookup.

The second solution is more direct. It rewrites the resolv.conf file so that it no longer refers to the Docker DNS service. The effect of this is that you lose Docker service discovery from the container (other containers in the same network can still resolve it) but you have cut out a middleman and potential point of error. I'm not sure why this sometimes is necessary but it has proven to fix the issue in some cases.

A possible third option

If you're facing the OpenVPN error (not curl) then your provider might have config files with IP addresses instead of DNS. That way your container won't need DNS to do a lookup for the server. Note that the trackers will still need DNS, so this will only solve the problem for you if it is your local network that in some way is blocking the DNS.

Container loses connection after some time

For some users, on some platforms, this is an issue. I have not encountered this myself - but there is no doubt that it's recurring. Why does the container lose connectivity? That we don't know and it could be many different reasons that manifest the same symptoms. We do however have some possible solutions.

Set the ping-exit option for OpenVPN and restart-flag in Docker

Most provider configs have a ping-restart option set. So if the tunnel fails, OpenVPN will restart and re-connect. That works well on regular systems. The problem is that if the container has lost internet connection restarting OpenVPN will not fix anything. What you can do though is to set/override this option using OPENVPN_OPTS=--inactive 3600 --ping 10 --ping-exit 60. This will tell OpenVPN to exit when it cannot ping the server for 1 minute.

When OpenVPN exits, the container will exit. And if you've then set restart=always or restart=unless-stopped in your Docker config then Docker will restart the container and that could/should restore connectivity. VPN providers sometimes push options to their clients after they connect. This is visible in the logs if they do. If they push ping-restart that can override your settings. So you could consider adding --pull-filter ignore ping to the options above.

This approach will probably work, especially if you're seeing logs like these from before:

Inactivity timeout (--ping-restart), restarting
SIGUSR1[soft,ping-restart] received, process restarting

Use a third-party tool to monitor and restart the container

The container has a health check script that is run periodically. It will report the health status to Docker and the container will show as "unhealthy" if basic network connectivity is broken. You can write your own script and add it to cron, or you can use a tool like https://github.com/willfarrell/docker-autoheal to look for and restart unhealthy containers.

This container has the autoheal label by default so it is compatible with the willfarrell/autoheal image

Send Username and Password via a file

Depending on your setup, you may not want to send your VPN user/pass via environment variables (the main reason being, it is accessible via docker inspect). If you prefer, there are two methods of avoiding credentials to be set via environment variables: - Option 1: Configure the container to use a file. - Option 2: Configure the container to use a secret. (Only available for Docker Swarm)

Procedure for Option 1: Configuring the container to use a file 1. Create a text file with a username and password in it, each on a separate line. For this example, we will assume it is located at ./openvpn-credentials.txt

this_is_my_username
this_is_my_password

  1. Set the Environment Variable for username/password to exactly: **None**

  2. Mount the file in this exact path: /config/openvpn-credentials.txt

Config example:

$ docker run --cap-add=NET_ADMIN -d \
              -v /your/storage/path/:/data \
              -v ./openvpn-credentials.txt:/config/openvpn-credentials.txt \
              -e OPENVPN_PROVIDER=PIA \
              -e OPENVPN_CONFIG=france \
              -e OPENVPN_USERNAME=**None** \
              -e OPENVPN_PASSWORD=**None** \
              -e LOCAL_NETWORK=192.168.0.0/16 \
              --log-driver json-file \
              --log-opt max-size=10m \
              -p 9091:9091 \
              haugene/transmission-openvpn

The example docker-compose.yml looks like this:

version: '3.3'
services:
    transmission-openvpn:
        cap_add:
            - NET_ADMIN
        volumes:
            - '/your/storage/path/:/data'
            - './openvpn-credentials.txt:/config/openvpn-credentials.txt'
        environment:
            - OPENVPN_PROVIDER=PIA
            - OPENVPN_CONFIG=france
            - OPENVPN_USERNAME=**None**
            - OPENVPN_PASSWORD=**None**
            - LOCAL_NETWORK=192.168.0.0/16
        logging:
            driver: json-file
            options:
                max-size: 10m
        ports:
            - '9091:9091'
        image: haugene/transmission-openvpn

Procedure for Option 2: Configure the container to use a secret

Note: Docker Secrets are only available for Docker Swarm (docker-compose). If you run the container standalone, refer to Option 1.

  1. Create a text file with a username and password in it, each on a separate line. For this example, we will assume it is located at ./openvpn-credentials.txt
this_is_my_username
this_is_my_password
  1. Mount the file as a secret like below. *The name of the secret must be exactly openvpn_creds, which will be exposed to the container at /run/secrets/openvpn_creds.

The example docker-compose.yml looks like this:

version: '3.3'
secrets:
  openvpn_creds:
    file: './openvpn-credentials.txt'
services:
    transmission-openvpn:
        cap_add:
            - NET_ADMIN
        volumes:
            - '/your/storage/path/:/data'
        environment:
            - OPENVPN_PROVIDER=PIA
            - OPENVPN_CONFIG=france
            - OPENVPN_USERNAME=**None**
            - OPENVPN_PASSWORD=**None**
            - LOCAL_NETWORK=192.168.0.0/16
        logging:
            driver: json-file
            options:
                max-size: 10m
        secrets:
            - openvpn_creds
        ports:
            - '9091:9091'
        image: haugene/transmission-openvpn

Bonus tip: The same steps can be followed for rpc_creds, as shown in [How do I enable authentication in the web ui].

AUTH: Received control message: AUTH_FAILED

If your logs end like this, the wrong username/password was sent to your VPN provider.

AUTH: Received control message: AUTH_FAILED
SIGTERM[soft,auth-failure] received, process exiting

We can divide the possible errors here into three. You have entered the wrong credentials, the server has some kind of error or the container has messed up your credentials. We have had challenges with special characters. Having "?= as part of your password has tripped up our scripts from time to time.

NOTE Some providers have multiple sets of credentials. Some for OpenVPN, others for web login, proxy solutions, etc. Make sure that you use the ones intended for OpenVPN. PIA users: this has recently changed. It used to be a separate pair, but now you should use the same login as you do in the web control panel. Before you were supposed to use a username like x12345, now it's the p12345 one. There is also a 99 character limit on password length.

First, check that your credentials are correct. Some providers have separate credentials for OpenVPN so it might not be the same as for their apps. Secondly, test a few different servers just to make sure that it's not just a faulty server. If this doesn't resolve it, it's probably the container.

To verify this you can mount a volume to /config in the container. So for example /temporary/folder:/config. Your credentials will be written to /config/openvpn-credentials.txt when the container starts, more on that here. So by mounting this folder you will be able to check the contents of that text file. The first line should be your username, the second should be your password.

This file is what's passed to OpenVPN. If your username/password is correct here then you should probably contact your provider.