[ci skip] Autodoc commit for eb5acbf.

OSC · Jan 13, 2025 · 68f6288 · 68f6288
1 parent c4b4afb
commit 68f6288
Show file tree

Hide file tree

Showing 260 changed files with 17,385 additions and 41,589 deletions.
diff --git a/latest/.buildinfo b/latest/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 59fea9060d1679feddf1b60366c9cd38
+config: 39c68f967cac093614240d5642d76658
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/latest/_images/4.0_file_editor.png b/latest/_images/4.0_file_editor.png
diff --git a/latest/_images/bc_saved_settings_edit.png b/latest/_images/bc_saved_settings_edit.png
diff --git a/latest/_images/bc_saved_settings_form.png b/latest/_images/bc_saved_settings_form.png
diff --git a/latest/_images/bc_saved_settings_select.png b/latest/_images/bc_saved_settings_select.png
diff --git a/latest/_images/dashboard-announcement.png b/latest/_images/dashboard-announcement.png
diff --git a/latest/_images/plantuml-6a8fdab5b21c9c0c998d0a21b362a10878872ac3.png b/latest/_images/plantuml-6a8fdab5b21c9c0c998d0a21b362a10878872ac3.png
diff --git a/latest/_images/plantuml-be1e1017662db91033e2642c95916bc1e948d557.png b/latest/_images/plantuml-be1e1017662db91033e2642c95916bc1e948d557.png
diff --git a/latest/_images/system-status.png b/latest/_images/system-status.png
diff --git a/latest/_plantuml/6a/6a8fdab5b21c9c0c998d0a21b362a10878872ac3.png b/latest/_plantuml/6a/6a8fdab5b21c9c0c998d0a21b362a10878872ac3.png
diff --git a/latest/_plantuml/be/be1e1017662db91033e2642c95916bc1e948d557.png b/latest/_plantuml/be/be1e1017662db91033e2642c95916bc1e948d557.png
diff --git a/latest/_sources/architecture.rst.txt b/latest/_sources/architecture.rst.txt
@@ -5,9 +5,9 @@ Architecture
 
 Below are some diagrams of OnDemand's architecture:
 
-#. Overview is a high level visual generated from Powerpoint.
+#. Overview is a high level visual generated from PowerPoint.
 #. System context and Container context diagrams below follow the `C4 <https://c4model.com/>`_.
-   model for software diagrams, are more technically detailed and are built using draw.io
+   model for software diagrams, are more technically detailed and are built using ``draw.io``
 #. Request flow diagram is a sequence diagram built using plantuml.
 
 Overview
@@ -97,7 +97,7 @@ Linux Host Adapter
 .. figure:: /app-flow-diagrams/flow_linux_host_adapter.png
 
 ===========
-Rstudio Job
+RStudio Job
 ===========
 
 .. figure:: /app-flow-diagrams/flow_rstudio_job.png

diff --git a/latest/_sources/authentication.rst.txt b/latest/_sources/authentication.rst.txt
@@ -21,7 +21,7 @@ No Open OnDemand functionality is available without authentication.
    If you managed to install an Apache authentication module at your center
    that currently does not have a tutorial listed below we would greatly
    appreciate it if you could take the time to contribute a detailed
-   walkthrough.
+   walk-through.
 
 
 .. tip::

diff --git a/latest/_sources/authentication/adfs-with-auth-mellon.rst.txt b/latest/_sources/authentication/adfs-with-auth-mellon.rst.txt
@@ -81,7 +81,7 @@ Note that this configuration assumes that SAML has been configured such that the
         MellonEnable "auth"
       </Location>
 
-#. Convert the key and cert files into pfx format
+#. Convert the key and cert files into PFX format
 
    .. code-block:: shell
 

diff --git a/latest/_sources/authentication/dex.rst.txt b/latest/_sources/authentication/dex.rst.txt
@@ -8,7 +8,7 @@ OpenID Connect with Dex
 Installing OnDemand Dex package
 -------------------------------
 
-First the OnDemand yum repos must be enabled, see :ref:`install-software`.
+First the OnDemand yum repositories must be enabled, see :ref:`install-software`.
 
 Install the ``ondemand-dex`` package:
 
@@ -36,7 +36,7 @@ Requirements:
 - Git
 - Make
 
