global-tunnel-ng

What is global-tunnel-ng?

The global-tunnel-ng npm package is used to configure global HTTP/HTTPS proxy settings for Node.js applications. It allows you to route all HTTP and HTTPS requests through a proxy server, which can be useful for various purposes such as accessing resources behind a firewall, anonymizing requests, or debugging network traffic.

What are global-tunnel-ng's main functionalities?

Setting up a global proxy

This feature allows you to set up a global proxy for all HTTP and HTTPS requests in your Node.js application. The `initialize` method configures the proxy server's host and port, and optionally, the number of sockets to use.

const globalTunnel = require('global-tunnel-ng');
globalTunnel.initialize({
  host: 'proxy.example.com',
  port: 8080,
  sockets: 50 // optional pool size for sockets
});

Disabling the global proxy

This feature allows you to disable the global proxy settings that were previously configured. The `end` method stops routing requests through the proxy server.

globalTunnel.end();

Customizing proxy settings

This feature allows you to customize the proxy settings further by providing optional parameters such as authentication credentials, protocol, and tunneling. The `initialize` method accepts these additional options to configure the proxy server as needed.

globalTunnel.initialize({
  host: 'proxy.example.com',
  port: 8080,
  proxyAuth: 'user:password', // optional authentication
  protocol: 'https', // optional protocol
  tunnel: true // optional tunneling
});

Other packages similar to global-tunnel-ng

proxy-agent

The proxy-agent package provides a flexible way to configure proxy settings for HTTP, HTTPS, and other protocols. It supports various proxy protocols such as HTTP, HTTPS, SOCKS, and PAC. Compared to global-tunnel-ng, proxy-agent offers more flexibility in terms of supported protocols and configuration options.

tunnel

The tunnel package is used to create HTTP and HTTPS agents that route requests through a proxy server. It supports both HTTP and HTTPS proxies and provides options for tunneling. Compared to global-tunnel-ng, the tunnel package focuses more on creating custom agents for specific requests rather than setting global proxy settings.

https-proxy-agent

The https-proxy-agent package is specifically designed to route HTTPS requests through an HTTP or HTTPS proxy server. It provides a simple and efficient way to configure proxy settings for HTTPS requests. Compared to global-tunnel-ng, https-proxy-agent is more specialized and focused on HTTPS requests.

README

global-tunnel

Configures the global http and https agents to use an upstream HTTP proxy.

Works transparently to tunnel modules that use node's default http.request() method as well as the popular request module.

Installation

You can install this package by just executing the following:

npm install global-tunnel-ng

Usage

To make all HTTP and HTTPS connections go through an outbound HTTP proxy:

var globalTunnel = require('global-tunnel-ng');

globalTunnel.initialize({
  host: '10.0.0.10',
  port: 8080,
  proxyAuth: 'userId:password', // optional authentication
  sockets: 50 // optional pool size for each http and https
});

This will use the CONNECT method for HTTPS requests and absolute-URIs for HTTP requests, which is how many network proxies are configured.

Optionally, to tear-down the global agent and restore node's default global agents:

globalTunnel.end();

Any active connections will be allowed to run to completion, but new connections will use the default global agents.

Advanced Usage

Options

The complete list of options to globalTunnel.initialize:

• host - the hostname or IP of the HTTP proxy to use
• port - the TCP port to use on that proxy
• connect (optional) controls what protocols use the CONNECT method. It has three possible values (strings):
  • neither - don't use CONNECT; just use absolute URIs
  • https - (the default) only use CONNECT for HTTPS requests
  • both - use CONNECT for both HTTP and HTTPS requests
• protocol - the protocol that the proxy speaks, either http: or https:.
• proxyAuth - (optional) to authenticate userId:password
• sockets - (optional) maximum number of TCP sockets to use in each pool. There are two pools: one for HTTP and one for HTTPS. Uses node's default (5) if falsy.

Variations

Here's a few interesting variations on the basic config.

Absolute URI Proxies

Another common proxy configuration is one that expects clients to use an absolute URI for the Request-URI for all HTTP and HTTPS requests. This is common for networks that use a proxy for security scanning and access control.

What does this mean? It means that instead of ...

GET / HTTP/1.1
Host: example.com

... your proxy expects ...

GET https://example.com/ HTTP/1.1

You'll need to specify connect: 'neither' if this is the case. If the proxy speaks HTTP (i.e. the connection from node --> proxy is not encrypted):

globalTunnel.initialize({
  connect: 'neither',
  host: '10.0.0.10',
  port: 3128
});

or, if the proxy speaks HTTPS to your app instead:

globalTunnel.initialize({
  connect: 'neither',
  protocol: 'https:',
  host: '10.0.0.10',
  port: 3129
});

Always-CONNECT Proxies

If the proxy expects you to use the CONNECT method for both HTTP and HTTPS requests, you'll need the connect: 'both' option.

What does this mean? It means that instead of ...

GET https://example.com/ HTTP/1.1

... your proxy expects ...

CONNECT example.com:443 HTTP/1.1

Be sure to set the protocol: option based on what protocol the proxy speaks.

globalTunnel.initialize({
  connect: 'both',
  host: '10.0.0.10',
  port: 3130
});

HTTPS configuration

EXPERIMENTAL

If tunnelling both protocols, you can use different HTTPS client configurations for the two phases of the connection.

globalTunnel.initialize({
  connect: 'both',
  protocol: 'https:'
  host: '10.0.0.10',
  port: 3130,
  proxyHttpsOptions: {
    // use this config for app -> proxy
  },
  originHttpsOptions: {
    // use this config for proxy -> origin
  }
});

Auto-Config

If globalTunnel.initialize doesnt receive a configuration as its first parameter the http_proxys and http_proxy environment variables will be used.

If these are missing the npm configurations https-proxy, http-proxy, proxy will be used instead.

If no environment variables or npm configurations are found nothing will be done.

Retrieving proxy URL, parsed config and proxy status

As the module does some extra job determining the proxy (including parsing the environment variables) and does some normalization (like defaulting the protocol to http:) it may be useful to retrieve the proxy URL used by the module.

The property globalTunnel.proxyUrl is the URL-formatted (including the optional basic auth if provided) proxy config currently in use. It is null if the proxy is not currently enabled.

Similarly, the globalTunnel.proxyConfig contains the entire parsed and normalized config.

The property globalTunnel.isProxying contains the information about whether the global proxy is on or off.

Compatibility

Any module that doesn't specify an explicit agent: option to http.request will also work with global-tunnel.

The unit tests for this module verify that the popular request module works with global-tunnel active.

For untested modules, it's recommended that you load and initialize global-tunnel first. This way, any copies of http.globalAgent will point to the right thing.

Contributing

If you'd like to contribute to or modify global-tunnel, here's a quick guide to get you started.

Development Dependencies

• node.js >= 0.10

Set-Up

Download via GitHub and install npm dependencies:

git clone [e-mail]:np-maintain/global-tunnel.git
cd global-tunnel
npm install

Testing

Testing is with the mocha framework. Tests are located in the test/ directory.

To run the tests:

npm test

Support

As this is a hard fork, you may still contact the given contacts below.

Email GoInstant Support or stop by #goinstant on freenode.

For responsible disclosures, email GoInstant Security.

To file a bug or propose a patch, please use github directly.

Legal

© 2014 GoInstant Inc., a salesforce.com company

Licensed under the BSD 3-clause license.