If you're not sure whether to use the SOCKS proxy check out our HTTP vs SOCKS article.
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.
- Work on per host basis
- Compatible with all programming environments
- Support advanced configurations: transparent mode and encryption
- 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
qgtunnelin 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.
Tunnel for DATABASE_URL
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:email@example.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:firstname.lastname@example.org:5432 to postgres://user:email@example.com:5432. 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
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.
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:
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/qgsocksify 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., 192.0.2.22/24), single addresses (192.0.2.22/32), 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:
The SOCKS wrapper is not straight forward to set up or debug so if you have any issues just get in contact with us and we'll help you out.