QuotaGuard Static

This add-on is operated by Teachmatic Ltd

Trusted Enterprise class Static IPs

QuotaGuard Static

Last Updated: 07 May 2015

Table of Contents

QuotaGuard Static is an add-on that allows you to route outbound traffic through a static IP address on Heroku. You can provide this IP address to an API partner for IP based whitelisting and open your own firewall to access internal resources.

QuotaGuard Static is accessible as an HTTP or SOCKS5 proxy so is language and platform agnostic. There is native support across Ruby, Python, Node.js, Scala, Java and every other mainstream language.

Provisioning the add-on

QuotaGuard Static can be added to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:create quotaguardstatic:starter
-----> Adding quotaguardstatic:starter to sharp-mountain-4005... done, v18 (free)
-----> Your static IPs are [10.11.12.13, 14.15.16.17]

Once QuotaGuard Static has been added a QUOTAGUARDSTATIC_URL setting will be available in the app configuration and will contain the full URL you should use to proxy your requests. This can be confirmed using the heroku config:get command.

$ heroku config:get QUOTAGUARDSTATIC_URL
http://user:pass@static.quotaguard.com:9293

After installing QuotaGuard Static the application should be configured to fully integrate with the add-on.

It may take up to 5 minutes for new users to be propagated to the SOCKS5 proxy instances so please be patient.

What are my IPs?

You are provided with two static IP addresses as part of our fault tolerant, load balanced service. Traffic may route through either one at any time.

Your two IP addresses will be printed on the command line when you provision the add-on or you can view them on your QuotaGuard Static dashboard, accessible from your Heroku App page.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service. This should be used for initial testing only as usage will count against your daily limits.

Though less portable it’s also possible to set local environment variables using export QUOTAGUARDSTATIC_URL=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add theQUOTAGUARDSTATIC_URL value retrieved from heroku config to .env.

$ heroku config -s | grep QUOTAGUARDSTATIC_URL >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

HTTP vs. SOCKS5 proxy

The first decision you must make as a developer is whether to target our HTTP or SOCKS proxy. SOCKS is more versatile as it handles TCP level traffic but the setup steps are more involved than the HTTP proxy. Our general rule of thumb is use HTTP if accessing a web service otherwise use SOCKS.

Please note the SOCKS server is accessible on port 1080, not the port specified in your QUOTAGUARDSTATIC_URL variable (port 9293).

