4 Access and Security

4.1 Network Port and Address

After initial installation RStudio accepts connections on port 8787. If you wish to listen on a different another port you can modify the www-port option. For example:

/etc/rstudio/rserver.conf

www-port=80

By default RStudio binds to address 0.0.0.0 (accepting connections from any remote IP). You can modify this behavior using the www-address option. For example:

/etc/rstudio/rserver.conf

www-address=127.0.0.1

Note that changes to the configuration will not take effect until the server is restarted.

4.2 IP Access Rules

RStudio Server can be configured to deny access to specific IP addresses or ranges of addresses. Access rules are defined in the configuration file /etc/rstudio/ip-rules

Access rules are established using the allow and deny directives and are processed in order, with the first matching rule governing whether a given address is allowed or denied. For example, to allow only clients within the 192.168.1.0/24 subnet but also deny access to 192.168.1.10 you would use these rules:

/etc/rstudio/ip-rules

deny    192.168.1.10
allow   192.168.1.0/24
deny    all

All clients outside of the specified subset are denied access because of the deny all rule at the end of the configuration.

Note that changes to the configuration will not take effect until the server is restarted.

4.3 Frame Origin

For security reasons, RStudio Server will not load inside a browser frame (such as a frameset or IFrame) by default. You can modify this behavior by using the www-frame-origin option. For example, if you would like to host RStudio inside a browser frame at example.com, you can tell RStudio to allow this as follows:

/etc/rstudio/rserver.conf

www-frame-origin=example.com

There are several special values available for the www-frame-origin option:

Value Meaning
none The default; do not allow RStudio to load in any frame.
same Allow RStudio to load in a frame if it has the same origin (host and port) as RStudio.
any Allow RStudio to load in a frame from any origin (not recommended)
my-domain.com Allow RStudio to load in a frame at my-domain.com

To interact programmatically with RStudio Server in an IFrame, see the Tutorial API.

4.4 Additional Security Considerations

To help mitigate against CSRF attacks, RStudio Server can automatically reject any request originating from an Origin or Referer that does not match the Host, X-Forwarded-Host, or Forwarded: host headers. To enable this check, add the following configuration:

/etc/rstudio/rserver.conf

www-disable-origin-check=0

In some cases, such as if running behind a proxy that you cannot modify, this check may be too strict, and can prevent access to RStudio Server, causing requests to return a 400 status. In such cases, it is recommended that you disable the check. Origin checking is currently disabled by default, but will likely be enabled by default in a future version of RStudio Server Pro.

You may wish to consider some origins to be safe in all cases, causing RStudio to consider such Origin or Referer values to be allowed instead of being rejected, even if they do not match a Host header. To specify such origins, add each of them as a www-allow-origin setting in rserver.conf. For example:

/etc/rstudio/rserver.conf

www-allow-origin=mysubdomain.mydomain.com
www-allow-origin=*.mydomain2.com

Note that wildcards (*) are accepted and will match any character, including hostname separators. For instance, the previous example of *.mydomain2.com will match both foo.bar.mydomain2.com and foo.mydomain2.com.

4.5 Additional Headers

In some cases, you may need to have RStudio Server set additional headers on client responses. To do this, simply specify server-add-header for each header that you need to add, in the form Header Name:Header Value. For example, to have the server set a few extra custom headers:

/etc/rstudio/rserver.conf

server-add-header=X-Header-1:Value 1
server-add-header=X-Header-2:Value 2

4.6 Secure Sockets (SSL)

4.6.1 SSL Configuration

If your RStudio Server is running on a public network then configuring it to use SSL (Secure Sockets Layer) encryption is strongly recommended. You can do this via the ssl-enabled setting along with related settings that specify the location of your SSL certificate and key. For example:

/etc/rstudio/rserver.conf

ssl-enabled=1
ssl-certificate=/var/certs/your_domain_name.crt
ssl-certificate-key=/var/certs/your_domain_name.key

The .crt file should be encoded in the PEM format; that is, the first line should read -----BEGIN CERTIFICATE-----, and the contents should be base64-encoded data. If your certificate is in another format, such as DER or PKCS, use the openssl command-line tool to convert it to PEM. For example:

openssl x509 -inform DER -outform PEM -text -in your_domain_name.der -out your_domain_name.crt

It’s important when installing the certificate .crt file that you concatenate together any intermediate certificates (i.e. the generic one from your certificate authority) with the certificate associated with your domain name. For example you could use a shell command of this form to concatenate the CA intermediate certificate to your domain name’s certificate:

$ cat certificate-authority.crt >> your_domain_name.crt

The resulting file should then be specified in the ssl-certificate option.

It’s also important to ensure that the file permissions on your SSL certificate key are as restrictive as possible so it can’t be read by ordinary users. The file should typically be owned by the root user and be set as owner readable and writable. For example:

