Proxy

This page covers two cases: an outbound proxy for Package Manager’s internet access, and a reverse proxy in front of Package Manager.

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:

/etc/rstudio-pm/rstudio-pm.gcfg
[Proxy]
URL = 127.0.0.1:80

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

/etc/rstudio-pm/rstudio-pm.gcfg
[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:

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

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

Note

The Password field here is an encrypted string. Plain text values are also allowed, but for maximum security, follow the instructions on how to use the rspm encrypt command.

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 must know the original request URL so that it can generate fully qualified URLs and return them to the requester. The proxy tells it with the following headers:

Header What Package Manager uses Notes
X-RSPM-Request The scheme, host, port, and path prefix of the original request. Takes precedence over the X-Forwarded-* headers. Set the value to the absolute URL of the original request, such as https://rspm.example.com/some/path. Recommended.
X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port The scheme, host, and port only. The path is always /, so these headers do not work if your proxy removes a path prefix. Use them when your proxy cannot add custom headers, such as the AWS Elastic Load Balancer.

If your proxy removes a path prefix, use X-RSPM-Request.

Set Server.Address

Package Manager builds Python package index pages from the configured Server.Address rather than from the proxy headers, so the proxy headers alone are not enough for Python packages. Set Server.Address to the public URL of Package Manager when any of these apply:

  • Package Manager is behind a proxy and serves Python packages.
  • Package Manager is served from a subdirectory, such as /packagemanager/.
  • You use OpenID Connect authentication.

Otherwise, Server.Address is optional.

/etc/rstudio-pm/rstudio-pm.gcfg
[Server]
Address = https://packagemanager.example.com/
ImportantCaching proxies need extra configuration

If your proxy also caches responses, configure it to include the Accept header in its cache key. The Python simple pages return either HTML or JSON for the same URL depending on that header, and a cache that ignores it serves one client’s format to another. See Simple page.

Using a Proxy for TLS/SSL

Reference the secure proxy section for information on configuring a proxy to handle HTTPS requests. If the proxy terminates TLS and sends plain HTTP to Package Manager, also set Server.Address to the proxy’s https URL, and set HTTP.ForceSecure and HTTP.NoWarning, as that section describes.

NGINX Configuration

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

Terminal
apt-get install nginx
Terminal
dnf install nginx
Terminal
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.

nginx.conf
http {
    server {
        listen 80;
        location / {
            client_max_body_size 0;
            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:

nginx.conf
http {
    server {
        listen 80;
        location /rspm/ {
            client_max_body_size 0;
            rewrite ^/rspm/(.*)$ /$1 break;
            proxy_set_header    X-RSPM-Request $scheme://$host:$server_port$request_uri;
            proxy_pass http://localhost:4242;
            proxy_redirect / /rspm/;
        }
    }
}

The client_max_body_size 0; line lets large package uploads through. Without it, NGINX rejects request bodies over 1 MB with a 413 error.

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

Terminal
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:

Terminal
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>
Back to top