Configuring and Troubleshooting an HTTP Proxy

The following configuration steps must be completed in order to install and operate UIP or Adapter Hub successfully on a machine which accesses the public internet via a proxy server. This work should be completed with the assistance of IT staff prior to attempting to install the software.

Some sites may use different proxy servers for different types of traffic (HTTP/HTTPS) to different destinations.
If the HTTPS proxy alters server certification chains using a custom proxy root CA its certificate must be installed into any machines that must communicate through it. Outgoing HTTPS/TLS connections will fail with security certificate trust errors which can be difficult to troubleshoot if this is not done.

Configuring host machine

It is recommended to add the DNS host name that the server will use access itself to the no_proxy= and NO_PROXY= environment settings. This improves system performance by allowing the various web services hosted by the same server to communicate with each other without having to traverse through the local network and the proxy server.
The DNS host name of the proxy server(s) must be resolvable using the DNS settings configured on the server.
If the proxy requires authentication a valid username and password must be included within the proxy URL value. (http://username:password@proxyhost.domain.tld:783)

Warning

If the proxy username or password contain any reserved characters that are not permitted within a URL they must be percent-encoded using their equivalent escape character sequence.

For example, the credentials domain\user:P@ss#1 would need to be input as domain%5Cuser:P%40ss%231.

Refer to IETF RFC 3986 sections 2.1 and 2.2 for more information about percent-encoding and reserved characters.

Note

In the steps below replace proxyurl with the URL of the applicable proxy server. Replace hostservername with the DNS HOST name that the server will use to access its own web services.
(e.g., UIP, adapter hub services, etc.)

Configure OS Environment Proxy Settings

Warning

If these settings are modified after the UIP software has been installed then a software upgrade will need to be completed before it will start using the modified proxy settings.

If there is no software update currently available for UIP the changeip.sh utility script can be used.

Warning

If these settings are modified after the software for Adapter Hub has been installed then a software upgrade will need to be completed before it will start using the modified proxy settings.

An upgrade can be triggered for Adapter Hub by downloading and executing the latest available hub-install.sh install script.

Update or create the file /etc/environment with the following content:

http_proxy="http://proxyurl"
https_proxy="http://proxyurl"
no_proxy="localhost,127.0.0.1,hostserverdnsname"
HTTP_PROXY="http://proxyurl"
HTTPS_PROXY="http://proxyurl"
NO_PROXY="localhost,127.0.0.1,hostserverdnsname"

Reload your environment using the command:
```
source /etc/environment
```
Update or create the file /etc/apt/apt.conf.d/30apt-proxy with the following content:
```
Acquire::http::Proxy "http://proxyurl";
Acquire::https::Proxy "http://proxyurl";
```

Create a file /etc/default/docker-proxy with the following content:

HTTP_PROXY="http://proxyurl"
HTTPS_PROXY="http://proxyurl"
NO_PROXY="localhost,127.0.0.1,hostserverdnsname"

Create the directory /etc/systemd/system/docker.service.d if it does not already exist
Create/modify the file /etc/systemd/system/docker.service.d/http-proxy.conf (for HTTP) with the following content:
```
[Service]
EnvironmentFile=/etc/default/docker-proxy
```
Create/modify the file /etc/systemd/system/docker.service.d/https-proxy.conf (for HTTPS) with the following content:
```
[Service]
EnvironmentFile=/etc/default/docker-proxy
```
If Docker is already installed the Docker service must be restarted in order for the changes to take effect.
```
sudo systemctl daemon-reload
sudo systemctl restart docker
```

HTTPS Proxies Which Modify Target Server Certificate

Some HTTPS proxies (e.g., ZScaler) modify the certification chain of TLS connections in order to perform packet inspection. A side effect of this process is that they replace the target server's original certificate with copy that has been issued and signed using the proxy's root Certification Authority (CA) certificate. Traffic that goes through this type of proxy will not be trusted by clients until the certificate for the proxy's root CA is imported into them.

Testing If You Are Behind A "Man-In-The-Middle" HTTPS Proxy

To check if your proxy changes the certification chain perform the following steps.

Web Browser

Connect to various https web pages such as https://nec.com and https://uip.nec-help.com. IT staff may allow traffic for certain sites to bypass the proxy server so it is a good idea to test multiple sites, including the sites listed in the UIP System Requirements.
Click on the small lock icon at the left of the URL location bar
Extend the popup to where you can view the certificate information
View the certificate information of the connection and examine its Issued By information. If the issuer appears to match the name of your proxy (e.g., Zscaler) instead of a well known certification authority that means that your proxy has modified the certification chain.

Ubuntu OS Bash Terminal

Run the following command from a terminal connected to the Ubuntu OS host machine. curl -vI https://www.nec.com --proxy 'proxyurl' | more
Review the output Server certificate: issuer: information.
If the issuer is a widely trusted commercial root certificate authority then the server certificate chain does not appear to be modified by the proxy.
If the issuer appears to match the name of your proxy (e.g., Zscaler) that means the HTTPS proxy has modified the certification chain

Obtain Proxy Root CA Certificate File

If you have access to a web browser which already trusts HTTPS connections which go through the HTTPS proxy server you can use that web browser to export a copy of the proxy root CA certificate to a file.

Connect to various https web pages such as https://nec.com and https://uip.nec-help.com.
Click on the small lock icon at the left of the URL location bar
Extend the popup to where you can view the certificate information
Go to the certificate Details view and select the root certificate at the top of the certificate hierarchy.
Export the root certificate as a *.crt file. If your browser asks you which certificate format is needed, select base64.

If you do not have access to a web browser which trusts the HTTPS proxy root CA certificate then it should be obtained from the IT staff responsible for supporting users of the proxy server.

If the IT staff provides a CA certificate with a *.pem or *.der file it should be converted into a compatible *.crt format. This can be done using the following openssl commands.

Convert PEM to PEM (.crt): openssl x509 -in proxy-ca.pem -inform PEM -out proxy-ca.crt
Convert DER to PEM (.crt): openssl x509 -in proxy-ca.der -inform der -out proxy-ca.crt

Add Proxy Root CA Certificate to Ubuntu OS

If the HTTPS proxy requires a proxy root CA certificate it should be installed into the Ubuntu OS of the host machine(s).

Copy the proxy-ca.crt certificate file to the target host machine
Make a new folder for the extra CA cert: sudo mkdir -p /usr/share/ca-certificates/extra
Copy the certificate into the new folder: sudo cp proxy-ca.crt /usr/share/ca-certificates/extra/proxy-ca.crt
Update the server to trust the CA certificates in the extra folder: sudo dpkg-reconfigure ca-certificates
If Docker is already installed the Docker service must be restarted in order for the changes to take effect.
```
sudo systemctl daemon-reload
sudo systemctl restart docker
```

Add Proxy Root CA Certificate to UIP, Adapters, and Adapter Hub Services

If the HTTPS proxy requires a proxy root CA certificate it should be imported into the UIP software.

Certificate Authority (CA) certificates can be imported using the Administration > Trusted CA page. CA certificates can also be imported when the UIP installation script is executed by using the --cacerts nap-install.sh script parameter.

This process must be repeated any time the HTTPS proxy root CA certificate changes. Administrators should include this in their maintenance planning for the UIP system.

Add Proxy Root CA Certificate to Adapter Hub

Detailed steps explaining how to configure trusted CA certificates for an Adapter Hub host machine can be found in the Adapter Hub > Importing a Trusted CA help topic.