Configuration

Relying on the default build is fine for a demo deployment, but it is not recommended for a production environment. Options can be configured by default under the file /etc/ood/config/ood_portal.yml.

This project includes a good starting configuration file that you can use:

sudo cp share/ood_portal_example.yml /etc/ood/config/ood_portal.yml

All the default options are listed in this configuration file. Feel free to read it through before continuing on.

Configure General Options

listen_addr_port (String, Array<String>, null)

the address and port server listens on for connections

Default

Don’t add a Listen directive in this Apache config (typically it exists in another config)

listen_addr_port: null

Example

Explicitly listen on port 443

listen_addr_port: "443"

servername (String, null)

the host name used to access the Open OnDemand portal

Default

Access website through IP address only

servername: null

Example

Access website through the host name www.example.com

servername: "www.example.com"

port (Integer, null)

the port used to access the Open OnDemand portal (if different than 80 or 443)

Default

Use port 80 or port 443 if SSL is enabled

port: null

Example

Use a higher numbered port to access the website

port: 8080

ssl (Array<String>, null)

a list of Apache directives that enable SSL support

Default

Disable SSL support

ssl: null

Example

See Add SSL Support

logroot (String)

the root directory where log files are stored (can be relative to ServerRoot)

Default

Store logs in $ServerRoot/logs directory

logroot: "logs"

Example

Store logs in a different directory

logroot: "/path/to/my/logs"

use_rewrites (Boolean)

Should RewriteEngine be used

Default

Use RewriteEngine

use_rewrites: true

Example

Disable RewriteEngine usage

use_rewrites: false

use_maintenance (Boolean)

Enable Rewrite rules for supporting maintenance mode of OnDemand Requires use_rewrites to be true

Default

Support maintenance mode support

use_maintenance: true

Example

Disable maintenance mode support

use_maintenance: false

maintenance_ip_whitelist (Array<String>)

List of IP regular expressions to be allowed to access OnDemand when maintenance is enabled

Default

No IPs are whitelisted

maintenance_ip_whitelist: []

Example

Allow 192.168.1.0/24 and 10.0.0.1 to access OnDemand during maintenance

maintenance_ip_whitelist:
  - '192.168.1..*'
  - '10.0.0.1'

lua_root (String)

the root directory where the Lua handler code resides

Default

Point to the install location of mod_ood_proxy

lua_root: "/opt/ood/mod_ood_proxy/lib"

Example

Point to a different directory

lua_root: "/path/to/lua/handlers"

lua_log_level (String, null)

the verbosity of the Lua module in the logs

Default

Use default log level of info

lua_log_level: null

Example

Decrease verbosity

lua_log_level: "warn"

user_map_cmd (String)

the system command used to map authenticated user name to a system user name

Default

Use ood_auth_map and echo back the authenticated user name as the system user name

user_map_cmd: "/opt/ood/ood_auth_map/bin/ood_auth_map.regex"

Example

Capture system user name from regular expression

user_map_cmd: "/opt/ood/ood_auth_map/bin/ood_auth_map.regex --regex='^(\\w+)@example.com'"

user_env (String, null)

the CGI environment variable that holds the authenticated user name used as the argument for the user mapping command

Default

Use REMOTE_USER if not defined

user_env: null

Example

Use a custom environment variable instead

user_env: "OIDC_CLAIM_preferred_username"

map_fail_uri (String, null)

the URI a user is redirected to if we fail to map the authenticated user name to a system user name

Default

Don’t redirect the user and just display an error message

map_fail_uri: null

Example

Redirect the user to a registration page you set up beforehand

map_fail_uri: "/register"

pun_stage_cmd (String)

the system command used to launch the nginx_stage command with sudo privileges

Default

Use default install location

pun_stage_cmd: "sudo /opt/ood/nginx_stage/sbin/nginx_stage"

Example

Use a different install location

pun_stage_cmd: "sudo /path/to/nginx_stage"

auth (Array<String>)

the list of Apache directives defining how authentication is handled for various protected resources on the website

Default

Use basic authentication with a plain-text password file (see Default Authentication)

auth:
  - "AuthType Basic"
  - "AuthName \"private\""
  - "AuthUserFile \"/opt/rh/httpd24/root/etc/httpd/.htpasswd\""
  - "RequestHeader unset Authorization"
  - "Require valid-user"

Example

See:

• Add LDAP Authentication
• Add Shibboleth Authentication
• Add CILogon Authentication

root_uri (String)