-Build and install the ondemand-dex binary:
+Build and install the ``ondemand-dex`` binary:
 
    .. code-block:: sh
 
@@ -53,7 +53,7 @@ Add the ``ondemand-dex`` user and group:
       sudo groupadd -r ondemand-dex
       sudo useradd -r -d /var/lib/ondemand-dex -g ondemand-dex -s /sbin/nologin -c "OnDemand Dex" ondemand-dex
 
-Get ``ondemand-dex`` repo and install web files and systemd unit file
+Get the ``ondemand-dex`` repository and install web files and systemd unit file
 
    .. code-block:: sh
 
@@ -96,7 +96,7 @@ The service for OnDemand Dex is ``ondemand-dex``:
 OnDemand Dex behind Apache reverse proxy
 ----------------------------------------
 
-By default Dex sits behing Apache and is accessed via a reverse proxy.
+By default Dex sits behind Apache and is accessed via a reverse proxy.
 OnDemand Dex behind the reverse proxy logic will force Dex to listen only on ``localhost`` and only
 via HTTP.
 
@@ -120,13 +120,13 @@ Dex Firewall
 
 By default when using SSL, Dex will use port ``5554`` for the communication between OnDemand and Dex as well as login interactions with users accessing OnDemand.  The port used for non-SSL is ``5556``.  The port being used by Dex must be externally accessible.
 
-Firewalld example:
+firewalld example:
    .. code-block:: sh
 
       $ sudo firewall-cmd --zone=public --add-port=5554/tcp --permanent
       $ sudo firewall-cmd --reload
 
-Iptables example:
+iptables example:
    .. code-block:: sh
 
       $ sudo iptables -I INPUT -p tcp -m tcp --dport 5554 -j ACCEPT

diff --git a/latest/_sources/authentication/duo-2fa-with-keycloak.rst.txt b/latest/_sources/authentication/duo-2fa-with-keycloak.rst.txt
@@ -8,7 +8,7 @@ These are the steps to setup two factor authentication with Duo using Keycloak.
 Install Keycloak Duo SPI
 --------------------------------------------------
 
-#. Clone the Keycloak Duo SPI repo
+#. Clone the Keycloak Duo SPI repository.
 
    .. code::
 
@@ -50,11 +50,11 @@ Configure Duo SPI
 --------------------------------------------------
 
 #. Log into your Keycloak instance
-#. Choose the realm to configure in upper left corner, eg ``ondemand``
+#. Choose the realm to configure in upper left corner, e.g., ``ondemand``
 #. Choose ``Realm Settings`` in the left menu then ``Security Defenses`` tab
 #. Add ``frame-src https://*.duosecurity.com/ 'self';`` to the beginning of the value for ``Content-Security-Policy``
 #. Choose ``Authentication`` in the left menu
-#. While on ``Flows`` tab ensure the dropdown for the flow name is ``Browser`` and click ``Copy``
+#. While on ``Flows`` tab ensure the drop-down for the flow name is ``Browser`` and click ``Copy``
 #. Name the new flow ``browser-with-duo``
 #. For all items below ``Username Password Form`` delete them by choosing ``Actions`` then ``Delete``
 #. Choose ``Actions`` for ``Browser-with-duo Forms`` and choose ``Add Execution``

diff --git a/latest/_sources/authentication/nsf-access.rst.txt b/latest/_sources/authentication/nsf-access.rst.txt
@@ -4,7 +4,7 @@ NSF ACCESS
 ----------
 
 If your site is a part of the `National Science Foundation`_'s (NSF)
-`ACCESS`_ program (formerley `XSEDE`_) you can use their Identity Provider (IDP)
+`ACCESS`_ program (formerly `XSEDE`_) you can use their Identity Provider (IDP)
 to authenticate users for your Open OnDemand instance.
 
 OIDC Client Registration
@@ -15,7 +15,7 @@ instance as an Open ID Connect (OIDC) client.
 ACCESS uses `CILogon`_ to provide a bridge from campus authentication, via the InCommon Federation,
 to OAuth/OIDC-based research cyberinfrastructure (CI).
 
-Once you've registered your Open OnDemand instance, you can then configure it accordingly.
+Once you have registered your Open OnDemand instance, you can then configure it accordingly.
 Since `ACCESS`_ uses Open ID Connect (OIDC) you can see our :ref:`oidc documentation <authentication-oidc>`
 for more details on how to configure Open OnDemand with what CILogon has provided in
 registering your application.
