Outbound Proxy#

Package Manager requires outbound internet access to the Posit Package Service to receive package updates.

If you need to use an outbound proxy server to access this service, you can use the Proxy.URL configuration setting to set the HTTP and HTTPS proxy behavior. For example:

[Proxy]
URL = 127.0.0.1:80

To add basic authorization credentials and/or use an HTTPS proxy, provide a complete URL:

[Proxy]
URL = https://user:pass@example.com

Package Manager requires that the proxy is enabled to perform SSL forwarding.

Secure Outbound Proxy Credentials#

Package Manager allows credentials to be used in a secure matter when configuring an outbound proxy. To do this, use the User and Password configuration options as follows:

[Proxy]
URL = https://example.com
User = user
Password = <encrypted-password>

For more information, refer to the Proxy Settings section in the Appendix.

Running with a Proxy#

If you are running Package Manager behind a proxy server, configure the proxy server so that it correctly handles all traffic to and from Package Manager. This section describes how to correctly configure a reverse proxy with Nginx or Apache HTTPD.

When Package Manager is behind a proxy, it is important to send the original request URL information to Package Manager so that it can generate fully qualified URLs and return them to the requester. For this reason, when proxying to Package Manager, we recommend adding a header, X-RSPM-Request, to the request. This header value should be the absolute URL of the original request made by the user or browser (i.e. https://rspm.company.com/some/path)

Some proxies (e.g., AWS Elastic Load Balancer) do not support custom headers. In this situation, if the X-RSPM-REQUEST header is not supplied, the standard headers X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Port attempt to parse the original request URL. If your proxy removes a server prefix from the path, X-Forwarded headers will not work for your use case, and you should use X-RSPM-Request. If both X-RSPM-Request and X-Forwarded headers are supplied, X-RSPM-Request takes precedence.

Using a Proxy for TLS/SSL#

Reference the secure proxy section for information on configuring a proxy to handle HTTPS requests.

NGINX Configuration#

A version of NGINX that supports reverse-proxying can be installed using the following command:

$ apt-get install nginx

$ yum install nginx

$ sudo zypper install nginx

To enable an instance of Nginx running on the same server to act as a front-end proxy to Package Manager, use a configuration similar to the following in your nginx.conf file. This configuration assumes Package Manager is running on the same host as Nginx and listening for HTTP requests on the :4242 port. If you are proxying to Package Manager on a different machine or port, replace the localhost:4242 references with the correct address of the server where Package Manager is hosted.

http {
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }
    server {
        listen 80;
        location / {
            proxy_set_header    X-RSPM-Request $scheme://$host:$server_port$request_uri;
            proxy_pass http://localhost:4242;
        }
    }
}

If you want to serve Package Manager from a custom path (e.g. /rspm) you would edit your nginx.conf file as shown below:

http {
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }
    server {
        listen 80;
        location /rspm/ {
            rewrite ^/rspm/(.*)$ /$1 break;
            proxy_set_header    X-RSPM-Request $scheme://$host:$server_port$request_uri;
            proxy_pass http://localhost:4242;
            proxy_redirect / /rspm/;
        }
    }
}

After adding these entries, reload Nginx so that the proxy settings take effect:

$ sudo systemctl restart nginx

Apache Configuration#

The Apache HTTPD server can act as a front-end proxy to Package Manager by first enabling three modules:

$ a2enmod rewrite
$ a2enmod headers
$ a2enmod proxy_http

The following configuration will permit proxying to Package Manager from the :3737 port. Depending on the layout of your Apache installation, you may need the Listen and VirtualHost directives in different files.

Listen 3737

<VirtualHost *:3737>
    RewriteEngine on
    RequestHeader set X-RSPM-Request "%{REQUEST_SCHEME}s://%{HTTP_HOST}s%{REQUEST_URI}s"
    ProxyPass / http://172.17.0.1:4242/
    ProxyPassReverse / http://172.17.0.1:4242/
</VirtualHost>

You can serve Package Manager from a custom path (e.g. /rspm) with a configuration like the following:

Listen 3737

<VirtualHost *:3737>
    RewriteEngine on
    RedirectMatch ^/rspm$ /rspm/
    RequestHeader set X-RSPM-Request "%{REQUEST_SCHEME}s://%{HTTP_HOST}s%{REQUEST_URI}s"
    ProxyPass /rspm/ http://172.17.0.1:4242/
    ProxyPassReverse /rspm/ http://172.17.0.1:4242/
    Header edit Location ^/ /rspm/
</VirtualHost>