$ sudo chmod 600 /var/certs/your_domain_name.key

4.6.2 SSL Protocols

By default RStudio Server supports the TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3 protocols for SSL. The list of supported protocols can configured via the ssl-protocols option. For example, to use only the TLSv1.1 and TLSv1.2 protocols you would use:

/etc/rstudio/rserver.conf

ssl-protocols=TLSv1.1 TLSv1.2

The list of supported protocols is space delimited (as illustrated above). Valid protocol values are: SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3.

Note that not all protocols may be available on your system; TLS 1.1 and 1.2 require OpenSSL 1.0.1, and TLS 1.3 requires OpenSSL 1.1.1 built with TLS 1.3 support.

4.7 SSL Ports

When RStudio Server is configured to use SSL the default behavior with respect to ports is:

  1. SSL is bound to port 443 (enabling access using the standard https protocol within the browser)
  2. The server also listens on port 80 and redirects all requests to port 443 (allowing users to specify the domain without the https protocol and be automatically redirected to the secure port)

However, if SSL is bound to another port (using the www-port option) then the automatic redirect behavior is not enabled. It’s also possible to disable automatic SSL redirects entirely using the ssl-redirect-http option as follows:

/etc/rstudio/rserver.conf

ssl-redirect-http=0

Note that changes to the configuration will not take effect until the server is restarted.

4.8 Cookies

By default, when RStudio Server is configured with SSL, all authorization cookies are marked with the secure cookie attribute. If you wish to use your own SSL termination but force RStudio Server to mark cookies as secure, you can add the following configuration option:

/etc/rstudio/rserver.conf

auth-cookies-force-secure=1

4.9 Server Permissions

4.9.1 Server Account

RStudio Server runs as the system root user during startup and then drops this privilege and runs as a more restricted user. RStudio Server then re-assumes root privilege for a brief instant when creating R sessions on behalf of users (the server needs to call setresuid when creating the R session, and this call requires root privilege).

The user account that RStudio Server runs under in the normal course of operations is rstudio-server. This account is automatically added to the system during installation and is created as a system rather than end user account (i.e. the --system flag is passed to useradd).

4.9.1.1 Alternate Server Account

You can configure RStudio Server so that it will run from an alternate account with the following steps:

  1. Create a new system user (if the one you want to use doesn’t already exist)
  2. Assign this user to the server-user option in the /etc/rstudio/rserver.conf configuration file (see example below)
  3. Restart RStudio Server

For example, to shutdown the server and create a new system user named rs-user you’d use the following commands:

sudo rstudio-server stop
sudo useradd --system rs-user

Then edit the /etc/rstudio/rserver.conf configuration file as follows:

/etc/rstudio/rserver.conf

server-user=rs-user

Finally, restart RStudio Server to begin running under the new user:

sudo rstudio-server start

4.9.2 umask

By default, RStudio Server sets its umask to 022 on startup. If you don’t want this behavior, for instance because you’d prefer the server process to use the default umask set in init, it can be disabled as follows:

/etc/rstudio/rserver.conf

server-set-umask=0

4.10 Running with a Proxy

4.10.1 Overview

If you are running RStudio Server behind a proxy server you need be sure to configure the proxy server so that it correctly handles all traffic to and from RStudio Server.

Beyond the normal reverse proxy configuration you’d apply for any HTTP server application, you also need to to ensure that websockets are forwarded correctly between the proxy server and RStudio Server to ensure that all RStudio functions work correctly. In particular, they’re needed to ensure that Shiny applications run from within the IDE work properly - if not, you may find that Shiny applications “gray out” and close without you being able to interact with them.

This section describes how to correctly configure a reverse proxy with Nginx and Apache.

4.10.2 Nginx Configuration

On Debian or Ubuntu a version of Nginx that supports reverse-proxying can be installed using the following command:

sudo apt-get install nginx

On CentOS or Red Hat you can install Nginx using the following command:

sudo yum install nginx

To enable an instance of Nginx running on the same server to act as a front-end proxy to RStudio Server you would add commands like the following to your nginx.conf file. Note that you must add code to proxy websockets in order to correctly display Shiny apps and R Markdown Shiny documents in RStudio Server. Also note that if you are proxying to a server on a different machine you need to replace references to localhost with the correct address of the server where you are hosting RStudio.

http {

  map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
  }
  
  server {
    listen 80;
    
    
    location / {
      proxy_pass http://localhost:8787;
      proxy_redirect http://localhost:8787/ $scheme://$host/;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_read_timeout 20d;
      proxy_set_header X-Forwarded-Host $host;
    }
  }
}

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

