From 7b7d694d2749b09ec79c09cc53f469959e5e91bc Mon Sep 17 00:00:00 2001
From: Trav <travert@osc.edu>
Date: Mon, 19 Oct 2026 15:09:10 -0700
Subject: [PATCH] Document vncserver_cmd, vncpasswd_cmd and vnc_clean for VNC
 apps

---
 .../files/submit-yml/vnc-bc-options.rst       | 99 ++++++++++++++++++-
 1 file changed, 97 insertions(+), 2 deletions(-)

diff --git a/source/reference/files/submit-yml/vnc-bc-options.rst b/source/reference/files/submit-yml/vnc-bc-options.rst
index fb1591fa5..d4339d72b 100644
--- a/source/reference/files/submit-yml/vnc-bc-options.rst
+++ b/source/reference/files/submit-yml/vnc-bc-options.rst
@@ -18,6 +18,8 @@ All the options in :ref:`basic-bc-options` apply in addition to what's listed be
         - display
         - websocket
       websockify_cmd: "/opt/websockify/run"
+      vncserver_cmd: "${VNCSERVER_CMD:-vncserver}"
+      vncpasswd_cmd: "${VNCPASSWD_CMD:-vncpasswd}"
       vnc_passwd: "vnc.passwd"
       vnc_args: nil
       name: ""
@@ -30,7 +32,7 @@ All the options in :ref:`basic-bc-options` apply in addition to what's listed be
       websockify_heartbeat_seconds: 30
 
 
-.. describe:: websockfiy_cmd (String, "/opt/websockify/run")
+.. describe:: websockify_cmd (String, "/opt/websockify/run")
 
     the command to start ``websockify``.
 
@@ -39,7 +41,7 @@ All the options in :ref:`basic-bc-options` apply in addition to what's listed be
 
       .. code-block:: yaml
 
-        websockfiy_cmd: "/opt/websockify/run"
+        websockify_cmd: "/opt/websockify/run"
 
     Example
       The ``/usr/bin/websockify`` command.
@@ -48,6 +50,68 @@ All the options in :ref:`basic-bc-options` apply in addition to what's listed be
 
         websockify_cmd: "/usr/bin/websockify"
 
+.. describe:: vncserver_cmd (String, "${VNCSERVER_CMD:-vncserver}")
+
+    the command used to start, check and stop the VNC server. Set it to a
+    full path so a user's ``PATH`` (for example a conda environment loaded
+    from ``~/.bashrc``) can't put a different ``vncserver`` first.
+
+    If this option isn't set, the ``VNCSERVER_CMD`` environment variable is
+    used, and if that isn't set either, ``vncserver`` from the ``PATH``.
+    The variable has to be set before the template starts the VNC server,
+    for example in a ``script_wrapper`` or with ``job_environment``.
+    Setting it in ``before.sh`` is too late, because ``before.sh`` is
+    sourced after the VNC server has started.
+
+    This option applies to the ``vnc`` template only. The ``vnc_container``
+    template runs ``vncserver`` inside the container.
+
+    Default
+      ``$VNCSERVER_CMD`` if it is set, otherwise ``vncserver`` from the ``PATH``.
+
+      .. code-block:: yaml
+
+        vncserver_cmd: "${VNCSERVER_CMD:-vncserver}"
+
+    Example
+      Always use TurboVNC's ``vncserver``.
+
+      .. code-block:: yaml
+
+        vncserver_cmd: "/opt/TurboVNC/bin/vncserver"
+
+    Example
+      Set the environment variable for every VNC app on a cluster, in the
+      cluster's ``batch_connect`` configuration.
+
+      .. code-block:: yaml
+
+        batch_connect:
+          vnc:
+            script_wrapper: |
+              export VNCSERVER_CMD="/opt/TurboVNC/bin/vncserver"
+              %s
+
+.. describe:: vncpasswd_cmd (String, "${VNCPASSWD_CMD:-vncpasswd}")
+
+    the command used to write the VNC password file. It works the same way
+    as ``vncserver_cmd``, with the ``VNCPASSWD_CMD`` environment variable.
+    This option applies to the ``vnc`` template only.
+
+    Default
+      ``$VNCPASSWD_CMD`` if it is set, otherwise ``vncpasswd`` from the ``PATH``.
+
+      .. code-block:: yaml
+
+        vncpasswd_cmd: "${VNCPASSWD_CMD:-vncpasswd}"
+
+    Example
+      Always use TurboVNC's ``vncpasswd``.
+
+      .. code-block:: yaml
+
+        vncpasswd_cmd: "/opt/TurboVNC/bin/vncpasswd"
+
 .. describe:: vnc_passwd (String, "vnc.passwd")
 
     the file ``vncserver`` will read for a password
@@ -195,6 +259,37 @@ All the options in :ref:`basic-bc-options` apply in addition to what's listed be
 
         extra_args: "-depth 32"
 
+.. describe:: vnc_clean (String, "...")
+
+    the shell code that stops this job's VNC server. It runs in two places:
+    before each attempt to start the VNC server, and in ``clean_up`` when
+    the job ends.
+
+    The default stops the server by its display number, so only the VNC
+    server this job started is stopped. Other VNC sessions the user has
+    on the same node, from other jobs, are left alone. The ``display``
+    variable is empty until the server has started, so before that the
+    default does nothing. With the ``vnc_container`` template, the default
+    runs ``vncserver -kill`` inside the container instance.
+
+    If you set this option, your code replaces the default completely and
+    is the only thing that stops the VNC server when the job ends. Check
+    that ``display`` is set before you use it.
+
+    Default
+      stop this job's VNC server by display.
+
+      .. code-block:: yaml
+
+        vnc_clean: '[[ -n ${display} ]] && ${VNCSERVER_CMD:-vncserver} -kill :${display}'
+
+    Example
+      also log which display was stopped.
+
+      .. code-block:: yaml
+
+        vnc_clean: '[[ -n ${display} ]] && vncserver -kill :${display} && echo "Stopped VNC display :${display}"'
+
 .. warning::
     These items below should not be set by users.  They are
     given for completeness only.  It's likely they'll cause