Example use cases

  1. Accessing an HTTP or HTTPS API (e.g. https://api.github.com/users/octocat/orgs) ==> HTTP Proxy
  2. Accessing a MySQL database ==> SOCKS

Using with Ruby/Rails

Ruby has an excellent REST client that easily allows you to specify an HTTP proxy. You can run the below example in an irb session and verify that the final IP returned is one of your two static IPs.

require "rest-client"

RestClient.proxy = ENV["QUOTAGUARDSTATIC_URL"]

res = RestClient.get("http://ip.jsontest.com")

puts "Your Static IP is: #{res.body}"

Using with Python/Django

Using with the Requests library

Requests is a great HTTP library for Python. It allows you to specify an authenticated proxy on a per request basis so you can pick and choose when to route through your static IP.

import requests
import os

proxies = {
"http": os.environ['QUOTAGUARDSTATIC_URL'],
"https": os.environ['QUOTAGUARDSTATIC_URL']
}

res = requests.get("http://ip.jsontest.com/", proxies=proxies)
print res.text

Using with urllib2

urllib2 is a more basic library used for HTTP communication in Python and uses environment variables to set a proxy service.

In your application initialization you should set the http_proxy variable to match the QUOTAGUARDSTATIC_URL.

# Assign QuotaGuard to your environment's http_proxy variable
os.environ['http_proxy'] = os.environ['QUOTAGUARDSTATIC_URL']

To test in the Python interpreter

import urllib2, os
os.environ['http_proxy'] = os.environ['QUOTAGUARDSTATIC_URL']
url = 'http://ip.jsontest.com/'
proxy = urllib2.ProxyHandler()
opener = urllib2.build_opener(proxy)
in_ = opener.open(url)
res = in_.read()
print res

Using with Node.js

Accessing an HTTP API with Node.js

To access an HTTP API you can use the standard HTTP library in Node.js but must ensure you correctly set the “Host” header to your target hostname, not the proxy hostname.

var http, options, proxy, url;

http = require("http");

url = require("url");

proxy = url.parse(process.env.QUOTAGUARDSTATIC_URL);
target  = url.parse("http://ip.jsontest.com/");

options = {
  hostname: proxy.hostname,
  port: proxy.port || 80,
  path: target.href,
  headers: {
    "Proxy-Authorization": "Basic " + (new Buffer(proxy.auth).toString("base64")),
    "Host" : target.hostname
  }
};

http.get(options, function(res) {
  res.pipe(process.stdout);
  return console.log("status code", res.statusCode);
});

Accessing an HTTPS API with Node.js

The standard Node.js HTTPS module does not handle making requests through a proxy very well. If you need to access an HTTPS API we recommend using the Request module (npm install request).

var request = require('request');

var options = {
    proxy: process.env.QUOTAGUARDSTATIC_URL,
    url: 'https://api.github.com/repos/joyent/node',
    headers: {
        'User-Agent': 'node.js'
    }
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

Accessing a MySQL Database using SOCKS Proxy in Node.js

To use a SOCKS proxy for any reason in Node.js we recommend socksjs as this is one of the only Node.js SOCKS modules to support authentication.

npm install socksjs

This sample creates a connection to a SOCKS connection to our proxy and uses that for all MySQL requests.

var mysql = require('mysql2');
var url = require("url");
var SocksConnection = require('socksjs');
var remote_options = {
host:'mysql.db.hostname',
port: 3306
};
var proxy = url.parse(process.env.QUOTAGUARDSTATIC_URL);
var auth = proxy.auth;
var username = auth.split(":")[0]
var pass = auth.split(":")[1]

var sock_options = {
host: proxy.hostname,
port: 1080,
user: username,
pass: pass
}
var sockConn = new SocksConnection(remote_options, sock_options)
var dbConnection = mysql.createConnection({
user: 'test',
database: 'test',
password: 'testpw',
stream: sockConn
});
dbConnection.query('SELECT 1+1 as test1;', function(err, rows, fields) {
if (err) throw err;

console.log('Result: ', rows);
sockConn.dispose();
});
dbConnection.end();

Using with PHP

PHP cURL is the easiest way to make HTTP requests via QuotaGuard Static. This example assumes that you have set the QUOTAGUARDSTATIC_URL environment variable which is automatically set for you when you provision the add-on.

The IP address printed on screen will be one of your two static IP addresses, run it a couple of times and you’ll probably see the other one too.

<?php

function lookup(){
  $quotaguard_env = getenv("QUOTAGUARDSTATIC_URL");
  $quotaguard = parse_url($quotaguard_env);

  $proxyUrl       = $quotaguard['host'].":".$quotaguard['port'];
  $proxyAuth       = $quotaguard['user'].":".$quotaguard['pass'];

  $url = "http://ip.jsontest.com/";

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_PROXY, $proxyUrl);
  curl_setopt($ch, CURLOPT_PROXYAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_PROXYUSERPWD, $proxyAuth);
  $response = curl_exec($ch);
  return $response;
}

$res = lookup();
print_r($res);

?>

Is the HTTP proxy secure when accessing HTTPS services?

Yes. You can access HTTPS services via the HTTP proxy whilst still getting full SSL/TLS security. When you make a request via the proxy to an HTTPS endpoint your client should transparently issue a CONNECT request rather than a basic GET request.

On receipt of this CONNECT request the proxy will open a tunnel between your client and the endpoint, allowing your client to negotiate a standard SSL session with the endpoint. Once negotiated all traffic sent between your client and the endpoint will be encrypted as if you had connected directly with them.

SOCKS proxy setup

QuotaGuard Static provides a wrapper script that transparently forwards all outbound TCP traffic through your Static IP.

The SOCKS wrapper is incompatible with Java, Play & Node.js. Please contact us for alternative options with these languages.

Installing the QuotaGuard Static socksify wrapper

Download and extract the wrapper in your app directory:

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

Now modify your app Procfile to prepend the wrapper to your standard commands:

 web: bin/qgsocksify bundle exec unicorn -p $PORT -c ./config/unicorn.rb

You should add all extracted files to your git repo except QUOTAGUARD-LICENSE.txt which can be gitignored.

$ echo "QUOTAGUARD-LICENSE.txt" >> .gitignore
$ git add bin/qgsocksify vendor/dante
$ git commit -m "Add QuotaGuard Static socksify"

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.

$ heroku config:set QUOTAGUARDSTATIC_MASK="100.30.68.0/24"

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:

$ heroku config:set QUOTAGUARDSTATIC_MASK="100.30.68.0/24,99.29.68.0/24"

Setting up MySQL access from Rails

This assumes that you have already followed the steps to download and install the SOCKS wrapper script as detailed in the section above.

To connect to a MySQL host via the proxy you need to add an extra line to your database.yml config file to ensure no connect_timeout is set. Without this option your app will not be able to connect to the database and will hang indefinitely.

The value is deliberately left out to force the mysql2 adapter to use nil as the timeout.

  connect_timeout:

Your full database.yml might look something like this (example values only).

common: &common
  adapter: mysql2
  username: secureuser
  password: securepassword
  encoding: utf8
  pool: 5
  connect_timeout:

development:
  <<: *common
  database: myapp_development

test:
  <<: *common
  database: myapp_test

production:
  <<: *common

Monitoring & logging

Real-time and historical usage stats can be displayed on the QuotaGuard Static Dashboard accessible from your Heroku Dashboard.

Dashboard

The QuotaGuard Static dashboard allows you to view your real-time and historical usage of every API.

The dashboard can be accessed via the CLI:

$ heroku addons:open quotaguardstatic
Opening quotaguardstatic for sharp-mountain-4005...

or by visiting the Heroku apps web interface and selecting the application in question. Select QuotaGuard Static from the Add-ons menu.

FAQs

Do you offer dedicated Static IPs?

Yes - dedicated IP addresses are available on request for subscriptions on the Enterprise plan and above. As they require dedicated infrastructure we only provision these on request so please contact us if you want a dedicated Static IP address.

What happens when I reach my usage limit?

To make sure we grow in harmony with your application QuotaGuard Static operates initially with a soft limit. When you reach your plan’s monthly usage limit your requests will continue going through but we will reach out to you via e-mail to ask that you upgrade your plan.

If you repeatedly exceed your limits without upgrading then hard limits may be placed on your account but this is a very last resort.

I’ve forgotten what my Static IPs are!

Both IPs are shown on your Dashboard which you can get to either from your Heroku Apps page or via the CLI.

Can I access your Brazilian instance in Sao Paulo?

QuotaGuard Static is deployed in the Heroku US & Europe regions and you are automatically assigned to an instance in the same region as your app. If you would like to use our South America instance located in Sao Paulo please contact us and we can manually relocate you. This will change your Static IP address.

$ heroku addons:open quotaguardstatic
Opening quotaguardstatic for sharp-mountain-4005...

Why have you given me two Static IP addresses?

We believe all apps should be built for scalability and high availability. Our commitment to this means we only provide load balanced, high availability services. Load balancing our nodes allows one node to fail or be brought down for maintenance with no impact to your application. Each IP you are given represents one proxy node that is running behind a load balancer.

What region does QuotaGuard Static run in?

We have instances in both the US and EU regions. When you provision the add-on you will be assigned Static IPs in the same region as your Heroku app ensuring we can always process your requests with an ultra low latency.

Can I access MySQL or Postgres through this?

Yes we have many users doing this. The easiest way for most languages is to use our SOCKS proxy wrapper(installation details higher up the page). If you are using Node.js you can also configure the SOCKS proxy in your Javascript code without using the wrapper (details also on this page).

QuotaGuard vs. QuotaGuard Static

We offer two products on Heroku, QuotaGuard and QuotaGuard Static.

QuotaGuard routes your traffic through a dynamic set of IP addresses that may change at any time and is intended for accessing APIs like Google Maps that restrict usage based on your IP address. It should be used if you want to access these APIs without your limit being shared with other Heroku apps.

QuotaGuard Static routes your traffic through a pair of static IP addresses that never change. It should be used if you need your traffic to pass through a known IP address for the purpose of firewall ingress rules or application whitelisting with a third party.

Please send us a mail if you’d like more guidance on what service fits your needs best.

Migrating between plans

Application owners can migrate at any time with no interruption to your service.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade quotaguardstatic:large
-----> Upgrading quotaguardstatic:large to sharp-mountain-4005... done, v18 ($90/mo)
       Your plan has been updated to: quotaguardstatic:large

Removing the add-on

QuotaGuard Static can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy quotaguardstatic
-----> Removing quotaguardstatic from sharp-mountain-4005... done, v20 (free)

Support

All QuotaGuard Static support and runtime issues should be submitted via the Heroku Support channels. Any non-support related issues or product feedback is welcome at feedback@teachmatic.com or by visiting QuotaGuard.com.