bash-proxy-config

bash-proxy-config: A script that facilitiates the setting and unsetting of upstream and local proxies, either for the current shell session, or individual commands. Also facilitates the starting of proxies.

Usage Examples

Specify that the current shell session should use the configured proxy named work for all non-local network requests:

# The following commands are equivalent:
proxy to:work
proxy for:nonlocal to:work

Specify that the curl command should be executed using the configured proxy named work:

proxy to:work curl https://github.com

Specify that the current shell session should use the configured proxy named work for all network requests, including localhost requests:

proxy for:all to:work

Specify that the current shell session should use no proxy:

proxy off

Specify that the curl command should be executed using the configured proxy named local when retrieving a local web page:

proxy to:local curl http://localhost/webpage

Specify that the current shell session should use the configured proxy named work for all non-local network requests, but execute the curl command using no proxy:

proxy to:work
proxy off curl https://github.com

Start the default proxy command defined by the configured proxy named work:

proxy listen:work

Start the FTP proxy command defined by the configured proxy named local:

proxy listen:local:ftp

Start the HTTP proxy command defined by the configured proxy named 8081, and proxy the outbound network calls from the proxy to an upstream configured proxy named local:

proxy listen:8081:http to:local

Overview

In Unix-like operating systems, it is common for many programs that initiate network requests to be capable of doing so using a specified network proxy. Some of these programs examine the following command-line environment variables to determine which, if any, proxies to use:

• HTTP_PROXY and/or http_proxy, for HTTP connections
• HTTPS_PROXY and/or https_proxy, for HTTPS connections. If not set, some programs will instead use variable HTTP_PROXY
• FTP_PROXY and/or ftp_proxy, for FTP connections
• no_proxy specifies hosts for which proxies should not be used, e.g. "localhost,127.0.0.0/8,[::]"

The purpose of bash-proxy-config is to provide commands to easily set, unset, and modify these proxy variables, either for the current shell session, or individual commands. This is useful when working in: corporate environments, where upstream corporate proxies are common, and; development environments, where local proxies might be used by developers to capture and debug local network requests, and; corporate development environments, where local proxies might forward network requests to upstream corporate proxies.

bash-proxy-config also provides additional functionality to start proxy commands associated with defined proxy configurations. This is handy for developers; it is convenient to start a local proxy using the same configuration being used to route network requests to that proxy.

Known Limitations

The use of proxy environment variables provides no way to conditionally direct some network requests to one proxy, while directing other network requests to another proxy.

Similarly, while the no_proxy environment variable allows the ability to specify certain hosts for which network requests should not be proxied, there is no ability to do the inverse; i.e. specify that only certain hosts should be proxied. Thus, bash-proxy-config supports all and nonlocal as valid values for the for: parameter, but does not support local, because that would not be feasible to implement via no_proxy.

Furthermore, no_proxy support across programs varies significantly; some programs allow wildcards and CIDR hosts to be specified in no_proxy, while other programs only support suffix substring matching.

Design Philosophy

bash-proxy-config is designed around the following principles:

• User configurability. Proxy configurations are defined in separate, user-controlled files.
• Configuration flexibility. A proxy configuration file is a Bash script that defines specific variables. Bash scripts can implement logic as simple or as sophisticated as necessary to define these variables. Futhermore, proxy configurations support inheritance of default values from other proxy configurations, allowing proxy variations to be defined with minimal redundancy.
• Configuration freshness. Since proxy configurations are reloaded during every invocation of bash-proxy-config, the Bash scripts that define proxy configurations can dynamically respond to changing network conditions, or other system status information, to determine appropriate proxy settings.
• Minimal environmental noise. bash-proxy-config expends noticeable effort to minimize the amount of variables and functions that get exposed to the parent shell session, in order to prevent the implementation details of bash-proxy-config from polluting the environment.

Installation

Getting the Source Code

bash-proxy-config is available via GitHub via the following methods:

Download the Latest Release:

https://github.com/dejayc/bash-proxy-config/archive/v1.1.0.zip

https://github.com/dejayc/bash-proxy-config/archive/v1.1.0.tar.gz

Browse the Latest Release:

https://github.com/dejayc/bash-proxy-config/releases/tag/v1.1.0

Git Clone:

git clone https://github.com/dejayc/bash-proxy-config

Installing the Source Code

bash-proxy-config files can be copied to any directory that is accessible by the user.

A typical user installation of bash-proxy-config consists of the following steps:

1. Create a new subdirectory .bash-proxy-config within the user's ${HOME} directory

2. Copy the following project file and subdirectory into .bash-proxy-config:

   config.sh
include/

