If you're not sure whether to use the SOCKS proxy check out our HTTP vs SOCKS article

Please note : This product includes software developed by Inferno Nettverk A/S, Norway. For more information on their software Dante, please see https://www.inet.no/dante/

Please note: The wrapper and tunnel are not  compatible with OSX or Windows. We recommend using a Virtual Machine  running Ubuntu for development testing if your main development  environment does not run Linux.  Please contact us if you require version for other OS.

QuotaGuard Static provides two ways to setup SOCKS5 proxy integration within your app: SOCKS5 tunnels and a wrapper script.


SOCKS5 tunnels:


  • Work on per host basis
  • Compatible with all programming environments
  • Support advanced configurations: transparent mode and encryption


Wrapper script:


  • Proxies all connections, with optional constraints by IP
  • Incompatible with some threaded environments and environments with event loops. Notably doesn’t support Java and Node.js


We recommend using SOCKS5 tunnels unless you need to route all traffic within the app through the SOCKS5 proxy.

Setting up SOCKS5 tunnel

SOCKS5 tunnel application allows you to create a local tunnels on  your server that will route all incoming traffic through the QuotaGuard  proxies. You have to setup separate tunnel configuration for every host  you want to proxy. To get started with the tunnel please follow these  steps:

  • Download and extract the qgtunnel in your app directory:
curl https://s3.amazonaws.com/quotaguard/qgtunnel-latest.tar.gz | tar xz

  • Prepend the tunnel application to your standard startup commands. For example unicorn app server for ruby:
web: bin/qgtunnel bundle exec unicorn -p $PORT -c ./config/unicorn.rb

  • Create tunnel configuration via DATABASE_URL or QuotaGuard dashboard.

  • Commit and deploy these changes.


If your application relies on DATABASE_URL environment  variable then you can use automatically generated configuration and  don’t have to perform additional configuration steps. For example if  your DATABASE_URL is  postgres://foo:bar@ec2-10-10-10-1.compute-1.amazonaws.com:5432/baz then  tunnel will be listening on port 5432 of your server and all connections  to this port will be forwarded to  ec2-10-10-10-1.compute-1.amazonaws.com:5432 via SOCKS5 proxy. In this  mode tunnel also enables transparent DNS override  which will resolve DNS name ec2-10-10-10-1.compute-1.amazonaws.com to  the localhost address so all connections to this hostname will  transparently go to the tunnel.

Custom tunnel configuration

Open QuotaGuard Static dashboard and visit Tunnels section of the Setup page. On the Setup page create a new tunnel configuration for the remote server by clicking on Create Tunnel. For example, if you want to access IP whitelisted postgres database located on a host ec2-10-10-10-1.compute-1.amazonaws.com, put tcp://ec2-10-10-10-1.compute-1.amazonaws.com:5432 into the Remote Destination and press Save. With this configuration your tunnel will listen on server’s port 5432 and will route all traffic to the ec2-10-10-10-1.compute-1.amazonaws.com via the SOCKS5 proxy. If you want to use a different local port, you can provide it explicitly in configuration interface.

Modify your app configuration to use localhost instead of remote server. For the same postgres example change connection string from: postgres://user:pass@ec2-10-10-10-1.compute-1.amazonaws.com:5432 to postgres://user:pass@ You can also export tunnel configuration to use it locally on your server without relying on QuotaGuard servers.

Debugging tunnel configuration

By default all fatal errors encountered by the qgtunnel will be logged to your heroku logs. If this information is not enough you can enable verbose output mode by setting QGTUNNEL_DEBUG environment variable to true.

export QGTUNNEL_DEBUG=true

Local tunnel configuration

By default qgtunnel will try to fetch configuration from the QuotaGuard API, but it also supports local configuration. You can download configuration file from the tunnel setup interface by pressing “Download configuration”. To enable local mode place downloaded file into root directory of your project under .qgtunnel filename, commit it and deploy.

Transparent mode

If your application depends on DNS based discovery process or needs  local tunnel to be resolvable via the DNS name regular tunneling mode  will not be enough. For this situation you should enable transparent  mode for the tunnel in your configuration. In transparent mode tunnel  application will alter DNS queries from your app to the local tunnel  address.

Let’s say you want to access replicated MongoDB cluster using the tunnel with 3 replicas located on the hosts: rs01.mongodb.net:52115, rs02.mongodb.net:52115 and rs1.mongodb.net:52115. For this configuration you will need to create  3 separate tunnels for each host on the port 52115  in transparent mode. Once this done, tunnel application will alter DNS  resolution process to resolve these host names to the appropriate  loopback address and auto discovery for your replicated cluster should  work as intended.

Installing the QuotaGuard Static wrapper

Download and extract the wrapper in your app directory


$ cd /home/myuser/my-app

$ curl https://s3.amazonaws.com/quotaguard/quotaguard-socksify-latest.tar.gz | tar xz

$ echo "QUOTAGUARD-LICENSE.txt" >> .gitignore

$ git add bin/statica vendor/dante

$ git commit -m "Add QuotaGuard Static socksify"        


Now you can prepend the qgsocksify wrapper to your standard commands to transparently route all traffic through your Static IPs. For example to run a Rails server:



bin/qgsocksify rails s



Controlling what traffic goes through proxy

You can provide a standard subnet mask to only route traffic to certain IP subnets via the QUOTAGUARDSTATIC_MASK environment variable. The mask supports sub-network specifications (e.g.,, single addresses (, host names (e.g., ftp.example.org), or domain names (e.g., .example.org). A domain name specification will match any host in that domain.




All outbound traffic to 100.30.68.* would be routed via your Static IPs. Multiple masks can be provided by comma separating the mask values:


Getting Help

The SOCKS wrapper is not straight forward to set up or debug so if you have any issues just get in contact with us at Support and we'll help you out.