1# Default HTTP Proxy Mapper User Guide for gRPC Core (and dependents) 2 3[A1-http-connect-proxy-support.md](https://github.com/grpc/proposal/blob/master/A1-http-connect-proxy-support.md) 4proposed how gRPC supports TCP-level proxies via the HTTP CONNECT request, 5defined in [RFC-2817](https://www.rfc-editor.org/rfc/rfc2817). 6 7This guide documents gRPC C-Core's default proxy mapper implementation. 8 9## HTTP Proxy 10 11**Case 1** in the proposal documents a use-case where all outbound traffic from 12an environment must go through a proxy. Configurations for such environments are 13usually performed using environment variables such as `http_proxy`. gRPC 14supports this by providing a default proxy mapper implementation that allows for 15overriding the server name (provided in the channel creation hostname) to 16resolve based on such configurations. 17 18### Enabling the HTTP Proxy 19 20C-Core checks the following places to determine the HTTP proxy to use, stopping 21at the first one that is set: 22 231. `GRPC_ARG_HTTP_PROXY` channel arg 242. `grpc_proxy` environment variable 253. `https_proxy` environment variable 264. `http_proxy` environment variable 27 28If none of the above are set, then no HTTP proxy will be used. 29 30The allowed format is an [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) URI 31string where the scheme is expected to be "http" and the authority portion is 32used to determine the proxy to be used. For example, for an HTTP proxy setting 33of `http://username:[email protected]:443`, `username:password` would be 34used as user credentials for proxy authentication as per 35[RFC7617](https://www.rfc-editor.org/rfc/rfc7617) and `proxy.google.com:443` 36would be the host:port HTTP proxy target. If the port part of the authority is 37omitted, a default port of 443 is used. Note that user credential can also be 38omitted if the proxy does not need authentication. 39 40### Disabling HTTP Proxy 41 42If an HTTP proxy is set, C-Core then checks the following places to exclude 43traffic destined to listed hosts from going through the proxy determined above, 44again stopping at the first one that is set: 45 461. `no_grpc_proxy` environment variable 472. `no_proxy`environment variable 48 49If none of the above are set, then the previously found HTTP proxy is used. 50 51The format takes a comma-separated list of names, and if any of these names 52matches as a suffix of the server host (provided in the channel target), then 53the proxy will not be used for that target. For example, with a `grpc_proxy` 54setting of `proxy.google.com` and a `no_grpc_proxy` setting of `example.com, 55google.com`, channel targets such as `dns:///foo.google.com:50051` and 56`bar.example.com:1234` will not use the proxy, but `baz.googleapis.com:443` 57would still use the configured proxy `proxy.google.com`. 58 59As of [PR#31119](https://github.com/grpc/grpc/pull/31119), CIDR blocks are also 60supported in the list of names. For example, a `no_proxy` setting of 61`10.10.0.0/24` would not use the proxy for channel targets that mention IP 62addresses as the host between the range `10.10.0.0` to `10.10.0.255`. 63 64### Disabling HTTP Proxy Channel-wide 65 66The lookup and subsequent usage of an HTTP proxy for a specific channel can also 67be disabled by setting the channel arg `GRPC_ARG_ENABLE_HTTP_PROXY` to 0. 68 69## Address Proxy 70 71**Case 2** in the proposal documents a partially protected environment, where 72access to certain addresses must go through a proxy. Name resolution 73of protected servers works normally, and the proxy allows the CONNECT request 74to use an IP address instead of a hostname. 75 76Only requests for certain hosts must go through the proxy. Requests to other 77servers work without the proxy. Custom logic is used to determine which hosts 78the proxy will be used for. 79 80To use the address proxy, both of the following parameters need to be specified: 811. Address of the proxy can be specified using `GRPC_ARG_ADDRESS_HTTP_PROXY` 82channel argument or `GRPC_ADDRESS_HTTP_PROXY` environment variable. Value of 83the channel argument is preferred if both values are specified. 841. Comma-separated list of IP addresses and/or CIDR blocks that should be 85accessed through the proxy. This can be specified using 86the `GRPC_ARG_ADDRESS_HTTP_PROXY_ENABLED_ADDRESSES` channel argument 87or `GRPC_ADDRESS_HTTP_PROXY_ENABLED_ADDRESSES` environment variable. Value of 88the channel argument is preferred if both values are specified.