@@ -49,7 +49,7 @@ Shibboleth and InCommon
 If your campus already runs Shibboleth authentication, you have an alternative to the Open ID Connect
 configuration above.
 
-The SAML metadata for idp.access-ci.org is published by InCommon and can be downloaded using the 
+The SAML metadata for ``idp.access-ci.org`` is published by InCommon and can be downloaded using the 
 Metadata Query (MDQ) Service from https://mdq.incommon.org/entities/https%3A%2F%2Faccess-ci.org%2Fidp . 
 Alternatively, you can download the metadata from https://identity.access-ci.org/access-metadata.xml 
 and configure it in a local file.

diff --git a/latest/_sources/authentication/oidc.rst.txt b/latest/_sources/authentication/oidc.rst.txt
@@ -12,7 +12,7 @@ The following prerequisites need to be satisfied:
 
 .. note::
 
-   The OnDemand repos have the ``mod_auth_openidc`` RPM for RHEL 8 and Rocky 8 that are newer than what the OS provides to make use of some newer features.
+   The OnDemand repositories have the ``mod_auth_openidc`` RPM for RHEL 8 and Rocky 8 that are newer than what the OS provides to make use of some newer features.
 
 The following is an example :program:`ood-portal-generator` configuration file:
 

diff --git a/latest/_sources/authentication/overview/configure-logout.rst.txt b/latest/_sources/authentication/overview/configure-logout.rst.txt
@@ -3,9 +3,9 @@
 Configure Logout
 ================
 
-The logout link on the dashboard is ``/logout``. OnDemand's Apache config has a separate directive to handle ``/logout``, which by default redirects the user to ``/pun/sys/dashboard/logout``, which is a default logout page displayed by the dashboard. Because authentication handled by Apache, this approach enables the logout URL to be changed based on the authentication strategy used.
+The logout link on the dashboard is ``/logout``. OnDemand's Apache configuration has a separate directive to handle ``/logout``, which by default redirects the user to ``/pun/sys/dashboard/logout``, which is a default logout page displayed by the dashboard. Because authentication handled by Apache, this approach enables the logout URL to be changed based on the authentication strategy used.
 
-To change the logout_redirect URL, set ``logout_redirect: "https:://URL/TO/LOGOUT/USER"`` in the ood-portal-generator config at ``/etc/ood/config/ood_portal.yml`` and regenerate the config.
+To change the logout_redirect URL, set ``logout_redirect: "https:://URL/TO/LOGOUT/USER"`` in the ``ood-portal-generator`` configuration at ``/etc/ood/config/ood_portal.yml`` and regenerate the configuration.
 
 
 .. describe:: logout_redirect (String, null)
@@ -20,14 +20,14 @@ To change the logout_redirect URL, set ``logout_redirect: "https:://URL/TO/LOGOU
           logout_redirect: "/pun/sys/dashboard/logout"
 
      Using OpenID Connect Apache module
-       Redirect to the mod_auth_oidc logout location:
+       Redirect to the ``mod_auth_oidc`` logout location:
 
        .. code-block:: yaml
 
           logout_redirect: "/oidc?logout=https%3A%2F%2Fondemand.my-center.edu"
 
      Using Shibboleth Apache module
-       If the Shibboleth IdP server deployed is at idp.my-center.edu, this is an example redirect with mod_auth_shib:
+       If the Shibboleth IdP server deployed is at ``idp.my-center.edu``, this is an example redirect with ``mod_auth_shib``:
 
        .. code-block:: yaml
 

