builtin-templates
=================

ln_manager provides some built-in process templaes which can be used in
config files:

.. _internal notebook template:

internal notebook template
--------------------------

this can be used to start a python notebook like its done when pressing
one of the "open notebook"-button on the ln_manager-UI (e.g. for
processes, within the topic inspector, or when double clicking a service
name).

it can be used like this:

.. code-block:: lnc

   process my notebook
   use_template: internal notebook template("%(CURDIR)/my_notebook.nb.py", "some title")
   node: localhost

this will start a notebook-UI on the manager host. The built-in template uses
``forward_x11_to_gui`` so manager-started notebook windows target the active GUI
context, including a web UI user's private X display.


see also instance-:ref:`instance/notebook_process_template`.

.. _internal scope template:

internal scope template
-----------------------

this will start a scope-UI subscribing to a specified topic and plotting a
specified field versus time.

it can be used like this:

.. code-block:: lnc

   process my topic1 scope
   use_template: internal scope template("topic1", "field1")
   node: localhost

this will start a scope-UI on the manager host. The built-in template uses
``forward_x11_to_gui`` so manager-started scope windows target the active GUI
context, including a web UI user's private X display.
it will subscribe to topic ``topic1`` and plot values of ``field1``.

see also instance-:ref:`instance/scope_process_template`.

.. _internal vncserver template:

internal vncserver template
---------------------------

this is used by the web UI to start a private VNC-backed X server for one
authenticated web-UI user. It accepts three parameters:

.. code-block:: lnc

   use_template: internal vncserver template("alice", "90", "5990")

The default command searches ``Xvnc`` and ``Xtigervnc`` in the manager
environment and starts the first one found roughly like this:

.. code-block:: bash

   Xvnc :90 -rfbport 5990 -localhost -SecurityTypes None \
     -AlwaysShared -UseBlacklist=0 -geometry 1280x900 -depth 24 -ac

Before starting ``Xvnc``, the template checks ``~/.vnc/xstartup`` for the user
running the VNC server process. If that file already exists, ln_manager leaves
it untouched and runs it inside the private X display. If it does not exist,
ln_manager looks for a lightweight window manager in this order:
``metacity``, ``xfwm4``, ``openbox``, ``mutter``, ``i3``. The first one found is
written into a generated ``~/.vnc/xstartup`` template. If no window manager is
found, the VNC server process fails with a message explaining which packages or
customization points to use.

The VNC port listens only on localhost. Browser clients reach it through the
authenticated ln_manager web port and the built-in noVNC bridge, so the default
template does not configure a VNC password. The template marks the process
ready when TigerVNC reports ``Listening for VNC connections`` and disables
TigerVNC's automatic authentication blacklist with ``-UseBlacklist=0``.

The template uses ``start_in_shell`` and passes the manager's ``PATH`` so
the shell can find ``Xvnc`` or ``Xtigervnc`` and the window-manager candidates.

The generated ``~/.vnc/xstartup`` is created on the host where the VNC server
process runs. With the built-in template this is the manager host. If a custom
``vncserver_process_template`` moves the VNC server to another host, configure
``~/.vnc/xstartup`` on that host too, or make sure the relevant home directory
is on a shared filesystem.

Additional arguments appended to the template command with ``command+:`` are
appended to the shell command after the default Xvnc arguments. This can be
useful for temporary debugging, for example ``command+:  -verbose -Log
*:stderr:100``.

.. _internal configured vncserver template:

internal configured vncserver template
--------------------------------------

this wraps built-in-:ref:`internal vncserver template` for a configured VNC
display. It accepts the user-facing VNC session name, the X11 display number,
and the VNC TCP port:

.. code-block:: lnc

   process remote xvnc desktop
   use_template: internal configured vncserver template("remote Xvnc desktop", "80", "5980")
   node: vnc_node

The wrapper starts the same TigerVNC ``Xvnc`` process as
``internal vncserver template`` and also sets ``vnc_session``, ``vnc_port``,
and ``vnc_display``. It is separate from ``internal vncserver template`` so the
private per-web-user VNC displays do not appear as configured VNC sessions.

see also instance-:ref:`instance/vncserver_process_template`.