ExternalVendorCode/balena-cli
1
0
Fork 0
mirror of https://github.com/balena-io/balena-cli.git synced 2025-04-27 14:30:07 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update README regarding proxy server support

Browse Source 
Change-type: patch
This commit is contained in:
Paulo Castro 2020-03-29 23:59:44 +01:00
parent 30738d93b0
commit 3e955f3a91
2 changed files with 54 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
README.md
View File

@ -89,20 +89,30 @@ HTTP(S) proxies can be configured through any of the following methods, in prece
`BALENARC_PROXY`. `BALENARC_PROXY`.
> Note: The `balena ssh` command has additional setup requirements to work behind a proxy. > Note: The `balena ssh` command has additional setup requirements to work behind a proxy.
> Check the [installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md). > Check the [installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md),
> and ensure that the proxy server is configured to allow proxy requests to ssh port 22, using
> SSL encryption. For example, in the case of the [Squid](http://www.squid-cache.org/) proxy
> server, it should be configured with the following rules in the `squid.conf` file:
> `acl SSL_ports port 22`
> `acl Safe_ports port 22`
Some installations of the balena CLI also include support for the `BALENARC_NO_PROXY` environment #### Proxy exclusion
variable, which allows proxy exclusion patterns to be defined. The current support status is listed
below. Eventually, all installation types will have support for it.
OS | Installation type | BALENARC_NO_PROXY environment variable support The `BALENARC_NO_PROXY` variable may be used to exclude specified destinations from proxying.
-- | ----------------- | ----------------------------------------------
Windows | standalone zip | Supported with CLI v11.24.0 and later > * This feature requires balena CLI version 11.30.8 or later. In the case of the npm [installation
Windows | native/GUI | Not supported > option](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md), it also requires
macOS | standalone zip | Not supported > Node.js version 10.16.0 or later.
macOS | native/GUI | Supported with CLI v11.24.0 and later > * To exclude a `balena ssh` target from proxying (IP address or `.local` hostname), the
Linux | standalone zip | Not supported > `--noproxy` option should be specified in addition to the `BALENARC_NO_PROXY` variable.
Any | npm | Supported with Node.js >= v10.16.0 and CLI >= v11.24.0
By default (if `BALENARC_NO_PROXY` is not defined), all [private IPv4
addresses](https://en.wikipedia.org/wiki/Private_network) and `'*.local'` hostnames are excluded
from proxying. Other hostnames that resolve to private IPv4 addresses are **not** excluded by
default, because matching takes place before name resolution.
`localhost` and `127.0.0.1` are always excluded from proxying, regardless of the value of
BALENARC_NO_PROXY.
The format of the `BALENARC_NO_PROXY` environment variable is a comma-separated list of patterns The format of the `BALENARC_NO_PROXY` environment variable is a comma-separated list of patterns
that are matched against hostnames or IP addresses. For example: that are matched against hostnames or IP addresses. For example:
@ -111,18 +121,10 @@ that are matched against hostnames or IP addresses. For example:
export BALENARC_NO_PROXY='*.local,dev*.mycompany.com,192.168.*' export BALENARC_NO_PROXY='*.local,dev*.mycompany.com,192.168.*'
``` ```
Matched patterns are excluded from proxying. Matching takes place _before_ name resolution, so a Matched patterns are excluded from proxying. Wildcard expressions are documented at
pattern like `'192.168.*'` will **not** match a hostname like `proxy.company.com` even if the [matcher](https://www.npmjs.com/package/matcher#usage). Matching takes place _before_ name
hostname resolves to an IP address like `192.168.1.2`. Pattern matching expressions are documented resolution, so a pattern like `'192.168.*'` will **not** match a hostname that resolves to an IP
at [matcher](https://www.npmjs.com/package/matcher#usage). address like `192.168.1.2`.
By default, if BALENARC_NO_PROXY is not defined, all [private IPv4
addresses](https://en.wikipedia.org/wiki/Private_network) and `'*.local'` are excluded from
proxying. Other hostnames that may resolve to private IPv4 addresses are **not** excluded by
default, as matching takes place _before_ name resolution. In addition, `localhost` and `127.0.0.1`
are always excluded from proxying, regardless of the value of BALENARC_NO_PROXY. These default
exclusions only apply to the CLI installations where BALENARC_NO_PROXY is supported, as listed in
the table above.
## Command reference documentation ## Command reference documentation

50
doc/cli.markdown
View File

@ -82,20 +82,30 @@ HTTP(S) proxies can be configured through any of the following methods, in prece
`BALENARC_PROXY`. `BALENARC_PROXY`.
> Note: The `balena ssh` command has additional setup requirements to work behind a proxy. > Note: The `balena ssh` command has additional setup requirements to work behind a proxy.
> Check the [installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md). > Check the [installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md),
> and ensure that the proxy server is configured to allow proxy requests to ssh port 22, using
> SSL encryption. For example, in the case of the [Squid](http://www.squid-cache.org/) proxy
> server, it should be configured with the following rules in the `squid.conf` file:
> `acl SSL_ports port 22`
> `acl Safe_ports port 22`
Some installations of the balena CLI also include support for the `BALENARC_NO_PROXY` environment #### Proxy exclusion
variable, which allows proxy exclusion patterns to be defined. The current support status is listed
below. Eventually, all installation types will have support for it.
OS | Installation type | BALENARC_NO_PROXY environment variable support The `BALENARC_NO_PROXY` variable may be used to exclude specified destinations from proxying.
-- | ----------------- | ----------------------------------------------
Windows | standalone zip | Supported with CLI v11.24.0 and later > * This feature requires balena CLI version 11.30.8 or later. In the case of the npm [installation
Windows | native/GUI | Not supported > option](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md), it also requires
macOS | standalone zip | Not supported > Node.js version 10.16.0 or later.
macOS | native/GUI | Supported with CLI v11.24.0 and later > * To exclude a `balena ssh` target from proxying (IP address or `.local` hostname), the
Linux | standalone zip | Not supported > `--noproxy` option should be specified in addition to the `BALENARC_NO_PROXY` variable.
Any | npm | Supported with Node.js >= v10.16.0 and CLI >= v11.24.0
By default (if `BALENARC_NO_PROXY` is not defined), all [private IPv4
addresses](https://en.wikipedia.org/wiki/Private_network) and `'*.local'` hostnames are excluded
from proxying. Other hostnames that resolve to private IPv4 addresses are **not** excluded by
default, because matching takes place before name resolution.
`localhost` and `127.0.0.1` are always excluded from proxying, regardless of the value of
BALENARC_NO_PROXY.
The format of the `BALENARC_NO_PROXY` environment variable is a comma-separated list of patterns The format of the `BALENARC_NO_PROXY` environment variable is a comma-separated list of patterns
that are matched against hostnames or IP addresses. For example: that are matched against hostnames or IP addresses. For example:
@ -104,18 +114,10 @@ that are matched against hostnames or IP addresses. For example:
export BALENARC_NO_PROXY='*.local,dev*.mycompany.com,192.168.*' export BALENARC_NO_PROXY='*.local,dev*.mycompany.com,192.168.*'
``` ```
Matched patterns are excluded from proxying. Matching takes place _before_ name resolution, so a Matched patterns are excluded from proxying. Wildcard expressions are documented at
pattern like `'192.168.*'` will **not** match a hostname like `proxy.company.com` even if the [matcher](https://www.npmjs.com/package/matcher#usage). Matching takes place _before_ name
hostname resolves to an IP address like `192.168.1.2`. Pattern matching expressions are documented resolution, so a pattern like `'192.168.*'` will **not** match a hostname that resolves to an IP
at [matcher](https://www.npmjs.com/package/matcher#usage). address like `192.168.1.2`.
By default, if BALENARC_NO_PROXY is not defined, all [private IPv4
addresses](https://en.wikipedia.org/wiki/Private_network) and `'*.local'` are excluded from
proxying. Other hostnames that may resolve to private IPv4 addresses are **not** excluded by
default, as matching takes place _before_ name resolution. In addition, `localhost` and `127.0.0.1`
are always excluded from proxying, regardless of the value of BALENARC_NO_PROXY. These default
exclusions only apply to the CLI installations where BALENARC_NO_PROXY is supported, as listed in
the table above.
## Support, FAQ and troubleshooting ## Support, FAQ and troubleshooting