rcloud.conf

RCloud is configured using a few configuration files: rserve.conf for the Rserve configuration and rcloud.conf which configures RCloud-specific behavior. Ideally, we would like to have just one file, but we're not there yet.

rcloud.conf allows arbitrary settings to be loaded into the .rc.conf configuration environment. Currently the file is in DCF (Debian Control File) format which is essentially Key: value ASCII file (this is for our convenience as R has read.dcf). The following settings are currently acted upon in the latest version of RCloud:

• Host: specifies the FQDN of the host running this instance. RCloud attempts to auto-detect this setting if not set
• Cookie.Domain: domain to use for setting cookies (defaults to Host: if not set). Since RCloud 2.1.2 this can have a special value * in which case RCloud will not try to set the domain and relies on the browser to use the domain of the document. This should be only used in special cases for transient deployment where the URL is not known a-priori, e.g., when running multiple deployment instances on a Kubernetes cluster from a fixed image.
• Session.Server: URL to the session server if the sessions server is to be used instead of flat files. Note that some features such as execution authentication requires a session server.
• Exec.auth: execution authentication method. If set, additional authentication is performed for the execution environment and the user of the session can be switched accordingly (see below). Currently supported values are pem which uses PEM (pluggable authentication modules - either Linux-PEM or OpenPEM is supported) to authenticate as a used of the RCloud machine, or as-local which considers the local user as automatically authenticated.
• Exec.match.user: if set to login then the execution environment switches the user according to the execution authentication result. Note that the Rserve instance must be run as root for this to work.
• Exec.anon.user: if set, anonymous users (i.e. those without GitHub credentials) will be allowed in Exec.auth mode and will switch to the given execution user. If Exec.auth is enabled and this option is not set, then anonymous access is denied.
• Exec.token.renewal.time: if set, integer, specifies the interval (in seconds) after which RCloud will request renewal of the execution token, invalidating the previous one in the process (to avoid abuse of excessive token lifetime). (since RCloud 1.3)
• Http.User: user-id to switch to when serving HTTP/HTTPS requests through Rserve. Again, only meaningful when Rserve is run with elevated privileges.
• Welcome.page: URL (can be relative) to the file that will be used to request execution authentication. The referenced page should take a ?redirect= query parameter to enable returning to the current page after login. Defaults to /rcloud.html since RCloud 2.2, in previous versions the default was /welcome.html
• Welcome.info: a string that will be appended to welcome info line on login, it will be interpreted as if passed to echo on a shell (i.e., supports backticks and shell variable expansion). Defaults to an empty string. (since RCloud 1.7)
• Goodbye.page: URL (can be relative) that will be loaded after RCloud logout. Defaults to /goodbye.R
• Preload.Data: comma separated list of RData files to load on startup
• Locale: locale to use for running R sessions (defaults to en_US.UTF-8). Note that we only test UTF-8 locales.
• cURL.CAinfo: path to a certificate bundle that may be needed to establish TLS/SSL connections. This is useful in cases where the system cURL installation does not have all necessary root or intermediate certificates. If the path is relative, it will be treated as relative to the configuration root (typically conf/).
• rcs.engine: back-end to use for RCloud Storage (RCS) which holds global state of an RCloud deployment. If not specified, flat-files are used which only works reliably in a single-user setting. For distributed deployment, redis engine is preferred.
• rcs.redis.host: host (or optionally host:port) of the Redis server to use for RCS. Defaults to localhost:6379 (this and the following two settings apply only when rcs.engine: redis is used)
• rcs.redis.db: database (integer) to use for RCloud in redis, defaults to 0 (since RCloud 1.3)
• rcs.redis.password: password to use when connecting to the Redis instance. The default is to not authenticate. (since RCloud 1.3)
• CRAN.mirror: URL to the default CRAN mirror to use if no CRAN mirror is set in the the repos option by other means. (since RCloud 1.1.2)
• compute.separation.modes: list of modes (comma separated, spaces allowed) that will use separation of the control and compute plane. If not set, compute separation is not used. (since RCloud 1.3)
• http.static.nocache: logical (yes or TRUE vs anything else), if enabled Cache-control: no-cache HTTP header is added for static content disallowing proxies and browsers to cache content. The default for RCloud 1.3-1.3.2 was yes, for all other versions is no. (since RCloud 1.3.3)
• rcloud.languages: list of packages (comma separated, spaces allowed) that will be loaded at RCloud start to provide languages for the cells. More information about RCloud language extensions on the wiki page
• rcloud.alluser.addons: list of packages that will be loaded at the start of each session, usually to provide UI extensions. (Formerly rcs.system.config.addons.)
• use.gist.user.home: if set to yes then the gist username is used as the home for the user. This is can be used in cases where there is no execution authentication, but there is notebook authentication and a desire to keep homes of those users separate. (since RCloud 1.5.3)
• support.email: if set, collapsed stack traces in the session pane and fatal error dialog will include a "email error" link which starts an email (using a mailto: link) including the full stack trace
• rcloud.proxy.headers.passthrough: comma separated list of headers that proxy.R will pass through in the response. (since RCloud 2.0.1)
• authfail.page: URL (can be relative) to content to show when authentication with credentials fails. The actual URL used may include appended ?redirect=... if the authentication was performed in response to accessing some content in RCloud. If not set, a simple text message is shown instead. (since RCloud 2.2)
• tokenfail.page: see authfail.page except this one is used if a token cannot be validated by login_successful.R in response to what should be a successful login (i.e., authentication succeeded, but the cookie token doesn't work - very rare condition). (since RCloud 2.2)

The following settings establish link to the notebook store on GitHub and/or other content:

• gist.backend: package providing back-end for the notebook store. RCloud includes githubgist which uses GitHub Gist API and gitgist which uses local GIT repositories. githubgist is currently the default but it may change in the future, so it is recommended to specify it explicitly. (since RCloud 1.2)

Different back-ends have different options that can be used. The following settings are used by the githubgist backend:

• github.client.id: client ID (mandatory!)
• github.client.secret: client secret (mandatory!)
• github.base.url: GitHub base URL, used for OAUTH if github.auth.forward is not set, and used for Open in GitHub with /gist if github.gist.url is not set. Prior to RCloud 1.8, this defaults to https://github.com/; no default in 1.8+.
• github.gist.url: URL for Open in GitHub. In RCloud 1.8+, if neither github.base.url nor github.gist.url is set, Open in GitHub will be disabled.
• github.api.url: GitHub API URL. Prior to RCloud 1.8, defaults to https://api.github.com/; not default in 1.8+.
• github.user.whitelist: optional, if set, only users in this list (, separated, no spaces) will be allowed to login
• github.auth: optional, if set to exec.token then the back-end is expected to use the same execution token as RCloud itself (instead of storing a separate token). This is useful for using our gist service server instead of GitHub. (since RCloud 1.8)
• github.auth.forward: optional, URL to use as target for pass-through authentication when github.auth: exec.token is used. It is typically https://your-rcloud-host-name/login_successful.R to use RCloud built-in target. (since RCloud 1.8)
• github.use.query.token: in 2020, github.com deprecated use of query string parameters in favor HTTP headers. If you are getting warning emails from GitHub, set this flag to false. Defaults to true for compatibility with rcloud-gist-services.

The gitgist backend uses the following settings::

• gist.git.root: path to the GIT storage root (mandatory, typically ${ROOT}/data/gists)

The search is implemented using SOLR. The following options are related to the search:

• solr.url: defines the URL for the SOLR instance. If not set, the search feature is not available.
• solr.auth.user, solr.auth.pwd: user/password for SOLR requests if authentication is required (optional).
• solr.post.method allows to change the way SOLR POST update requests are issued. It can have one of the values async (default in RCloud 1.8: asynchronous, internal httr), sync (synchronous, internal httr - used in RCloud 1.7) or curl (asynchronous external curl command). Generally, sync is the safest but can have impact on user experience if the SOLR instance takes longer to respond. async works best on most systems except for RedHat which has a bug in ssl which prevents it from working with SSL-secured SOLR instances - in that case curl is an alternative. (since RCloud 1.8)
• solr.curl.cmd: if solr.post.method is set to curl then this can be used to change the default invocation of curl, i.e., can be changed to a full path or even add non-standard options to CURL. (since RCloud 1.8)

A couple of options are wildcarded, controlling multiple start-up options:

• rcs.system.* sets key/value pairs to the RCS tree .allusers/system/* when RCloud is started up. See .allusers in the RCS wiki page for useful settings in that tree.

• rcloud.menu.* adds menu items to the right area of the navbar when the user interface loads - see the Navbar Menus Extension Point for more information.

Other:

• python.extra.libs: colon-separated list of paths to append to sys.path in the Python engine (only used if Python support is enabled; since RCloud 1.2)

The rcloud.jupyter package has its own set of options including rcloud.jupyter.python.path (path to the python executable), rcloud.jupyter.python.extra.libs, rcloud.jupyter.cell.exec.timeout, rcloud.jupyter.kernel.startup.timeout, rcloud.jupyter.language.mapping.config and rcloud.jupyter.connection_dir.path - see rcloud.jupyter for details.

Sections

The DCF format of the configuration file provides support for multiple sections separated by an empty line. The first section specifies the main, global configuration directives. Additional directives are interpreted according to the content. The following additional sections are supported:

• gist.source: string, names an alternative gist source to be configured. Notebooks in this source are also available in addition to the main, global gist source. The section has to contain one gist.source directive and any gist-specific directives needed to configure the source. (since RCloud 1.4)

Legacy

• gist.deployment.stash: if set, then this RCloud installation will be static (read-only) and use the supplied stash name as the source for all notebooks. This is used for deployments of services based on RCloud without the need for a GitHub instance. Do NOT set for regular RCloud deployments. The stash must be previously loaded into RCS for this to work. You can safely ignore this setting if you don't know about stashes. This setting has been superseded by the gitgist back-end which provides the same fundamental functionality but in a much more flexible manner. It was deprecated in RCloud 1.3 and removed in RCloud 1.4.