2 Server Management
2.1 Core Administrative Tasks
2.1.1 Configuration Files
RStudio Server uses several configuration files all located within the /etc/rstudio
directory. Configuration files include:
rserver.conf | Core server settings |
rsession.conf | Settings related to individual R sessions |
notifications.conf | Notifications to be delivered to user sessions Pro |
profiles | User and group resource limits Pro |
r-versions | Manual specification of additional versions of R Pro |
ip-rules | IP access rules (allow or deny groups of IP addresses) Pro |
load-balancer | Load balancing configuration Pro |
health-check | Template for content to return for server health checks Pro |
google-accounts | Mappings from Google accounts to local accounts Pro |
file-locks | Configuration for file locking |
login.html | Custom HTML for login page |
The rserver.conf
and rsession.conf
files are created by default during installation however the other config files are optional so need to be created explicitly. It should be noted that the rsession.conf
file must be readable by each RStudio user, so it should be given appropriate permissions (e.g. 644).
The notifications.conf
and r-versions
files are created, but their entries are commented out as an example.
Whenever making changes to configuration files you need to restart the server for them to take effect. You can do this using the restart
command of the server management utility:
$ sudo rstudio-server restart
2.1.2 Stopping and Starting
During installation RStudio Server is automatically registered as a daemon which starts along with the rest of the system. The exact nature of this will depend on the init system in use on your system: - On systems using systemd (such as Debian 7, Ubuntu 15, and RedHat/CentOS 7), this registration is performed as a systemd script at /etc/systemd/system/rstudio-server.service
. - On systems using Upstart (such as older versions of Debian and Ubuntu, and RedHat/CentOS 6), this registration is performed using an Upstart script at /etc/init/rstudio-server.conf
. - On systems using init.d, including RedHat/CentOS 5, an init.d script is installed at /etc/init.d/rstudio-server.
To manually stop, start, and restart the server you use the following commands:
$ sudo rstudio-server stop
$ sudo rstudio-server start
$ sudo rstudio-server restart
To check the current stopped/started status of the server:
$ sudo rstudio-server status
2.1.3 Managing Active Sessions
There are a number of administrative commands which allow you to see what sessions are active and request suspension of running sessions.
To list all currently active sessions:
$ sudo rstudio-server active-sessions
2.1.3.1 Suspending Sessions
When R sessions have been idle (no processing or user interaction) for a specified period of time (2 hours by default) RStudio Server suspends them to disk to free up server resources. When the user next interacts with their session it is restored from disk and the user resumes right back where they left off. This is all done seamlessly such that users aren’t typically aware that a suspend and resume has occurred.
To manually suspend an individual session:
$ sudo rstudio-server suspend-session <pid>
To manually suspend all running sessions:
$ sudo rstudio-server suspend-all
The suspend commands also have a “force” variation which will send an interrupt to the session to request the termination of any running R command:
$ sudo rstudio-server force-suspend-session <pid>
$ sudo rstudio-server force-suspend-all
The force-suspend-all
command should be issued immediately prior to any reboot so as to preserve the data and state of active R sessions across the restart.
2.1.3.2 Killing Sessions
If you are for any reason unable to cooperatively suspend an R session using the commands described above you may need to force kill the session. Force killing a session results in SIGKILL being sent to the process, causing an immediate termination.
To force kill an individual session:
$ sudo rstudio-server kill-session <pid>
To force kill all running sessions:
$ sudo rstudio-server kill-all
Note that these commands should be exclusively reserved for situations where suspending doesn’t work as force killing a session can cause user data loss (e.g. unsaved source files or R workspace content).
2.1.4 Taking the Server Offline
If you need to perform system maintenance and want users to receive a friendly message indicating the server is offline you can issue the following command:
$ sudo rstudio-server offline
When the server is once again available you should issue this command:
$ sudo rstudio-server online
2.1.5 Upgrading to a New Version
If you perform an upgrade of RStudio Server and an existing version of the server is currently running, then the upgrade process will also ensure that active sessions are immediately migrated to the new version. This includes the following behavior:
- Running R sessions are suspended so that future interactions with the server automatically launch the updated R session binary
- Currently connected browser clients are notified that a new version is available and automatically refresh themselves.
- The core server binary is restarted
To upgrade to a new version of RStudio Server you simply install the new version. For example on Debian/Ubuntu:
$ sudo gdebi <rstudio-server-package.deb>
For RedHat/CentOS:
$ sudo yum install <rstudio-server-package.rpm>
For openSUSE / SLES:
$ sudo zypper install <rstudio-server-package.rpm>
2.2 Administrative Dashboard
RStudio Server includes an administrative dashboard with the following features:
- Monitoring of active sessions and their CPU and memory utilization;
- The ability to suspend, forcibly terminate, or assume control of any active session;
- Historical usage data for individual server users (session time, memory, CPU, logs);
- Historical server statistics (CPU, memory, active sessions, system load); and
- Searchable server log (view all messages or just those for individual users)
The dashboard can be an invaluable tool in understanding server usage and capacity as well as to diagnose and resolve problems.
Note that at this time, historical monitoring is not available for sessions spawned via the Job Launcher.
2.2.1 Enabling the Dashboard
The administrative dashboard is accessed at the following URL:
http://<server-address>/admin
The administrative dashboard is disabled by default. To enable it you set the admin-enabled
option. You can also specify that only users of certain group have access to the dashboard using the admin-group
option. For example:
/etc/rstudio/rserver.conf
admin-enabled=1
admin-group=rstudio-admins
You can specify a single group as the above example does or a comma-delimited list of groups. For example:
/etc/rstudio/rserver.conf
admin-group=server-admins,rstudio-admins,domain-admins
Note that changes to the configuration will not take effect until the server is restarted.
2.2.2 Administrator Superusers
You can further designate a certain user or group of users as administrative “superusers”. Superusers have the following additional privileges:
- Suspend or terminate active sessions
- Assume control of active sessions (e.g. for troubleshooting)
- Login to RStudio as any other server user
Administrative superusers do not have root privilege on the system, but rather have a narrow set of delegated privileges that are useful in managing and supporting the server. You can define the users with this privilege using the admin-superuser-group
setting. For example:
/etc/rstudio/rserver.conf
admin-superuser-group=rstudio-superuser-admins
Note that as with the admin groups above, you can specify a single group as the above example does or a comma-delimited list of groups. For example:
/etc/rstudio/rserver.conf
admin-superuser-group=rstudio-superuser-admins,domain-admins
Changes to the configuration will not take effect until the server is restarted.
2.2.3 Server Log Time Zone
You can control the time zone in which the server logs are displayed in the admin dashboard by the use of the admin-monitor-log-use-server-time-zone
option. For example:
/etc/rstudio/rserver.conf
admin-monitor-log-use-server-time-zone=1
Setting this option to 1
will display the server logs in the server’s time zone. The default value of 0
will display the log times in UTC.
2.2.3.1 Google Accounts Restrictions
Note that the ability to login as other users and assume control of existing sessions is not available if you are authenticating with Google Accounts. This is because Google authentication uses a different user-identity mechanism which isn’t compatible with the way that user session impersonation is implemented.