From 02eb9b48108f732fed118040e08fde5ca4710b3b Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Fri, 28 Jul 2023 11:27:53 +0100 Subject: [PATCH 01/17] event handlers: improve docs --- src/glossary.rst | 7 +-- src/installation.rst | 3 +- .../task-implementation/job-scripts.rst | 3 +- src/user-guide/writing-workflows/runtime.rst | 61 +++++++++++++------ .../writing-workflows/scheduler.rst | 23 ++++--- 5 files changed, 64 insertions(+), 33 deletions(-) diff --git a/src/glossary.rst b/src/glossary.rst index 4affe15b47..6daa019174 100644 --- a/src/glossary.rst +++ b/src/glossary.rst @@ -1654,8 +1654,6 @@ Glossary WARNING messages from a task :term:`job`. - .. TODO cylc-flow cfgspec/workflow.py references "event handlers" plural - handler event handler event handlers @@ -1671,9 +1669,8 @@ Glossary .. seealso:: - - :cylc:conf:`task events <[runtime][][events]>` - - :cylc:conf:`workflow events <[scheduler][events]>` - - :ref:`Cylc User Guide ` + - :ref:`user_guide.scheduler.workflow_event_handling` + - :ref:`user_guide.runtime.task_event_handling` runahead limit diff --git a/src/installation.rst b/src/installation.rst index 3107d94f21..c50549c5ee 100644 --- a/src/installation.rst +++ b/src/installation.rst @@ -250,6 +250,7 @@ To do so create a symbolic link to the wrapper, for each of these commands: ln -s cylc rosie ln -s cylc isodatetime + Configuration ------------- @@ -259,7 +260,7 @@ However, many things may need to be configured, e.g: * :ref:`AdminGuide.PlatformConfigs` (jobs hosts, runners, etc) * :ref:`Scheduler Hosts` -* :ref:`Default Event Handlers` +* :ref:`Default Event Handlers`. Cylc Flow ^^^^^^^^^ diff --git a/src/user-guide/task-implementation/job-scripts.rst b/src/user-guide/task-implementation/job-scripts.rst index 4e1aebe8a6..a737c16640 100644 --- a/src/user-guide/task-implementation/job-scripts.rst +++ b/src/user-guide/task-implementation/job-scripts.rst @@ -127,7 +127,8 @@ execution has started, succeeded, or failed. Custom messages can also be sent by the same mechanism, with various severity levels. These can be used to trigger other tasks off specific task outputs (see :ref:`MessageTriggers`), or to trigger execution of event handlers by the scheduler (see -:ref:`EventHandling`), or just to write information to the scheduler log. +:ref:`user_guide.runtime.task_event_handling`) +or just to write information to the scheduler log. .. cylc-scope:: global.cylc[platforms][] diff --git a/src/user-guide/writing-workflows/runtime.rst b/src/user-guide/writing-workflows/runtime.rst index a23c94b642..d7f4bbb79f 100644 --- a/src/user-guide/writing-workflows/runtime.rst +++ b/src/user-guide/writing-workflows/runtime.rst @@ -567,22 +567,25 @@ task ``whizz`` downstream. The scheduler will then stall with script = "sleep 10" -.. _EventHandling: +.. _user_guide.runtime.task_event_handling: -Event Handling --------------- +Task Event Handling +------------------- -.. seealso:: +Task event handlers allow configured commands to run when task events occur. - * Task events :cylc:conf:`[runtime][][events]` - * Workflow events :cylc:conf:`[scheduler][events]` +.. note:: -.. cylc-scope:: flow.cylc[runtime][] + Cylc supports workflow events e.g. ``startup`` and ``shutdown`` + and task events e.g. ``submitted`` and ``failed``. -Custom *event handler* scripts can be called when certain workflow and task -events occur. Event handlers can be used to send a message, raise an alarm, or -whatever you like. They can even call ``cylc`` commands to intervene in the -workflow. + See also :ref:`user_guide.scheduler.workflow_event_handling`. + +Event handlers can be used to send a message, raise an alarm, or whatever you +like. They can even call ``cylc`` commands to intervene in the workflow. + +Task event handlers are configured by +:cylc:conf:`flow.cylc[runtime][][events]`. .. note:: @@ -596,7 +599,7 @@ They should return quickly to avoid tying up the scheduler process pool - see :ref:`Managing External Command Execution`. -.. cylc-scope:: +.. _user_guide.runtime.task_event_handling.event_specific_handlers: Event-Specific Handlers ^^^^^^^^^^^^^^^^^^^^^^^ @@ -634,18 +637,40 @@ can be: Values should be a list of commands, command lines, or command line templates (see below) to call if the specified event is triggered. + +.. _user_guide.runtime.task_event_handling.general_event_handlers: + General Event Handlers ^^^^^^^^^^^^^^^^^^^^^^ -Alternatively you can configure ``handler events`` and ``handlers`` -under :cylc:conf:`[runtime][][events]`, where the former is a list -of events (as above), and the latter a list of commands, command lines, lines -or command line templates (see below) to call if any of the specified events -are triggered. +.. cylc-scope:: flow.cylc[runtime][][events] + +Alternatively you can configure a list of generic event :cylc:conf:`handlers` to be run +for configured :cylc:conf:`handler events`. + +:cylc:conf:`handler events` + A list of events which may include any of the above + events (e.g. ``submission failed`` or ``warning``) or + any of a task's :term:`custom outputs `. +:cylc:conf:`handlers` + A list of commands to be run for these events. + Information about the event can be provided using + :ref:`user_guide.runtime.event_handlers.task_event_handling.template_variables`. + +Example: + +.. code-block:: cylc + + handlers = """ + my-handler %(event)s %(workflow)s, + echo %(workflow)s-%(event)s >> my-log-file + """ + handler events = submission failed, failed, warning, my-custom-output .. cylc-scope:: -.. _task_event_template_variables: + +.. _user_guide.runtime.event_handlers.task_event_handling.template_variables: Task Event Template Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/src/user-guide/writing-workflows/scheduler.rst b/src/user-guide/writing-workflows/scheduler.rst index 7b9d704c40..bf6e2f31c2 100644 --- a/src/user-guide/writing-workflows/scheduler.rst +++ b/src/user-guide/writing-workflows/scheduler.rst @@ -8,20 +8,27 @@ Many of these configurations can also be defined at the site or user level in the :cylc:conf:`global.cylc[scheduler]` section where it applies to all workflows. -.. _EventHandlers: -Event handlers --------------- +.. _user_guide.scheduler.workflow_event_handling: + +Workflow Event Handling +----------------------- + +Workflow event handlers allow configured commands to run when workflow events +occur. .. note:: - Workflow event handlers are configured by: + Cylc supports workflow events e.g. ``startup`` and ``shutdown`` + and task events e.g. ``submitted`` and ``failed``. + + See also :ref:`user_guide.runtime.task_event_handling`. + +Workflow event handlers are configured by: - * :cylc:conf:`flow.cylc[scheduler][events]` - * :cylc:conf:`global.cylc[scheduler][events]` +* :cylc:conf:`flow.cylc[scheduler][events]` (per workflow) +* :cylc:conf:`global.cylc[scheduler][events]` (user/site defaults) -Workflow event handlers allow configurable actions to be performed when -workflow events occur. Workflow Events ^^^^^^^^^^^^^^^ From ef54dee28076a825fb3b4fca03ad9bcf4dabc5e7 Mon Sep 17 00:00:00 2001 From: Tim Pillinger <26465611+wxtim@users.noreply.github.com> Date: Thu, 31 Aug 2023 16:24:03 +0100 Subject: [PATCH 02/17] keep sphinx version <7 --- setup.cfg | 2 +- src/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/setup.cfg b/setup.cfg index 5e4c82900b..f32e4121db 100644 --- a/setup.cfg +++ b/setup.cfg @@ -51,7 +51,7 @@ install_requires = eralchemy==1.2.* hieroglyph>=2.1.0 setuptools>=50 - sphinx>=4.4 + sphinx>=4.4,<7 sphinx_rtd_theme>=1.0.0 sphinxcontrib-svg2pdfconverter sphinxcontrib-spelling diff --git a/src/conf.py b/src/conf.py index 04c9bc6670..30d63db376 100644 --- a/src/conf.py +++ b/src/conf.py @@ -112,7 +112,7 @@ # Mapping to other Sphinx projects we want to import references from. intersphinx_mapping = { 'rose': ( - 'http://metomi.github.io/rose/2.0.0/html', None + 'http://metomi.github.io/rose/2.1.0/html', None ), 'python': ( 'https://docs.python.org/3/', None From 07580bfaaddcbf428b0cfe889de2354d5e968c9e Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Fri, 14 Jul 2023 16:10:21 +0100 Subject: [PATCH 03/17] cylc hub: document multi-user config post jupyter server v2 upgrade * Auto-spawning of other user's servers can now be configured. * Jupyter Server security policy must be defined if Jupyter Lab or any other server extension is included in the deployment. * Simplify some sections and expand on the new configurations. --- src/7-to-8/major-changes/ui.rst | 6 +- src/conf.py | 5 + src/reference/architecture/ui-server.rst | 31 +- src/reference/changes.rst | 30 ++ .../sharing-access-to-workflows.rst | 433 +++++++++++------- 5 files changed, 328 insertions(+), 177 deletions(-) diff --git a/src/7-to-8/major-changes/ui.rst b/src/7-to-8/major-changes/ui.rst index 616d1bc192..9542ee5b43 100644 --- a/src/7-to-8/major-changes/ui.rst +++ b/src/7-to-8/major-changes/ui.rst @@ -45,7 +45,11 @@ and as a multi user hub, ``cylc hub``. Both are dependent on `Cylc UI Server`_ i Launching the UI via the hub will require authentication. The default Authenticator uses PAM to authenticate system users with their username and password. -Going via the hub unlocks the :ref:`Authorization` feature. + +Going via the hub unlocks the ability to grant other users the permission +to view and interact with workflows running under your account. +Site administrators will need to configure this, for more information +see :ref:`cylc.uiserver.multi-user`. .. figure:: ../../img/hub.png :figwidth: 80% diff --git a/src/conf.py b/src/conf.py index 30d63db376..fd6e0cef41 100644 --- a/src/conf.py +++ b/src/conf.py @@ -110,6 +110,8 @@ autosummary_imported_members = False # Mapping to other Sphinx projects we want to import references from. +# NOTE: To work search available references, use: +# $ python -m sphinx.ext.intersphinx /objects.inv | less intersphinx_mapping = { 'rose': ( 'http://metomi.github.io/rose/2.1.0/html', None @@ -119,6 +121,9 @@ ), 'jupyter_server': ( 'https://jupyter-server.readthedocs.io/en/latest/', None + ), + 'jupyter_hub': ( + 'https://jupyterhub.readthedocs.io/en/stable/', None ) } diff --git a/src/reference/architecture/ui-server.rst b/src/reference/architecture/ui-server.rst index 4ebe6ca22f..4a2e477b0c 100644 --- a/src/reference/architecture/ui-server.rst +++ b/src/reference/architecture/ui-server.rst @@ -92,8 +92,14 @@ spawns UI Servers on behalf of users and provides each with a fixed URL Users can access each other's UI Servers providing they have been granted permission. -Authorization is performed by Cylc within the `Cylc UI Server`_, see -:ref:`cylc authorization`. +*Authentication* is provided by either `Jupyter Server`_ or `Jupyter Hub`_. + +*Authorization* in the `Cylc UI Server`_ is provided by Cylc. In +multi-user mode this allows users to connect to each others UI Servers for +monitoring or control purposes. + +For more information on security and configuration see +:ref:`cylc.uiserver.multi-user`. .. _Jupyter Hub technical overview: https://jupyterhub.readthedocs.io/en/stable/reference/technical-overview.html @@ -109,24 +115,3 @@ For information on the architecture of `Jupyter Hub`_ and the .. image:: img/gui-arch-multi-user.svg :width: 100% - - -.. _cylc authorization: - -Authorization -------------- - -*Authentication* is provided by either `Jupyter Server`_ or `Jupyter Hub`_. - -*Authorization* in the `Cylc UI Server`_ is provided by Cylc. In -multi-user mode this allows users to connect to each others UI Servers for -monitoring or control purposes. - -See also :ref:`Authorization`. - -.. note:: - - This authorization only applies to the ``/cylc`` endpoints managed by the - Cylc extension. Other `Jupyter Server`_ extensions such as `Jupyter Lab`_ - do not share this authorization and will not be accessible to other users - (unless they can be configured to allow this). diff --git a/src/reference/changes.rst b/src/reference/changes.rst index 3c1fcb618c..8afb98b79b 100644 --- a/src/reference/changes.rst +++ b/src/reference/changes.rst @@ -20,6 +20,36 @@ For more detail see the component changelogs: * `metomi-rose-changelog`_ * `metomi-isodatetime-changelog`_ + +---------- + +Cylc 8.3.0 +---------- + +.. admonition:: Cylc Components + :class: hint + + TODO + +.. + Uncomment this before 8.3.0 release + + :cylc-flow: `8.2 `__ + :cylc-uiserver: `1.3 `__ + :cylc-rose: `1.3 `__ + + +Upgrade To The Latest Jupyter Releases +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Cylc UI Server has been updated to work with the latest releases of +`Jupyter Server`_ and `Jupyter Hub`_. + +If you are utilising Cylc's multi-user functionality then your configuration +will require some changes to work with these releases. + +See :ref:`cylc.uiserver.multi-user` for more details + ---------- Cylc 8.2.0 diff --git a/src/user-guide/sharing-access-to-workflows.rst b/src/user-guide/sharing-access-to-workflows.rst index 4e74e5f28b..97763534eb 100644 --- a/src/user-guide/sharing-access-to-workflows.rst +++ b/src/user-guide/sharing-access-to-workflows.rst @@ -1,148 +1,266 @@ -.. _Authorization: +.. _cylc.uiserver.multi-user: Authorizing Others to Access Your Workflows =========================================== -The Cylc UI Server supports multi user access. You can grant control of your -workflows to other users, by adding or removing privileges on a Cylc operation -basis. This requires site level configuration, with individual users being able -to set authorization settings, within the bounds set by the site. +For multi-user setups, the Cylc web GUI can be deployed as part of a +`Jupyter Hub`_ setup where a central service spawns servers on behalf of users. -Sites can set default access rights for users, for more information, see -:ref:`site_configuration`. +The Cylc UI Server can be configured to allow specified users to monitor and +optionally control workflows running under other user accounts. -Note, if this feature is not configured, the default is no multi user access, -only the workflow owner will be able to interact with it. +This has many use cases including: -If you grant access to another user, this access will apply to all of your -workflows. +* Collaborative research setups where multiple users need to access the same + workflow. +* Production systems where different levels of support may have different + levels of access. +* Support where administrators may require access to users workflows. -Granting Access ---------------- +A multi-user Cylc setup consists of three components: -There are three methods of identifying a user to grant access to: +1. `Jupyter Hub`_ +2. `Jupyter Server`_ +3. `Cylc UI Server`_ -- ``*`` character, to indicate any authenticated user, -- using the ``group:`` prefix to indicate a system group. E.g. - ``group:groupname``, will assign permissions to all members of the system - group named ``groupname``. For more information, see :ref:`group_support`. -- ``username`` to indicate a specific user. +And may additionally include other Jupyter Server extensions such as +`Jupyter Lab`_ to provide a full interactive virtual workstation in the +browser. +In order to allow access to other users servers, to permit the monitoring and +optionally control of other users workflows, each of these three components +must be configured: -Using glob (``*``) to pattern match usernames and group names is not currently -supported. +1. `Jupyter Hub`_ must be configured to allow connections to other users servers. +2. The `Jupyter Server`_ authorisation policy must be set. +3. Cylc must be configured with user permissions. -Permissions are additive. If the user appears elsewhere in configuration, for -example as a member of a system group, the permission level is taken as the -greatest possible. +This configuration can all be performed in the same Jupyter / Cylc UI Server +configuration file see :ref:`UI_Server_config` for more details. -However, negations take precedence. +.. rubric:: Quick Example: -Note, defaults in site config only apply if a user does not appear in the -``c.CylcUIServer.user_authorization``. +.. code-block:: python -Methods of Assigning Permissions --------------------------------- -Assigning permissions can be done in two ways: + # /etc/cylc/uiserver/jupyter_config.py - - using individual Cylc operations, e.g. ``play``, ``pause`` - - using predefined access groups: ``READ``, ``CONTROL``, ``ALL``. + # 1. Jupyter Hub + # Allow all authenticated users to access, start and stop + # eachothers servers + c.JupyterHub.load_roles = [ + { + "name": "user", + "scopes": ["self", "access:servers", "servers"], + } + ] -Using both methods is supported, e.g ["READ", "stop", "pause"] -Individual Operations -^^^^^^^^^^^^^^^^^^^^^ -To assign users permissions, you can list the operations you wish to grant + # 2. Jupyter Server + # Set a safe authorisation policy for multi-user setups + # Note: This is ONLY necessary if you are deploying the Cylc UI Server + # using commands other than `cylc hub` and `cylc hubapp`, + # otherwise, it is the default. + from cylc.uiserver.authorise import CylcAuthorizer + c.ServerApp.authorizer_class = CylcAuthorizer -.. code-block:: python + # 3. Cylc + # Delegate permissions to users c.CylcUIServer.user_authorization = { - "user1": ["read", "pause", "play"] + # proivide all authenticated users with read-only access to eachothers + # servers + "*": ["READ"], } -Provided you have permission (via the site config file) to grant ``user1`` -these permissions, this will result in ``user1`` being able to see your -workflows (from the ``read`` operation), and ``pause`` and ``play`` your workflows. +The rest of this document takes you through each of these configurations, some +of the key options and how they relate to their respective systems. + + +.. _jupyterhub.authorization: +Jupyter Hub Authorisation +------------------------- -To remove permissions prepend the operation with a ``!``. -For example, +By default, `Jupyter Hub`_ only allows users to access their own servers. + +In order to allow access to other users servers, two scopes must be configured: + +``access:servers`` + Permits us to connect to another users server. +``servers`` + Permits us to start another users server. + +This is done using the +:py:attr:`c.JupyterHub.load_roles ` +configuration. +For more information see the +:ref:`JupyterHub scopes reference `. + +Example: .. code-block:: python + # /etc/cylc/uiserver/jupyter_config.py + + c.JupyterHub.load_roles = [ + { + # allow all authenticated users to access, start and stop + # eachother's servers + "name": "user", + "scopes": ["self", "access:servers", "servers"], + } + ] + + +.. _jupyterserver.authorization: + +Jupyter Server Authorisation +---------------------------- + +.. tip:: + + You can skip this section if you are starting Jupyter Hub using ``cylc hub`` + command and have not overridden the + :py:attr:`c.JupyterHub.spawner_class ` + configuration (so are spawning the ``cylc hubapp`` command). + +.. autoclass:: cylc.uiserver.authorise.CylcAuthorizer + + +.. _cylc.uiserver.user_authorization: + +Cylc User Authorisation +----------------------- + +Cylc Authorisation is configurable on a per-user and per-command basis but +not on a per-workflow basis. + +By default users can only see and interact with their own workflows. + +Sites can restrict the permissions which users are allowed to delegate to each +other and can configure default permissions (see :ref:`site_configuration`). + +Authorization is configured by these two configurations: + +* :py:attr:`c.CylcUIServer.user_authorization + ` (user configuration) +* :py:attr:`c.CylcUIServer.site_authorization + ` (site configuration) + +.. rubric:: Example: + +.. code-block:: python + + # ~/.cylc/uiserver/jupyter_config.py + c.CylcUIServer.user_authorization = { - "group:groupA": ["read", "play", "stop"], - "user2": ["!stop"] + # : [, ...], + + # allow "user1" to monitor my workflows + "user1": ["READ"], + + # allow "user2" to monitor and trigger tasks in my workflows + "user2": ["READ", "Trigger"], } -Providing your site configuration permits you to grant this access, -this configuration, for ``user2`` (who is a member of system group ``groupA``), -would result in them having ``read`` and ``play`` access. Permission to stop your -workflows has been removed so this action will be forbidden. -Access Groups -^^^^^^^^^^^^^ -For convenience, cylc operations available in the UI have been bundled into -access groups. These should be capitalized to distinguish from cylc operations. - -We currently support ``READ``, ``CONTROL`` and ``ALL`` and to remove permissions -to operations in these groups, use ``!READ``, ``!CONTROL``, ``!ALL``. - - -.. csv-table:: Access Group Mappings - :header: "Operation", "READ", "CONTROL", "ALL" - - "Broadcast", , , "X" - "Ext-trigger",, "X", "X" - "Hold",, "X", "X" - "Kill",, "X", "X" - "Message",, "X", "X" - "Pause",, "X", "X" - "Play",, "X", "X" - "Poll",, "X", "X" - "Read","X", , "X" - "Release",, "X", "X" - "ReleaseHoldPoint",, "X", "X" - "Reload",, "X", "X" - "Remove",, "X", "X" - "Resume",, "X", "X" - "SetGraphWindowExtent",, "X", "X" - "SetHoldPoint",, "X", "X" - "SetOutputs",, "X", "X" - "SetVerbosity",, "X", "X" - "Stop",, "X", "X" - "Trigger",, "X", "X" +Users +^^^^^ +There are three methods of identifying a user to grant access to: + +```` + Configures permissions for a singe user. +``group:`` + Configures a user group. For more information, see :ref:`group_support`. +``*`` + Configures permissions for any authenticated user (see + :ref:`Jupyter Hub authenticators reference ` + for details). .. note:: - The ``READ`` access group is shorthand for all read-only operations. At present, - this is solely the ``read`` operation, which grants access to GraphQL queries and - subscriptions, and enables users to see the workflows in the UI. In future - the ``READ`` access group may be extended. + Using glob patterns (e.g. ``*``) to pattern match user and group names is + not currently supported. + + +Permissions +^^^^^^^^^^^ + +.. TODO: autogenerate this permission list + https://github.com/cylc/cylc-uiserver/issues/466 + +Permissions can be granted for each Cylc command individually, for convenience +commands are arranged into groups to avoid having to list them individually: + +``READ`` (i.e. read-only access) + A user with read permissions may view workflows, monitor tasks states and + open log files, but they cannot interact with the workflows. + + * ``Read`` +``CONTROL`` (e.g. start & stop workflows) + A user with control permissions may issue commands to interact with workflows + and can start/stop workflows but cannot redefine the workflow configuration + itself (without direct filesystem access). + + * ``Clean`` + * ``Ext-trigger`` + * ``Hold`` + * ``Kill`` + * ``Message`` + * ``Pause`` + * ``Play`` + * ``Poll`` + * ``Release`` + * ``ReleaseHoldPoint`` + * ``Reload`` + * ``Remove`` + * ``Resume`` + * ``SetGraphWindowExtent`` + * ``SetHoldPoint`` + * ``SetOutputs`` + * ``SetVerbosity`` + * ``Stop`` + * ``Trigger`` +``ALL`` (i.e. full control) + A user with all permissions may alter task configuration so may inject + arbitrary code into the workflow. + + * ``Broadcast`` .. note:: - Granting CONTROL access does not automatically grant READ access. + With the exception of ``Read`` all of the above permissions map onto the + Cylc GraphQL mutations which themselves map onto the command line. + + E.G. the ``Play`` permission maps onto ``mutation play`` in the GraphQL + schema and ``cylc play`` on the command line. + + To find out more about a command, see the GraphQL or CLI documentation. + +By default, users have ``ALL`` permissions for their own workflows and no +permissions to other users workflows. -.. _user_configuration: +Permissions are additive, so delegating both ``READ`` and ``CONTROL`` would +provide all permission in both groups. -User Authorization Configuration --------------------------------- -``c.CylcUIServer.user_authorization``, which is loaded from -``~/.cylc/uiserver/jupyter_config.py``, contains your preferences for granting access -to other users. This configuration should be entered as a Python -dictionary. If a user does not appear in your user config, the default site -access will apply. -You are only permitted to grant access, within the bounds set at site level. +The ``!`` character can be used to subtract permissions, e.g. delegating +``CONTROL`` and ``!Stop`` would provide all control permissions except stop. + +.. note:: + + Granting acess to a group does not automatically grant access to lower + groups e.g. granting ``CONTROL`` access does not automatically grant + ``READ`` access. -Example User Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^ -An example user configuration: +Examples +^^^^^^^^ .. code-block:: python + # ~/.cylc/uiserver/jupyter_config.py + c.CylcUIServer.user_authorization = { "*": ["READ"], "group:groupA": ["CONTROL"], @@ -154,62 +272,97 @@ In this scenario: - ``"*"`` represents any authenticated user. They have permission to view all workflows, and view them on the GUI. - - ``"group:groupA"`` applies ``CONTROL`` permissions to any member of system ``groupA``. Note that, since permissions are additive, these users will gain ``READ`` access from the ``"*":["READ"]`` assignment. - - ``"user1"`` will have permission to view workflows, ``pause`` but not ``play`` workflows, even if ``user1`` is a member of the system ``groupA``. This is due to negations taking precedence over additions. - - ``"user2"`` is not permitted to view workflows, or perform any operations. + .. _site_configuration: -Site Authorization Configuration --------------------------------- -The site_authorization configuration allows sites to configure sensible defaults -and limits for the permissions users can delegate. +Cylc Site Configuration +----------------------- + +The :py:attr:`c.CylcUIServer.site authorization +` configuration allows sites +to configure sensible defaults and limits for the permissions users can +delegate. + +It takes the form: + +.. code-block:: python + + { + "": { + "": { + "default": [], + "limit", [] + } + } + } + +Where ```` is the username of the account that is running a server and +```` is the username of an account trying to connect to it. + +Sites can set both limits and defaults for users: -Note that as the UI Server runs as the workflow owner, they have full control -over it and in theory may bypass these restrictions in a variety of ways. As an -extreme example, a workflow owner could pass their account credentials to -another person, and that cannot be prevented by technical means. However, a -workflow owner cannot unilaterally gain access to any other user's account or -workflows by configuring their own UI Server. +``limit`` + Determines the maximum access users can grant to their workflows. +``default`` + Sets a default access level, which applies if the user does not appear in + the user_authorization configuration (via explicit user name or group). -``c.CylcUIServer.site_authorization``, which is loaded from -``/etc/cylc/uiserver/jupyter_config.py``, or, alternatively, the environment variable -``CYLC_SITE_CONF_PATH``, contains these site default and limit settings for -users. This configuration should be entered as a Python dictionary. + Note, these defaults apply only if a user does not appear in + :py:attr:`c.CylcUIServer.user_authorization + `. +* If a limit is not set but a default is, then the limit is the default. +* If a default is not set but a limit is, then the default is no access. -Defaults and Limits -^^^^^^^^^^^^^^^^^^^ -Sites set both limits and defaults for users. +.. note:: + + As the UI Server runs as the workflow owner, the owner has full control over + it and in theory may bypass these restrictions in a variety of ways. As an + extreme example, a workflow owner could pass their account credentials to + another person. This cannot be prevented by technical means. However, a + workflow owner cannot unilaterally gain access to any other user's account + or workflows by configuring their own UI Server. -- ``limit`` determines the maximum access users can grant to their workflows. +.. note:: -- ``default`` sets a default access level, which applies if the user does - not appear in the user_authorization configuration (via explicit user name or group). + Changes to the Cylc authorization configuration will take effect when the + Cylc UI Server is restarted. -Missing Configurations in Site Authorization -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -For site configuration: -* if a limit is not set but a default is, then the limit is the default. -* if a default is not set but a limit is, then the default is no access. +.. _group_support: + +Group Support +^^^^^^^^^^^^^ + +Unix-like systems support user groups. Cylc authorization supports granting +access by membership of these system groups. You can indicate a system group +by using the ``group:`` indicator. + +System groups are found by +:py:mod:`get_groups` + +.. autofunction:: cylc.uiserver.authorise.get_groups Example Site Authorization Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Whilst most site configurations will be simpler than the example below, this example provides an indication of the combinations available. .. code-block:: python + # /etc/cylc/uiserver/jupyter_config.py + c.CylcUIServer.site_authorization = { "*": { # For all ui-server owners, "*": { # Any authenticated user @@ -253,31 +406,9 @@ example provides an indication of the combinations available. } -.. _group_support: - -Group Support -^^^^^^^^^^^^^ -Unix-like systems support grouping users. Cylc authorization supports granting -access by membership of these system groups. You can indicate a system group -by using the ``group:`` indicator. - -System groups are found by - :py:mod:`get_groups` - - .. autofunction:: cylc.uiserver.authorise.get_groups - - -Changing Access Rights -^^^^^^^^^^^^^^^^^^^^^^ -Changing authorization permissions in your ``jupyter_config.py`` will require the -UI Server to be restarted before any changes are applied. - Interacting with Others' Workflows ---------------------------------- -The authorization system in Cylc 8 is complete, although expect access to other -users' workflows via the UI to be further developed in future. - .. spelling:word-list:: userA @@ -294,18 +425,14 @@ have the correct permissions, you will see userB's workflows for interaction. Operations that are not authorized will appear greyed out on the UI. + Troubleshooting Authorization ----------------------------- If authorization is not performing as expected, check - you are permitted by the site configuration to give away access. - - you have provided ``read`` permissions, which enables the user to see your workflows. - - check the spelling in your configuration. The correct spelling is ``c.CylcUIServer.user_authorization`` - -- the server has been started by the user of the workflows you are trying to - access. Users currently can only spawn their own UI Servers. From 982152c039b7a77b98849069977fd8080bf31ea0 Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Tue, 15 Aug 2023 15:27:44 +0100 Subject: [PATCH 04/17] Update src/reference/changes.rst Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com> --- src/reference/changes.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/reference/changes.rst b/src/reference/changes.rst index 8afb98b79b..120410422d 100644 --- a/src/reference/changes.rst +++ b/src/reference/changes.rst @@ -34,9 +34,9 @@ Cylc 8.3.0 .. Uncomment this before 8.3.0 release - :cylc-flow: `8.2 `__ - :cylc-uiserver: `1.3 `__ - :cylc-rose: `1.3 `__ + :cylc-flow: `8.3 `__ + :cylc-uiserver: `1.4 `__ + :cylc-rose: `1.4 `__ Upgrade To The Latest Jupyter Releases From 0eb1d11cf4743a332c2fdbe7f206fa205cc6704d Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Tue, 15 Aug 2023 12:43:56 +0100 Subject: [PATCH 05/17] Apply suggestions from code review Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com> --- src/conf.py | 2 +- src/reference/architecture/ui-server.rst | 2 +- .../sharing-access-to-workflows.rst | 40 +++++++++---------- 3 files changed, 22 insertions(+), 22 deletions(-) diff --git a/src/conf.py b/src/conf.py index fd6e0cef41..53b4d7916f 100644 --- a/src/conf.py +++ b/src/conf.py @@ -110,7 +110,7 @@ autosummary_imported_members = False # Mapping to other Sphinx projects we want to import references from. -# NOTE: To work search available references, use: +# NOTE: To search available references, use: # $ python -m sphinx.ext.intersphinx /objects.inv | less intersphinx_mapping = { 'rose': ( diff --git a/src/reference/architecture/ui-server.rst b/src/reference/architecture/ui-server.rst index 4a2e477b0c..0af147b37d 100644 --- a/src/reference/architecture/ui-server.rst +++ b/src/reference/architecture/ui-server.rst @@ -95,7 +95,7 @@ permission. *Authentication* is provided by either `Jupyter Server`_ or `Jupyter Hub`_. *Authorization* in the `Cylc UI Server`_ is provided by Cylc. In -multi-user mode this allows users to connect to each others UI Servers for +multi-user mode this allows users to connect to each other's UI Servers for monitoring or control purposes. For more information on security and configuration see diff --git a/src/user-guide/sharing-access-to-workflows.rst b/src/user-guide/sharing-access-to-workflows.rst index 97763534eb..759b4ecc04 100644 --- a/src/user-guide/sharing-access-to-workflows.rst +++ b/src/user-guide/sharing-access-to-workflows.rst @@ -36,7 +36,7 @@ must be configured: 3. Cylc must be configured with user permissions. This configuration can all be performed in the same Jupyter / Cylc UI Server -configuration file see :ref:`UI_Server_config` for more details. +configuration file. See :ref:`UI_Server_config` for more details. .. rubric:: Quick Example: @@ -46,7 +46,7 @@ configuration file see :ref:`UI_Server_config` for more details. # 1. Jupyter Hub # Allow all authenticated users to access, start and stop - # eachothers servers + # each other's servers c.JupyterHub.load_roles = [ { "name": "user", @@ -67,7 +67,7 @@ configuration file see :ref:`UI_Server_config` for more details. # 3. Cylc # Delegate permissions to users c.CylcUIServer.user_authorization = { - # proivide all authenticated users with read-only access to eachothers + # provide all authenticated users with read-only access to each other's # servers "*": ["READ"], } @@ -83,12 +83,12 @@ Jupyter Hub Authorisation By default, `Jupyter Hub`_ only allows users to access their own servers. -In order to allow access to other users servers, two scopes must be configured: +In order to allow access to other users' servers, two scopes must be configured: ``access:servers`` - Permits us to connect to another users server. + Permits us to connect to another user's server. ``servers`` - Permits us to start another users server. + Permits us to start another user's server. This is done using the :py:attr:`c.JupyterHub.load_roles ` @@ -105,7 +105,7 @@ Example: c.JupyterHub.load_roles = [ { # allow all authenticated users to access, start and stop - # eachother's servers + # each other's servers "name": "user", "scopes": ["self", "access:servers", "servers"], } @@ -137,7 +137,7 @@ not on a per-workflow basis. By default users can only see and interact with their own workflows. -Sites can restrict the permissions which users are allowed to delegate to each +Sites can restrict the permissions that users are allowed to grant each other and can configure default permissions (see :ref:`site_configuration`). Authorization is configured by these two configurations: @@ -170,7 +170,7 @@ Users There are three methods of identifying a user to grant access to: ```` - Configures permissions for a singe user. + Configures permissions for a single user. ``group:`` Configures a user group. For more information, see :ref:`group_support`. ``*`` @@ -180,7 +180,7 @@ There are three methods of identifying a user to grant access to: .. note:: - Using glob patterns (e.g. ``*``) to pattern match user and group names is + Using glob patterns to match user and group names is not currently supported. @@ -190,7 +190,7 @@ Permissions .. TODO: autogenerate this permission list https://github.com/cylc/cylc-uiserver/issues/466 -Permissions can be granted for each Cylc command individually, for convenience +Permissions can be granted for each Cylc command individually. For convenience, commands are arranged into groups to avoid having to list them individually: ``READ`` (i.e. read-only access) @@ -238,11 +238,11 @@ commands are arranged into groups to avoid having to list them individually: To find out more about a command, see the GraphQL or CLI documentation. -By default, users have ``ALL`` permissions for their own workflows and no -permissions to other users workflows. +By default, users have full permissions (``READ``, ``CONTROL`` and ``ALL``) for their own workflows and no +permissions for other users' workflows. -Permissions are additive, so delegating both ``READ`` and ``CONTROL`` would -provide all permission in both groups. +Permissions are additive, so for example, granting ``READ`` and ``CONTROL`` +would provide all of the permissions from those two groups. The ``!`` character can be used to subtract permissions, e.g. delegating ``CONTROL`` and ``!Stop`` would provide all control permissions except stop. @@ -271,10 +271,10 @@ Examples In this scenario: - ``"*"`` represents any authenticated user. They have permission to view all - workflows, and view them on the GUI. + workflows on the GUI. - ``"group:groupA"`` applies ``CONTROL`` permissions to any member of system ``groupA``. - Note that, since permissions are additive, these users will gain ``READ`` access + Note that, since permissions are inherited, these users will gain ``READ`` access from the ``"*":["READ"]`` assignment. - ``"user1"`` will have permission to view workflows, ``pause`` but not ``play`` workflows, even if ``user1`` is a member of the system ``groupA``. This is due @@ -287,10 +287,10 @@ In this scenario: Cylc Site Configuration ----------------------- -The :py:attr:`c.CylcUIServer.site authorization +The :py:attr:`c.CylcUIServer.site_authorization ` configuration allows sites to configure sensible defaults and limits for the permissions users can -delegate. +grant. It takes the form: @@ -300,7 +300,7 @@ It takes the form: "": { "": { "default": [], - "limit", [] + "limit": [] } } } From f02c46d31280d9a768339e44887f4c92891451b4 Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Tue, 12 Sep 2023 13:49:06 +0100 Subject: [PATCH 06/17] fix task message validator --- src/user-guide/task-implementation/job-scripts.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/user-guide/task-implementation/job-scripts.rst b/src/user-guide/task-implementation/job-scripts.rst index a737c16640..a5ba61d8af 100644 --- a/src/user-guide/task-implementation/job-scripts.rst +++ b/src/user-guide/task-implementation/job-scripts.rst @@ -182,8 +182,7 @@ status message does not get through, the server will recover the correct task status by polling on job timeout (or earlier if regular polling is configured). -Task messages are validated by -:py:class:`cylc.flow.unicode_rules.TaskMessageValidator`. +Task messages are validated by: .. autoclass:: cylc.flow.unicode_rules.TaskMessageValidator :noindex: From 640b80d3df257b588f862178404ce5da5b6ec575 Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Tue, 12 Sep 2023 13:58:57 +0100 Subject: [PATCH 07/17] spolling ++ --- src/dictionaries/words | 2 ++ src/user-guide/sharing-access-to-workflows.rst | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/src/dictionaries/words b/src/dictionaries/words index d390f1c02c..13f17b63e5 100644 --- a/src/dictionaries/words +++ b/src/dictionaries/words @@ -5,6 +5,7 @@ arg args auth authenticator +authoriser backticks baz boolean @@ -185,6 +186,7 @@ timeouts timestep timezone timezones +uiserver unpaused unpausing untracked diff --git a/src/user-guide/sharing-access-to-workflows.rst b/src/user-guide/sharing-access-to-workflows.rst index 759b4ecc04..637d2e70c3 100644 --- a/src/user-guide/sharing-access-to-workflows.rst +++ b/src/user-guide/sharing-access-to-workflows.rst @@ -249,7 +249,7 @@ The ``!`` character can be used to subtract permissions, e.g. delegating .. note:: - Granting acess to a group does not automatically grant access to lower + Granting access to a group does not automatically grant access to lower groups e.g. granting ``CONTROL`` access does not automatically grant ``READ`` access. From ed1affc468cb490f020ca245bbc827f55e15f71d Mon Sep 17 00:00:00 2001 From: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com> Date: Wed, 13 Sep 2023 10:30:12 +0100 Subject: [PATCH 08/17] Update outdated UTC mode docs (#639) --- src/workflow-design-guide/general-principles.rst | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/src/workflow-design-guide/general-principles.rst b/src/workflow-design-guide/general-principles.rst index ea97d5e4ca..a001890dd9 100644 --- a/src/workflow-design-guide/general-principles.rst +++ b/src/workflow-design-guide/general-principles.rst @@ -8,18 +8,11 @@ writing any workflow. More advanced topics are covered later: :ref:`Efficiency And Maintainability` and :ref:`Portable Workflows Label`. -UTC Mode --------- - -Cylc has full timezone support if needed, but real time NWP workflows should use -UTC mode to avoid problems at the transition between local standard time and -daylight saving time, and to enable the same workflow to run the same way in -different timezones. - -.. code-block:: cylc +Cycle point time zone +--------------------- - [scheduler] - UTC mode = True +Cylc has full local timezone support if needed, but the default cycle point time +zone is UTC. See :cylc:conf:`flow.cylc[scheduler]cycle point time zone`. Fine Or Coarse-Grained Workflows From 7c8380d0557fc1f8407869fbdf068393a1e3a39e Mon Sep 17 00:00:00 2001 From: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com> Date: Wed, 13 Sep 2023 11:24:46 +0100 Subject: [PATCH 09/17] GH Actions: update setup-miniconda to v2.2.0 (#649) --- .github/actions/install-dependencies/action.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/actions/install-dependencies/action.yml b/.github/actions/install-dependencies/action.yml index 7260e93220..cb3ae4fade 100644 --- a/.github/actions/install-dependencies/action.yml +++ b/.github/actions/install-dependencies/action.yml @@ -25,7 +25,7 @@ runs: libfontconfig1-dev \ aspell-en - - uses: conda-incubator/setup-miniconda@35d1405e78aa3f784fe3ce9a2eb378d5eeb62169 # v2.1.1 + - uses: conda-incubator/setup-miniconda@3b0f2504dd76ef23b6d31f291f4913fb60ab5ff3 # v2.2.0 with: channels: conda-forge python-version: ${{ matrix.python-version || '' }} From 2ace983e2eb7322bfc78f3f9b6577da1dda56880 Mon Sep 17 00:00:00 2001 From: WXTIM <26465611+wxtim@users.noreply.github.com> Date: Wed, 27 Sep 2023 10:03:44 +0100 Subject: [PATCH 10/17] fix some aspects of the tutorials --- src/tutorial/runtime/runtime-configuration.rst | 8 +++++--- src/user-guide/installing-workflows.rst | 2 +- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/src/tutorial/runtime/runtime-configuration.rst b/src/tutorial/runtime/runtime-configuration.rst index e14649abf8..fbc6ac43a8 100644 --- a/src/tutorial/runtime/runtime-configuration.rst +++ b/src/tutorial/runtime/runtime-configuration.rst @@ -311,8 +311,8 @@ Start, Stop, Restart cylc get-resources api-key - Add the following lines to the bottom of the :cylc:conf:`flow.cylc` file replacing - ``xxx...`` with your API key: + Add the following lines to the ``[runtime]`` section of the + :cylc:conf:`flow.cylc` file replacing .. code-block:: cylc @@ -327,7 +327,8 @@ Start, Stop, Restart Add three more ``get_observations`` tasks for each of the remaining weather stations. - You will need the codes for the other three weather stations, which are: + You will need the API key and the site codes for the other three + weather stations, which are: * Camborne - ``3808`` * Shetland - ``3005`` @@ -379,6 +380,7 @@ Start, Stop, Restart .. code-block:: bash + cylc install cylc play runtime-tutorial If all goes well the workflow will startup and the tasks will run and diff --git a/src/user-guide/installing-workflows.rst b/src/user-guide/installing-workflows.rst index 601bd5cae2..3bdccd0c4f 100644 --- a/src/user-guide/installing-workflows.rst +++ b/src/user-guide/installing-workflows.rst @@ -402,7 +402,7 @@ The run directory now looks as follows: If your workflow needs to create or install scripts or executables at runtime and you don't want Cylc to delete them on re-installation, you can use - ``bin`` and ``lib/python`` directories in the :ref:` workflow share directory `. + ``bin`` and ``lib/python`` directories in the :ref:`workflow_share_directories`. Expected Errors From f3cda73f2332119f2f3316a31369e8310bee17d0 Mon Sep 17 00:00:00 2001 From: WXTIM <26465611+wxtim@users.noreply.github.com> Date: Wed, 27 Sep 2023 12:29:29 +0100 Subject: [PATCH 11/17] response to review --- src/tutorial/runtime/runtime-configuration.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/tutorial/runtime/runtime-configuration.rst b/src/tutorial/runtime/runtime-configuration.rst index fbc6ac43a8..7dc17fbce9 100644 --- a/src/tutorial/runtime/runtime-configuration.rst +++ b/src/tutorial/runtime/runtime-configuration.rst @@ -312,7 +312,7 @@ Start, Stop, Restart cylc get-resources api-key Add the following lines to the ``[runtime]`` section of the - :cylc:conf:`flow.cylc` file replacing + :cylc:conf:`flow.cylc` file .. code-block:: cylc @@ -327,8 +327,8 @@ Start, Stop, Restart Add three more ``get_observations`` tasks for each of the remaining weather stations. - You will need the API key and the site codes for the other three - weather stations, which are: + You will need to use the same API key for the other three + weather stations, and set the ``SITE_ID`` values, which are: * Camborne - ``3808`` * Shetland - ``3005`` From 2351aba6b6cd7693e98cd2ef75e21e56af94ce73 Mon Sep 17 00:00:00 2001 From: Tim Pillinger <26465611+wxtim@users.noreply.github.com> Date: Wed, 27 Sep 2023 13:34:25 +0000 Subject: [PATCH 12/17] Response to review --- src/tutorial/runtime/runtime-configuration.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/tutorial/runtime/runtime-configuration.rst b/src/tutorial/runtime/runtime-configuration.rst index 7dc17fbce9..9750534d6a 100644 --- a/src/tutorial/runtime/runtime-configuration.rst +++ b/src/tutorial/runtime/runtime-configuration.rst @@ -311,8 +311,8 @@ Start, Stop, Restart cylc get-resources api-key - Add the following lines to the ``[runtime]`` section of the - :cylc:conf:`flow.cylc` file + Add the following lines to the bottom of the :cylc:conf:`flow.cylc` file replacing + ``xxx...`` with your API key: .. code-block:: cylc @@ -327,8 +327,7 @@ Start, Stop, Restart Add three more ``get_observations`` tasks for each of the remaining weather stations. - You will need to use the same API key for the other three - weather stations, and set the ``SITE_ID`` values, which are: + You will need the codes for the other three weather stations, which are: * Camborne - ``3808`` * Shetland - ``3005`` From ad332f6ed99f8c542752eef11fe3cac0c1e5a881 Mon Sep 17 00:00:00 2001 From: WXTIM <26465611+wxtim@users.noreply.github.com> Date: Wed, 27 Sep 2023 14:55:36 +0100 Subject: [PATCH 13/17] add install to tutorial --- src/tutorial/runtime/runtime-configuration.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/src/tutorial/runtime/runtime-configuration.rst b/src/tutorial/runtime/runtime-configuration.rst index 7dc17fbce9..bd817edba2 100644 --- a/src/tutorial/runtime/runtime-configuration.rst +++ b/src/tutorial/runtime/runtime-configuration.rst @@ -431,6 +431,7 @@ Start, Stop, Restart .. code-block:: bash cylc validate . + cylc install .. TODO: Add advice on what to do if the command fails. From 963f9c0f8ff083194af1aad5b45a30e1c137ffb1 Mon Sep 17 00:00:00 2001 From: WXTIM <26465611+wxtim@users.noreply.github.com> Date: Wed, 27 Sep 2023 16:08:38 +0100 Subject: [PATCH 14/17] response to review --- src/user-guide/installing-workflows.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/user-guide/installing-workflows.rst b/src/user-guide/installing-workflows.rst index 3bdccd0c4f..4c0d28e10a 100644 --- a/src/user-guide/installing-workflows.rst +++ b/src/user-guide/installing-workflows.rst @@ -402,7 +402,8 @@ The run directory now looks as follows: If your workflow needs to create or install scripts or executables at runtime and you don't want Cylc to delete them on re-installation, you can use - ``bin`` and ``lib/python`` directories in the :ref:`workflow_share_directories`. + ``bin`` and ``lib/python`` directories in the + :ref:`workflow share directory`. Expected Errors From 885eecd7a50a6b71a3e5898fa009e69c8be9af68 Mon Sep 17 00:00:00 2001 From: WXTIM <26465611+wxtim@users.noreply.github.com> Date: Fri, 29 Sep 2023 09:17:18 +0100 Subject: [PATCH 15/17] ignore linux.die.net on linkchecker --- src/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/conf.py b/src/conf.py index 53b4d7916f..d45a8b9c8d 100644 --- a/src/conf.py +++ b/src/conf.py @@ -147,7 +147,8 @@ linkcheck_ignore = [ # linkcheck has trouble handling GH anchors - r'https://github.com/.*#.*' + r'https://github.com/.*#.*', + r'https://linux.die.net/.*' ] nitpick_ignore_regex = [ From 80741701ed35b153da33383c4027ca176635179c Mon Sep 17 00:00:00 2001 From: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com> Date: Tue, 3 Oct 2023 16:20:17 +0100 Subject: [PATCH 16/17] Small reword in tutorials --- src/tutorial/runtime/runtime-configuration.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/tutorial/runtime/runtime-configuration.rst b/src/tutorial/runtime/runtime-configuration.rst index cd57c84236..3fdc5b300c 100644 --- a/src/tutorial/runtime/runtime-configuration.rst +++ b/src/tutorial/runtime/runtime-configuration.rst @@ -367,10 +367,16 @@ Start, Stop, Restart .. TODO: Add advice on what to do if the command fails. - #. **Test The** ``get_observations`` **Tasks.** + #. **Test the** ``get_observations`` **tasks.** Next we will test the ``get_observations`` tasks. + Install the workflow: + + .. code-block:: bash + + cylc install + Open a user interface (:ref:`tutorial.tui` or :ref:`tutorial.gui`) to view your workflow. @@ -379,7 +385,6 @@ Start, Stop, Restart .. code-block:: bash - cylc install cylc play runtime-tutorial If all goes well the workflow will startup and the tasks will run and From 81bd7b94ceb7e0d8aad0033e36c92d1de4862aba Mon Sep 17 00:00:00 2001 From: WXTIM <26465611+wxtim@users.noreply.github.com> Date: Thu, 5 Oct 2023 15:06:21 +0100 Subject: [PATCH 17/17] exclude linkcheck failures --- src/conf.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/conf.py b/src/conf.py index d45a8b9c8d..b18b4a693b 100644 --- a/src/conf.py +++ b/src/conf.py @@ -146,9 +146,8 @@ '-Nfontname=sans'] linkcheck_ignore = [ - # linkcheck has trouble handling GH anchors - r'https://github.com/.*#.*', - r'https://linux.die.net/.*' + 'https?://linux.die.net/man/1/bash', + 'https?://github.com/.*#.*', ] nitpick_ignore_regex = [