3. Update the user's .bashrc file to source either of the following files:

   .bash-proxy-config/include/alias.sh, which defines a new alias named proxy:

   source "${HOME}/.bash-proxy-config/include/alias.sh"
   

   Note that aliases do not appear in the output of the set command.

   OR:

   .bash-proxy-config/include/fn.sh, which defines a new function named proxy:

   source "${HOME}/.bash-proxy-config/include/fn.sh"
   

4. If a configuration file other than ${HOME}/.bash-proxy-config/config.sh is to be used, specify the proper location by prefixing the source command with a variable assignment in the form of:

   BASH_PROXY_CONFIG='/path/to/bash-proxy-config/config.sh'
   

   For example, to load an instance of bash-proxy-config that has been installed to the directory /var/bash-proxy-config/, insert the following statement into .bashrc:

   BASH_PROXY_CONFIG='/var/bash-proxy-config/config.sh' \
     source '/var/bash-proxy-config/include/alias.sh'
   
   

   (Note the backslash \ line continuation character above.)

Configuration of Proxies

bash-proxy-config uses variables within the specified configuration script (normally .bash-config-proxy/config.sh) to configure proxy settings. Users should customize these variables as appropriate to their environment.

When installed typically, config.sh is read during each invocation of bash-config-proxy, in order to ensure configuration freshness, and reduce pollution of internal environment variables and functions into the parent session.

Creating a Proxy Configuration

Proxy Configuration Names

Proxy configurations must be named by the user so they can be referenced from bash-proxy-config commands. In the following example, proxy configuration local is referenced:

proxy to:local

Configuration names may contain lowercase letters a through z, and numbers 0 through 9. No other characters are permitted.

Typical configuration names include local, corp, upstream, etc. Since all-numeric names are allowed, names such as 8080 can be used to identify local proxies on specific ports.

Proxy Configuration Variables

To create a proxy configuration that can be invoked by bash-proxy-config, create script variables within config.sh with names that adhere to the following convention:

PROXY_{{NAME}}_{{SETTING}}

{{NAME}} consists of the proxy configuration name, converted to uppercase.

{{SETTING}} may consist of any of the following settings: DEFAULT, FOR, FTP_URL, HTTP_URL, HTTPS_URL, NO_PROXY, or URL.

(NOTE: also see the section Proxy Startup Variables for additional settings.)

For example, to define a proxy configuration named local with a proxy URL of http://localhost:8080, define the following variable within config.sh:

PROXY_LOCAL_URL='http://localhost:8080'

Once any such variable has been defined for a proxy configuration, that configuration may be invoked using bash-proxy-config.

Proxy Configuration Default Values

Proxy configurations can easily extend other proxy configurations, to reduce the need for copying and pasting values between configurations.

For example, to create a proxy configuration named debug that is identical to proxy configuration local, define the following variable:

PROXY_DEBUG_DEFAULT='local'

This assignment causes bash-proxy-config to use the proxy configuration settings of local whenever settings for debug are undefined.

If proxy configuration debug needs a specific setting to differ from that of local, the new setting (e.g. 'NO_PROXY') can be specified:

PROXY_DEBUG_DEFAULT='local'
PROXY_DEBUG_NO_PROXY='debug.localhost'

All other values for debug will continue to derive from local.

Description of Proxy Configuration Variables

