configurable-http-proxy

configurable-http-proxy (CHP) provides you with a way to update and manage a proxy table using a command line interface or REST API. It is a simple wrapper around [node-http-proxy][]. node-http-proxy is an HTTP programmable proxying library that supports websockets and is suitable for implementing components such as reverse proxies and load balancers. By wrapping node-http-proxy, configurable-http-proxy extends this functionality to [JupyterHub] deployments.

Table of Contents

• Install
• Usage
  • Starting the proxy
  • Setting a default target
  • Command-line options
• Using the REST API
  • REST API Basics
  • Authenticating via passing a token
  • Getting the routing table
  • Adding new routes
  • Deleting routes
• Custom error pages
  • Setting the path for custom error pages
  • Setting a target for custom error handling
• Host-based routing
• Troubleshooting

Install

Prerequisite: Node.js ≥ 10

If you're installing configurable-http-proxy in Linux, you can follow the instruction of nodesource to install arbitrary version of Node.js.

To install the configurable-http-proxy package globally using npm:

npm install -g configurable-http-proxy

To install from the source code found in this GitHub repo:

git clone https://github.com/jupyterhub/configurable-http-proxy
cd configurable-http-proxy
npm install  # Use 'npm install -g' for global install

[Return to top][]

Usage

The configurable proxy runs two HTTP(S) servers:

• The public-facing interface to your application (controlled by --ip, --port)
  • listens on all interfaces by default.
• The inward-facing REST API (--api-ip, --api-port)
  • listens on localhost by default
  • The REST API uses token authorization, where the token is set in the CONFIGPROXY_AUTH_TOKEN environment variable.

[Return to top][]

Starting the proxy

configurable-http-proxy [options]

where [options] are the command-line options described below.

[Return to top][]

Setting a default target

The default target is used when a client has requested a URL for which there is no routing target found in the proxy table. To set a default target, pass the command line option, --default-target, when starting the configurable proxy:

configurable-http-proxy --default-target=proto://host[:port]

For example:

configurable-http-proxy --default-target=https://localhost:8888

[Return to top][]

Command-line options

Usage: configurable-http-proxy [options]

Options:
  -V, --version                      output the version number
  --ip                   Public-facing IP of the proxy
  --port  (defaults to 8000)      Public-facing port of the proxy
  --ssl-key                 SSL key to use, if any
  --ssl-cert               SSL certificate to use, if any
  --ssl-ca                  SSL certificate authority, if any
  --ssl-request-cert                 Request SSL certs to authenticate clients
  --ssl-reject-unauthorized          Reject unauthorized SSL connections (only meaningful if --ssl-request-cert is given)
  --ssl-protocol       Set specific SSL protocol, e.g. TLSv1_2, SSLv3
  --ssl-ciphers             `:`-separated ssl cipher list. Default excludes RC4
  --ssl-allow-rc4                    Allow RC4 cipher for SSL (disabled by default)
  --ssl-dhparam        SSL Diffie-Helman Parameters pem file, if any
  --api-ip                       Inward-facing IP for API requests (default: "localhost")
  --api-port                      Inward-facing port for API requests (defaults to --port=value+1)
  --api-ssl-key             SSL key to use, if any, for API requests
  --api-ssl-cert           SSL certificate to use, if any, for API requests
  --api-ssl-ca              SSL certificate authority, if any, for API requests
  --api-ssl-request-cert             Request SSL certs to authenticate clients for API requests
  --api-ssl-reject-unauthorized      Reject unauthorized SSL connections (only meaningful if --api-ssl-request-cert is given)
  --client-ssl-key          SSL key to use, if any, for proxy to client requests
  --client-ssl-cert        SSL certificate to use, if any, for proxy to client requests
  --client-ssl-ca           SSL certificate authority, if any, for proxy to client requests
  --client-ssl-request-cert          Request SSL certs to authenticate clients for API requests
  --client-ssl-reject-unauthorized   Reject unauthorized SSL connections (only meaningful if --client-ssl-request-cert is given)
  --default-target             Default proxy target (proto://host[:port])
  --error-target               Alternate server for handling proxy errors (proto://host[:port])
  --error-path