On April 1, 2021, we are moving all of our QuotaGuard Support Documentation to
https://quotaguard.github.io/qg-docs/
Please Update Your Support Bookmarks
Documentation for this article will be maintained at
https://quotaguard.github.io/qg-docs/quickstart-socks5.html
Please click on the above link to ensure you are reading
the most recent and updated documentation.
SOCKS5 is a very flexible TCP level tunneling protocol which works on a
per host basis and is compatible with all programming environments.
If you're not sure whether to use the SOCKS proxy, then please 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/
QuotaGuard Static provides three ways to setup SOCKS5 proxy integration
within your app:
- QuotaGuard Tunnel, process-based tunneling
program (recommended) - QuotaGuard Socksify script, routing-based tunneling
program - Framework specific support for SOCKS5
QGTunnel is an extremely versatile wrapper script for your process. It
allows you to map one or more local ports to route through the
QuotaGuard proxy servers. It supports a DNS override mode for protocols
that require the hostname stay the same (ie: HTTPS) or to minimize the
impact on the code. QGTunnel also supports end-to-end encryption of your
tunnel data for protocols that are not encrypted (ie: redis).
We recommend QGTunnel unless you need to route all traffic within the
app through the SOCKS5 proxy.
QGSocksify is a routing-based tunneling program. It allows for all or
some of the outgoing traffic to be routed through the proxy server based
on the destination IP or IP range.
Additionally, many languages support SOCKS5 proxies natively or via a
add-on package.
Please note: The wrapper is 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.
To Get Started with the SOCKS5 Proxy Utilizing QGTunnel, Please Follow These Steps;
Download QGTunnel
Download and extract the qgtunnel package in the root directory of
your app:
curl https://s3.amazonaws.com/quotaguard/qgtunnel-latest.tar.gz | tar xz
Setup the Tunnel
Login to our Admin Dashboard and begin to setup
the tunnel.
At the top right, click Settings, then Setup. On the left, click Tunnel,
then Create Tunnel. You should reach this screen below.
For example, the example here assumes a MySQL server.
Remote Destination: tcp://hostname.for.your.server.com:3306
Local Port: 3306
Transparent: true
Encrypted: false
This setup assumes that your server is located at
“hostname.for.your.server.com” and is listening on port 3306 (the
default MySQL port).
Use the same port for the local port, unless you are using that port or
it is below 1024, then you will have to change this to some other port
(say 3307).
Transparent mode allows QuotaGuard to override the DNS
for hostname.for.your.server.com to 127.0.0.1, which redirects traffic
to the QGTunnel software. This means you can connect to
either hostname.for.your.server.com or 127.0.0.1 to connect through the
QGTunnel. More information is available on transparent mode as you
follow along in these instructions
Encrypted mode can be used to encrypt data end-to-end, but if your
protocol is already encrypted then you don’t need to spend time setting
it up. We have more details on end-to-end encryption as you follow along
in these instructions.
Creating the tunnels in the dashboard is for convenience. Please see the
last step (Harden your setup) for how to remove a dependency from your
system.
Change your code (maybe)
You may have to change your code to connect through QGTunnel.
With transparent mode, and when using the same local and remote port,
you should not have to change your code.
Without transparent mode, you will want to connect to 127.0.0.1:3306 (in
this example). If you changed the local port, then you will need to
change the port number to match.
Change your Procfile
Heroku Users: You have a procfile even if it’s not explicitly in your
code base. To find it, log into the Heroku dashboard, click on the
Resources tab, and you will see a list of your dyno processes. The text
you see (like web npm start) next to each one acts as your Procfile if
you do not have one explicitly in your code base.
Modify your app Procfile to prepend the QGTunnel application to your
standard commands:
Before:
web: bundle exec unicorn -p $PORT -c ./config/unicorn.rb
After:
web: bin/qgtunnel bundle exec unicorn -p $PORT -c ./config/unicorn.rb
Deploy
Commit and deploy your changes. Be sure to add bin/qgtunnel. If you
are using transparent mode, be
sure vendor/nss_wrapper/libnss_wrapper.so is also committed.
(Optional) If problems arise…
By default all fatal errors encountered by the qgtunnel will be logged
to your logs.
If this information is not enough you can enable verbose output mode by
setting QGTUNNEL_DEBUG environment variable to true and restart the
application while watching the logs.
Send any information in the logs (please redact any credentials,
including your QuotaGuard connection URL) to
our Support so we can help figure out
the problem.
IMPORTANT: Harden your setup.
This step is highly recommended as we do not have any SLA on our
website, which can be out due to maintenance at any time.
By default qgtunnel will try to fetch configuration from the QuotaGuard
API, but it also supports local configuration.
You can download a configuration file from the Dashboard by
pressing Download configuration on the Tunnel page.
Place the downloaded file into the root directory of your project under
the .qgtunnel filename, commit and deploy.
With this file your application will not depend on the availability of
our website during application startup.
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 our Support and we'll help you out.