[ci skip] Autodoc commit for 86ef0754fe514af3f00b2560eec105af21865688.

OSC · Dec 6, 2023 · 682c1e3 · 682c1e3
1 parent da095e0
commit 682c1e3
Show file tree

Hide file tree

Showing 397 changed files with 102,466 additions and 0 deletions.
diff --git a/update-usr-sharing/.buildinfo b/update-usr-sharing/.buildinfo
@@ -0,0 +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: 1fb2f0dce803acd14e9e5109260db8d4
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/update-usr-sharing/.nojekyll b/update-usr-sharing/.nojekyll
diff --git a/update-usr-sharing/_images/2.0_files_app.png b/update-usr-sharing/_images/2.0_files_app.png
diff --git a/update-usr-sharing/_images/app-dev-tutorial-ps-to-quota-1.png b/update-usr-sharing/_images/app-dev-tutorial-ps-to-quota-1.png
diff --git a/update-usr-sharing/_images/app-dev-tutorial-ps-to-quota-2.png b/update-usr-sharing/_images/app-dev-tutorial-ps-to-quota-2.png
diff --git a/update-usr-sharing/_images/app-dev-tutorial-ps-to-quota-published.png b/update-usr-sharing/_images/app-dev-tutorial-ps-to-quota-published.png
diff --git a/update-usr-sharing/_images/app-links-no-group.png b/update-usr-sharing/_images/app-links-no-group.png
diff --git a/update-usr-sharing/_images/app-sharing-1.png b/update-usr-sharing/_images/app-sharing-1.png
diff --git a/update-usr-sharing/_images/app-sharing-2.png b/update-usr-sharing/_images/app-sharing-2.png
diff --git a/update-usr-sharing/_images/app-sharing-3.png b/update-usr-sharing/_images/app-sharing-3.png
diff --git a/update-usr-sharing/_images/app-sharing-4.png b/update-usr-sharing/_images/app-sharing-4.png
diff --git a/update-usr-sharing/_images/app-sharing-5.png b/update-usr-sharing/_images/app-sharing-5.png
diff --git a/update-usr-sharing/_images/app-sharing-6.png b/update-usr-sharing/_images/app-sharing-6.png
diff --git a/update-usr-sharing/_images/app-sharing-mode-after.png b/update-usr-sharing/_images/app-sharing-mode-after.png
diff --git a/update-usr-sharing/_images/app-sharing-mode-before.png b/update-usr-sharing/_images/app-sharing-mode-before.png
diff --git a/update-usr-sharing/_images/app-sharing-permissions-after.png b/update-usr-sharing/_images/app-sharing-permissions-after.png
diff --git a/update-usr-sharing/_images/app-sharing-permissions-before.png b/update-usr-sharing/_images/app-sharing-permissions-before.png
diff --git a/update-usr-sharing/_images/bc-card-w-hostlink.png b/update-usr-sharing/_images/bc-card-w-hostlink.png
diff --git a/update-usr-sharing/_images/cancel_session.png b/update-usr-sharing/_images/cancel_session.png
diff --git a/update-usr-sharing/_images/custom-pages-documentation.png b/update-usr-sharing/_images/custom-pages-documentation.png
diff --git a/update-usr-sharing/_images/custom_pinned_apps.png b/update-usr-sharing/_images/custom_pinned_apps.png
diff --git a/update-usr-sharing/_images/customization_homedirmissing_default.png b/update-usr-sharing/_images/customization_homedirmissing_default.png
diff --git a/update-usr-sharing/_images/customization_homedirmissing_pammkdir.png b/update-usr-sharing/_images/customization_homedirmissing_pammkdir.png
diff --git a/update-usr-sharing/_images/customization_xdmod.png b/update-usr-sharing/_images/customization_xdmod.png
diff --git a/update-usr-sharing/_images/customization_xdmod_jobcomposer_warning_1.png b/update-usr-sharing/_images/customization_xdmod_jobcomposer_warning_1.png
diff --git a/update-usr-sharing/_images/customization_xdmod_jobcomposer_warning_2.png b/update-usr-sharing/_images/customization_xdmod_jobcomposer_warning_2.png
diff --git a/update-usr-sharing/_images/dashboard-announcement.png b/update-usr-sharing/_images/dashboard-announcement.png
diff --git a/update-usr-sharing/_images/dashboard_branding_logo_and_colors.png b/update-usr-sharing/_images/dashboard_branding_logo_and_colors.png
diff --git a/update-usr-sharing/_images/dashboard_motd.png b/update-usr-sharing/_images/dashboard_motd.png
diff --git a/update-usr-sharing/_images/dashboard_navbar_branding_bluered.png b/update-usr-sharing/_images/dashboard_navbar_branding_bluered.png
diff --git a/update-usr-sharing/_images/def-apps-menu.png b/update-usr-sharing/_images/def-apps-menu.png
diff --git a/update-usr-sharing/_images/def-category-menu.png b/update-usr-sharing/_images/def-category-menu.png
diff --git a/update-usr-sharing/_images/def-full-menu.png b/update-usr-sharing/_images/def-full-menu.png
diff --git a/update-usr-sharing/_images/def-navigation-link.png b/update-usr-sharing/_images/def-navigation-link.png
diff --git a/update-usr-sharing/_images/def-page-links.png b/update-usr-sharing/_images/def-page-links.png
diff --git a/update-usr-sharing/_images/def-profiles-links.png b/update-usr-sharing/_images/def-profiles-links.png
diff --git a/update-usr-sharing/_images/def-templates-menu.png b/update-usr-sharing/_images/def-templates-menu.png
diff --git a/update-usr-sharing/_images/files-open-in-terminal.png b/update-usr-sharing/_images/files-open-in-terminal.png
diff --git a/update-usr-sharing/_images/files_menu_shortcuts_osc.png b/update-usr-sharing/_images/files_menu_shortcuts_osc.png
diff --git a/update-usr-sharing/_images/flow_access_dashboard.png b/update-usr-sharing/_images/flow_access_dashboard.png
diff --git a/update-usr-sharing/_images/flow_access_passenger_app.png b/update-usr-sharing/_images/flow_access_passenger_app.png
diff --git a/update-usr-sharing/_images/flow_access_usr_app_via_app_sharing.png b/update-usr-sharing/_images/flow_access_usr_app_via_app_sharing.png
diff --git a/update-usr-sharing/_images/flow_authentication.png b/update-usr-sharing/_images/flow_authentication.png
diff --git a/update-usr-sharing/_images/flow_linux_host_adapter.png b/update-usr-sharing/_images/flow_linux_host_adapter.png
diff --git a/update-usr-sharing/_images/flow_rstudio_job.png b/update-usr-sharing/_images/flow_rstudio_job.png
diff --git a/update-usr-sharing/_images/flow_start_shell_session.png b/update-usr-sharing/_images/flow_start_shell_session.png
diff --git a/update-usr-sharing/_images/flow_vnc_desktop_job.png b/update-usr-sharing/_images/flow_vnc_desktop_job.png
diff --git a/update-usr-sharing/_images/form-display-attribute.png b/update-usr-sharing/_images/form-display-attribute.png
diff --git a/update-usr-sharing/_images/grouped_pinned_apps.png b/update-usr-sharing/_images/grouped_pinned_apps.png
diff --git a/update-usr-sharing/_images/help_menu_links.png b/update-usr-sharing/_images/help_menu_links.png
diff --git a/update-usr-sharing/_images/interactive-app-compression-quality.png b/update-usr-sharing/_images/interactive-app-compression-quality.png
diff --git a/update-usr-sharing/_images/interactive-app-shell-link.png b/update-usr-sharing/_images/interactive-app-shell-link.png
diff --git a/update-usr-sharing/_images/interactive-apps-menu.png b/update-usr-sharing/_images/interactive-apps-menu.png
diff --git a/update-usr-sharing/_images/linux_host_undetermined.png b/update-usr-sharing/_images/linux_host_undetermined.png
diff --git a/update-usr-sharing/_images/main-navigation-menu.png b/update-usr-sharing/_images/main-navigation-menu.png
diff --git a/update-usr-sharing/_images/ood_container_view.png b/update-usr-sharing/_images/ood_container_view.png
diff --git a/update-usr-sharing/_images/ood_overview.png b/update-usr-sharing/_images/ood_overview.png
diff --git a/update-usr-sharing/_images/ood_system_view.png b/update-usr-sharing/_images/ood_system_view.png
diff --git a/update-usr-sharing/_images/pinned_apps.png b/update-usr-sharing/_images/pinned_apps.png
diff --git a/update-usr-sharing/_images/plantuml-6a8fdab5b21c9c0c998d0a21b362a10878872ac3.png b/update-usr-sharing/_images/plantuml-6a8fdab5b21c9c0c998d0a21b362a10878872ac3.png
diff --git a/update-usr-sharing/_images/plantuml-be1e1017662db91033e2642c95916bc1e948d557.png b/update-usr-sharing/_images/plantuml-be1e1017662db91033e2642c95916bc1e948d557.png
diff --git a/update-usr-sharing/_images/support_ticket_custom_form.png b/update-usr-sharing/_images/support_ticket_custom_form.png
diff --git a/update-usr-sharing/_images/support_ticket_form.png b/update-usr-sharing/_images/support_ticket_form.png
diff --git a/update-usr-sharing/_images/support_ticket_menu.png b/update-usr-sharing/_images/support_ticket_menu.png
diff --git a/update-usr-sharing/_sources/architecture.rst.txt b/update-usr-sharing/_sources/architecture.rst.txt
@@ -0,0 +1,115 @@
+.. _architecture:
+
+Architecture
+============
+
+Below are some diagrams of OnDemand's architecture:
+
+#. 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
+#. Request flow diagram is a sequence diagram built using plantuml.
+
+Overview
+--------
+
+
+.. figure:: /architecture/ood_overview.png
+
+#. Apache is the server front end, running as the Apache user, and accepting all requests from users and serves four primary functions:
+
+   #. Authenticates user.
+   #. Starts Per-User NGINX processes (PUNs).
+   #. Reverse proxies each user to her PUN via Unix domain sockets.
+   #. Reverse proxies to interactive apps running on compute nodes (RStudio, Jupyter, VNC desktop) via TCP sockets.
+
+#. The Per-User NGINX serves web apps in Ruby and NodeJS and is how users submit jobs and start interactive apps.
+
+
+System context
+-----------------------
+
+Users use OnDemand to interact with their HPC resources through a web browser.
+
+.. figure:: /architecture/ood_system_view.png
+
+All the gray components are specific to a given site and outside the OnDemand
+system.
+
+Container context
+-----------------------
+
+.. tip::
+
+   In the C4 nomenclature, 'containers' are one level below the system context. This is
+   not to be confused with Linux containers via cgroups and namespaces (i.e. Docker or
+   Singularity or `OCI containers <https://www.opencontainers.org/>`_).
+
+The Front-end proxy is the only component that is shared with all clients.
+The Front-end proxy will create Per User Nginx (PUN) processes (light blue boxes labeled "Per User Instance").
+
+.. figure:: /architecture/ood_container_view.png
+
+* Everything contained in the dotted line is a part of the OnDemand system (see blue box in System context diagram).
+* Everything outside of it in gray is site specific components.
+* The "Per User Instance" light blue boxes are replicated for every user accessing the system.
+
+Request Flow
+-------------
+
+This is the request flow through the OnDemand system. A user initiates a
+request through a browser and this illustrates how that request propagates
+through the system to a particular application (including the dashboard).
+
+.. uml:: architecture/request-flow.uml
+
+Other Request Flow Diagrams
+----------------------------
+
+================
+Dashboard Access
+================
+
+.. figure:: /app-flow-diagrams/flow_access_dashboard.png
+
+=============
+Passenger App
+=============
+
+.. figure:: /app-flow-diagrams/flow_access_passenger_app.png
+
+================
+User App Sharing
+================
+
+.. figure:: /app-flow-diagrams/flow_access_usr_app_via_app_sharing.png
+
+==============
+Authentication
+==============
+
+.. figure:: /app-flow-diagrams/flow_authentication.png 
+
+==================
+Linux Host Adapter
+==================
+
+.. figure:: /app-flow-diagrams/flow_linux_host_adapter.png
+
+===========
+Rstudio Job
+===========
+
+.. figure:: /app-flow-diagrams/flow_rstudio_job.png
+
+=============
+Shell Session
+=============
+
+.. figure:: /app-flow-diagrams/flow_start_shell_session.png
+
+===============
+VNC Desktop Job
+===============
+
+.. figure:: /app-flow-diagrams/flow_vnc_desktop_job.png
diff --git a/update-usr-sharing/_sources/authentication.rst.txt b/update-usr-sharing/_sources/authentication.rst.txt
@@ -0,0 +1,44 @@
+.. _authentication:
+
+Authentication
+==============
+
+Open OnDemand supports most authentication modules that work with Apache HTTP
+Server version 2.4. The following :ref:`authentication-overview` section
+provides an introduction to setting up these generic authentication modules
+with an Open OnDemand installation. Tutorials will also be provided with the
+focus on setting up some of the more common authentication modules (e.g.,
+OpenID Connect with KeyCloak).
+
+After installing Open OnDemand you **must** add authentiction of some kind
+to generate the correct Apache configuration.  When no authentiction is
+supplied Apache will only serve a static page that directs you here.
+
+No Open OnDemand functionality is available without authentiction.
+
+.. note::
+
+   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.
+
+
+.. tip::
+
+    :ref:`Dex <authentication-dex>` is a very good starting option if you can connect
+    to LDAP or Active Directory and not an institutional Single Sign-On service.
+
+.. toctree::
+   :maxdepth: 2
+
+   authentication/overview
+   authentication/oidc
+   authentication/dex
+   authentication/shibboleth
+   authentication/cas
+   authentication/tutorial-oidc-keycloak-rhel7
+   authentication/duo-2fa-with-keycloak
+   authentication/adfs-with-auth-mellon
+   authentication/nsf-access
+   authentication/insecure
diff --git a/update-usr-sharing/_sources/authentication/adfs-with-auth-mellon.rst.txt b/update-usr-sharing/_sources/authentication/adfs-with-auth-mellon.rst.txt
@@ -0,0 +1,113 @@
+.. _authentication-adfs-with-auth-mellon:
+
+SAML Authentication with Active Directory Federated Services (ADFS) and mod_auth_mellon
+========================================================================================
+
+The following details how to use ADFS infrastructure via SAML authentication to authenticate to an OpenOnDemand deployment. 
+
+Prepare the Host
+--------------------------------------------------
+Before beginning, retrieve the following information from the ADFS administrator:
+
+#. The SAML 2.0 service URL (e.g., https://adfs.organization.com/ADFS/ls)
+#. The IdP metadata URL (e.g., https://adfs.organization.com/ADFS/metadata.xml)
+#. Ensure SSL is properly configured and any organizational certificate authorities are properly integrated into the host's trust store, see :ref:`add-ssl`
+
+Install mod_auth_mellon
+--------------------------------------------------
+
+#. Ensure Software Collections is enabled on the system
+#. Install the mod_auth_mellon module:
+
+.. tabs::
+
+  .. tab:: EL7
+
+    .. code-block:: shell
+
+      yum install httpd24-mod_auth_mellon httpd24-mod_ssl
+
+  .. tab:: EL8+
+
+    .. code-block:: shell
+
+      yum install mod_auth_mellon mod_ssl
+
+  .. tab:: Ubuntu
+
+    .. code-block:: shell
+
+      apt install libapache2-mod-auth-mellon
+
+Configure mod_auth_mellon
+--------------------------------------------------
+
+Note that this configuration assumes that SAML has been configured such that the returned NameID directly maps to a Unix user on the OOD host. For more information, see https://jdennis.fedorapeople.org/doc/mellon-user-guide/mellon_user_guide.html
+
+#. Download the IDP metadata file
+
+   .. code-block:: shell
+
+      cd /etc/httpd/mellon/
+      wget https://adfs.organization.com/ADFS/metadata.xml -O idpmetadata.xml
+
+#. Generate the mellon metadata
+
+   .. code-block:: shell
+
+      export mellon_endpoint="https://$(hostname)/mellon"
+      /usr/libexec/mod_auth_mellon/mellon_create_metadata.sh "${mellon_endpoint}/metadata" "${mellon_endpoint}"
+      mv *.cert ./mellon.cert
+      mv *.key ./mellon.key
+      mv *.xml ./mellon_metadata.xml
+
+#. Create a mellon configuration file
+
+   .. code-block:: shell
+
+      vi /etc/httpd/conf.d/00-mellon.conf
+
+#. Add the following to the ``00-mellon.conf`` file
+
+   .. code-block:: xml
+
+      <Location />
+        MellonSPPrivateKeyFile /etc/httpd/mellon/mellon.key
+        MellonSPCertFile /etc/httpd/mellon/mellon.cert
+        MellonSPMetadataFile /etc/httpd/mellon/mellon_metadata.xml
+        MellonIdPMetadataFile /etc/httpd/mellon/idpmetadata.xml
+
+        MellonEndpointPath /mellon
+        MellonEnable "auth"
+      </Location>
+
+#. Convert the key and cert files into pfx format
+
+   .. code-block:: shell
+
+      openssl pkcs12 -export -inkey /etc/httpd/mellon/mellon.key -in /etc/httpd/mellon/mellon.cert -out /etc/httpd/mellon/mellon.pfx
+
+#. Provide the ``mellon.pfx`` and ``mellon_metadata.xml`` files to your ADFS administrator. The files can then be imported into the ADFS system. 
+
+Configure OOD
+--------------------------------------------------
+
+#. Edit the ``ood_portal.yml`` file to include the following:
+
+   .. code-block:: yaml
+
+      # /etc/ood/config/ood_portal.yml
+      ---
+      # ...
+      # Your other custom configuration options...
+      # ...
+
+      auth:
+        - 'AuthType Mellon'
+        - 'Require valid-user'
+
+#. Restart the HTTPD
+
+   .. code-block:: shell
+
+      systemctl restart httpd
diff --git a/update-usr-sharing/_sources/authentication/cas.rst.txt b/update-usr-sharing/_sources/authentication/cas.rst.txt
@@ -0,0 +1,13 @@
+.. _authentication-cas:
+
+CAS
+---
+
+Several HPC centers running OnDemand have successfully configured authentication using Central Authentication Service (CAS).
+
+See `this Discourse <https://discourse.osc.edu/t/implementing-authentication-via-cas/34>`__ topic regarding several different examples configuring CAS authentication with OnDemand.
+
+Related links:
+
+- `mod_auth_cas <https://github.com/apereo/mod_auth_cas>`__
+- `CAS project website <https://www.apereo.org/projects/cas>`__