QGTunnel Setup Guide for Heroku and SMTP
Table of contents
To setup QGTunnel for QuotaGuard via Heroku with a SMTP endpoint connection, we suggest you go with the SOCKS proxy using our QGTunnel software. Here are some setup instruction to get you started:
Step 1. Download QGTunnel and Save to Root of Your Project
curl https://s3.amazonaws.com/quotaguard/qgtunnel-latest.tar.gz | tar xz
Step 2. Log in to QuotaGuard Dashboard and Create the Tunnel
Using the Heroku CLI you can log into our dashboard with the following command:
heroku addons:open quotaguardstatic
Or if you prefer, you can login from the Heroku dashboard by clicking on QuotaGuard Static on the resources tab of your application.
Once you are logged into our dashboard, in the top right menu, go to Setup (Gear Icon), click on QGTunnel Configuration, then “Create a Tunnel”.
Fill in the following data:
Remote Destination: tcp://hostname.for.your.server.com:25
Local Port: 25
Transparent: true
Encrypted: false
This setup assumes that the remote SMTP server is located at hostname.for.your.server.com and is listening on port 25. This is usually the default port.
The Local Port is the port number that QGTunnel will listen on. In this example we set it to 2525, because port 25 is in the reserved port range (0-1023) and may not be accessible on your platform.
Transparent mode allows QGTunnel 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 tunnel.
Encrypted mode can be used to encrypt data end-to-end for protocols that are not encrypted already.
Step 3: Change Your Code to Connect Through the Tunnel
With transparent mode you will only have to change to connect to port 2525 instead of 22. You can also connect to 127.0.0.1:2525.
Without transparent mode, you will want to connect to 127.0.0.1:2525.
Step 4: Change your Startup Code:
Change the startup code that starts up your application. In Heroku this is done with a Procfile. Basically you just need to prepend your startup code with “bin/qgtunnel”.
So for a Procfile that was previously:
web: your-application your arguments
you would now want:
web: bin/qgtunnel your-application your arguments
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”.
Step 5: Commit and Push your Code
Be sure that the file bin/qgtunnel
is added to your repository.
If you are using transparent mode, be sure that vendor/nss_wrapper/libnss_wrapper.so
is also added to your repository.
If you are not using transparent mode, you will want to set the environment variable QGTUNNEL_DNSMODE to DISABLED to avoid seeing an error message in your logs.
Step 6: Troubleshoot Any Problems
If you have problems, enable the environment variable QGTUNNEL_DEBUG=true
and then restart your application while watching the logs.
If you can’t figure it out, send QuotaGuard Support the information in the logs. Please redact any sensitive information, including your QuotaGuard connection URL because it contains your password.
Step 7: VERY IMPORTANT
After you get everything working, we suggest you download your QGTunnel configuration from our dashboard as a .qgtunnel file and put that in the root of your project. This prevents your project from relying on the QuotaGuard website during startup.
Alternatively you can put the contents of the downloaded configuration file in a QGTUNNEL_CONFIG environment variable.
By following these steps, you can set up QGTunnel for Heroku SMTP connections using QuotaGuard’s Static IP services. If you have any questions or issues, contact QuotaGuard Support for assistance.