diff --git a/latest/_sources/authentication/overview/map-user.rst.txt b/latest/_sources/authentication/overview/map-user.rst.txt
@@ -19,11 +19,16 @@ Since 2.0 you should use the simpler and faster :ref:`user_map_match <ood-portal
 
 Both with variations will be discussed here.
 
+.. tip::
+
+  Since 4.0 user mapping also accepts UIDs to be returned as well as usernames.
+  This can be helpful at centers where duplicate usernames and/or have multiple
+  domains.
 
 Remote User
 -----------
 
-It's worth discussusing where ``REMOTE_USER`` is coming from.  When apache
+It's worth discussing where ``REMOTE_USER`` is coming from.  When apache
 has successfully authenticates a request it sets the variable ``REMOTE_USER``
 from, well, the remote.
 
@@ -39,11 +44,11 @@ If you're using an OpenID Connect provider you may need to set
 tells apache how to set ``REMOTE_USER`` from the claim response.
 
 
-Reguluar Expression User Mapping
---------------------------------
+Regular Expression User Mapping
+-------------------------------
 
 The simplest and fastest way to map a ``REMOTE_USER`` to a system user is through
-:ref:`user_map_match <ood-portal-generator-user-map-match>`.  It isn't directly
+:ref:`user_map_match <ood-portal-generator-user-map-match>`.  This is not directly
 regular expression matching, but it's close enough for most use cases.
 See it's documentation for examples and more.
 
@@ -52,7 +57,7 @@ Dex Automatic Configuration
 
 When using the OpenId Connector `dex`_ and setting `oidc_remote_user_claim`_
 to ``email`` we automatically set `user_map_match`_ to ``^([^@]+)@.*$`` as
-a convienience.
+a convenience.
 
 User Map Command for Advanced Mappings
 --------------------------------------
@@ -69,12 +74,12 @@ configuration and be sure to make this mapping script executable.
   Be aware, this script is executed on every request.
 
 Let's take a simple example.  It uses bash's builtin regular expression matching
-against ``([^@]+)@osc.edu`` - an osc dot edu email address.  If that matches against 
-``$1`` (the ``REMOTE_USER``) after it's url-decoded, then we return an all lowercase
+against ``([^@]+)@osc.edu`` - an ``osc.edu`` email address.  If that matches against 
+``$1`` (the ``REMOTE_USER``) after it's URL decoded, then we return an all lowercase
 version of the first part of an email address.
 
-The contract this script has with ood is that ``REMOTE_USER`` is url-encoded and
-passed into it as the first arguement, ``$1``.
+The contract this script has with Open OnDemand is that ``REMOTE_USER`` is URL encoded and
+passed into it as the first argument, ``$1``.
 
 The script will return 0 and output the match if it can correctly map the user.
 Otherwise, if it fails, it will output nothing and exit 1.

diff --git a/latest/_sources/authentication/shibboleth.rst.txt b/latest/_sources/authentication/shibboleth.rst.txt
@@ -8,12 +8,12 @@ The following prerequisites need to be satisfied:
 - A Shibboleth IdP server deployed, e.g., ``idp.my-center.edu`` (outside of
   scope of this document)
 - The `Apache module for Shibboleth`_ installed on the OnDemand Server and
-  properly configured with its own Apache config (outside of scope of this
+  properly configured with its own Apache configuration (outside of scope of this
   document)
 
 .. warning::
 
-   It is required you turn on ``ShibCompatValidUser`` in your Apache config
+   It is required you turn on ``ShibCompatValidUser`` in your Apache configuration
    when setting up the Shibboleth module for Apache above.
 
    .. code-block:: apache

diff --git a/...t/_sources/authentication/tutorial-oidc-keycloak-rhel7/add-custom-theme.rst.txt b/...t/_sources/authentication/tutorial-oidc-keycloak-rhel7/add-custom-theme.rst.txt
@@ -28,9 +28,3 @@ Here are two links to get started with a custom theme:
 Remember after adding a theme you still need to configure your realm in the
 Keycloak admin UI to use the theme for the login pages.
 
-.. note::
-
-   Soon we will offer an ood-keycloak base theme that be easier to extended to
-   provide most of the common themeing a site might like to perform. It will
-   also work well for OTP views.
-
diff --git a/latest/_sources/customizations.rst.txt b/latest/_sources/customizations.rst.txt
@@ -38,6 +38,8 @@ directory while members of the ``staff`` Unix group can.
   sudo chown root:staff /var/www/ood/apps/sys/files
 
 
+.. _configure_announcements:
+
 Announcements
 -------------
 
@@ -62,15 +64,31 @@ the user would see this message at the top of the dashboard:
 
 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:: Config Files
-   :stub-columns: 1
+.. list-table:: Announcement configuration keys.
 
+   * - Key
+     - Description
    * - type
-     - warning, info, success, or danger
-     - this is the Bootstrap alert style
+     - The type of announcement. Values can be ``warning``, ``info``, ``success``, or ``danger``.
    * - msg
-     - string containing markdown formatted message
-     - if this is a blank string (only whitespace), the alert will not display
+     - The announcement's message.
+   * - 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
+     - Specify if the announcement is dismissible or not with ``true`` or ``false``.
+       Defaults to ``true``.
+   * - 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
+     - Optional parameter to customize the text content for the button to dismiss the announcement.
+       Defaults to ``Accept`` for required and ``OK`` for dismissible.
+
+.. tip::
+  You can use ``required`` announcements to present users with a ToS (terms of service),
+  EULA (end user license agreement) or similar.
 
 Because the announcement is rendered via ERB you can do some interesting things, like stop showing the announcement past a specified date:
 

diff --git a/latest/_sources/enable-desktops.rst.txt b/latest/_sources/enable-desktops.rst.txt
@@ -4,7 +4,7 @@ Enable Interactive Desktop
 ==========================
 
 This installation guide will walk you through setting up an Interactive Desktop
-app that your users will be able to use to launch a Gnome 2, Mate, or Xfce
+app that your users will be able to use to launch a Gnome 2, Mate, or XFCE
 desktop on a compute node within your HPC cluster. The user should then be able
 to connect to a running session through their browser using the `noVNC`_
 client.

diff --git a/latest/_sources/enable-desktops/add-cluster.rst.txt b/latest/_sources/enable-desktops/add-cluster.rst.txt
@@ -34,7 +34,7 @@ modify.
       :file:`/etc/ood/config/clusters.d/`.
 
 #. Navigate to your OnDemand site, in particular the Dashboard App, and you
-   should see in the top dropdown menu "Interactive Apps" ⇒ "Oakley Desktop"
+   should see in the top drop-down menu "Interactive Apps" ⇒ "Oakley Desktop"
    (or whatever you set as the ``title``).
 
    After choosing "Oakley Desktop" from the menu, you should be presented with

diff --git a/latest/_sources/enable-desktops/custom-job-submission.rst.txt b/latest/_sources/enable-desktops/custom-job-submission.rst.txt
@@ -55,39 +55,39 @@ Since it has the extension ``.erb`` we can take advantage of the Ruby language
 to make the configuration file dynamic. In particular, you will now have access
 to the user-submitted form arguments defined as:
 
-bc_num_hours
+``bc_num_hours``
   *Default:* ``"1"``
 
   A Ruby ``String`` containing the number of hours a user requested for the
   Desktop batch job to run.
 
-bc_num_slots
+``bc_num_slots``
   *Default:* ``"1"``
 
   A Ruby ``String`` containing either the number of nodes or processors
   (depending on the type of resource manager the cluster uses) a user
   requested.
 
-bc_account
+``bc_account``
   *Default:* ``""``
 
   A Ruby ``String`` that holds the account the user supplied to charge the job
   against.
 
-bc_queue
+``bc_queue``
   *Default:* ``""``
 
   A Ruby ``String`` that holds the queue the user requested for the job to run
   on.
 
-bc_email_on_started
+``bc_email_on_started``
   *Default:* ``"0"``
 
   A Ruby ``String`` that can either be ``"0"`` (do not send the user an email
   when the job starts) or ``"1"`` (send an email to the user when the job
   starts).
 
-node_type
+``node_type``
   *Default:* ``""``
 
   A Ruby ``String`` that can be used for more advanced job submission. This is
@@ -172,7 +172,7 @@ This can be handled in your custom job submission configuration file as such:
        - "select=1:ncpus=<%= bc_num_slots.blank? ? 1 : bc_num_slots.to_i %>"
 
 All `batch script options`_ are underneath the ``script`` configuration option.
-In particular since there is no option to modify number of nodes/cpus, we need
+In particular since there is no option to modify number of nodes or CPUs, we need
 to directly interact with the ``native`` command line arguments. This is
 specified as an array of :command:`qsub` arguments.
 
@@ -224,7 +224,7 @@ LinuxHost Adapter
 --------------------
 
 If you're using the :ref:`resource-manager-linuxhost` you actually don't *need* a specialized
-submit.yml.erb. There is no need to specify resources like the other adapters above.
+``submit.yml.erb``. There is no need to specify resources like the other adapters above.
 
 You can however, use it to override the adapter's global fields for mount binding and specifying
 which container use.