diff --git a/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/configure-cilogon.rst.txt b/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/configure-cilogon.rst.txt index 48b477663..954353de4 100644 --- a/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/configure-cilogon.rst.txt +++ b/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/configure-cilogon.rst.txt @@ -5,7 +5,7 @@ Configure Keycloak with CILogon We will now use Keycloak's admin Web UI to setup the ability to log existing users in with CILogon. -When a user logs in with CILogon for the first time they will be redirected back to Keycloak to log in with their local (ie LDAP) +When a user logs in with CILogon for the first time they will be redirected back to Keycloak to log in with their local (i.e., LDAP) credentials. This performs a mapping of their CILogon identity with their Keycloak identity. .. warning:: @@ -18,11 +18,11 @@ Register your Keycloak instance with CILogon #. Go to ``https://cilogon.org/oauth2/register`` and fill out the form - #. The Home URL will be the base URL of your Keycloak instance, eg: ``https://ondemand-idpdev.hpc.osc.edu``. + #. The Home URL will be the base URL of your Keycloak instance, e.g.: ``https://ondemand-idpdev.hpc.osc.edu``. #. The callback URL will be ``https://ondemand-idpdev.hpc.osc.edu/auth/realms//broker/cilogon/endpoint``. Replace ``https://ondemand-idpdev.hpc.osc.edu`` with your Keycloak instance #. The box for "Is this a public client?" should not be checked - #. For "Scopes" be sure to check "profile" and "org.cilogon.userinfo" + #. For "Scopes" be sure to check ``profile`` and ``org.cilogon.userinfo`` You will be provided a Client ID and a Client Secret, be sure to save these values. Your registered client will not be usable until you receive an email from CILogon stating your client has been approved. @@ -36,7 +36,7 @@ Add the CILogon Identity Provider #. Select the "Add provider..." drop down and choose "OpenID Connect v1.0" #. Fill in the fields as noted below - #. Alias: cilogon (This must be cilogon as this alias is used in the callback URL) + #. Alias: ``cilogon`` (This must be ``cilogon`` as this alias is used in the callback URL) #. Display Name: CILogon #. Enabled: ON #. First Login Flow: browser @@ -46,7 +46,7 @@ Add the CILogon Identity Provider #. Client Authentication: Client secret sent as post #. Client ID: #. Client Secret: - #. Default Scopes: "openid profile org.cilogon.userinfo" + #. Default Scopes: ``openid profile org.cilogon.userinfo`` #. Click "Save" @@ -56,7 +56,7 @@ Support users removing CILogon mappings In order for a user to remove an existing CILogon mapping in Keycloak they must navigate to ``https://ondemand-idpdev.hpc.osc.edu/auth/realms//account/identity``. Replace ``ondemand-idpdev.hpc.osc.edu`` with the web URL for your Keycloak instance. -The URL can be added to the OnDemand Help dropdown with custom text to make it easier for users to access their Keycloak identity page. +The URL can be added to the OnDemand Help drop-down with custom text to make it easier for users to access their Keycloak identity page. #. Add ``OOD_DASHBOARD_HELP_CUSTOM_URL`` to ``/etc/ood/config/apps/dashboard/env`` that points to the URL of the identity page for your Keycloak instance. Example: ``https://ondemand-idpdev.hpc.osc.edu/auth/realms/osc/account/identity`` diff --git a/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/configure-keycloak-webui.rst.txt b/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/configure-keycloak-webui.rst.txt index 6ac157a96..b5abca7c6 100644 --- a/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/configure-keycloak-webui.rst.txt +++ b/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/configure-keycloak-webui.rst.txt @@ -23,16 +23,16 @@ Configure LDAP ------------------------------------------ #. Choose User Federation on the left (verify ondemand realm is current realm) -#. Select "ldap" for provider +#. Select ``ldap`` for provider #. Import Users set to OFF #. Edit Mode set to READ_ONLY #. Vendor set to other – for OpenLDAP - #. User Object Classes set to posixAccount – OSC specific and odd - #. Connection URL: ldaps://ldap1.infra.osc.edu:636 ldaps://ldap2.infra.osc.edu:636 – using multiple to demonstrate more than 1 - #. User DN: ou=People,dc=osc,dc=edu + #. User Object Classes set to ``posixAccount`` – OSC specific and odd + #. Connection URL: ``ldaps://ldap1.infra.osc.edu:636 ldaps://ldap2.infra.osc.edu:636`` – using multiple to demonstrate more than 1 + #. User DN: ``ou=People,dc=osc,dc=edu`` #. Auth Type: none – OSC specific as we allow anonymous binds - #. Use Truststore SPI: never – OSC specific since our LDAP certificates are already trusted since from InCommon, leaving default is probably acceptable if no truststoreSpi defined in XML configs + #. Use Truststore SPI: never – OSC specific since our LDAP certificates are already trusted since from InCommon, leaving default is probably acceptable if no ``truststoreSpi`` defined in XML configurations. #. Save @@ -48,8 +48,8 @@ Add OnDemand as a client #. Choose Clients, then click Create in top right corner - #. Client ID: ondemand-dev.hpc.osc.edu - #. Client Protocol: openid-connect + #. Client ID: ``ondemand-dev.hpc.osc.edu`` + #. Client Protocol: ``openid-connect`` #. Save (leave Root URL blank) #. Then edit Settings for the newly created client: @@ -65,6 +65,6 @@ Add OnDemand as a client #. Finally, get the client secret to use with OnDemand installation: - #. Select the "Credentials" tab of the "Client" you are viewing i.e. "Clients >> ondemand-dev.hpc.osc.edu" + #. Select the "Credentials" tab of the "Client" you are viewing i.e. ``Clients >> ondemand-dev.hpc.osc.edu`` #. Copy the value for "secret" for future use in this tutorial (and keep it secure). diff --git a/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/install-keycloak.rst.txt b/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/install-keycloak.rst.txt index d2c22232f..bebd4b120 100644 --- a/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/install-keycloak.rst.txt +++ b/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/install-keycloak.rst.txt @@ -6,7 +6,7 @@ Install Keycloak We will install and launch Keycloak server behind Apache. Login to the host where you will install Keycloak. In this tutorial, we are -installing Keycloak on the same host as OnDemand, which is webdev07.hpc.osc.edu. +installing Keycloak on the same host as OnDemand, which is ``webdev07.hpc.osc.edu``. .. warning:: @@ -25,7 +25,7 @@ Initial Installation Steps sudo tar xzf keycloak-9.0.0.tar.gz -#. Add keycloak user and change ownership of files +#. Add ``keycloak`` user and change ownership of files .. code-block:: sh @@ -38,13 +38,13 @@ Initial Installation Steps sudo install -d -o keycloak -g keycloak /var/lib/keycloak - This makes a home directory, which is needed when running API calls as keycloak user. Finally we set proper permissions: + This makes a home directory, which is needed when running API calls as ``keycloak`` user. Finally we set proper permissions: .. code-block:: sh sudo chown keycloak: -R keycloak-9.0.0 -#. Restrict access to keycloak-9.0.0/standalone, which will contain +#. Restrict access to ``keycloak-9.0.0/standalone``, which will contain sensitive data for the Keycloak server .. code-block:: sh @@ -60,7 +60,7 @@ Initial Installation Steps sudo yum install java-1.8.0-openjdk-devel -#. Added 'admin' to '/opt/keycloak-9.0.0/standalone/configuration/keycloak-add-user.json', (re)start server to load user. +#. Added 'admin' to ``/opt/keycloak-9.0.0/standalone/configuration/keycloak-add-user.json``, (re)start server to load user. If you are not already there: @@ -87,22 +87,22 @@ Initial Installation Steps sudo -u keycloak ./bin/jboss-cli.sh 'embed-server,/socket-binding-group=standard-sockets/socket-binding=proxy-https:add(port=443)' sudo -u keycloak ./bin/jboss-cli.sh 'embed-server,/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=redirect-socket,value=proxy-https)' - Or you can use a config.cli file that contains these commands. We have + Or you can use a ``config.cli`` file that contains these commands. We have provided an example file to make use of in this gist, with blocks commented - out so you can wget the file, edit as appropriate, and run via: + out so you can ``wget`` the file, edit as appropriate, and run via: .. code-block:: sh sudo -u keycloak ./bin/jboss-cli.sh --file=config.cli - Where the config.cli looks like: + Where the ``config.cli`` looks like: .. literalinclude:: example-keycloak-jboss-config.cli Start Keycloak Server ------------------------- -#. Create keycloak.service to start and stop the server: +#. Create ``keycloak.service`` to start and stop the server: .. code-block:: sh @@ -125,7 +125,7 @@ Start Keycloak Server EOF - Then start keycloak: + Then start ``keycloak``: .. code-block:: sh @@ -148,7 +148,7 @@ Start Keycloak Server Place Apache in front of Keycloak --------------------------------- -#. Define apache config to proxy keycloak requests +#. Define apache configuration to proxy Keycloak requests. .. note:: @@ -164,7 +164,7 @@ Place Apache in front of Keycloak Add ``/opt/rh/httpd24/root/etc/httpd/conf.d/ood-keycloak.conf``, making changes for the appropriate SSL certificate locations. Notice we are proxying ``https://ondemand-idpdev.hpc.osc.edu`` to ``http://localhost:8080`` which is the default - port the Keycloak webserver runs as. + port the Keycloak web-server runs as. .. literalinclude:: example-keycloak-apache.conf @@ -185,13 +185,13 @@ Differences if installing Keycloak on separate host When installing Keycloak on a separate host, the difference between this tutorial would be: -#. throughout the rest of the tutorial replace ``https://ondemand-idpdev.hpc.osc.edu`` with the keycloak host +#. throughout the rest of the tutorial replace ``https://ondemand-idpdev.hpc.osc.edu`` with the Keycloak host #. possibly use Apache 2.4 default distribution instead of software collections, - meaning that configuration would be at /etc/httpd/conf.d/ instead of - /opt/rh/httpd24/root/etc/httpd/conf.d/ and starting the + meaning that configuration would be at ``/etc/httpd/conf.d/`` instead of + ``/opt/rh/httpd24/root/etc/httpd/conf.d/`` and starting the service is likely ``sudo systemctl start httpd`` instead of ``sudo systemctl start httpd24-httpd`` -For example, if Keycloak were installed on a separate host idp.hpc.edu then the -Apache config might look like: +For example, if Keycloak were installed on a separate host ``idp.hpc.edu`` then the +Apache configuration might look like: .. literalinclude:: example-keycloak-apache-separate-host.conf diff --git a/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/install_mod_auth_openidc.rst.txt b/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/install_mod_auth_openidc.rst.txt index 18b201623..6b571eabf 100644 --- a/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/install_mod_auth_openidc.rst.txt +++ b/latest/_sources/authentication/tutorial-oidc-keycloak-rhel7/install_mod_auth_openidc.rst.txt @@ -3,21 +3,21 @@ Configure OnDemand to authenticate with Keycloak ================================================ -OnDemand's Apache needs to use mod_auth_openidc to be able to act as an OpenID -Connect client to Keycloak. We will install mod_auth_openidc and modify -OnDemand's Apache configs to enable authentication via Keycloak. +OnDemand's Apache needs to use ``mod_auth_openidc`` to be able to act as an OpenID +Connect client to Keycloak. We will install ``mod_auth_openidc`` and modify +OnDemand's Apache configurations to enable authentication via Keycloak. -Install mod_auth_openidc ------------------------- +Install ``mod_auth_openidc`` +---------------------------- -#. Install httpd24-mod_auth_openidc from ondemand-web repo +#. Install ``httpd24-mod_auth_openidc`` from ondemand-web repository. .. code-block:: sh sudo yum install httpd24-mod_auth_openidc -Re-generate main config using ood-portal-generator +Re-generate main configuration using ood-portal-generator ----------------------------------------------------------- #. Edit the YAML configuration file for the :ref:`ood-portal-generator` located @@ -49,12 +49,12 @@ Re-generate main config using ood-portal-generator Notice that we are - * changing the Authentication directives for openid-connect - * specifying /oidc to be the sub-uri used by mod_auth_openidc - * specifying that /logout should redirect to this /oidc sub-uri to handle logout + * changing the Authentication directives for ``openid-connect`` + * specifying ``/oidc`` to be the URI used by ``mod_auth_openidc`` + * specifying that /logout should redirect to this ``/oidc`` URI to handle logout and specifying after logout, the user should be redirected back to OnDemand (which in this tutorial's case is ``https%3A%2F%2Fondemand-dev.hpc.osc.edu``, - the query param escaped format of ``https://ondemand-dev.hpc.osc.edu``) + the query parameter escaped format of ``https://ondemand-dev.hpc.osc.edu``) #. Then build and install the new Apache configuration file with: @@ -62,7 +62,7 @@ Re-generate main config using ood-portal-generator sudo /opt/ood/ood-portal-generator/sbin/update_ood_portal - The effect of this change in the Apache config (in case you want to apply the changes manually) are: + The effect of this change in the Apache configuration (in case you want to apply the changes manually) are: #. Change the authentication directives for all of the Locations that require authentication i.e.: @@ -100,10 +100,10 @@ Re-generate main config using ood-portal-generator Require valid-user -Add Keycloak config to OnDemand Apache for mod_auth_openidc ------------------------------------------------------------ +Add Keycloak configuration to OnDemand Apache for ``mod_auth_openidc`` +---------------------------------------------------------------------- -#. Add the file /opt/rh/httpd24/root/etc/httpd/conf.d/auth_openidc.conf with the contents: +#. Add the file ``/opt/rh/httpd24/root/etc/httpd/conf.d/auth_openidc.conf`` with the contents: .. code-block:: none @@ -140,7 +140,7 @@ Add Keycloak config to OnDemand Apache for mod_auth_openidc #. Then restart OnDemand's Apache. OnDemand should now be authenticating using KeyCloak. - Stop both servives: + Stop both services: .. code-block:: sh diff --git a/latest/_sources/customizations.rst.txt b/latest/_sources/customizations.rst.txt index 1ebb49c93..553a26961 100644 --- a/latest/_sources/customizations.rst.txt +++ b/latest/_sources/customizations.rst.txt @@ -47,7 +47,7 @@ To add an announcement message that appears at the top of the dashboard you can On each request the dashboard will check for the existence of this file. If it exists, the contents will be converted using markdown converter to HTML and displayed inside a bootstrap alert. -For example, if I create an announcement.md file with the contents: +For example, if I create an ``announcement.md`` file with the contents: .. code-block:: md @@ -62,7 +62,7 @@ the user would see this message at the top of the dashboard: Example of the Dashboard announcement. -If the announcement file has the extension ``yml`` and is a yaml file it is first rendered using ERB and then the resulting file is parsed as YAML. The valid keys are: +If the announcement file has the extension ``yml`` and is a YAML file it is first rendered using ERB and then the resulting file is parsed as YAML. The valid keys are: .. list-table:: Announcement configuration keys. @@ -70,19 +70,19 @@ If the announcement file has the extension ``yml`` and is a yaml file it is firs - Description * - type - The type of announcement. Values can be ``warning``, ``info``, ``success``, or ``danger``. - * - msg + * - ``msg`` - The announcement's message. - * - id + * - ``id`` - Optional unique identifier for the announcement. This is useful for managing changes to announcements that are used as ToS or EULA that users need to agree to. When provided, it will be used to validate if the announcement has been dismissed regardless of the content. Changing the ``id`` will make the announcement appear again. - * - dismissible + * - ``dismissible`` - Specify if the announcement is dismissible or not with ``true`` or ``false``. Defaults to ``true``. - * - required + * - ``required`` - Specify if the announcement is required or not with ``true`` or ``false``. Defaults to ``false``. When this is set to ``true``, the OOD UI will only render the announcement and the user will not be able to submit jobs until the announcement has been accepted. - * - button_text + * - ``button_text`` - Optional parameter to customize the text content for the button to dismiss the announcement. Defaults to ``Accept`` for required and ``OK`` for dismissible. @@ -101,7 +101,7 @@ Because the announcement is rendered via ERB you can do some interesting things, will prevent SSH login to Ruby nodes and Ruby VDI sessions. <% end %> -.. note:: Warnings about the announcement file being missing may be present in users' nginx logs. Despite the warning the Dashboard will still function normally without those files being present. +.. note:: Warnings about the announcement file being missing may be present in users' Nginx logs. Despite the warning the Dashboard will still function normally without those files being present. The file path for the announcement message can be customize using configuration properties, see :ref:`OnDemand configuration documentation `. @@ -110,7 +110,7 @@ Because the announcement is rendered via ERB you can do some interesting things, Message of the Day (MOTD) ------------------------- -You can configure the Dashboard to display the /etc/motd file on the front page - the same file that is displayed when ssh-ing to a login node. +You can configure the Dashboard to display the ``/etc/motd`` file on the front page - the same file that is displayed when logging into to a login node. To display a MOTD file on the Dashboard ensure that the environment variables ``$MOTD_PATH`` and ``$MOTD_FORMAT`` are set, where @@ -158,28 +158,28 @@ Currently only the dashboard uses the colors in the navbar. - Property - Details * - Title - - dashboard_title + - ``dashboard_title`` - The title appears in the navbar and is controlled by the property ``dashboard_title``. The default value is "Open OnDemand". * - Logo - - dashboard_logo - - The default value for ``dashboard_logo`` is ``/public/logo.png`` and this should be the URL to the logo. By default if you place a logo.png at ``/var/www/ood/public/logo.png`` it will be accessible via the URL ``https://your.ondemand.institution.edu/public/logo.png``. SVG logo format is also supported. + - ``dashboard_logo`` + - The default value for ``dashboard_logo`` is ``/public/logo.png`` and this should be the URL to the logo. By default if you place a ``logo.png`` at ``/var/www/ood/public/logo.png`` it will be accessible via the URL ``https://your.ondemand.institution.edu/public/logo.png``. SVG logo format is also supported. * - Logo height - - dashboard_logo_height + - ``dashboard_logo_height`` - The CSS height of the dashboard logo. * - Favicon - - public_url + - ``public_url`` - The favicon is expected to exist at the path ``$public_url/favicon.ico``. For a default OOD installation the favicon will be located at ``/var/www/ood/public/favicon.ico``. * - Brand background color - - brand_bg_color + - ``brand_bg_color`` - Controls the background color of the navbar in the dashboard * - Brand foreground color - - brand_link_active_bg_color + - ``brand_link_active_bg_color`` - Controls the background color the active link in the navbar in the dashboard * - Replace header title with logo - - dashboard_header_img_logo - - Value should be url to logo i.e. ``/public/logo.png``. the background color the active link in the navbar in the dashboard + - ``dashboard_header_img_logo`` + - Value should be URL to logo i.e. ``/public/logo.png``. the background color the active link in the navbar in the dashboard * - Use white text on black background for navbar. - - navbar_type + - ``navbar_type`` - By default we use ``inverse`` for this value, which specifies to use `Bootstrap 3's inverted navbar `_ where text is white and background is black (or dark grey). You can set this to ``default`` to use black text on light grey background if it fits your branding better. .. note:: It is possible to configure these settings using environment variables, although this is deprecated. @@ -188,7 +188,7 @@ Currently only the dashboard uses the colors in the navbar. .. figure:: /images/dashboard_navbar_branding_bluered.png :align: center - Nav bar if I set ``brand_bg_color`` to ``#0000ff`` and ``brand_link_active_bg_color`` to ``#ff0000`` and ``dashboard_title`` to ``OSC OnDemand`` + Navigation bar when ``brand_bg_color`` is ``#0000ff`` and ``brand_link_active_bg_color`` is ``#ff0000`` and ``dashboard_title`` is ``OSC OnDemand``. Custom CSS files ................ @@ -231,7 +231,7 @@ These URLs can be specified, which will appear in the Help menu and on other loc - https://www.osc.edu/ondemand * - Developer Documentation - OOD_DASHBOARD_DEV_DOCS_URL - - https://osc.github.io/ood-documentation/master/app-development.html (link appears in Develop dropdown if developer mode enabled for user) + - https://osc.github.io/ood-documentation/master/app-development.html (link appears in Develop drop-down if developer mode enabled for user) * - Change Password URL - OOD_DASHBOARD_PASSWD_URL - https://my.osc.edu @@ -240,7 +240,7 @@ These URLs can be specified, which will appear in the Help menu and on other loc - https://idp.osc.edu/auth/realms/osc/account/identity Since OnDemand 2.1, custom links can be added to the Help menu using the configuration property ``help_menu``. -Links will be inserted at the end of the core links already included in the menu by the OnDemand codebase. +Links will be inserted at the end of the core links already included in the menu by the OnDemand code-base. ``help_menu`` supports all the link definitions developed for the custom navigation configuration. For more information on how to create custom links, see for example :ref:`adding urls to menus `. @@ -324,7 +324,7 @@ Start by creating the file - For possible scratch space directories, we look for either :file:`/fs/scratch/{project_name}` or :file:`/fs/scratch/{user_name}` - Additionally project scratch directories have a 'title' attribute and will - with in the dropdown with both the title and the path. + with in the drop-down with both the title and the path. The following example adds all directories within the specified base directories to the favorite paths. This approach is ideal when there is no specific directory naming logic to follow. It also appropriately handles Access Control Lists (ACLs). If a directory does not exist, no error is raised, making this configuration easily exportable to different clusters. @@ -469,8 +469,8 @@ can never read files the user cannot read). By setting a colon delimited `OOD_ALLOWLIST_PATH` environment variable, the Job Composer, File Editor, and Files app respect the allowlist in the following manner: -1. Users will be prevented from navigating to, uploading, downloading, viewing, or editing files that are not an eventual child of the allowlisted paths -2. Users will be prevented from copying a template directory from an arbitrary path in the Job Composer if the arbitrary path that is not an eventual child of the allowlisted paths +1. Users will be prevented from navigating to, uploading, downloading, viewing, or editing files that are not an eventual child of the allowed paths. +2. Users will be prevented from copying a template directory from an arbitrary path in the Job Composer if the arbitrary path that is not an eventual child of the allowed paths. 3. Users should not be able to get around this using symlinks We recommend setting this environment variable in ``/etc/ood/config/nginx_stage.yml`` as a YAML mapping (key value pairs) in the mapping (hash/dictionary) ``pun_custom_env`` i.e. below would a list that allows access to home directories, project space, and scratch space at OSC: @@ -495,7 +495,7 @@ Set Default SSH Host Because there are no hosts configured, no hosts are allowed. -In ``/etc/ood/config/apps/shell/env`` set the env var ``OOD_DEFAULT_SSHHOST`` to change the default ssh host. +In ``/etc/ood/config/apps/shell/env`` set the environment variable ``OOD_DEFAULT_SSHHOST`` to change the default ssh host. Since 1.8, there is no out of the box default (in previous versions it was 'localhost', but this has been removed). This will control what host the shell app ssh's to when the URL accessed is ``/pun/sys/shell/ssh/default`` which is the URL other apps will use (unless there is context to specify the cluster to ssh to). @@ -546,7 +546,7 @@ Enable and configure Shell Ping Pong Version 3.1 added the ability for the shell application to send and receive ping pong messages to keep the connection alive, and thus the terminal session alive. -The drawback to this is that these persistant connections can actually outlive your +The drawback to this is that these persistent connections can actually outlive your authentication timeout settings. Meaning users can have active shell sessions for much longer than your authentication systems would normally allow. This is because the connection was made while you were authenticated and it persists after your session @@ -620,13 +620,13 @@ Here's a simple example of what a wrapper script could look like. Fix Unauthorized WebSocket Connection in Shell App -------------------------------------------------- -If you see a 401 error when attempting to launch a Shell app session, where the request URL starts with wss:// and the response header includes ``X-OOD-Failure-Reason: invalid origin``, you may need to set the ``OOD_SHELL_ORIGIN_CHECK`` configuration option. +If you see a 401 error when attempting to launch a Shell app session, where the request URL starts with ``wss://`` and the response header includes ``X-OOD-Failure-Reason: invalid origin``, you may need to set the ``OOD_SHELL_ORIGIN_CHECK`` configuration option. There is a security feature that adds proper CSRF_ protection using both the Origin request header check and a CSRF_ token check. The Origin check uses X-Forwarded-Proto_ and X-Forwarded-Host_ that Apache mod_proxy_ sets to build the string that is used to compare with the Origin request header the browser sends in the WebSocket upgrade request. -In some edge cases this string may not be correct, and as a result valid WebSocket connections will be denied. In this case you can either set ``OOD_SHELL_ORIGIN_CHECK`` env var to the correct https string, or disable the origin check altogether by setting ``OOD_SHELL_ORIGIN_CHECK=off`` (or any other value that does not start with "http") in the ``/etc/ood/config/apps/shell/env`` file. +In some edge cases this string may not be correct, and as a result valid WebSocket connections will be denied. In this case you can either set ``OOD_SHELL_ORIGIN_CHECK`` environment variable to the correct https string, or disable the origin check altogether by setting ``OOD_SHELL_ORIGIN_CHECK=off`` (or any other value that does not start with "http") in the ``/etc/ood/config/apps/shell/env`` file. Either way the CSRF token will still provide protection from this vulnerability. @@ -697,7 +697,7 @@ The manifest contains additional metadata about a job, such as a name, the defau In the event that a job is created from a template that is missing from the `manifest.yml`, "Job Composer" will assign the following default values: - ``name`` The name of the template folder. -- ``host`` The cluster id of the first cluster with a valid resource_mgr listed in the OOD cluster config +- ``host`` The cluster id of the first cluster with a valid resource_mgr listed in the OOD cluster configuration. - ``script`` The first ``.sh`` file appearing in the template folder. - ``notes`` The path to the location where a template manifest should be located. @@ -707,7 +707,7 @@ Job Composer Script Size Limit Since 1.7 the Job composer shows users 'Suggested file(s)' and 'Other valid file(s)'. Other valid files are _any_ files less than ``OOD_MAX_SCRIPT_SIZE_KB`` which defaults to 65 (meaning 65kb). -To reconfigure this, simply set the environment variable in the job composers' env file +To reconfigure this, simply set the environment variable in the job composers' environment file ``/etc/ood/config/apps/myjobs/env`` like so: .. code:: sh @@ -721,7 +721,7 @@ Hiding Job Arrays When composing a new job, the job arrays field is shown on supported clusters. To Hide this field even on supported clusters, an option was added. -To reconfigure this, simply set the environment variable in the job composers' env file +To reconfigure this, simply set the environment variable in the job composers' environment file ``/etc/ood/config/apps/myjobs/env`` like so: .. code:: sh @@ -768,7 +768,7 @@ When configured a widget like the one below will appear on the dashboard's landi The configuration for what apps to pin allows for three variants. You can configure specific apps with a string of the type ``router/app_name``. -For example ``sys/jupyter`` is the system installed app named jupyter. +For example ``sys/jupyter`` is the system installed app named ``jupyter``. Secondly you can configure globs like ``sys/*`` to pin all system installed apps. Or Maybe ``sys/minimal_*`` to pin all system installed apps that begin with 'minimal'. @@ -829,13 +829,13 @@ from grouping by category): .. figure:: /images/grouped_pinned_apps.png One can also change the menu length in the 'App's menu item. If you've -pinned more than 6 apps and you want to them to show up in this dropdown +pinned more than 6 apps and you want to them to show up in this drop-down list, simply increase the length with the option below. .. code:: yaml # /etc/ood/config/ondemand.d/ondemand.yml - pinned_apps_menu_length: 6 # the default number of items in the dropdown menu list + pinned_apps_menu_length: 6 # the default number of items in the drop-down menu list pinned_apps_group_by: category # defaults to nil, no grouping Pinned Apps customizations @@ -857,7 +857,7 @@ All the values are optional and any set will override the default from the appli Text Line 2 Text Line 3 -The CSS for the pinned app tiles has been optimized to support upto three lines of text for the ``sub_caption`` property. +The CSS for the pinned app tiles has been optimized to support up to three lines of text for the ``sub_caption`` property. .. figure:: /images/custom_pinned_apps.png @@ -885,7 +885,7 @@ Simply drop new files into ``/etc/ood/config/apps/dashboard/views/widgets`` and in the configuration. These partial files can be any format Rails recognizes, notably ``.html`` or ``.html.erb`` extensions. -Also if you use subdirectories under widgets, they can be referenced by relative paths. For example +Also if you use sub-directories under widgets, they can be referenced by relative paths. For example ``views/widgets/cluster/_my_cluster_widget.html.erb`` would be referenced in the configuration as ``cluster/my_cluster_widget``. @@ -933,7 +933,7 @@ Initial translation dictionary files with defaults that work well for OSC and us #. Copy the translation dictionary file (or create a new file with the same structure of the keys you want to modify) to ``/etc/ood/config/locales/en.yml`` and modify that copy. #. If you want apps to look for these dictionary files in a different location than ``/etc/ood/config/locales/en.yml`` you can change the location by defining ``OOD_LOCALES_ROOT`` environment variable. -#. The default locale is "en". You can use a custom locale. For example, if you want the locale to be French, you can create a ``/etc/ood/config/locales/fr.yml`` and then configure the Dashboard to use this locale by setting the environment variable ``OOD_LOCALE=fr`` where the locale is just the name of the file without the extension. Do this in either the nginx_stage config or in the Dashboard and Job Composer env config file. +#. The default locale is "en". You can use a custom locale. For example, if you want the locale to be French, you can create a ``/etc/ood/config/locales/fr.yml`` and then configure the Dashboard to use this locale by setting the environment variable ``OOD_LOCALE=fr`` where the locale is just the name of the file without the extension. Do this in either the ``nginx_stage`` configuration or in the Dashboard and Job Composer environment configuration file. In each default translation dictionary file the values that are most site-specific (and thus relevant for change) appear at the top. @@ -951,7 +951,7 @@ In each default translation dictionary file the values that are most site-specif - `Job Composer`_ - ``jobcomposer`` * - ``/etc/ood/config/locales/en.yml`` - - All localizable apps will check this path, unless ``OOD_LOCALES_ROOT`` is set. + - All localize-able apps will check this path, unless ``OOD_LOCALES_ROOT`` is set. - Any .. warning:: @@ -1000,7 +1000,7 @@ Two messages related to file system usage that sites may want to change: Customize Text in the Job Composer's options form ................................................. -The OSC-default value for ``options_account_help`` says that the account field is optional unless a user is a member of multiple projects. +The OSC default value for ``options_account_help`` says that the account field is optional unless a user is a member of multiple projects. Items of note include what to call Accounts which might also be Charge Codes, or Projects. At OSC entering an account is optional unless a user is a member of multiple projects which is reflected in the default value for the string ``options_account_help``. @@ -1074,8 +1074,8 @@ is given in the following format: .. warning:: A block must be equal to 1 KiB for proper conversions. -Individual Fileset Quota -........................ +Individual File-set Quota +......................... If the quota is defined as a ``fileset`` quota, then it applies to all disk resources used underneath a given volume. This requires the object to be @@ -1099,7 +1099,7 @@ The format is given as: Where ``block_usage`` and ``file_usage`` are the disk resource usages attributed to the specified user only. -.. note:: For each user with resources under this fileset, the above object will be repeated with just ``user``, ``block_usage``, and ``file_usage`` changing. +.. note:: For each user with resources under this ``fileset``, the above object will be repeated with just ``user``, ``block_usage``, and ``file_usage`` changing. .. _balance-warnings-on-dashboard: @@ -1195,7 +1195,7 @@ You can do this by setting Open OnDemand in 'Maintenance Mode'. While Maintenance mode is active, Apache will not serve requests for paths outside the ``/public/maintenance/*`` wildcard. Instead, it will serve the ``/var/www/ood/public/maintenance/index.html`` file, which you can change or brand to be your own. Changes to this file will persist through upgrades. -Any assets (e.g., images, stylesheets, or javascript) needed by the HTML file should be placed +Any assets (e.g., images, stylesheets, or JavaScript) needed by the HTML file should be placed in the ``/var/www/ood/public/maintenance/`` directory. You can also put symbolic links into the ``/var/www/ood/public/maintenance/`` directory, if you want to reuse assets located elsewhere in your file system. @@ -1222,7 +1222,7 @@ These are the settings you'll need for this functionality. To start maintenance mode (and thus start serving this page) simply ``touch /etc/ood/maintenance.enable`` to create the necessary file. When your downtime is complete just remove the file and all the traffic will be served normally again. The existence of this file is what starts or stops maintenance -mode, not it's content, so you will not need to restart apache or modify it's config files for this to +mode, not it's content, so you will not need to restart apache or modify it's configuration files for this to take affect. @@ -1252,7 +1252,7 @@ Grafana must be configured to support embedded panels and at this time it is als The dashboard used by OSC is the `OnDemand Clusters `_ dashboard. -Settings used to access Grafana are configured in the cluster config. The following is an example from OSC: +Settings used to access Grafana are configured in the cluster configuration. The following is an example from OSC: .. code:: yaml @@ -1274,7 +1274,7 @@ Settings used to access Grafana are configured in the cluster config. The follo When viewing a dashboard in Grafana choose the panel you'd wish to display and select `Share`. Then choose the `Embed` tab which will provide you with the iframe URL that will need to be generated within OnDemand. -The time ranges and values for labels (eg: `var-cluster=`) will be autofilled by OnDemand. +The time ranges and values for labels (e.g.: `var-cluster=`) will be auto-filled by OnDemand. * ``orgId`` is the ``orgId`` query parameter * The dashboard ``name`` is the last segment of the URI before query parameters @@ -1296,7 +1296,7 @@ Batch connect session cards like this have links to the compute node on which th However, some sites may want to disable this feature because they do not allow ssh sessions on the compute nodes. -To disable this, simply set the environment variable in the dashboards' env file +To disable this, simply set the environment variable in the dashboards' environment file ``/etc/ood/config/apps/dashboard/env`` to a falsy value (0, false, off). .. code:: sh @@ -1404,26 +1404,26 @@ XDMoD Integration requires XDMoD 9+, OnDemand 1.8+, and the ability to facilitat Steps to enable the XDMoD reports in the OnDemand Dashboard: -#. Configure OnDemand with XDMoD host URL in PUN /etc/ood/config/nginx_stage.yml +#. Configure OnDemand with XDMoD host URL in PUN ``/etc/ood/config/nginx_stage.yml``. .. code-block:: yaml pun_custom_env: OOD_XDMOD_HOST: "https://xdmod.osc.edu" -#. Add OnDemand host as domain to XDMoD portal settings for CORS /etc/xdmod/portal_settings.ini +#. Add OnDemand host as domain to XDMoD portal settings for CORS ``/etc/xdmod/portal_settings.ini``. .. code-block:: none domains = "https://ondemand.osc.edu" -#. Configure identity provider to include OnDemand host in HTTP `Content-Security-Policy for frame-ancestors `_ since OnDemand uses iFrames to trigger SSO with XDMoD when a user logs in. Below is what we ensured Content-Security-Policy header for frame-ancestors was set to when configuring Keycloak: +#. Configure identity provider to include OnDemand host in HTTP `Content-Security-Policy for frame-ancestors `_ since OnDemand uses an iframe to trigger SSO with XDMoD when a user logs in. Below is what we ensured Content-Security-Policy header for frame-ancestors was set to when configuring Keycloak: .. code-block:: none frame-ancestors https://*.osc.edu 'self' -#. If you want the XDMoD links in the OnDemand Job Composer you also need to configure OnDemand with XDMoD resource id in each cluster config. For example, in the hpctoolset the resource_id for the hpc cluster is 1 in XDMoD, so we modify /etc/ood/config/clusters.d/hpc.yml to add a xdmod map to the custom map at the bottom of the file: +#. If you want the XDMoD links in the OnDemand Job Composer you also need to configure OnDemand with XDMoD resource id in each cluster configuration. For example, in the ``hpctoolset`` the resource_id for the HPC cluster is 1 in XDMoD, so we modify ``/etc/ood/config/clusters.d/hpc.yml`` to add a XDMoD map to the custom map at the bottom of the file: .. code-block:: yaml :emphasize-lines: 10- @@ -1485,7 +1485,7 @@ This feature is disabled behind a feature toggle. To enable it, set the configur For more information on how to configure properties, see :ref:`configuration documentation `. When enabled, the cancel button will appear for active sessions. -When the session is cancelled, the job will be cancelled in the scheduler, +When the session is canceled, the job will be canceled in the scheduler, the status will change to ``completed``, and the session card will be kept. For completed sessions, the system will only show the delete button. diff --git a/latest/_sources/glossary.rst.txt b/latest/_sources/glossary.rst.txt index 2a2180464..57f96da5f 100644 --- a/latest/_sources/glossary.rst.txt +++ b/latest/_sources/glossary.rst.txt @@ -14,7 +14,7 @@ Glossary Runs on the cluster but is not a compute-node. Web-node - A term used for when a site or institution has enough funds/personel to run the OOD login on a dedicated server and not on a login-node. + A term used for when a site or institution has enough funds/personnel to run the OOD login on a dedicated server and not on a login-node. PUN The Per User Nginx. An Nginx instance running as the user. diff --git a/latest/_sources/how-tos/analytics/google-analytics.rst.txt b/latest/_sources/how-tos/analytics/google-analytics.rst.txt index f33c25880..ba673ac38 100644 --- a/latest/_sources/how-tos/analytics/google-analytics.rst.txt +++ b/latest/_sources/how-tos/analytics/google-analytics.rst.txt @@ -7,7 +7,7 @@ Adding Google Analytics .. _Google IAM roles: https://cloud.google.com/iam/docs/understanding-roles .. _Google Analytics: https://analytics.google.com/analytics/web -If you wish you can setup your Open-OnDemand instance to send usage data to Google Analytics +If you wish you can setup your Open OnDemand instance to send usage data to Google Analytics (GA) that you can then query and report on, this page walks through how to do just that. .. note:: @@ -35,7 +35,7 @@ Querying Google Analytics work as intended. As OSC does not use GA we're unable to update these examples ourselves, but would accept updates for the same. -Now that you have Open-OnDemand sending information to GA and it's all configured correctly, +Now that you have Open OnDemand sending information to GA and it's all configured correctly, you can now query GA for this information, parse it and present it in any fashion you like. Here's a small portion of how we query GA in ruby, but there are many `GA client libraries`_ diff --git a/latest/_sources/how-tos/app-development.rst.txt b/latest/_sources/how-tos/app-development.rst.txt index c8be31e7c..7d69b90e4 100644 --- a/latest/_sources/how-tos/app-development.rst.txt +++ b/latest/_sources/how-tos/app-development.rst.txt @@ -4,8 +4,8 @@ App Development =============== OnDemand is made up of the platform (Apache and NGINX), Passenger apps and -plugins. Passenger apps are rack based Ruby apps, wsgi based Python web apps, or -Node.js apps that follow a convention for the app's startup file. +plugins. Passenger apps are rack based Ruby apps, WSGI based Python web apps, or +NodeJs apps that follow a convention for the app's startup file. The Dashboard app, Shell app, and all other core apps in OnDemand are Passenger apps that can be replaced by custom Passenger apps. Or you can create your own. diff --git a/latest/_sources/how-tos/app-development/app-sharing.rst.txt b/latest/_sources/how-tos/app-development/app-sharing.rst.txt index a82654a32..2ac176b7b 100644 --- a/latest/_sources/how-tos/app-development/app-sharing.rst.txt +++ b/latest/_sources/how-tos/app-development/app-sharing.rst.txt @@ -23,7 +23,7 @@ Apps may be shared via a variety of methods including: System Installed Apps --------------------- -Admins may install apps to the system by copying the application directory to ``/var/www/ood/apps/sys``. Default directory permissions (``755``) will allow all users with access to OnDemand to see and run that app. Apps may have their access restricted by changing the permissions on individual application directories. For example if a site does not wish to show licensed software to un-licensed users they might do the following: +Admins may install apps to the system by copying the application directory to ``/var/www/ood/apps/sys``. Default directory permissions (``755``) will allow all users with access to OnDemand to see and run that app. Apps may have their access restricted by changing the permissions on individual application directories. For example if a site does not wish to show licensed software to unlicensed users they might do the following: .. code-block:: sh @@ -95,7 +95,7 @@ These changes take effect immediately, although when a user is added or removed Code Sharing ------------ -Code sharing is when an application's source code is shared between two or more users who run it as a personal development application. Models for this sharing can include using a web-based file repository such as Github, emailing Zip'd app directories, or a group readable directory symlinked to each user's ``~/ondemand/dev/`` directory. +Code sharing is when an application's source code is shared between two or more users who run it as a personal development application. Models for this sharing can include using a web-based file repository such as Github, emailing zipped app directories, or a group readable directory symlinked to each user's ``~/ondemand/dev/`` directory. For an example of the later consider: @@ -138,7 +138,7 @@ Enabling The App Sharing Dashboard for finding an app. #. Set ``OOD_APP_CATALOG_URL=https://link.to.online/app/catalog`` to link externally to an advertised listing of apps available. -#. Pin usr apps to the dashboard and group them by category. +#. Pin user (``usr``) apps to the dashboard and group them by category. .. code:: yaml @@ -185,7 +185,7 @@ approach has these benefits (assuming users named ``efranz`` and ``an0047``: permissions on this directory. Thus by setting ``750`` on ``/var/www/ood/apps/usr/an0047`` this ensures that an0047 can only share apps with users in his primary group. At times we have created a \ - supplemental group (shinyusr) and chgrp the share directory to this group so + supplemental group (``shinyusr``) and chgrp the share directory to this group so that the developer can share apps with every user in this group. #. The developer who can share apps can modify permissions on the app directories themselves i.e. @@ -206,9 +206,9 @@ In summary, to enable a new user to create shared apps, run these commands: Example of Executable Sharing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is with two users Eric (efranz) and Bob (an0047). +This is with two users Eric (``efranz``) and Bob (``an0047``). -Eric has a dev app "MATLAB", and interactive plugin app. Eric can +Eric has a development app "MATLAB", and interactive plugin app. Eric can 1. Launch MATLAB 2. View and Edit the code @@ -224,11 +224,11 @@ i.e. ``~efranz/ondemand/dev/matlab``: .. figure:: /images/app-sharing-2.png :align: center -If Eric shares the git repo path or URL with Bob, Bob can clone this into his +If Eric shares the git repository path or URL with Bob, Bob can clone this into his home directory if he is enabled as a developer. This is called "Source Code Sharing". Eric can share this app with Bob by selecting "My Shared Apps" and cloning the MATLAB -repo to deploy ``~efranz/ondemand/share/matlab`` +repository to deploy ``~efranz/ondemand/share/matlab`` .. figure:: /images/app-sharing-3.png :align: center diff --git a/latest/_sources/how-tos/app-development/enabling-development-mode.rst.txt b/latest/_sources/how-tos/app-development/enabling-development-mode.rst.txt index d5734b3c8..256b7d8b4 100644 --- a/latest/_sources/how-tos/app-development/enabling-development-mode.rst.txt +++ b/latest/_sources/how-tos/app-development/enabling-development-mode.rst.txt @@ -6,9 +6,9 @@ Enabling App Development Enable in OnDemand v1.6+: ......................... -Here are example steps to enable a user "efranz", assuming efranz's home directory is at ``/home/efranz``: +Here are example steps to enable a user ``efranz``, assuming ``efranz``'s home directory is at ``/home/efranz``: -#. Create a symlink so OnDemand finds efranz's apps: +#. Create a symlink so OnDemand finds ``efranz``'s apps: .. code:: sh @@ -17,15 +17,15 @@ Here are example steps to enable a user "efranz", assuming efranz's home directo sudo ln -s /home/efranz/ondemand/dev gateway -#. Have efranz access the Dashboard, and efranz will see the Develop dropdown +#. Have ``efranz`` access the Dashboard, and they will see the Develop drop-down. Enable in OnDemand v1.4 & v1.5: ............................... -Here are example steps to enable a user "efranz", assuming efranz's home directory is at ``/home/efranz``: +Here are example steps to enable a user ``efranz``, assuming ``efranz``'s home directory is at ``/home/efranz``: -#. Create a symlink so OnDemand finds efranz's apps: +#. Create a symlink so OnDemand finds ``efranz``'s apps: .. code:: sh @@ -33,17 +33,17 @@ Here are example steps to enable a user "efranz", assuming efranz's home directo cd /var/www/ood/apps/dev/efranz sudo ln -s /home/efranz/ondemand/dev gateway -#. Create dev directory ``/home/efranz/ondemand/dev`` where efranz's dev apps will go (or ask efranz to do that) -#. Have efranz access the Dashboard, and efranz will see the Develop dropdown +#. Create ``dev`` directory ``/home/efranz/ondemand/dev`` where ``efranz``'s development apps will go (or ask ``efranz`` to do that). +#. Have ``efranz`` access the Dashboard, and they will see the Develop drop-down. Enable in OnDemand v1.3: ........................ -Here are example steps to enable a user "efranz", assuming efranz's home directory is at ``/home/efranz``: +Here are example steps to enable a user ``efranz``, assuming ``efranz``'s home directory is at ``/home/efranz``: -#. Create dev directory ``/home/efranz/ondemand/dev`` where efranz's dev apps will go (or ask efranz to do that) -#. Have efranz access the Dashboard, and efranz will see the Develop dropdown. (if this doesn't happen, ) +#. Create ``dev`` directory ``/home/efranz/ondemand/dev`` where ``efranz``'s development apps will go (or ask ``efranz`` to do that). +#. Have ``efranz`` access the Dashboard, and they will see the Develop drop-down. (if this does not happen) .. note:: @@ -55,13 +55,13 @@ Specify dedicated host for development (optional) The default host for the shell app is typically a login node. If this node does not contain a similar environment as the host OnDemand is installed on, including access to Software Collection (SCL) packages, it may be useful to provide developers a dedicated development host they can SSH to. This could even be the OnDemand host itself. If you configure the OnDemand dashboard to know about the dedicated development host, the dashboard will present links to open the shell app to this host. -To specify a dedicated development host so OnDemand, set ``OOD_DEV_SSH_HOST`` environment variable for the dashboard in the file ``/etc/ood/config/apps/dashboard/env``. For example at OSC one of our OnDemand installs uses ondemand-test.osc.edu for the development host so we have this line: `OOD_DEV_SSH_HOST="ondemand-test.osc.edu" `_ +To specify a dedicated development host so OnDemand, set ``OOD_DEV_SSH_HOST`` environment variable for the dashboard in the file ``/etc/ood/config/apps/dashboard/env``. For example at OSC one of our OnDemand installs uses ``ondemand-test.osc.edu`` for the development host so we have this line: `OOD_DEV_SSH_HOST="ondemand-test.osc.edu" `_ Make everyone a developer by default (optional) ............................................... -To revert to the way developer enabling worked in OnDemand 1.3, change the nginx_stage app_root configuration for dev apps by modifying /etc/ood/config/nginx_stage.yml and replacing +To revert to the way developer enabling worked in OnDemand 1.3, change the ``nginx_stage`` app_root configuration for development apps by modifying ``/etc/ood/config/nginx_stage.yml`` and replacing .. code-block:: yaml :emphasize-lines: 2 @@ -83,11 +83,11 @@ with usr: '/var/www/ood/apps/usr/%{owner}/gateway/%{name}' sys: '/var/www/ood/apps/sys/%{name}' -Then users can just create the directory ``~/ondemand/dev`` and the Develop dropdown will appear. +Then users can just create the directory ``~/ondemand/dev`` and the Develop drop-down will appear. .. warning:: If you do this, it is recommended that you treat the node that OnDemand is running on as a login node, as you are effectively giving those users shell access by letting them run arbitrary code on the OnDemand node (of course the UID of the processes are still their regular unprivileged user UID). -If you do this, you still might want to restrict who sees the Develop dropdown in the Dashboard. To do that you can explicitly show or hide the dropdown in the Dashboard by setting ``Configuration.app_development_enabled`` to true based on one or more Ruby statements in the initializer ``/etc/ood/config/apps/dashboard/initializers/ood.rb``. Code in the initializer runs as the user. This code also has access to the `ood_support library `__ in which we provide some helper classes to work with User's and Groups. For example: +If you do this, you still might want to restrict who sees the Develop drop-down in the Dashboard. To do that you can explicitly show or hide the drop-down in the Dashboard by setting ``Configuration.app_development_enabled`` to true based on one or more Ruby statements in the initializer ``/etc/ood/config/apps/dashboard/initializers/ood.rb``. Code in the initializer runs as the user. This code also has access to the `ood_support library `__ in which we provide some helper classes to work with User's and Groups. For example: .. code-block:: ruby diff --git a/latest/_sources/how-tos/app-development/interactive/additional-info.rst.txt b/latest/_sources/how-tos/app-development/interactive/additional-info.rst.txt index 94a4d60fb..bcf3bb632 100644 --- a/latest/_sources/how-tos/app-development/interactive/additional-info.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/additional-info.rst.txt @@ -5,8 +5,8 @@ Adding Additional Information to the session cards .. _bc_info_html_md_erb: -info.{md,html}.erb ------------------- +``info.{md,html}.erb`` +---------------------- It's possible for you to add additional information to this session's card. @@ -30,8 +30,8 @@ created_at .. _bc_completed_html_md_erb: -completed.{md,html}.erb ------------------------- +``completed.{md,html}.erb`` +--------------------------- :ref:`bc_info_html_md_erb` above will display on the session's card regardless of the state of the job - it will always be displayed. diff --git a/latest/_sources/how-tos/app-development/interactive/conn-params.rst.txt b/latest/_sources/how-tos/app-development/interactive/conn-params.rst.txt index aa3e6f410..a73c77e17 100644 --- a/latest/_sources/how-tos/app-development/interactive/conn-params.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/conn-params.rst.txt @@ -20,7 +20,7 @@ Jupyter Notebook Example Here's an example using a Jupyter application which needs needs to know the exact API to connect to. We can either connect to -JuypterLab at ``/lab`` or Juypter Notebook at ``/tree``, but this +JupyterLab at ``/lab`` or Jupyter Notebook at ``/tree``, but this information is not known until the job has been submitted. So once the job is submitted, we need to export the ``jupyter_api`` diff --git a/latest/_sources/how-tos/app-development/interactive/dynamic-form-widgets.rst.txt b/latest/_sources/how-tos/app-development/interactive/dynamic-form-widgets.rst.txt index 9e7d81ffc..dc5a29dbd 100644 --- a/latest/_sources/how-tos/app-development/interactive/dynamic-form-widgets.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/dynamic-form-widgets.rst.txt @@ -8,7 +8,7 @@ Dynamic Form Widgets Prior to version 2.0, sites would have to make their own custom `form.js` to add dynamic behavior for batch connect forms. While sites can still have their -own custom javascript, 2.0 added out of the box support for common use cases based +own custom JavaScript, 2.0 added out of the box support for common use cases based on configuration. .. warning:: @@ -23,7 +23,7 @@ Your own ``form.js`` ******************** If we don't support what you need for your application to be dynamic, then you can add your -own ``form.js`` in the root of the project. It is free form javascript, so most anything is +own ``form.js`` in the root of the project. It is free form JavaScript, so most anything is allowed. `jQuery`_ is available to interact with elements. @@ -78,7 +78,7 @@ But using Nvidia's `CUDA`_ libraries only makes sense when the user is requestin So, we want to hide the ``cuda_version`` element when a users chooses standard ``node_type``. Here's the example YAML for this app with two select widgets. This -instructs the webpage to hide the ``cuda_version`` when the ``standard`` +instructs the web-page to hide the ``cuda_version`` when the ``standard`` ``node_type`` is selected. .. warning:: @@ -115,7 +115,7 @@ Here we have a checkbox ``enable_cuda_version`` that will show ``cuda_version`` when checked and hide it when it's not checked. .. tip:: - Checkboxes respond to ``when-checked: true`` and ``when-un-checked: true`` + Check-boxes respond to ``when-checked: true`` and ``when-un-checked: true`` for hiding elements when checked or unchecked. .. code-block:: yaml @@ -161,7 +161,7 @@ The ``data-min`` and ``data-max`` directives allow you to set the minimum and maximum values of another element based on the current value of a select element. Sites have node types of all shapes and sizes. Some sites even have -heterogenous clusters where there are different node types in the cluster. +heterogeneous clusters where there are different node types in the cluster. This feature allows for setting the minimum and maximum values for input fields like the number of cores to request. @@ -171,7 +171,7 @@ different sizes. In the ``oakley`` cluster nodes have a total 28 cores and in th ``ruby`` cluster they have 40. In this example ``data-max-num-cores-for-cluster-oakley`` is attached to the standard -node type. This config is saying, when the ``node_type`` is ``standard`` +node type. This configuration is saying, when the ``node_type`` is ``standard`` and the ``cluster`` is ``oakley`` set maximum ``num_cores`` to 28. .. code-block:: yaml diff --git a/latest/_sources/how-tos/app-development/interactive/form-widgets.rst.txt b/latest/_sources/how-tos/app-development/interactive/form-widgets.rst.txt index 0fed933a9..dbb65f321 100644 --- a/latest/_sources/how-tos/app-development/interactive/form-widgets.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/form-widgets.rst.txt @@ -132,7 +132,7 @@ Form Widgets allows users to navigate through directories to select a path. This is useful in forms where a path must be selected and you - want to allow your users to choose an arbirary path. + want to allow your users to choose an arbitrary path. ``directory`` is the initial directory the path selector will open to when the users opens the modal. This defaults to the users' HOME. diff --git a/latest/_sources/how-tos/app-development/interactive/form.rst.txt b/latest/_sources/how-tos/app-development/interactive/form.rst.txt index 84ef8b92d..70ded1793 100644 --- a/latest/_sources/how-tos/app-development/interactive/form.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/form.rst.txt @@ -1,7 +1,7 @@ .. _app-development-interactive-form: -User Form (form.yml.erb) -======================== +User Form (``form.yml.erb``) +============================ The configuration file ``form.yml`` creates the `html form`_ your customers will use to start the interactive application. @@ -56,7 +56,7 @@ building and launching the ``my_app`` Interactive App session. Since 4.0 HTML IDs of the form items are always lowercase. The examples above show lowercase configurations of ``account``. Specifying ``Account``, or ``ACCOUNT`` or any variation of uppercase and lowercase will result in - the same behhavior as specifying ``account`` (all lower case). + the same behavior as specifying ``account`` (all lower case). If you write your own ``form.js`` take care to note that HTML IDs of these form items will **always** be lowercase regardless of how they're defined in @@ -70,7 +70,7 @@ building and launching the ``my_app`` Interactive App session. Configuration ------------- -This is the full list of items with details, you may supply to this yaml file to configure this application. +This is the full list of items with details, you may supply to this YAML file to configure this application. .. describe:: cluster (Array or String) @@ -106,7 +106,7 @@ This is the full list of items with details, you may supply to this yaml file to .. describe:: cacheable (Boolean) - whether or not the application is cacheable or not. Defaults to true. + whether or not the application is cache-able or not. Defaults to true. .. _bc_form_header: .. describe:: form_header (String) @@ -114,7 +114,7 @@ This is the full list of items with details, you may supply to this yaml file to New in 4.0. Add a text header to the form. Note this is different from the - manifest's description as it does not appear as hoverover text. + manifest's description as it does not appear as hover-over text. .. _bc_form_attributes: @@ -155,7 +155,7 @@ The most commonly used predefined attributes are given as: .. _bc_account: -bc_account +``bc_account`` This adds a ``text_field`` to the HTML form that will be used as the charged account for the submitted job. @@ -163,7 +163,7 @@ bc_account .. _bc_queue: -bc_queue +``bc_queue`` This adds a ``text_field`` to the HTML form that will supply the name of the queue that the batch job is submitted to. @@ -171,14 +171,14 @@ bc_queue .. _bc_num_hours: -bc_num_hours +``bc_num_hours`` This adds a ``number_field`` to the HTML form that describes the maximum amount of hours the submitted batch job may run. This attribute gets converted to seconds and then set on `OodCore::Job::Script#wall_time`_. -bc_num_slots +``bc_num_slots`` This adds a ``number_field`` to the HTML form that describes the number of processors, CPUs on a single node, or nodes that the submitted job may use (depends on the resource manager used, e.g., Torque, Slurm, ...). @@ -196,7 +196,7 @@ bc_num_slots .. _bc_email_on_started: -bc_email_on_started +``bc_email_on_started`` This adds a ``check_box`` to the HTML form that determines whether the user should be notified by email when the batch job starts. @@ -232,7 +232,7 @@ auto_primary_group auto_modules_ This will generate a list of modules in a ``select`` widget. - For example ``auto_modules_matlab`` will automatically populate a dropdown + For example ``auto_modules_matlab`` will automatically populate a drop-down list of every single ``matlab`` version available, including the default version. @@ -320,7 +320,7 @@ auto_accounts .. warning:: We only have support for Slurm accounts at this time. -auto_qos +``auto_qos`` This will automatically generate a ``select`` widget populated with a list of all the QoS (Quality of Service) values available. These are cluster aware if you have :ref:`dynamic options ` enabled. @@ -550,7 +550,7 @@ are: that will be sent to the server and used. Lastly you can also set extra ``data`` HTML attributes like the - example ``Toyota`` below. These extra attributes can be used by javascript + example ``Toyota`` below. These extra attributes can be used by JavaScript or options for :ref:`dynamic options `. Default @@ -576,17 +576,17 @@ are: .. describe:: cacheable (Boolean, true) - whether the form item is cacheable or not + Whether the form item is cache-able or not. Default - cacheable + The item is cache-able. .. code-block:: yaml cacheable: true Example - The item is not cacheable + The item is not cache-able. .. code-block:: yaml @@ -722,7 +722,7 @@ Caching form items `````````````````` Since 1.8 caching form items is configurable. By default all form items are -cacheable. As seen above you can enable or disable caching for the entire app +cache-able. As seen above you can enable or disable caching for the entire app when using the top level ``cacheable`` configuration. You can also configure on a per item basis through attributes. @@ -741,9 +741,9 @@ dashboard's environment file ``/etc/ood/config/apps/dashboard/env``. Let's see an example. Here, we've disabled caching for the app and did not set OOD_BATCH_CONNECT_CACHE_ATTR_VALUES, so the site-wide configuration is set -to true by default. So, ``bc_num_slots`` and ``python_version`` are not cacheable, +to true by default. So, ``bc_num_slots`` and ``python_version`` are not cache-able, meaning the user will have to fill those form entries out every time they submit -the job. But since ``bc_queue``'s attribute is set to true, it is cacheable. +the job. But since ``bc_queue``'s attribute is set to true, it is cache-able. .. code-block:: yaml @@ -796,13 +796,13 @@ In 1.8 there are now several ways to configure what cluster to submit to. The easiest way is to use the the top level ``cluster`` configuration. If you've configured just one item, then the form UI does not change for the user. If -you configure an array of two or more options then a select dropdown will +you configure an array of two or more options then a select drop-down will automatically be added to the top of the form. .. code-block:: yaml # ${HOME}/ondemand/dev/my_app/form.yml - # which will generate a dropdown select automatically + # which will generate a drop-down select automatically --- cluster: - "cluster1" @@ -822,7 +822,7 @@ shown in the UI you can configure a cluster form item and specify it's attribute This gives you some flexibility in the form UI instead of the default select widget that shows all lowercase cluster names. -Here's an example were the user will be shown a select dropdown menu item with +Here's an example were the user will be shown a select drop-down menu item with different text than the default. .. code-block:: yaml @@ -840,7 +840,7 @@ different text than the default. The last option is to :ref:`configure the cluster in the submit file `. When using this option, there's no need to add any cluster configuration to the -form.yml. +``form.yml``. .. _global_bc_form_items: @@ -861,7 +861,7 @@ above. Only the location is in an ``ondemand.d`` file in ``/etc/ood/config/ondem under the ``global_bc_form_items`` key. Here's an example of defining a select widget with options called ``global_queues``. -Note the appropriate previx of ``global``. +Note the appropriate prefix of ``global``. .. code-block:: yaml diff --git a/latest/_sources/how-tos/app-development/interactive/manifest.rst.txt b/latest/_sources/how-tos/app-development/interactive/manifest.rst.txt index 648c99280..da0ac06b2 100644 --- a/latest/_sources/how-tos/app-development/interactive/manifest.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/manifest.rst.txt @@ -1,7 +1,7 @@ .. _app-development-manifest: -Manifest yml files -================== +Manifest YAML files +=================== Every app (interactive and passenger) needs a ``manifest.yml`` file to describe it to the Open OnDemand platform. @@ -19,29 +19,29 @@ to the Open OnDemand platform. # metadata: # field_of_science: botany -name +``name`` The name of the app. This will be shown in menu bars and on icons. -category +``category`` The category of the app. This is used to group apps in navigation menus. -subcategory +``subcategory`` The subcategory of the app. This is used to group apps within the navigation menu lists. -role +``role`` The role of the app. Here ``batch_connect`` has special meaning to Open OnDemand and is required to indicate it's a batch connect app. Otherwise it's assumed to be a Passenger app. -description +``description`` The description of the app. This will be used for additional text when hovering over icons. -icon (Optional) - Apps default to look for an icon.png or icon.svg in their root directory, +``icon`` (Optional) + Apps default to look for an ``icon.png`` or ``icon.svg`` in their root directory, but this overrides that to specify the icon. -url (Optional) - The url of the application. By default this is generated dynamically but +``url`` (Optional) + The URL of the application. By default this is generated dynamically but can be overridden. -metadata (Optional) +``metadata`` (Optional) These are key value pairs you can add to apps for extra grouping capabilities. -new_window (Optional) +``new_window`` (Optional) A boolean (``true`` or ``false``) flag to toggle if the app should open a new window when clicked. diff --git a/latest/_sources/how-tos/app-development/interactive/saved-settings.rst.txt b/latest/_sources/how-tos/app-development/interactive/saved-settings.rst.txt index 81a7b3edb..e139ece4b 100644 --- a/latest/_sources/how-tos/app-development/interactive/saved-settings.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/saved-settings.rst.txt @@ -38,7 +38,7 @@ Using Settings .............. When a user has saved settings for a given interactive application, -they'll now see a dropdown menu to choose those settings. Note that +they'll now see a drop-down menu to choose those settings. Note that when a given saved setting is chosen, the form updates the values automatically. diff --git a/latest/_sources/how-tos/app-development/interactive/setup/enable-reverse-proxy.rst.txt b/latest/_sources/how-tos/app-development/interactive/setup/enable-reverse-proxy.rst.txt index 2ca4e0e55..347fbab78 100644 --- a/latest/_sources/how-tos/app-development/interactive/setup/enable-reverse-proxy.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/setup/enable-reverse-proxy.rst.txt @@ -28,7 +28,7 @@ Requirements If the :command:`hostname` command gives you a value that cannot be used to connect to the compute node from the OnDemand host, then you can - override it in the cluster config with a :command:`bash` command that will + override it in the cluster configuration with a :command:`bash` command that will work, e.g.: .. code-block:: yaml @@ -78,7 +78,7 @@ Steps to Enable in Apache .. tip:: - What if my site foregos the FQDN in the host names for compute nodes, and + What if my site foregoes the FQDN in the host names for compute nodes, and we have compute names that give their hosts as: - ``ab001`` ... ``ab100`` (for the AB cluster) diff --git a/latest/_sources/how-tos/app-development/interactive/sub-apps.rst.txt b/latest/_sources/how-tos/app-development/interactive/sub-apps.rst.txt index 6805f6a53..6487e920c 100644 --- a/latest/_sources/how-tos/app-development/interactive/sub-apps.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/sub-apps.rst.txt @@ -1,10 +1,10 @@ -Sub-Apps and Reconfiguring existing apps -======================================== +Sub-Apps and Re-configuring existing apps +========================================= Sub-Apps are a term we use for providing variants of existing apps. They act as a child to the existing parent application. That is, -they inheret all the options and scripts from the existing application +they inherit all the options and scripts from the existing application and override some or all of options. You may want to do this to provide variants of existing apps. @@ -20,8 +20,8 @@ You have 2 options for supplying sub-app overrides. * Place new ``form.yml`` files in ``/etc/ood/config/apps/my_app``. * OR provide new ``form.yml`` files in ``/var/www/ood/apps/sys/my_app/local``. -There are pros and cons to each scheme. With the former, you sperate the overriedes (the sub-apps) -and the actuall app. The subapps residing in ``/etc/ood`` and the actual apps residing in ``/var/www``. +There are pros and cons to each scheme. With the former, you separate the overrides (the sub-apps) +and the actual app. The sub-apps residing in ``/etc/ood`` and the actual apps residing in ``/var/www``. This would allow you to update one without having to update the other. With latter scheme you keep the overrides with the main application itself. This has the benefit diff --git a/latest/_sources/how-tos/app-development/interactive/submit.rst.txt b/latest/_sources/how-tos/app-development/interactive/submit.rst.txt index 7b733c9ff..bf35600a5 100644 --- a/latest/_sources/how-tos/app-development/interactive/submit.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/submit.rst.txt @@ -1,7 +1,7 @@ .. _app-development-interactive-submit: -Job Submission (submit.yml.erb) -=============================== +Job Submission (``submit.yml.erb``) +=================================== The configuration file ``submit.yml.erb`` controls the content of the batch script as well as the submission arguments used when submitting the batch job. @@ -110,7 +110,7 @@ start GUI applications. The options available are ``basic``, ``vnc`` or ``vnc_container``. ``vnc_container`` is basically just like ``vnc`` only in that it -boostraps the VNC programs inside a container instead of on the +bootstraps the VNC programs inside a container instead of on the host machine. .. describe:: template (String) diff --git a/latest/_sources/how-tos/app-development/interactive/template.rst.txt b/latest/_sources/how-tos/app-development/interactive/template.rst.txt index 1505d3f29..19ca33846 100644 --- a/latest/_sources/how-tos/app-development/interactive/template.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/template.rst.txt @@ -18,7 +18,7 @@ The ``template/`` directory can be found at:: When an Interactive App session is first "Launched" by the user, the ``template/`` directory is: -#. Copied to the user's home directory under an appropriately namespaced data +#. Copied to the user's home directory under an appropriately name-spaced data root directory:: ${HOME}/ondemand/data/sys/dashboard/batch_connect/dev/my_app/output// diff --git a/latest/_sources/how-tos/app-development/interactive/view.rst.txt b/latest/_sources/how-tos/app-development/interactive/view.rst.txt index 5f91bada7..732ec51a3 100644 --- a/latest/_sources/how-tos/app-development/interactive/view.rst.txt +++ b/latest/_sources/how-tos/app-development/interactive/view.rst.txt @@ -140,7 +140,7 @@ can do: Connect to My App -All stylization is handled through the HTML `class global attribute`_ using +All styles are handled through the HTML `class global attribute`_ using predefined Bootstrap and Font Awesome classes. .. _app-development-interactive-view-examples: @@ -186,7 +186,7 @@ login page. In this example, the password is stored in a hidden input field that the user -doesn't see and it gets communicated to the Jupyter server in the ``POST`` +does not see and it gets communicated to the Jupyter server in the ``POST`` request. .. _bc_native_vnc_view: @@ -214,15 +214,15 @@ variables and objects you may need to create helpful instructions. You can also `refer to the original files for help in creating new panels `_. -Configuration.native_vnc_login_host +``Configuration.native_vnc_login_host`` The OOD_NATIVE_VNC_LOGIN_HOST configuration if given. -connect.host +``connect.host`` The compute node host the interactive job is on -connect.port +``connect.port`` The compute node port the interactive job has opened -connect.password +``connect.password`` The VNC password for the interactive job -ENV["USER"] +``ENV["USER"]`` The USER environment variable .. _eruby (embedded ruby): https://en.wikipedia.org/wiki/ERuby diff --git a/latest/_sources/how-tos/debug/debug-apache.rst.txt b/latest/_sources/how-tos/debug/debug-apache.rst.txt index fa1375647..6a1092564 100644 --- a/latest/_sources/how-tos/debug/debug-apache.rst.txt +++ b/latest/_sources/how-tos/debug/debug-apache.rst.txt @@ -47,7 +47,7 @@ and the ServerName you may have configured. Showing virtualhosts can help debug Apache request routing. The output from these commands will show you how Apache is routing based off of the ServerName in the VirtualHost. -If you're seeing the default Apache webpage you likely have to :ref:`configure the ServerName ` +If you're seeing the default Apache web-page you likely have to :ref:`configure the ServerName ` which corresponds directly to `Apache's ServerName configuration`_ (and restart Apache). Or you're using the wrong hostname in your browser. @@ -71,7 +71,7 @@ Performance Tuning If you're servicing many clients at time (more than 50) you will likely need to change the `Apache Httpd's MPM configuration`_. The default configuration may degrade service when -Httpd has to serve many clients (I.e., when you have a lot of customers using Open OnDemand). +httpd has to serve many clients (I.e., when you have a lot of customers using Open OnDemand). We suggest configurations similar to this. @@ -84,7 +84,7 @@ We suggest configurations similar to this. The example configuration below can handle about 256 simultaneous requests. Use this as an example and increase or decrease `MaxRequestWorkers` accordingly - (based on your resources, cpus & memory and how much traffic you anticipate) then recalculate + (based on your resources, CPUs & memory and how much traffic you anticipate) then recalculate `ServerLimit`, `ThreadsPerChild` and whatever else you may want to change. diff --git a/latest/_sources/how-tos/monitoring/logging.rst.txt b/latest/_sources/how-tos/monitoring/logging.rst.txt index 89c4120cc..d4044bec1 100644 --- a/latest/_sources/how-tos/monitoring/logging.rst.txt +++ b/latest/_sources/how-tos/monitoring/logging.rst.txt @@ -9,7 +9,7 @@ provides context around these locations. In general administrators will want to note whether they need to see: - System type logs for authentication to the :ref:`web-node ` itself or OOD's own configuration. -- Session data for things like connecting to interactive apps (Jupyter, Rstudio, Codeserver, etc.) from +- Session data for things like connecting to interactive apps (Jupyter, RStudio, CodeServer, etc.) from the user's PUN, which is already running on the web-node. System Logs @@ -75,7 +75,7 @@ information they may need there as well for connections and errors. able to substitute user or escalate to root in order to see these files. In general the session data or job submission files for apps across the dashboard, such as the Job Composer, -Batch Connect, or Frame-renderer, all start from the root of: +Batch Connect, and so on, all start from the root of: :file:`~/ondemand/data/sys/` @@ -96,12 +96,12 @@ used to connect to the batch connect app. page you can match the Session ID you see there to the directory with the desired ``output.log`` to debug. -One important thing to note is if trying to launch a Jupyter or Rstudio session and encountering failures, the +One important thing to note is if trying to launch a Jupyter or RStudio session and encountering failures, the ``output.log`` would show you things like what modules are being loaded and what kernels are available. **Example** -Suppose a user is having trouble connecting to a Codeserver session they created. +Suppose a user is having trouble connecting to a CodeServer session they created. To see what data is being used by this batch connect app for the connection, look in: .. code-block:: sh diff --git a/latest/_sources/how-tos/monitoring/prometheus.rst.txt b/latest/_sources/how-tos/monitoring/prometheus.rst.txt index 65192e448..9a1c016be 100644 --- a/latest/_sources/how-tos/monitoring/prometheus.rst.txt +++ b/latest/_sources/how-tos/monitoring/prometheus.rst.txt @@ -25,7 +25,7 @@ Dependencies: Install via RPM -------------------------- -For yum/dnf based systems the `ondemand_exporter`_ can be installed via RPM. +For ``yum`` or ``dnf`` based systems the `ondemand_exporter`_ can be installed via RPM. .. code-block:: sh @@ -33,8 +33,8 @@ For yum/dnf based systems the `ondemand_exporter`_ can be installed via RPM. The RPM will install the following files that should work out of the box: -- **RHEL/Rocky/AlmaLinux 8 & 9 only**: /etc/httpd/conf.d/ondemand_exporter.conf -- /etc/sudoers.d/ondemand_exporter +- **RHEL/Rocky/AlmaLinux 8 & 9 only**: ``/etc/httpd/conf.d/ondemand_exporter.conf`` +- ``/etc/sudoers.d/ondemand_exporter`` Ensure that the new Apache configuration is loaded by restarting Apache diff --git a/latest/_sources/install-ihpc-apps.rst.txt b/latest/_sources/install-ihpc-apps.rst.txt index a8641ce70..74db82e11 100644 --- a/latest/_sources/install-ihpc-apps.rst.txt +++ b/latest/_sources/install-ihpc-apps.rst.txt @@ -131,8 +131,8 @@ interactive apps that are currently deployed at OSC and other contributing insti - https://github.com/OSC/bc_osc_qgis - yes - noVNC - * - RELION (for REgularised LIkelihood OptimisatioN) - - Shanghai Jiao Tong University (SJTU) + * - RELION (for ``REgularised LIkelihood OptimisatioN``) + - Shanghai ``Jiao Tong University (SJTU)`` - https://github.com/SJTU-HPC/bc_relion - yes - diff --git a/latest/_sources/installation/add-cluster-config.rst.txt b/latest/_sources/installation/add-cluster-config.rst.txt index ffdd6e984..5a32c070d 100644 --- a/latest/_sources/installation/add-cluster-config.rst.txt +++ b/latest/_sources/installation/add-cluster-config.rst.txt @@ -68,7 +68,7 @@ client binaries. .. toctree:: :maxdepth: 1 - :caption: Cluster Config + :caption: Cluster Configuration cluster-config-schema resource-manager/torque diff --git a/latest/_sources/installation/cluster-config-schema.rst.txt b/latest/_sources/installation/cluster-config-schema.rst.txt index 1d2fa332e..2f9b8e963 100644 --- a/latest/_sources/installation/cluster-config-schema.rst.txt +++ b/latest/_sources/installation/cluster-config-schema.rst.txt @@ -1,9 +1,9 @@ .. _cluster-config-schema: -Cluster Config Schema v2 -======================== +Cluster Configuration Schema v2 +=============================== -The cluster config controls many OnDemand features including job submission, shell access, names in menus. +The cluster configuration controls many OnDemand features including job submission, shell access, names in menus. First an example: ***************** @@ -134,8 +134,8 @@ bin_overrides: Adapter support for this feature is mixed. For example for Slurm `sbatch`, `scontrol`, `scancel` and `squeue` are all supported. For Torque only `qsub` is supported. Unsupported options are ignored. -acls: -##### +``acls``: +######### .. warning:: @@ -144,7 +144,7 @@ acls: are being handled in the Linux kernel, is much faster, simpler and frankly, safer. Access control lists provide a method to limit cluster access by group membership. -ACLs are implicitly allowlists but may be set explicitly to either `allowlist` or `blocklist`. +ACLs are implicitly allow-lists but may be set explicitly to either `allowlist` or `blocklist`. .. code-block :: yaml @@ -196,7 +196,7 @@ Suppose you need want to create a *login cluster that does not schedule or run j To accomplish this, you need to simply leave out the ``v2.job`` stanza that associates a scheduler with the cluster. -An example config file in ``ondemand.d/pitzer_01_login.yml``: +An example configuration file in ``clusters.d/pitzer_01_login.yml``: .. code-block:: yaml @@ -209,5 +209,5 @@ An example config file in ``ondemand.d/pitzer_01_login.yml``: login: host: "pitzer-login01.hpc.osu.edu" -Again, the thing to note here is we've left off the ``v2.job`` which renders the cluster useable only for logins, i.e. +Again, the thing to note here is we've left off the ``v2.job`` which renders the cluster use-able only for logins, i.e. *no jobs will be scheduleable on this cluster.* diff --git a/latest/_sources/installation/install-software.rst.txt b/latest/_sources/installation/install-software.rst.txt index bac97137b..025ca7d60 100644 --- a/latest/_sources/installation/install-software.rst.txt +++ b/latest/_sources/installation/install-software.rst.txt @@ -8,7 +8,7 @@ Open OnDemand uses these packages, among many others. - Apache HTTP Server 2.4 - Ruby 3.3 with :command:`rake`, :command:`bundler`, and development libraries -- Node.js 20 +- NodeJs 20 .. note:: diff --git a/latest/_sources/installation/modify-system-security.rst.txt b/latest/_sources/installation/modify-system-security.rst.txt index eb7443fb9..4c7ef38eb 100644 --- a/latest/_sources/installation/modify-system-security.rst.txt +++ b/latest/_sources/installation/modify-system-security.rst.txt @@ -20,7 +20,7 @@ SELinux The OnDemand SELinux package makes several changes to allow OnDemand to run with SELinux enabled. -* Set contexts of several filesystem paths specific to OnDemand. +* Set contexts of several file-system paths specific to OnDemand. * Enable SELinux booleans. * Apply a custom policy to allow actions to performed by `ood_pun_t` context. @@ -40,12 +40,12 @@ The custom SELinux booleans provided by the OnDemand SELinux policy: The following SELinux booleans are enabled by the ``ondemand-selinux`` package: -* httpd_setrlimit -* httpd_mod_auth_pam -* httpd_run_stickshift -* httpd_can_network_connect -* daemons_use_tty -* use_nfs_home_dirs (can be disabled if the OnDemand web node is not using NFS for home directories) +* ``httpd_setrlimit`` +* ``httpd_mod_auth_pam`` +* ``httpd_run_stickshift`` +* ``httpd_can_network_connect`` +* ``daemons_use_tty`` +* ``use_nfs_home_dirs`` (can be disabled if the OnDemand web node is not using NFS for home directories) The following example disabled the OnDemand SSH SELinux boolean. diff --git a/latest/_sources/installation/resource-manager/ccq.rst.txt b/latest/_sources/installation/resource-manager/ccq.rst.txt index 68fe514c0..5497084ec 100644 --- a/latest/_sources/installation/resource-manager/ccq.rst.txt +++ b/latest/_sources/installation/resource-manager/ccq.rst.txt @@ -30,21 +30,21 @@ cluster looks like: with the following configuration options: -adapter +``adapter`` This is set to ``ccq``. -image +``image`` The default cloud image to use when launching jobs. There is no default. -cloud +``cloud`` The cloud provider being used. Valid options are ``gcp`` or ``aws``. Defaults to ``gcp``. -scheduler +``scheduler`` The name of the scheduler being used. There is no default. -bin +``bin`` The path to the CCQ client installation binaries. Defaults to ``/opt/CloudyCluster/srv/CCQ``. -jobid_regex - The regular expression to extract the job id from the ccqstat output. Defaults to ``job id is: (?\\d+) you``. - You should only need this if the ccqstat output changes format. If you are required to reconfigure, you'll need to +``jobid_regex`` + The regular expression to extract the job id from the ``ccqstat`` output. Defaults to ``job id is: (?\\d+) you``. + You should only need this if the ``ccqstat`` output changes format. If you are required to reconfigure, you'll need to extract the named group ``job_id`` as the default does. -bin_overrides +``bin_overrides`` Replacements/wrappers for CCQ's job submission and control clients. *Optional* Supports the following clients: @@ -64,7 +64,7 @@ You may see this error when you initially try to start a job. .. code-block:: text The /opt/CloudyCluster/srv/CCQ/ccqsub command was prompted. You need - to generate the certificate manually in a shell by running 'ccqstat' + to generate the certificate manually in a shell by running ``ccqstat`` and entering your username/password This is because CCQ libraries require a certificate to be generated to communicate with the diff --git a/latest/_sources/installation/resource-manager/kubernetes.rst.txt b/latest/_sources/installation/resource-manager/kubernetes.rst.txt index bba6afa0d..abe625011 100644 --- a/latest/_sources/installation/resource-manager/kubernetes.rst.txt +++ b/latest/_sources/installation/resource-manager/kubernetes.rst.txt @@ -39,37 +39,37 @@ cluster looks like: ssh_allow: false -adapter +``adapter`` This is set to ``kubernetes``. -config_file - The KUBECONFIG file. *Optional*. Defaults to ~/.kube/config. Sites can also - set the KUBECONFIG environment varaible, but this configuration has precedence. -cluster +``config_file`` + The KUBECONFIG file. *Optional*. Defaults to ``~/.kube/config``. Sites can also + set the KUBECONFIG environment variable, but this configuration has precedence. +``cluster`` The cluster name. Saved to and referenced from your KUBECONFIG. -context +``context`` The context to use when issuing kubectl commands. *Optional*. Defaults to cluster when using OIDC authentication. Saved to and referenced from your KUBECONFIG. -username_prefix +``username_prefix`` The prefix to your users in your KUBECONFIG. Use this prefix to differentiate between different clusters (like test and production). -namespace_prefix +``namespace_prefix`` The prefix to your namespace. Use this prefix if you have assertions on what namespaces are available. I.e., a Kyverno policy that ensures all namespaces are ``user-\w+``. -all_namespaces +``all_namespaces`` A boolean to determine if the user will query for pods in other namespaces. When false users will only query in their namespace. If true they will query and display pods from all namespaces. -auto_supplemental_groups: +``auto_supplemental_groups`` Automatically populate a container's ``securityContext.supplementalGroups`` with the users supplemental groups. -server - The kubernetes server to communicate with. This field is a map with ``endpoint`` and +```server`` + The Kubernetes server to communicate with. This field is a map with ``endpoint`` and ``cert_authority_file`` keys. -auth: +``auth`` See the notes on `Authentication`_ below. -mounts: - Site wide mount points for all kubernetes jobs. See the - :ref:`documentation on kubernetes mounts ` for more details. +``mounts`` + Site wide mount points for all Kubernetes jobs. See the + :ref:`documentation on Kubernetes mounts ` for more details. .. note:: @@ -79,7 +79,7 @@ mounts: Per User Kubernetes ******************* -To get kubernetes to act like a Per User resource there are some conventions +To get Kubernetes to act like a Per User resource there are some conventions we put in place. Users only schedule pods in their own namespaces and they always run those pods as themselves. @@ -91,9 +91,9 @@ viewing active jobs and seeing pods from other namespaces in that view. Second is that we specify the `Kubernetes security context`_ such that pods have the same UID and GID as the actual user. -Open OnDemand will always use the users UID and GID as the runAsUser and runAsGroup. -fsGroup is always the same as runAsGroup. runAsNonRoot is always set to true. -supplementalGroups are empty by default. One can automatically populate them with a +Open OnDemand will always use the users UID and GID as the ``runAsUser`` and ``runAsGroup``. +``fsGroup`` is always the same as ``runAsGroup``. ``runAsNonRoot`` is always set to true. +``supplementalGroups`` are empty by default. One can automatically populate them with a cluster configuration above or specify them for each app individually. You should have policies in place to enforce these. @@ -102,7 +102,7 @@ Bootstrapping the Kuberenetes cluster ************************************* Before anyone can use your Kubernetes cluster from Open OnDemand, you'll need -to create the `open ondemand kubernetes resources`_ on your cluster. +to create the `open ondemand Kubernetes resources`_ on your cluster. Below is an example of adding the necessary resources: @@ -115,11 +115,11 @@ Bootstrapping OnDemand web node to communicate with Kubernetes ************************************************************** The OnDemand web node ``root`` user must be configured -to use the ``ondemand`` service account deployed by the `open ondemand kubernetes resources`_ and +to use the ``ondemand`` service account deployed by the `open ondemand Kubernetes resources`_ and be able to execute ``kubectl`` commands. First deploy ``kubectl`` to the OnDemand web node. -Replace ``$VERSION`` with the version of the Kubernetes controller, eg. ``1.21.5``. +Replace ``$VERSION`` with the version of the Kubernetes controller, e.g., ``1.21.5``. .. code-block:: sh @@ -167,7 +167,7 @@ to refresh your tokens before they expire. If you wish to create a non-expiring token, you will need to create the secret through a -``kubectl apply`` command on the yaml below. +``kubectl apply`` command on the YAML below. Next extract the ``ondemand`` ServiceAccount token. Here is an example command to extract the token using an account that has ClusterAdmin privileges: @@ -190,7 +190,7 @@ the token using an account that has ClusterAdmin privileges: TOKEN=$(kubectl describe serviceaccount ondemand -n ondemand | grep Tokens | awk '{ print $2 }') kubectl describe secret $TOKEN -n ondemand | grep "token:" -Below are example commands to bootstrap the kubeconfig for ``root`` user on the OnDemand web node +Below are example commands to bootstrap the Kubernetes configuration for ``root`` user on the OnDemand web node using the token from above. Run these commands as ``root`` on the OnDemand web node. .. code-block:: sh @@ -206,7 +206,7 @@ Replace the following values: - ``$CACERT`` the path to Kubernetes cluster CA cert - ``$TOKEN`` the token for ``ondemand`` ServiceAccount -Below is an example of verifying the kubeconfig is valid: +Below is an example of verifying the Kubernetes configuration is valid: .. code-block:: sh @@ -217,7 +217,7 @@ Deploy Hooks to bootstrap users Kubernetes configuration We ship with `open ondemand provided hooks`_ to bootstrap users when the login to Open OnDemand. These scripts will create their namespace, a networking policy, -and rolebindings for user and the service accounts in their namespace. +and role-bindings for user and the service accounts in their namespace. A user ``oakley`` would create the ``oakley`` namespace. If you've configured to use prefix ``user-``, then the namespace would be ``user-oakley``. @@ -225,7 +225,7 @@ to use prefix ``user-``, then the namespace would be ``user-oakley``. The networking policy ensures that pods cannot communicate inbetween namespaces. The RoleBindings give user, ``oakley`` in this case, sufficient privileges -to the ``oakley`` namespace. Refer to the `open ondemand kubernetes resources`_ +to the ``oakley`` namespace. Refer to the `open ondemand Kubernetes resources`_ for details on the roles and privileges created. You'll need to employ :ref:`PUN pre hooks ` @@ -264,7 +264,7 @@ You can refer to `osc's prehook`_ but we'll also provide this example. As you can see in this pre hook, the username is passed in to the script which then defines the ``HOOKENV`` and calls two `open ondemand provided hooks`_. -``k8s-bootstrap-ondemand.sh`` boostraps the user in the kubernetes cluster as described +``k8s-bootstrap-ondemand.sh`` boostraps the user in the Kubernetes cluster as described above. Since we use OIDC at OSC we use ``set-k8s-creds.sh`` to add or update the user in their @@ -321,7 +321,7 @@ is managed outside of Open OnDemand. We will not ``set-context`` or ``set-cluster``. We will pass ``--context`` to kubectl commands if you have it configured -in the cluster config (above). Otherwise, it's assumed that the current context +in the cluster configuration (above). Otherwise, it's assumed that the current context is set out of bounds. OIDC Authentication @@ -345,7 +345,7 @@ Another approach would be to use the same OIDC client configuration for OnDemand auth: type: 'odic' -This uses the OIDC credentails that you've logged in with. When +This uses the OIDC credentials that you've logged in with. When the dashboard starts up it will ``set-context`` and ``set-cluster`` to what you've configured. @@ -367,13 +367,13 @@ GKE Authentication svc_acct_file: '~/.gke/my-service-account-file' It's expected that you have a service account that can then manipulate -the cluster you're interacting with. Every user should have a cooresponding +the cluster you're interacting with. Every user should have a corresponding service account to interact with GKE. -When the dasbhoard starts up, we use ``gcloud`` to configure your KUBECONFIG. +When the dashboard starts up, we use ``gcloud`` to configure your KUBECONFIG. -Google Cloud's Goolge Kubernetes Engine (GKE) needs some more documentation -on what privileges this serivce account is setup with and how one may bootstrap +Google Cloud's Google Kubernetes Engine (GKE) needs some more documentation +on what privileges this service account is setup with and how one may bootstrap it. .. _oidc_k8_audience: @@ -412,19 +412,19 @@ Open OnDemand apps in a Kuberenetes cluster ******************************************* Kuberenetes is so different from other HPC clusters that the interface we have for -other schedulers didn't quite fit. So Open OnDemand apps developed for kubernetes +other schedulers didn't quite fit. So Open OnDemand apps developed for Kubernetes clusters look quite different from other schedulers. Essentially most things we'll need are packed into the ``native`` key of the ``submit.yml.erb`` files. -See the :ref:`tutorial for a kubernetes app that behaves like HPC compute ` as well as -the :ref:`tutorial for a kubernetes app ` +See the :ref:`tutorial for a Kubernetes app that behaves like HPC compute ` as well as +the :ref:`tutorial for a Kubernetes app ` for more details. Kyverno Policies **************** -Once Kubernetes is available to OnDemand, it's possible for users to use ``kubectl`` to submit arbirary pods to +Once Kubernetes is available to OnDemand, it's possible for users to use ``kubectl`` to submit arbitrary pods to Kubernetes. To ensure proper security with Kubernetes a policy engine such as `Kyverno`_ can be used to ensure certain security standards. @@ -529,7 +529,7 @@ a user's namespaces with the ability to pull from this registry: .. _kubernetes security context: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context .. _open ondemand provided hooks: https://github.com/OSC/ondemand/tree/master/hooks -.. _open ondemand kubernetes resources: https://github.com/OSC/ondemand/blob/master/hooks/k8s-bootstrap/ondemand.yaml +.. _open ondemand Kubernetes resources: https://github.com/OSC/ondemand/blob/master/hooks/k8s-bootstrap/ondemand.yaml .. _osc's prehook: https://github.com/OSC/osc-ood-config/blob/master/hooks/pre-hook.sh .. _kyverno: https://kyverno.io .. _kyverno baseline and restricted sescurity policies: https://github.com/kyverno/kyverno/tree/main/charts/kyverno-policies/templates diff --git a/latest/_sources/installation/resource-manager/linuxhost.rst.txt b/latest/_sources/installation/resource-manager/linuxhost.rst.txt index d5ca0d379..ca0894e1f 100644 --- a/latest/_sources/installation/resource-manager/linuxhost.rst.txt +++ b/latest/_sources/installation/resource-manager/linuxhost.rst.txt @@ -12,15 +12,15 @@ The LinuxHost adapter facilitates launching jobs immediately without using a bat The adapter pieces together several tools to achieve behavior similar to what a scheduler offers: -ssh +``ssh`` connects from the web node to a configured host such as a login node. -tmux +``tmux`` Specially named ``tmux`` sessions offer the ability to rediscover running jobs -timeout +``timeout`` is used to set a 'walltime' after which the job is killed -pstree +``pstree`` is used to detect the job's parent ``sinit`` process so that it can be killed -singularity +``singularity`` containerization provides a PID namespace without requiring elevated privileges that ensures that all child processes are cleaned up when the job either times out or is killed .. note:: There are many recipes for managing processes on arbitrary Linux hosts, and we will be exploring others in future development of this adapter. @@ -97,25 +97,25 @@ A YAML cluster configuration file for a Linux host looks like: with the following configuration options: -adapter +``adapter`` This is set to ``linux_host``. -submit_host +``submit_host`` The target execution host for jobs. May be the head for a login round robin. May also be "localhost". -ssh_hosts +``ssh_hosts`` All nodes the submit_host can DNS resolve to. -site_timeout +``site_timeout`` The number of seconds that a user's job is allowed to run. Distinct from the length of time that a user selects. -debug +``debug`` When set to ``true`` job scripts are written to ``$HOME/tmp.UUID_tmux`` and ``$HOME/tmp.UUID_sing`` for debugging purposes. When ``false`` those files are written to ``/tmp`` and deleted as soon as they have been read. -singularity_bin +``singularity_bin`` The absolute path to the ``singularity`` executable on the execution host(s). -singularity_bindpath +``singularity_bindpath`` The comma delimited list of paths to bind mount into the host; cannot simply be ``/`` because Singularity expects certain dot files in its containers' root; defaults to: ``/etc,/media,/mnt,/opt,/run,/srv,/usr,/var,/users``. -singularity_image - The absolute path to the Singularity image used when simply PID namespacing jobs; expected to be a base distribution image with no customizations. -strict_host_checking +``singularity_image`` + The absolute path to the Singularity image used to create PID namespaces; expected to be a base distribution image with no customizations. +``strict_host_checking`` When ``false`` the SSH options include ``StrictHostKeyChecking=no`` and ``UserKnownHostsFile=/dev/null`` this prevents jobs from failing to launch. -tmux_bin +``tmux_bin`` The absolute path to the ``tmux`` executable on the execution host(s). @@ -125,14 +125,14 @@ tmux_bin software on the target host, not launching specific application containers. As a result, even if your use of this adapter is reserved to launching specific application containers, you currently must specify a value in the - cluster config for ``singularity_bindpath`` and ``singularity_image``, even + cluster configuration for ``singularity_bindpath`` and ``singularity_image``, even if these will be specified in each interactive app plugin. .. note:: In order to communicate with the execution hosts the adapter uses SSH in ``BatchMode``. The adapter does not take a position on whether authentication - is performed by user owned passwordless keys, or host-based authentication; + is performed by user owned password-less keys, or host-based authentication; however OSC has chosen to provide `host based authentication `_ to its users. @@ -155,7 +155,7 @@ First update the PAM stack to include the following line: session required pam_exec.so type=open_session /etc/security/limits.sh -This goes into a file used by the ``sshd`` PAM configs which on CentOS/RHEL default to ``/etc/pam.d/password-auth-ac`` and needs to be included in the proper position, after ``pam_systemd.so``. Also set ``pam_systemd.so`` to ``required``: +This goes into a file used by the ``sshd`` PAM configurations which on CentOS/RHEL default to ``/etc/pam.d/password-auth-ac`` and needs to be included in the proper position, after ``pam_systemd.so``. Also set ``pam_systemd.so`` to ``required``: .. code-block:: none :emphasize-lines: 3,4 @@ -185,10 +185,10 @@ The following example of ``/etc/security/limits.sh`` is used by OSC on interacti CPUQuota=700% fi -Approach #2: libcgroup cgroups -.............................. +Approach #2: ``libcgroup`` cgroups +................................... -The libcgroup cgroups rules and configurations are a per-group resource limit where the group is defined in the examples at ``/etc/cgconfig.d/limits.conf``. The following examples limit resources of all tmux processes launched for the LinuxHost Adapter so they all share 700 CPU shares and 64GB of RAM. This requires setting ``tmux_bin`` to a wrapper script that in this example will be ``/usr/local/bin/ondemand_tmux``. +The ``libcgroup`` cgroups rules and configurations are a per-group resource limit where the group is defined in the examples at ``/etc/cgconfig.d/limits.conf``. The following examples limit resources of all ``tmux`` processes launched for the LinuxHost Adapter so they all share 700 CPU shares and 64GB of RAM. This requires setting ``tmux_bin`` to a wrapper script that in this example will be ``/usr/local/bin/ondemand_tmux``. Example of ``/usr/local/bin/ondemand_tmux``: @@ -260,7 +260,7 @@ error while loading shared libraries .................................... The default mounts for singularity are ``'/etc,/media,/mnt,/opt,/srv,/usr,/var,/users'``. It's likely -either you've overwritten this with too few mounts (like /lib, /opt or /usr) or your container lacks +either you've overwritten this with too few mounts (like ``/lib``, ``/opt`` or ``/usr``) or your container lacks the library in question. If the library exists on the host, consider mounting it into the container. Otherwise install it in @@ -285,7 +285,7 @@ Enable this, and you'll see the two shell scripts that ran during this job. Open Export the SINGULARITY_BINDPATH so you're sure to have the same mounts, and run this ``/usr/bin/singularity exec ... tmp.73S0QFxC5e_sing`` command manually on one of the ssh hosts. This will -emulate what the linuxhost adapter is doing and you should be able to modify and rerun until you fix +emulate what the ``linuxhost`` adapter is doing and you should be able to modify and rerun until you fix the issue. @@ -310,7 +310,7 @@ Again, mounting ``var`` fixed this error too. .. note:: - Subsequent versions of the adapter are expected to use `unshare `_ for PID namespacing as the default method instead of Singularity. Singularity will continue to be supported. + Subsequent versions of the adapter are expected to use `unshare `_ for PID namespaces as the default method instead of Singularity. Singularity will continue to be supported. diff --git a/latest/_sources/installation/resource-manager/lsf.rst.txt b/latest/_sources/installation/resource-manager/lsf.rst.txt index e22ed0995..2820bdde8 100644 --- a/latest/_sources/installation/resource-manager/lsf.rst.txt +++ b/latest/_sources/installation/resource-manager/lsf.rst.txt @@ -32,21 +32,21 @@ looks like: with the following configuration options: -adapter +``adapter`` This is set to ``lsf``. -bindir +``bindir`` The path to the LSF client ``bin/`` directory. -libdir +``libdir`` The path to the LSF client ``lib/`` directory. -envdir +``envdir`` The path to the LSF client ``conf/`` directory. -serverdir +``serverdir`` The path to the LSF client ``etc/`` directory. -bin_overrides +``bin_overrides`` Replacements/wrappers for LSF's job submission and control clients. *Optional* -submit_host +``submit_host`` A different, optional host to ssh to and *then* issue commands. *Optional* -cluster +``cluster`` The cluster to interact with when running LSF's multi-cluster mode. *Required to enable multi-cluster mode* Supports the following clients: @@ -71,7 +71,7 @@ Given these settings in ``lsf.conf``: LSB_QUERY_PORT=688X LSB_QUERY_ENH=y -It's recommented that you set ``LSB_MBD_PORT`` to the same value +It's recommended that you set ``LSB_MBD_PORT`` to the same value as ``LSB_QUERY_PORT`` It has also been observed that setting these values in ``lsb.params`` diff --git a/latest/_sources/installation/resource-manager/sge.rst.txt b/latest/_sources/installation/resource-manager/sge.rst.txt index aa5687542..57cf620df 100644 --- a/latest/_sources/installation/resource-manager/sge.rst.txt +++ b/latest/_sources/installation/resource-manager/sge.rst.txt @@ -32,21 +32,21 @@ cluster looks like: with the following configuration options: -adapter +``adapter`` This is set to ``sge``. -cluster +``cluster`` The Grid Engine cluster name. *Optional* -bin +``bin`` The path to the Grid Engine client installation binaries. -sge_root +``sge_root`` The path to the root directory of the Grid Engine installation. *Default:* ``/var/lib/gridengine`` -conf +``conf`` The path to the Grid Engine configuration file for this cluster. *Optional* -libdrmaa_path - The full path to libdrmaa.so. Provide this to enable use of libdrmaa for more precise job status reporting. *Optional* -submit_host +``libdrmaa_path`` + The full path to ``libdrmaa.so``. Provide this to enable use of ``libdrmaa`` for more precise job status reporting. *Optional* +``submit_host`` A different, optional host to ssh to and *then* issue commands. *Optional* -bin_overrides +``bin_overrides`` Replacements/wrappers for Grid Engine's job submission and control clients. *Optional* Supports the following clients: @@ -59,7 +59,7 @@ bin_overrides .. tip:: - DRMAA improves OnDemand's ability to report on the precise status of jobs. To use this feature ensure that libdrmaa.so for Grid Engine is installed or built and set the config value for ``libdrmaa_path`` and ``sge_root``. If DRMAA is not installed then OnDemand is unable to get a precise job status for single jobs and will only return either queued or complete. + DRMAA improves OnDemand's ability to report on the precise status of jobs. To use this feature ensure that ``libdrmaa.so`` for Grid Engine is installed or built and set the configuration value for ``libdrmaa_path`` and ``sge_root``. If DRMAA is not installed then OnDemand is unable to get a precise job status for single jobs and will only return either queued or complete. Common Issues ------------- @@ -76,7 +76,7 @@ substitution and there's a syntax error. line 156: done < <(tail -f --pid=${SCRIPT_PID} “vnc.log”) &’ What you'll need to do is add a ``script_wrapper`` element to your clusters' configuration like below. -This sets the sh shell to behave like bash and ensures you've sourced your users' bashrc file. +This sets the sh shell to behave like bash and ensures you've sourced your users' ``.bashrc`` file. .. code-block:: yaml diff --git a/latest/_sources/installation/resource-manager/slurm.rst.txt b/latest/_sources/installation/resource-manager/slurm.rst.txt index 0c4de157c..f92e3a6a9 100644 --- a/latest/_sources/installation/resource-manager/slurm.rst.txt +++ b/latest/_sources/installation/resource-manager/slurm.rst.txt @@ -41,22 +41,22 @@ cluster looks like: with the following configuration options: -adapter +``adapter`` This is set to ``slurm``. -cluster +``cluster`` The Slurm cluster name. *Optional*, passed to SLURM as ``-M `` .. warning:: Using the ``cluster`` option is discouraged. This is because maintenance outages on the Slurm database will propagate to Open OnDemand. Instead sites should use different ``conf`` files for each cluster to limit maintenance outages. -bin +``bin`` The path to the Slurm client installation binaries. -conf +``conf`` The path to the Slurm configuration file for this cluster. *Optional* -submit_host +``submit_host`` A different, optional host to ssh to and *then* issue commands. *Optional* -bin_overrides +``bin_overrides`` Replacements/wrappers for Slurm's job submission and control clients. *Optional* Supports the following clients: @@ -66,8 +66,8 @@ bin_overrides - `scontrol` - `scancel` -copy_environment - Copies the environment of the PUN when issuing CLI commands. Default behaviour +``copy_environment`` + Copies the environment of the PUN when issuing CLI commands. Default behavior for Open OnDemand is to use ``--export=NONE`` flag. Setting this to true will cause Open OnDemand to issue CLI commands with ``--export=ALL``. Though this may cause issues as the PUN's environment is very different than a regular shell session. diff --git a/latest/_sources/reference/commands/nginx-stage/commands/app-clean.rst.txt b/latest/_sources/reference/commands/nginx-stage/commands/app-clean.rst.txt index 0bb0eca3b..8b5e9ada5 100644 --- a/latest/_sources/reference/commands/nginx-stage/commands/app-clean.rst.txt +++ b/latest/_sources/reference/commands/nginx-stage/commands/app-clean.rst.txt @@ -1,7 +1,7 @@ .. _nginx-stage-app-clean: -nginx_stage app_clean -===================== +``nginx_stage app_clean`` +========================= This command will remove any deployed web application NGINX configuration files for applications that don't exist anymore on the @@ -16,10 +16,10 @@ file system. Examples -------- -To clean up all the stale app configs: +To clean up all the stale app configurations: .. code-block:: sh sudo nginx_stage app_clean -This displays the paths to all the app configs that were deleted. +This displays the paths to all the app configurations that were deleted. diff --git a/latest/_sources/reference/commands/nginx-stage/commands/app-list.rst.txt b/latest/_sources/reference/commands/nginx-stage/commands/app-list.rst.txt index e9aa4e373..bf2ecc310 100644 --- a/latest/_sources/reference/commands/nginx-stage/commands/app-list.rst.txt +++ b/latest/_sources/reference/commands/nginx-stage/commands/app-list.rst.txt @@ -1,7 +1,7 @@ .. _nginx-stage-app-list: -nginx_stage app_list -==================== +``nginx_stage app_list`` +======================== This command lists all the deployed web application NGINX configuration files. @@ -15,10 +15,10 @@ configuration files. Examples -------- -To list all the deployed app configs: +To list all the deployed app configurations: .. code-block:: sh sudo nginx_stage app_list -This will return the paths to all the deployed app configs. +This will return the paths to all the deployed app configurations. diff --git a/latest/_sources/reference/commands/nginx-stage/commands/app-reset.rst.txt b/latest/_sources/reference/commands/nginx-stage/commands/app-reset.rst.txt index 9c88d5403..f127f7b8a 100644 --- a/latest/_sources/reference/commands/nginx-stage/commands/app-reset.rst.txt +++ b/latest/_sources/reference/commands/nginx-stage/commands/app-reset.rst.txt @@ -1,7 +1,7 @@ .. _nginx-stage-app-reset: -nginx_stage app_reset -===================== +``nginx_stage app_reset`` +========================= This command will update all the deployed application NGINX configuration files using the current template. @@ -27,11 +27,11 @@ General Options Examples -------- -To update all the deployed app configs using the currently available +To update all the deployed app configurations using the currently available template: .. code-block:: sh sudo nginx_stage app_reset --sub-uri '/pun' -This will return the paths to the newly generated app configs. +This will return the paths to the newly generated app configurations. diff --git a/latest/_sources/reference/commands/nginx-stage/commands/app.rst.txt b/latest/_sources/reference/commands/nginx-stage/commands/app.rst.txt index 407f4adcd..fed495a15 100644 --- a/latest/_sources/reference/commands/nginx-stage/commands/app.rst.txt +++ b/latest/_sources/reference/commands/nginx-stage/commands/app.rst.txt @@ -1,7 +1,7 @@ .. _nginx-stage-app: -nginx_stage app -=============== +``nginx_stage app`` +=================== This command will generate a web application NGINX configuration file and subsequently restart the NGINX process as the user. @@ -42,7 +42,7 @@ General Options Examples -------- -To generate an app config from the request:: +To generate an app configuration from the request:: http://ondemand.center.edu/pun/usr/jim/myapp/session/1 @@ -52,20 +52,20 @@ and subsequently restart the per-user NGINX process: sudo nginx_stage app --user 'bob' --sub-uri '/pun' --sub-request '/usr/jim/myapp/session/1' -To generate **only** the app config: +To generate **only** the app configuration: .. code-block:: sh sudo nginx_stage app --user 'bob' --sub-uri '/pun' --sub-request '/sys/dashboard' --skip-nginx -This will return the path to the app config and will not restart the +This will return the path to the app configuration and will not restart the NGINX process. Default Installation .................... :numref:`app-mapping-table` details the mapping between the requested URL path -to the app root directory for in the NGINX app config under a default +to the app root directory for in the NGINX app configuration under a default installation. .. _app-mapping-table: @@ -75,12 +75,12 @@ installation. * - App type - URL path - File system path - * - dev + * - ``dev`` - :file:`/dev/{app_name}/\*` - :file:`/var/www/ood/apps/dev/{app_owner}/gateway/{app_name}` - * - usr + * - ``usr`` - :file:`/usr/{app_owner}/{app_name}/\*` - :file:`/var/www/ood/apps/usr/{app_owner}/gateway/{app_name}` - * - sys + * - ``sys`` - :file:`/sys/{app_name}/\*` - :file:`/var/www/ood/apps/sys/{app_name}` diff --git a/latest/_sources/reference/commands/nginx-stage/commands/nginx-clean.rst.txt b/latest/_sources/reference/commands/nginx-stage/commands/nginx-clean.rst.txt index aca195b49..1faa1adec 100644 --- a/latest/_sources/reference/commands/nginx-stage/commands/nginx-clean.rst.txt +++ b/latest/_sources/reference/commands/nginx-stage/commands/nginx-clean.rst.txt @@ -1,7 +1,7 @@ .. _nginx-stage-nginx-clean: -nginx_stage nginx_clean -======================= +``nginx_stage nginx_clean`` +=========================== This command will kill all per-user NGINX (PUN) processes that do not have active connections. diff --git a/latest/_sources/reference/commands/nginx-stage/commands/nginx-list.rst.txt b/latest/_sources/reference/commands/nginx-stage/commands/nginx-list.rst.txt index 550c27af8..bb51fbdca 100644 --- a/latest/_sources/reference/commands/nginx-stage/commands/nginx-list.rst.txt +++ b/latest/_sources/reference/commands/nginx-stage/commands/nginx-list.rst.txt @@ -1,7 +1,7 @@ .. _nginx-stage-nginx-list: -nginx_stage nginx_list -====================== +``nginx_stage nginx_list`` +========================== This command will list all the users with running per-user NGINX (PUN) processes. diff --git a/latest/_sources/reference/commands/nginx-stage/commands/nginx-show.rst.txt b/latest/_sources/reference/commands/nginx-stage/commands/nginx-show.rst.txt index 57dd03781..60b77f805 100644 --- a/latest/_sources/reference/commands/nginx-stage/commands/nginx-show.rst.txt +++ b/latest/_sources/reference/commands/nginx-stage/commands/nginx-show.rst.txt @@ -1,7 +1,7 @@ .. _nginx-stage-nginx-show: -nginx_stage nginx_show -====================== +``nginx_stage nginx_show`` +========================== This command will show the relevant details of a running per-user NGINX (PUN) process for a given user. diff --git a/latest/_sources/reference/commands/nginx-stage/commands/nginx.rst.txt b/latest/_sources/reference/commands/nginx-stage/commands/nginx.rst.txt index d9324a53b..6b813e652 100644 --- a/latest/_sources/reference/commands/nginx-stage/commands/nginx.rst.txt +++ b/latest/_sources/reference/commands/nginx-stage/commands/nginx.rst.txt @@ -1,7 +1,7 @@ .. _nginx-stage-nginx: -nginx_stage nginx -================= +``nginx_stage nginx`` +===================== This command will start an NGINX process as the user as well as control this process. diff --git a/latest/_sources/reference/commands/nginx-stage/commands/pun.rst.txt b/latest/_sources/reference/commands/nginx-stage/commands/pun.rst.txt index 8ca89d02e..9d00e833a 100644 --- a/latest/_sources/reference/commands/nginx-stage/commands/pun.rst.txt +++ b/latest/_sources/reference/commands/nginx-stage/commands/pun.rst.txt @@ -1,7 +1,7 @@ .. _nginx-stage-pun: -nginx_stage pun -=============== +``nginx_stage pun`` +=================== This command will generate a per-user NGINX (PUN) configuration file for the given user and subsequently launch the NGINX process as the user. diff --git a/latest/_sources/reference/commands/ood-portal-generator.rst.txt b/latest/_sources/reference/commands/ood-portal-generator.rst.txt index cc70ce12e..70cc16536 100644 --- a/latest/_sources/reference/commands/ood-portal-generator.rst.txt +++ b/latest/_sources/reference/commands/ood-portal-generator.rst.txt @@ -97,7 +97,7 @@ Options .. warning:: The systemd file for Apache will run the update_ood_portal script with defaults and will not use a different file, rendering this option obsolete unless you also - modify systemd config (``/etc/systemd/system/httpd24-httpd.service.d/ood-portal.conf`` in + modify systemd configuration (``/etc/systemd/system/httpd24-httpd.service.d/ood-portal.conf`` in RHEL 7, ``/etc/systemd/system/httpd.service.d/ood-portal.conf`` in RHEL 8). .. option:: -t