the URI a user is redirected to when they access the root of the website (e.g., https://www.example.com/)

Default

Redirect the user to the Dashboard App

root_uri: "/pun/sys/dashboard"

Example

Redirect to a different URI

root_uri: "/my_uri"

analytics (Hash, null)

the object describing how to track server-side analytics with a Google Analytics account and property

Default

Do not track analytics

analytics: null

Example

See Add Google Analytics

Configure Public Assets

This is a location where files can be served without a user being authenticated. Useful to serve favicon, images, or user documentation. If either of these properties are null then users won’t be able to access public assets through the website.

public_uri (String, null)

the URI used to access public assets (no authentication needed)

Default

Access as http://www.example.com/public

public_uri: "/public"

Example

Access under a different URI

public_uri: "/assets"

public_root (String, null)

the root directory where the public assets are served from

Default

Using a default installation

public_root: "/var/www/ood/public"

Example

Serve files under a different directory

public_root: "/path/to/public/files"

Configure Logout Redirect

The Dashboard App will send the user to this URI when they click the Logout button. This URI will then redirect the user to the logout mechanism for your corresponding authentication mechanism. If either of these properties are null then users will get an error when they try to logout from the Dashboard App.

logout_uri (String, null)

the URI used to logout from an Apache session

Default

Access as http://www.example.com/logout

logout_uri: "/logout"

Example

Access under a different URI

logout_uri: "/log_me_out"

logout_redirect (String, null)

the URI the user is redirected to when accessing the logout URI above

Default

Fallback to the Dashboard App log out page

logout_redirect: "/pun/sys/dashboard/logout"

Example

See:

• Add Shibboleth Authentication
• Add CILogon Authentication

Configure Reverse Proxy

The reverse proxy will proxy a request to any specified host and port through IP sockets. This is different than what is used for proxying to per-user NGINX processes through Unix domain sockets. This can be used to connect to Jupyter notebook servers, RStudio servers, VNC servers, and more… This is disabled by default as it can be security risk if not properly setup using a good host_regex.

A URL request to the node_uri will reverse proxy to the given host and port using the full URI path. So a request to the frontend Apache proxy that looks like:

GET /<node_uri>/<host>/<port>/... HTTP/1.1
Host: ondemand.example.edu

will be reverse proxied to the backend server with the following request format:

GET /<node_uri>/<host>/<port>/... HTTP/1.1
Host: <host>:<port>

A URL request to the rnode_uri will reverse proxy to the given host and port using the relative URI path. So a request to the frontend Apache proxy that looks like:

GET /<rnode_uri>/<host>/<port>/... HTTP/1.1
Host: ondemand.example.edu

will be reverse proxied to the backend server with the following request format:

GET /... HTTP/1.1
Host: <host>:<port>

Notice that we strip off the portion of the URI request path that is used to determine the backend web server.

Both formats are provided to better support the varying capabilities for the multitude of web application servers. For the case of using node_uri the developer will need to modify the web server to accommodate requests with a sub-URI that follows the dynamic formatting of /<node_uri>/<host>/<port>. For the case of using rnode_uri the developer needs to confirm that all assets and links supplied by the web server are relative and not absolute.

host_regex (String)

the regular expression used as a whitelist for allowing a user to reverse proxy to a given host

Default

Allow proxying to all hosts in the world (please change this if you enable this feature)

host_regex: "[^/]+"

Example

Restrict access to only within internal network

host_regex: "[\\w.-]+\\.example\\.com"

node_uri (String, null)

the URI used to reverse proxy a user to a server running on a given host and port that knows the full URI path

Default

This feature is disabled by default

node_uri: null

Example

Use the recommended URI by our team

node_uri: "/node"

rnode_uri (String, null)

the URI used to reverse proxy a user to a server running on a given host and port that knows the relative URI path

Default

This feature is disabled by default

rnode_uri: null

Example

Use the recommended URI by our team

rnode_uri: "/rnode"

Configure per-user NGINX

The reverse proxy will proxy a request under the pun_uri URI to the user’s per-user NGINX (PUN) process through Unix domain sockets. It will send process signals to the user’s PUN through the nginx_uri URI. If either of these properties are null then PUN access will be disabled.

nginx_uri (String, null)

the URI used to control the PUN process

Default

User’s can send signals to PUN through http://www.example.com/nginx

nginx_uri: "/nginx"

Example

Use a different URI

node_uri: "/my_pun_controller"

pun_uri (String, null)

the URI used to access the PUN process

Default

User’s access their PUN through http://www.example.com/pun

pun_uri: "/pun"

Example

Use a different URI

pun_uri: "/my_pun_apps"

pun_socket_root (String)

the root directory that contains the socket files for the running PUNs

Default

Using a default installation

pun_socket_root: "/var/run/ondemand-nginx"

Example

Socket files are located in a different directory

pun_socket_root: "/path/to/pun/sockets"

pun_max_retries (Integer)

the number of times the proxy attempt to connect to the PUN before giving up and displaying an error to the user

Default

Only try 5 times

pun_max_retries: 5

Example

Try 25 times

pun_max_retries: 25

Configure OpenID Connect

If using OpenID Connect for authentication, these are a few properties you will need to tweak. For a better understanding of these options you should read more on mod_auth_openidc.

oidc_uri (String, null)

the redirect URI used by mod_auth_openidc for authentication

Default

This is disabled by default

oidc_uri: null

Example

Enable it on a recommended URI

oidc_uri: "/oidc"

oidc_discover_uri (String, null)

the URI a user is redirected to if they are not authenticated by mod_auth_openidc and is used to discover the ID provider the user will use to login through

Default

This is disabled by default

oidc_discover_uri: null

Example

Enable it to a recommended URI

oidc_discover_uri: "/discover"

oidc_discover_root (String, null)

the root directory on the file system that serves the HTML code used for the discovery page

Default

This is disabled by default

oidc_discover_root: null

Example

Enable it to the recommended path

oidc_discover_root: "/var/www/ood/discover"

Configure User Registration

If you are using a grid-mapfile to map the authenticated user name to a system user name, then this will be used to generate mappings in the file for a user’s first time accessing your website. Setting either property below to null will disable this feature.

Note

This is unnecessary if you use regular expressions for mapping the authenticated user name to a system user name.

register_uri (String, null)

the URI a user is redirected to if no mapping exists between an authenticated user name and a system user name

Default

This is disabled by default. An error is displayed the user if mapping fails.

register_uri: null

Example

Enable it to a recommended URI

register_uri: "/register"

register_root (String, null)

the root directory on the file system that serves the HTML code used for the registration page

Default

This is disabled by default. An error is displayed the user if mapping fails.

register_root: null

Example

Enable it to the recommended path

register_root: "/var/www/ood/register"