http {

  map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
  }
  
  server {
    listen 80;
    
    location /rstudio/ {
      rewrite ^/rstudio/(.*)$ /$1 break;
      proxy_pass http://localhost:8787;
      proxy_redirect http://localhost:8787/ $scheme://$host/rstudio/;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_read_timeout 20d;
      proxy_set_header X-Forwarded-Host $host;
    }

After adding these entries you’ll then need to restart Nginx so that the proxy settings take effect:

sudo /etc/init.d/nginx restart

Note that RStudio needs the X-Forwarded-Host header set for various security reasons, and nginx does not supply this header by default. It must contain the original Host value of the request, which is usually set to $host in the nginx configuration file.

In some cases, such as when streaming job statuses from the launcher, the default response buffering in nginx can be too slow for delivering real-time updates, especially when configured to use SSL. If job output streams are not working properly from the home page, we recommend disabling response buffering by adding the following line under the server directive:

server {
  # ... follows previous configuration
  proxy_buffering off;
}

4.10.3 Apache Configuration

To enable an instance of Apache running on the same server to act as a front-end proxy to RStudio Server you need to use the mod_proxy and mod_proxy_wstunnel modules. The steps for enabling this module vary across operating systems so you should consult your distribution’s Apache documentation for details.

On Debian and Ubuntu systems Apache can be installed with mod_proxy using the following commands:

sudo apt-get install apache2
sudo apt-get install libapache2-mod-proxy-html
sudo apt-get install libxml2-dev

Then, to update the Apache configuration files to activate mod_proxy you execute the following commands:

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_wstunnel

On CentOS and RedHat systems Apache can be installed with mod_proxy and mod_proxy_wstunnel by following the instructions here:

http://httpd.apache.org/docs/2.4/platform/rpm.html

By default with Apache 2.4, mod_proxy and mod_proxy_wstunnel should be enabled. You can check this by opening the file /etc/httpd/conf.modules.d/00-proxy.conf and making sure the following lines are included and not commented out:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so

Once you have enabled mod_proxy and mod_proxy_wstunnel in your Apache installation you need to add the required proxy commands to your VirtualHost definition. Note that you will also need to include code to correctly proxy websockets in order to correctly proxy Shiny apps and R Markdown documents within RStudio Server. Also note that if you are proxying to a server on a different machine you need to replace references to localhost with the correct address of the server where you are hosting RStudio.

<VirtualHost *:80>

  <Proxy *>
    Allow from localhost
  </Proxy>

  RewriteEngine on
  RewriteCond %{HTTP:Upgrade} =websocket
  RewriteRule /(.*)     ws://localhost:8787/$1  [P,L]
  RewriteCond %{HTTP:Upgrade} !=websocket
  RewriteRule /(.*)     http://localhost:8787/$1 [P,L]
  ProxyPass / http://localhost:8787/
  ProxyPassReverse / http://localhost:8787/
  ProxyRequests Off

</VirtualHost>

Note that if you want to serve RStudio from a custom path (e.g. /rstudio) you would replace the directives described above to:

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket
RewriteRule /rstudio/(.*)     ws://localhost:8787/$1  [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket
RewriteRule /rstudio/(.*)     http://localhost:8787/$1 [P,L]
ProxyPass /rstudio/ http://localhost:8787/
ProxyPassReverse /rstudio/ http://localhost:8787/
ProxyRequests Off

Finally, after you’ve completed all of the above steps you’ll then need to restart Apache so that the proxy settings take effect:

sudo /etc/init.d/apache2 restart

4.10.4 RStudio Configuration

If your RStudio Server and proxy server are running on the same machine you can also change the port RStudio Server listens on from 0.0.0.0 (all remote clients) to 127.0.0.1 (only the localhost). This ensures that the only way to connect to RStudio Server is through the proxy server. You can do this by adding the www-address entry to the /etc/rstudio/rserver.conf file as follows:

www-address=127.0.0.1

Note that you may need to create this config file if it doesn’t already exist.

4.10.5 Customizing Default Proxy

RStudio Server Pro exposes itself over TCP by means of an nginx proxy instance that runs as the rserver-http process on the local machine. In some cases, this proxy instance may need to be customized.

In order to customize it, you can create any of the following three files. Each file modifies the nginx configuration at /var/lib/rstudio-server/conf/rserver-http.conf in the following way:

  • /etc/rstudio/nginx.http.conf - allows you to add additional nginx directives under the root http node, and should be used for altering basic HTTP settings
  • /etc/rstudio/nginx.server.conf - allows you to add additional nginx directives under the server node, and should be used for altering basic server settings
  • /etc/rstudio/nginx.site.conf - allows you to add additional nginx directives under the location / node, and should be used for altering responses sent from RStudio

Simply add the desired nginx configuration in the files above to modify the desired section - the contents of each file is copied into the rserver-http.conf template verbatim. Then, restart rstudio-server for the changes to take effect.

In most cases, you should not need to create these files and modify the nginx template that is provided.