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.5 Compatibility with Safari 13+
Starting in Safari 13, if you are loading RStudio inside a browser frame on a completely different domain all cookies will be blocked because those will be considered third-party cookies.
Embedding RStudio in a subdomain of the main site causes its cookies to be considered first-party, allowing RStudio to work.
Alternatively, you can place RStudio in the same domain as the main wrapping site but under a different URL path. This requires using a proxy in front of both the main site and RStudio. See Running with a Proxy below for more information.
Note: In a near future, most browsers vendors plan to apply the same restrictions to cookies in some degree.
4.6 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
, Forwarded: host
or X-RStudio-Request
headers. To enable this check, add the following configuration:
/etc/rstudio/rserver.conf
www-enable-origin-check=1
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.7 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.8 Secure Sockets (SSL)
4.8.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.8.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.9 SSL Ports
When RStudio Server is configured to use SSL the default behavior with respect to ports is:
- SSL is bound to port 443 (enabling access using the standard https protocol within the browser)
- 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.9.1 Strict Transport Security
When SSL is enabled, RStudio Server sends an HTTP Strict Transport Security (HSTS) header, Strict-Transport-Security
, by default on outbound responses. This header tells the browser to forbid all HTTP connections to the domain for a period of time.
RStudio Server sets this period of time to 1 day (84600 seconds) by default, because if HTTPS issues arise it can be difficult to address them when the browser is locked to HTTPS because of HSTS. Once you are confident that your HTTPS setup is correct, you can increase the period by specifying the desired number of seconds in the ssl-hsts-max-age
option. For example, to lock browsers to HTTPS for one year:
/etc/rstudio/rserver.conf
ssl-hsts-max-age=31536000
If all subdomains of the server on which RStudio Server is hosted support HSTS, you can extend HSTS protection to them as well with the ssl-hsts-include-subdomains
option. This doesn’t happen by default since RStudio Server does not know what other services it’s sharing a domain with, but it’s a recommended security best practice, so you should turn it on if you can.
/etc/rstudio/rserver.conf
ssl-hsts-include-subdomains=1
Finally, we do not recommend disabling HSTS, but if you need to, you can do so by setting ssl-hsts=0
.
4.11 Server Permissions
4.11.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.11.1.1 Alternate Server Account
You can configure RStudio Server so that it will run from an alternate account with the following steps:
- Create a new system user (if the one you want to use doesn’t already exist)
- Assign this user to the
server-user
option in the/etc/rstudio/rserver.conf
configuration file (see example below) - 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.11.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.12 Running with a Proxy
4.12.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 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.
It’s also important to ensure that your reverse proxy uses a relatively lenient connection timeout; we recommend 60 seconds. Several components of RStudio Server use HTTP Long Polling to push information to the browser; a connection timeout of 30 seconds or fewer will result in HTTP 504 (gateway timeout) errors from the reverse proxy.
This section describes how to correctly configure a reverse proxy with Nginx and Apache.
4.12.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;
# Use preferably
proxy_set_header X-RStudio-Request $scheme://$host:$server_port$request_uri;
# OR existing X-Forwarded headers
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
# OR alternatively the Forwarded header (just an example)
proxy_set_header Forwarded "host=$host:$server_port;proto=$scheme;";
}
}
}
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_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 20d;
# Use preferably
proxy_set_header X-RStudio-Request $scheme://$host:$server_port$request_uri;
proxy_set_header X-RStudio-Root-Path /rstudio
# OR let the proxy rewrite the root path
proxy_redirect http://localhost:8787/ $scheme://$host/rstudio/;
proxy_cookie_path / /rstudio;
# OR existing X-Forwarded headers
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
# OR alternatively the Forwarded header (just an example)
proxy_set_header Forwarded "host=$host:$server_port;proto=$scheme;";
}
Note: The header
X-RStudio-Root-Path
and the configuration optionwww-root-path
server the same purpose. If either is set RStudio will always return cookies and redirects for the correct path, without requiring rewrite assistance from the proxy. The header value has precedence over the configuration value.
/etc/rstudio/rserver.conf
www-root-path=/rstudio
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-RStudio-Request
, X-Forwarded-[Host|Port|Proto]
, or Forwarded
headers 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.12.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. Apache as reverse proxy already includes X-Forwarded-Host
(with port) and X-Forwarded-Proto
by default.
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/
# Use preferably
RequestHeader set X-RStudio-Request "%{req_scheme}e://%{http_host}e%{req_uri}e"
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/
# Use preferably
RequestHeader set X-RStudio-Request "%{req_scheme}e://%{http_host}e%{req_uri}e"
RequestHeader set X-RStudio-Root-Path "/rstudio"
# Or alternatively
ProxyPassReverse /rstudio/ http://localhost:8787/
ProxyPassReverseCookiePath "/" "/rstudio"
ProxyRequests Off
Note: The header
X-RStudio-Root-Path
and the configuration optionwww-root-path
server the same purpose. If either is set RStudio will always return cookies and redirects for the correct path, without requiring rewrite assistance from the proxy. The header value has precedence over the configuration value.
/etc/rstudio/rserver.conf
www-root-path=/rstudio
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.12.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.12.5 Custom Paths and Path-Rewriting Proxies
In the examples above we have configurations where RStudio is served by the proxy under a custom /rstudio
path. This is called a path-rewriting proxy setup.
RStudio can use different combinations of HTTP headers and/or options to determine its location when path-rewriting in is use:
- Use
X-RStudio-Request
if possible. This way RStudio knows exacly the address presented in the user’s browser.- Otherwise, you must use
X-Forwarded-*
family of headers or theForwarded
header.
- Otherwise, you must use
- Use
X-RStudio-Root-Path
if possible. This way RStudio knows which portion of the path was added by the proxy.- Alternatively, use the option
www-root-path
for the same effect. - Otherwise, you must use additional options in your proxy configuration to adjust redirects and cookies for the right path.
- Alternatively, use the option
The most reliable configuration is using X-RStudio-Request
and X-RStudio-Root-Path
defined as in the examples above. There’s little involvement of the proxy when using these headers.
If you have little experience with proxies but still want to use a custom path, we recommend using the www-root-path
option in RStudio and at least the headers X-Forwarded-Host
and X-Forwarded-Proto
.
Finally, if you want the proxy to have total control of custom path then define the rewrite rules yourself directly in the proxy configuration based on the alternatives suggested in the example above. In this case, do not use the option www-root-path
or the header X-RStudio-Root-Path
.
4.12.6 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 roothttp
node, and should be used for altering basic HTTP settings/etc/rstudio/nginx.server.conf
- allows you to add additional nginx directives under theserver
node, and should be used for altering basic server settings/etc/rstudio/nginx.site.conf
- allows you to add additional nginx directives under thelocation /
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.