How to Connect to MongoDB using QuotaGuard

    Table of contents

    We have lots of users that use MongoDB through our proxy servers. We suggest you go with the SOCKS proxy using our QGTunnel software.

    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 Choosing 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


    QGTunnel 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).

    Additionally, many languages support SOCKS5 proxies natively or via an 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.

    1) Download QGTunnel

    Download and extract the qgtunnel package in the root directory of your app:

    $ curl | tar xz

    2) Setup the Tunnel

    Login to our Admin Dashboard and go the Tunnels page to setup the tunnel.

    Click Create a Tunnel. You should reach this screen below.


    A Note About Mongodb+Srv URL

    If you are connecting with a mongodb+srv URL (eg: mongodb+srv:// then you can lookup your cluster’s shards here:

    Be sure to prepend your cluster address with mongodb._tcp (_eg: This will produce the hostnames of your shards (_eg:,, and cluster0-shard-00-02.abc123.mongodb.net_).

    You will then need to create a tunnel for each shard.

    Remote Destinations:
    *  tcp:// 
    *  tcp://
    ​*  tcp://
    Local Port: 27017
    Transparent: true
    Encrypted: false

    This setup assumes that the remote mongodb server is listening on port 27017. This is usually the default port.

    Transparent mode allows QGTunnel to override the DNS for to localhost, which redirects traffic to the QGTunnel software.

    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 believe mongodb is already encrypted, but you should double check.

    Not using mongodb+srv?

    If you are not using a mongodb+srv URL, please let us know what your connection URL looks like and we can help you set that up too. Send us an email at QuotaGuard Support.

    3) Change Your Code to Connect Through the Tunnel (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. You can also connect to

    Without transparent mode, you will want to connect to (like in this example). If you changed the local port, then you will need to change the port number to match.

    4) 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:


    web: your-application your arguments  


    web: bin/qgtunnel your-application your arguments  

    Heroku Users: If you do not have a Procfile, then Heroku is using a default setup in place of the Procfile based on the framework or language you are using. You can usually find this information on the Overview tab of the application in Heroku’s dashboard. It is usually under the heading “Dyno Information”.

    5) Environment Variable

    Setup the environment variable QUOTAGUARDSTATIC_URL or QUOTAGUARDSHIELD_URL to be equal to your Connection URL in the Setup page of our dashboard. Be sure to use the QUOTAGUARDSHIELD_URL for QuotaGuard Shield subscriptions and QUOTAGUARDSTATIC_URL for QuotaGuard Static subscriptions.

    If you added us from a cloud provider (Azure, Cloudfoundry, Heroku, AWS, IBM Cloud, Pivotal, etc.) then this is usually done for you.

    Please note that QGTunnel handles converting the HTTP URL and port to the SOCKS5 URL and port. So either of the connection URLs will work.

    6) Deploy

    Commit and deploy your changes. Be sure to add bin/qgtunnel.

    If you are using transparent mode, be sure vendor/nss_wrapper/ is also committed.

    7) (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.

    On Heroku, for example, you enable QGTunnel’s debug from the Heroku CLI with:

    heroku config:set QGTUNNEL_DEBUG=true

    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 with you.

    8) 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 Tunnels 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.

    Ready to Get Started?

    Get in touch or create a free trial account