From 56fc2d9e73fd62a2d464e3e61d132c365cdf800a Mon Sep 17 00:00:00 2001
From: Scott Wales <scott.wales@bom.gov.au>
Date: Thu, 14 Sep 2023 15:08:18 +1000
Subject: [PATCH] Document ssh forward environment variables

Documents cylc/cylc-flow#5709
---
 .../config/writing-platform-configs.rst       | 62 ++++++++++++++++++-
 1 file changed, 60 insertions(+), 2 deletions(-)

diff --git a/src/reference/config/writing-platform-configs.rst b/src/reference/config/writing-platform-configs.rst
index b38d89bec59..2222f57cd26 100644
--- a/src/reference/config/writing-platform-configs.rst
+++ b/src/reference/config/writing-platform-configs.rst
@@ -327,8 +327,8 @@ Symlinks for remote install targets are created during :ref:`RemoteInit` followi
 ``cylc play``.
 
 
-Advanced Platform Example
--------------------------
+Advanced Platform Examples
+--------------------------
 
 Platform with no ``$HOME`` directory
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -370,3 +370,61 @@ In this example Cylc will install workflows into
    If you are running :term:`schedulers <scheduler>` directly on the login node
    and submitting jobs locally then the platform name and install target should
    be ``localhost``.
+
+Sharing environment variables with the Cylc server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. admonition:: Scenario
+
+    An environment variable on the computer where you're running `cylc play`
+    needs to be shared with the Cylc server (e.g. to set up storage paths) or
+    with Cylc task hosts (e.g. to set PBS account defaults)
+
+Normally if a Cylc server or task is running on a remote host it will not keep
+environment variables that are present when you run ``cylc play``. You can
+whitelist variables to be sent to remote hosts using
+:cylc:conf:`global.cylc[scheduler][run hosts]ssh forward environment variables`.
+
+These variables are forwared to the Cylc server and then from there to task
+hosts. They can then be used to affect the global configuration or the task
+configuration (for instance ``qsub`` may use the value of ``$PROJECT`` to set a
+default account to charge usage to).
+
+ .. code-block:: cylc
+    :caption: part of a ``global.cylc`` config file
+
+    [scheduler]
+        [[run hosts]]
+            ssh forward environment variables = LUSTRE_DISK, PROJECT
+
+    [install]
+        [[symlink dirs]]
+            [[[hpc]]]
+                run = {{ environ['LUSTRE_DISK'] }}
+
+    [platforms]
+        [[hpc]]
+            submit method = pbs
+            [[[directives]]]
+                -P = {{ environ['PROJECT'] }}
+
+In this example Cylc will install workflows into the directory specified by
+``$LUSTRE_DISK`` and use the project specified by ``$PROJECT`` on the server
+where you run ``cylc play``, e.g.
+
+ .. code-block:: sh
+
+    export LUSTRE_DISK=/g/data/foo
+    export PROJECT=bar
+    cylc play
+
+will store the workflow under ``/g/data/foo`` and submit jobs under project
+``bar``.
+
+It's better to be explicit in what's happening when setting up the
+configuration - even though ``qsub`` will pick up ``$PROJECT`` from the
+environment we're also explicitly setting the account to use with ``-P`` in
+case the task is run manually.
+
+This setting only affects task submission - to set a variable once the task has
+started see :cylc:conf:`global.cylc[platforms][<platform name>]copyable environment variables`.