Variable Name	Purpose
PROXY_DEFAULT_TO	The default value to use when the to: parameter is not specified during a bash-proxy-config command. The value for this setting should be the lowercase name of a proxy configuration.
PROXY_{{NAME}}_DEFAULT	Specifies the proxy configuration to be used to look up default values when a setting is not defined in the proxy configuration for {{NAME}}. Proxy configurations can inherit default values from other proxy configurations in this manner. The value for this setting should be the lowercase name of a proxy configuration.
PROXY_{{NAME}}_FOR	Specifies the default value of the for: parameter for proxy configuration {{NAME}}. This parameter controls the type of network requests that are sent to the proxy. Valid values are: all, which represents all network requests; and nonlocal, which represents all network requests except for localhost network requests. If not defined, defaults to the value specified in PROXY_{{DEFAULT}}_FOR, where {{DEFAULT}} is defined by PROXY_{{NAME}}_DEFAULT.
PROXY_{{NAME}}_FTP_URL	Specifies the proxy URL to use for FTP connections when using proxy configuration {{NAME}}. If not defined, defaults to the value specified first in: PROXY_{{NAME}}_URL PROXY_{{DEFAULT}}_FTP_URL PROXY_{{DEFAULT}}_URL where {{DEFAULT}} is defined by PROXY_{{NAME}}_DEFAULT.
PROXY_{{NAME}}_HTTP_URL	Specifies the proxy URL to use for HTTP connections when using proxy configuration {{NAME}}. If not defined, defaults to the value specified first in: PROXY_{{NAME}}_URL PROXY_{{DEFAULT}}_HTTP_URL PROXY_{{DEFAULT}}_URL where {{DEFAULT}} is defined by PROXY_{{NAME}}_DEFAULT.
PROXY_{{NAME}}_HTTPS_URL	Specifies the proxy URL to use for HTTPS connections when using proxy configuration {{NAME}}. If not defined, defaults to the value specified first in: PROXY_{{NAME}}_URL PROXY_{{DEFAULT}}_HTTPS_URL PROXY_{{DEFAULT}}_URL where {{DEFAULT}} is defined by PROXY_{{NAME}}_DEFAULT.
PROXY_{{NAME}}_NO_PROXY	Specifies the hosts to not proxy network requests to when using proxy configuration {{NAME}}, when parameter for: has the value nonlocal. The value of this variable is passed to commands via environment variable no_proxy; each command may interpret that variable differently. If not defined, defaults to the value specified in PROXY_{{DEFAULT}}_NO_PROXY, where {{DEFAULT}} is defined by PROXY_{{NAME}}_DEFAULT.
PROXY_{{NAME}}_URL	Specifies the proxy URL to use for FTP, HTTP, and HTTPS connections when using proxy configuration {{NAME}}, when the following variables are not defined: PROXY_{{NAME}}_FTP_URL PROXY_{{NAME}}_HTTP_URL PROXY_{{NAME}}_HTTPS_URL If not defined, defaults to the value specified in PROXY_{{DEFAULT}}_URL, where {{DEFAULT}} is defined by PROXY_{{NAME}}_DEFAULT.

Proxy Startup Variables

In addition to the variables that define proxy configurations, additional variables may be specified to allow proxies to be started on demand, via the listen: parameter, invoked as such:

proxy listen:8081

Or, to explicitly specify that the FTP proxy (and not the HTTP proxy) should be started, invoke:

proxy listen:8081:ftp

To specify that the FTP proxy should be started, with its outbound network connections themselves being proxied to a different proxy named company, invoke:

proxy listen:8081:ftp to:company

These additional variables follow the same naming convention as other proxy configuration variables:

PROXY_{{NAME}}_{{SETTING}}

{{NAME}} consists of the proxy configuration name, converted to uppercase.

{{SETTING}} may consist of any of the following settings: FTP_LISTEN, FTP_LISTEN_TO, HTTP_LISTEN, HTTP_LISTEN_TO, HTTPS_LISTEN, HTTPS_LISTEN_TO, LISTEN, LISTEN_TO.

The value of these settings must define the system command to be executed in order to start the proxy. For example, to specify that the ncat command should be executed when starting the HTTP proxy for the configuration named local, specify:

PROXY_LOCAL_HTTP_LISTEN='ncat'

The LISTEN parameter (without protocol prefix) is used as the default command when no protocol-specific variable has been defined.

The _TO variation of the variable is used when the to: parameter is specified when starting the proxy. For the following example startup command:

proxy listen:8081:ftp to:company

the following variables would be checked in this order:

• PROXY_8081_FTP_LISTEN_TO
• PROXY_8081_LISTEN_TO
• PROXY_8081_FTP_LISTEN
• PROXY_8081_LISTEN

Each of these variables support the special placeholder {{PROXY}}, which is a literal text placeholder to be replaced with the proxy definition specified by the to: parameter, if present. For example, for the following setting:

PROXY_LOCAL_LISTEN_TO='ncat --proxy {{PROXY}}'

invoking the following command:

proxy listen:local:http to:8081

would cause the following command to be executed:

ncat --proxy http://localhost:8081/

assuming that PROXY_8081_HTTP_URL or PROXY_8081_URL were defined as http://localhost:8081/.

Verifying Proxy Settings

To verify the settings that bash-proxy-config applies, execute the proxy-show and proxy-settings commands to see which variables and settings are applied by bash-proxy-config.

For example, to see what environment variables are applied by bash-proxy-config for proxy configuration local, execute:

proxy to:local proxy-show

To see what internal settings (include applied default values) have been calculated by bash-proxy-config for all proxy configurations, execute:

proxy proxy-settings

Note that proxy-settings shows internal settings for all proxy configurations, even if a specific proxy configuration has been specified via the to: parameter.

License and Copyright

bash-proxy-config: Copyright 2018 by Dejay Clayton, all rights reserved.
Licensed under the 2-Clause BSD License.

• https://github.com/dejayc/bash-proxy-config
• http://opensource.org/licenses/BSD-2-Clause