Pivotal Web Services End of Availability Announced
For more information, see Frequently Asked Questions.

Page last updated:

QuotaGuard Static enables a PWS app to route outbound traffic through a static IP. You can provide this IP address to an API partner for IP-based allowlists and open your own firewall to access internal resources.

QuotaGuard Static is language and platform agnostic. It supports Ruby, Python, Node.js, Scala, Java, and other languages. QuotaGuard Static comes in three flavors:

Outbound. Included in all plans.

  1. An HTTP proxy for accessing HTTP and HTTPS web services
  2. A SOCKS5 proxy for TCP-level routing such as accessing a database or LDAP server

Inbound. Included in the Micro plan and above.

  1. A HTTP or HTTPS reverse proxy for accessing your PWS app on a static IP

Managing Services

For information about creating and binding a service instance, see Managing Service Instances with the cf CLI.

What are My IPs?

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

Once QuotaGuard Static is bound to your app, it updates the VCAP_SERVICES environment variable with an entry that contains the credentials as well as other information needed to access your proxy. See Delivering Service Credentials to an Application and VCAP_SERVICES Environment Variable.

The VCAP_SERVICES entry looks similar to the following:

  "quotaguard": [
      "name": "QuotaGuardInstance",
      "label": "quotaguard",
      "tags": [],
      "plan": "starter",
      "credentials": {
        "QUOTAGUARDSTATIC_URL": "http://username:password@proxy.quotaguard.com:9293"

To start using QuotaGuard Static, configure your app to use the proxy URL in the QUOTAGUARDSTATIC_URL parameter.

HTTP vs. SOCKS5 Proxy

The first decision you must make as a developer is whether to target our HTTP or SOCKS proxy. SOCKS handles TCP-level traffic, but the setup of SOCKS is more complex. As a general rule of thumb, use HTTP if accessing a web service; otherwise, use SOCKS.

Note: The SOCKS server is accessible on port 1080, not the port specified in your QUOTAGUARDSTATIC_URL variable (port 9293).

Example use cases

  • For accessing an HTTP or HTTPS API (for example, https://api.github.com/users/octocat/orgs), use HTTP Proxy.
  • For accessing a MySQL database, use SOCKS.

Using QuotaGuard Static with Your App

Ruby and Rails

Ruby has an excellent REST client that 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"


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

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

Python and 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, which means that you can choose when to route traffic through your static IP.

import requests
import os

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

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

Using with urllib2

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

In your app initialization, set the http_proxy variable to match 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, do the following:

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


Accessing an HTTP API with Node.js

To access an HTTP API, you can use the standard HTTP library in Node.js. Ensure that 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.quotaguard.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) { 
  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. To install this module, run the npm install request command.

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) {

request(options, callback);

Accessing a MySQL Database Using SOCKS Proxy in Node.js

If you want to use a SOCKS proxy in Node.js, we recommend installing socksjs because this SOCKS module supports authentication:

npm install socksjs

The following example shows how to create a connection to a SOCKS connection to our proxy and use it for all MySQL requests.

var mysql = require('mysql2'),
    url = require('url'),
    SocksConnection = require('socksjs');

var remote_options = {
    port: 3306

var proxy = url.parse(process.env.QUOTAGUARDSTATIC_URL),
    auth = proxy.auth,
    username = auth.split(':')[0],
    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: 'dbuser',
    database: 'dbname',
    password: 'dbpassword',
    stream: sockConn
dbConnection.query('SELECT 1+1 as test1;', function(err, rows, fields) {
    if (err) throw err;

    console.log('Result: ', rows);


PHP cURL is the easiest way to make HTTP requests through QuotaGuard Static. The example below 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.


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.quotaguard.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_PROXYUSERPWD, $proxyAuth);
  $response = curl_exec($ch);
  return $response;

$res = lookup();



The JVM allows you to configure socksProxyHost. The example below uses Apache HttpClient. The same configuration applies to other JVM-based clients.

import java.net.*;
import java.io.*;

public class HelloWorld {
    public static void main(String []args) throws IOException {
        URL proxyUrl = new URL(System.getenv("QUOTAGUARDSTATIC_URL"));
        String userInfo = proxyUrl.getUserInfo();
        String user = userInfo.substring(0, userInfo.indexOf(':'));
        String password = userInfo.substring(userInfo.indexOf(':') + 1);

        URLConnection conn = null;
        System.setProperty("http.proxyHost", proxyUrl.getHost());
        System.setProperty("http.proxyPort", Integer.toString(proxyUrl.getPort()));

        Authenticator.setDefault(new Authenticator() {
                protected PasswordAuthentication getPasswordAuthentication() {
                    return new PasswordAuthentication(user, password.toCharArray());

        URL url = new URL("http://ip.quotaguard.com");
        conn = url.openConnection();
        BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));

        String inputLine;
        while ((inputLine = in.readLine()) != null)


You can check available proxy-related JVM settings here.


The Clojure clj-http library allows you to configure a proxy for an HTTP request. The example below shows you how to use this with the add-on:

(defn get-quota-guard []
  (let [proxy-uri (java.net.URI. (env :quotaguardstatic-url))]
    (client/get "http://httpbin.org/ip"
      {:proxy-host (.getHost proxy-uri)
       :proxy-port (.getPort proxy-uri)
       :headers {
         (str "Basic " (.encode (sun.misc.BASE64Encoder.)
           (.getBytes (.getUserInfo proxy-uri))))}})))

Is the HTTP Proxy Secure When Accessing HTTPS Services?

Yes. You can access HTTPS services through the HTTP proxy whilst still getting full SSL and TLS security. When you make a request using 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 opens a tunnel between your client and the endpoint, allowing your client to negotiate a standard SSL session with the endpoint. Once this is negotiated, all traffic sent between your client and the endpoint will be encrypted as if you had connected directly with it.

We are also testing HTTPS proxy endpoints. Please contact us if you want to trial it. With an HTTPS endpoint, your initial CONNECT request is also encrypted. This protects the proxy credentials and remote hostname but requires an additional TLS handshake. Please note that HTTPS endpoints are supported only by libcurl-based HTTP client libraries. We recommend checking if your language has bindings for it.

SOCKS Proxy Setup

QuotaGuard Static provides two ways for setting up SOCKS5 proxy integration in your app: SOCKS5 tunnels and a wrapper script.

SOCKS5 tunnels:

  • Work on a per-host basis.
  • Compatible with all programming environments.
  • Support advanced configurations such as transparent mode and encryption.

Wrapper script:

  • Proxies all connections, with optional constraints by IP.
  • Incompatible with some threaded environments and environments with event loops. Does not 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 a SOCKS5 Tunnel

The SOCKS5 tunnel app allows you to create a local tunnel for your app. All traffic to the local port will be forwarded through QuotaGuard proxies. You must set up a separate tunnel configuration for every host you want to proxy. To get started with the tunnel, follow these steps:

  1. Download and extract qgtunnel in your app directory:

    $ curl https://s3.amazonaws.com/quotaguard/qgtunnel-latest.tar.gz | tar xz
  2. Add the tunnel app to your standard startup commands as follows:


    bundle exec unicorn -p $PORT -c ./config/unicorn.rb


    bin/qgtunnel bundle exec unicorn -p $PORT -c ./config/unicorn.rb
  3. Create your tunnel configuration through DATABASE_URL or QuotaGuard dashboard.

  4. Commit and deploy these changes.


If your app relies on the DATABASE_URL environment variable, then you can use automatically generated configuration without performing additional configuration steps. For example, if your DATABASE_URL is postgres://foo:bar@ec2-10-10-10-1.compute-1.amazonaws.com:5432/baz , then the tunnel will be listening on port 5432 of your dyno and all connections to this port will be forwarded to ec2-10-10-10-1.compute-1.amazonaws.com:5432 through the SOCKS5 proxy. In this mode, the tunnel also enables transparent DNS override, which resolves the ec2-10-10-10-1.compute-1.amazonaws.com DNS name to the localhost address. All connections to this hostname will transparently go to the tunnel.

Custom Tunnel Configuration

  1. Open the QuotaGuard Static dashboard and navigate to the Tunnels section of the Setup page. You can open the dashboard from your PWS services page.

  2. On the Setup page, create a new tunnel configuration for the remote server by clicking Create Tunnel. For example, if you want to access an IP-allowed Postgres database located on ec2-10-10-10-1.compute-1.amazonaws.com, enter tcp://ec2-10-10-10-1.compute-1.amazonaws.com:5432 in Remote Destination and click Save. With this configuration, your tunnel will listen on the dyno’s port 5432 and route all traffic to ec2-10-10-10-1.compute-1.amazonaws.com through the SOCKS5 proxy. If you want to use a different local port, you can provide it explicitly in the configuration interface.

  3. Modify your app configuration to use localhost instead of the remote server. For the same Postgres example, change the connection string from postgres://user:pass@ec2-10-10-10-1.compute-1.amazonaws.com:5432 to postgres://user:pass@ You can also export your tunnel configuration to use it locally on your dyno without relying on QuotaGuard servers.

Debugging Tunnel Configuration

By default, all fatal errors encountered by qgtunnel are logged. If this information is insufficient, you can enable verbose output mode by setting the QGTUNNEL_DEBUG environment variable to true.

Local Tunnel Configuration

By default, qgtunnel tries to fetch configuration from the QuotaGuard API, but it also supports local configuration. You can download the configuration file from the tunnel setup interface by clicking Download configuration. To enable local mode, place the downloaded file into the root directory of your project under the .qgtunnel filename, commit, and deploy it.

Transparent Mode

If your app depends on DNS-based discovery or needs a local tunnel to be resolvable through the DNS name, regular tunneling mode is not sufficient. In this case, you should enable transparent mode for the tunnel in your configuration. In transparent mode, the tunnel app alters DNS queries from your app to the local tunnel address.

For example, if you want to use the tunnel to access a replicated MongoDB cluster with 3 replicas located on the rs01.mongodb.net:52115, rs02.mongodb.net:52115, and rs1.mongodb.net:52115 hosts, you need to create 3 separate tunnels for each host on port 52115 in transparent mode. Once this is done, the tunnel app will alter DNS resolution 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 Socksify Wrapper

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

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

  1. Download and extract the wrapper in your app directory:

    $ curl https://s3.amazonaws.com/quotaguard/quotaguard-socksify-latest.tar.gz | tar xz
  2. Add the wrapper to your standard startup commands. For example:

    bin/qgsocksify bundle exec unicorn -p $PORT -c ./config/unicorn.rb
  3. Add all extracted files except QUOTAGUARD-LICENSE.txt, which can be included in .gitignore, to your Git repository.

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

Controlling What Traffic Goes Through the Socksify Wrapper

You can provide a standard subnet mask to route traffic only to certain IP subnets through the QUOTAGUARDSTATIC_MASK environment variable. The mask supports sub-network specifications (for example,, single addresses (for example,, host names (for example, ftp.example.org), or domain names (for example, .example.org). A domain name specification will match any host in that domain.


All outbound traffic to 100.30.68.* is routed through your static IPs. Multiple masks can be provided using comma-separated mask values:


Inbound Proxy Setup

Inbound Proxy allows you to always access your app on a static IP address. This feature is available on the Micro plan and above.

WARNING: This should not be used as a replacement for a DNS entry resolving a custom domain to your PWS app.

Once you have provisioned the add-on, you just need to visit the QuotaGuard Static dashboard to complete your setup. You can do this from your PWS services page.

Navigate to the Setup page and enter the full URL of your app. We then create a unique URL for you that you can use to access your web app, for example, a62b1d0b4983db763450411fd393b3ce-eu-west-1.getstatica.com.

This corresponds to a DNS A record that resolves to one of your two QuotaGuard Static IPs. You should include both IP addresses in all firewall rules or allowlists as we may swap between the IP addresses at any time.

Open this URL in your browser to see your own web app.

Note: It may take up to 10 minutes for configuration and DNS changes to propagate.

In your firewall you can now just open access to the two QuotaGuard Static IPs to work with your cloud app.

SSL Setup

Our self-service automated setup supports SSL by default. For custom domains, you have to upload a valid certificate to enable SSL. In both cases, SSL is terminated on QuotaGuard proxies.

Monitoring and Logging

Real-time and historical usage stats can be displayed on the QuotaGuard Static dashboard, which is accessible from your PWS service page.


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


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 provision these IP addresses only on request. Please contact us if you want a dedicated static IP address.

What happens when I reach my usage limit?

To ensure we grow in harmony with your app, QuotaGuard Static initially operates 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 by email 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 from your PWS services page.

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 provide only load-balanced, highly available services. Load balancing our nodes allows one node to fail or be brought down for maintenance with no impact to your app. Each IP you are given represents one proxy node that is running behind a load balancer.

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. (Its installation details are provided on this page.) If you are using Node.js, you can also configure the SOCKS proxy in your JavaScript code without using the wrapper. (Details are also available on this page.)


All QuotaGuard Static support and runtime issues should be submitted through the PWS Support channels. Non-support related issues or product feedback is welcome at support@quotaguard.com or by visiting QuotaGuard.com.