.. _config/instance/instancename: ``instance`` section ==================== syntax:: INSTANCE_SECTION := "instance\n" + SETTING* SETTING := SETTING-NAME + ": " + SETTING-VALUE + "\n" usually the first entry in your config file. The instance-section describes global settings valid for this ln-instance. The most-important setting is the manager-address and the instance-name -- each ln-instance has to have a unique manager-address and should have a unique name. Reusing the same name in different instances can cause conflicts within the ln-daemon! example: .. code-block:: lnc instance name: %(env USER)'s first LN setup manager: :%(get_port_from_string %(instance_name)) enable_auto_groups: true the following sections list all possible ``SETTING-NAME``'s. they all follow the same ``name: value``-syntax like shown in above's example. .. _instance/name: name ---- required name of this instance. it needs to be globally unique to avoid conflicts with other LN instances. Daemons use this name to separate resources from different manager instances. example: ``name: test config file for %(env USER)@%(hostname)`` manager ------- required manager TCP port number of this instance. expected to be in format ``HOST:PORT`` where HOST is optional and PORT is a TCP/IP port number where LN clients communicate with the LN manager. Usually leave HOST empty, as in ``:PORT``, so the same config file can be started on different hosts. example: ``manager: :54412`` instead of hardcoding a port number which can only be used once, i suggest to let the ln-manager generate a fixed port-number from your instance-name (which should be unique):: manager: :%(get_port_from_string "%(instance_name)") documentation ------------- this can be used to specify a URL or filename for instance-specific documentation. In the GTK ``ln_manager`` GUI this integrates with the global ``docs`` button at the top-right of the notebook. When ``documentation`` is set, pressing ``docs`` opens a small popup menu with: * ``instance documentation`` for this configured URL or filename * ``LN documentation`` for the built-in LN reference documentation served at ``/doc/`` When ``documentation`` is not set, the same ``docs`` button directly opens the built-in LN documentation. The selected target is opened via `xdg-open`_. this is useful to provide documentation to the user. URL's, pdf- and text-files are known to open fine. .. _xdg-open: https://linux.die.net/man/1/xdg-open .. _instance-enable_auto_groups: enable_auto_groups ------------------ when set to ``true`` will interpret ``/``-character in process & state names as delimiters between groups and display-names. groups will be automatically created. this is useful when you define many processes e.g. in an include-file and you want them to all be assigned to the same group. example: .. code-block:: lnc #... process proc1 #... process proc2 #... process proc3 #... group groupAB members: proc3 group groupA members: proc1, proc2, groupAB process proc4 #... group groupC members: proc4 will create a group/process structure like this:: groupA |- proc1 |- proc2 |- groupAB |- proc3 groupC |- proc4 this exact same group-structure can also be achieved like this .. code-block:: lnc instance #... enable_auto_groups: true process groupA/proc1 #... process groupA/proc2 #... process groupA/groupAB/proc3 #... process groupC/proc4 #... ln_manager will create 3 groups from this: ``groupA``, ``groupAB``, ``groupC`` and automatically assign members. together with the :ref:`push_name_prefix`-directive this can be further reduced like this: .. code-block:: lnc instance #... enable_auto_groups: true push_name_prefix: groupA process proc1 #... process proc2 #... process groupAB/proc3 #... pop_name_prefix process groupC/proc4 #... .. versionadded:: 0.8.5 .. _instance/log_file: log_file -------- when set, all log messages generated by ln_manager will be written to the named text file (utf-8). log_file_size_limit ------------------- when set, ln_manager will "rotate" the ``log_file`` when the specified file-size is exceeded. see ``log_file_keep_count`` below for description of rotation. the specified size can have one of these commonly used suffixes: ``B``, ``kB``, ``MB``, ``GB``. if you use this limit it is strongly suggested to also set ``log_file_keep_count >= 1``. log_file_keep_count ------------------- how many rotated logfiles to keep when rotation is triggered by ``log_file_size_limit``. default value is `0`, meaning there will always only ever be one log-file which is always smaller than the specified size limit. when set to `1` there will be at most one additional file with a filename of ``._`` and so on. when there are already ``N`` files, the oldest will be deleted. example: .. code-block:: lnc instance #... log_file: %(CURDIR)/manager.log log_file_size_limit: 10MB log_file_keep_count: 3 this will create a logfile ``manager.log`` and up to 3 further files name ``manager.log._``. .. _instance/manager_log_history_size: manager_log_history_size ------------------------ how many ln-manager log entries should be retained in manager memory. default value is ``5120``. this value mainly matters for the :doc:`save all debug-info workflow `, because that export stores the manager's in-memory log history from the current manager process. this is different from :ref:`max_log_items `: * ``manager_log_history_size`` controls how much manager log history is kept in memory at all. * ``max_log_items`` controls how many log entries the GUI log views keep displayed. if ``manager_log_history_size`` is smaller than ``max_log_items``, older manager log messages may already have been dropped before the GUI or the debug-info export can still access them. setting this to ``0`` disables in-memory manager log retention. example: .. code-block:: lnc instance #... manager_log_history_size: 20000 .. _instance/max_log_items: max_log_items ------------- how many log entries to keep in memory / displayed in the "log"-tab. default value is ``5000``. this limits the number of rows kept in the ln-manager GUI log views. it does not increase the amount of manager log history retained for the :doc:`save all debug-info workflow `; for that, see :ref:`manager_log_history_size `. consider using a :ref:`log file` instead of further increasing this number of GUI items. daemon_log_history_size ----------------------- how many log entries each connected ``ln_daemon`` should keep in its in-memory daemon log history. default value is ``2000``. this setting is applied to daemons connected to this manager instance. newer daemons also expose this log history to the manager's debug-info export, so increasing this value can be useful when you want the :doc:`save all debug-info workflow ` to include more daemon-side context. setting this to ``0`` disables retention of daemon log messages in memory. example: .. code-block:: lnc instance #... daemon_log_history_size: 5000 .. _instance/webui_auth_file: webui_auth_file --------------- optional filename for the built-in browser UI authentication file. For the full browser UI setup and usage guide, see :doc:`ln_manager_webui`. When this is set, ``ln_manager`` serves the browser UI on the same TCP port as the normal manager connection, but only after HTTP authentication succeeded. The file must contain one `` `` pair per line, for example: .. code-block:: text alice s3cret bob another_password The file must not be readable by group or others. In practice this means it should usually be created with ``chmod 600``. Successful browser login creates a cookie-backed session stored in a sibling file named ``.sessions``. That sessions file is also forced to mode ``0600``. Instead of hardcoding the filename in the config, you can leave this option unset and use the environment variable ``LNM_WEBUI_AUTH_FILE``. If both are provided, the environment variable wins. In the GTK GUI, the global ``web ui`` button opens this browser UI in the user's preferred browser at ``/lnm/`` on the current manager host and port. Example: .. code-block:: lnc instance # ... webui_auth_file: %(env HOME)/.config/ln_manager/webui.keys .. _instance/webui_https_cert_file: webui_https_cert_file --------------------- optional TLS certificate file for serving the built-in browser UI over HTTPS. When this is set, ``ln_manager`` accepts both plain HTTP and HTTPS on the same manager TCP port. The manager detects TLS ClientHello records before consuming the normal manager/client protocol magic bytes. The HTTPS URL therefore uses the same host and port as the normal manager connection: .. code-block:: text https://MANAGER_HOST:MANAGER_PORT/ The certificate must be usable by Python's ``ssl`` module. Browsers generally require the certificate to be trusted by the browser or operating system before the page is treated as a normal trusted HTTPS origin. See :doc:`ln_manager_webui_https_certificates` for certificate options and the hostname requirements of browser-trusted certificates. Instead of hardcoding the filename in the config, you can leave this option unset and use the environment variable ``LNM_WEBUI_HTTPS_CERT_FILE``. If both are provided, the environment variable wins. Example: .. code-block:: lnc instance # ... webui_https_cert_file: %(env HOME)/.config/ln_manager/webui.crt webui_https_key_file: %(env HOME)/.config/ln_manager/webui.key .. _instance/webui_https_key_file: webui_https_key_file -------------------- optional private key file for ``webui_https_cert_file``. If the private key is contained in ``webui_https_cert_file``, this option may be left unset. Instead of hardcoding the filename in the config, you can leave this option unset and use the environment variable ``LNM_WEBUI_HTTPS_KEY_FILE``. If both are provided, the environment variable wins. See :doc:`ln_manager_webui_https_certificates` for how certificate and private key files are usually obtained and which browser trust requirements apply. groups_opened_default --------------------- when set to ``false`` all groups will be displayed in a "closed" state after manager startup. groups_sorted_default --------------------- when set to ``true`` all group members will sorted by their name. otherwise they will appear in the order they are read from the config file. .. _instance/daemon_private_key_file: daemon_private_key_file ----------------------- sets a default value for hosts-:ref:`hosts/daemon_private_key_file`. .. _instance/daemon_public_key_file: daemon_public_key_file ---------------------- sets a default value for hosts-:ref:`hosts/daemon_public_key_file`. .. _instance/additional_ssh_arguments: additional_ssh_arguments ------------------------ sets a default value for hosts-:ref:`hosts/additional_ssh_arguments`. .. _instance/ssh_binary: ssh_binary ---------- sets a default value for hosts-:ref:`hosts/ssh_binary`. .. _instance/daemon_start_script: daemon_start_script ------------------- sets a default value for hosts-:ref:`hosts/daemon_start_script`. .. _instance/daemon_start_shell: daemon_start_shell ------------------ sets a default value for hosts-:ref:`hosts/daemon_start_shell`. .. _instance/default_change_user_to: default_change_user_to ---------------------- sets a default value for hosts-:ref:`hosts/default_change_user_to`. The inherited value uses the same ``username`` or ``username:group1[:group2...]`` syntax as :ref:`process/change_user_to`. When supported by the daemon platform, spawned processes also receive the selected user's configured supplementary groups plus any groups listed explicitly. .. _instance/default_expected_user: default_expected_user --------------------- sets a default value for hosts-:ref:`hosts/expected_user`. .. _instance/scope_process_template: scope_process_template ---------------------- ln_manager provides an internal process-template to instantiate scope-processes when you double-click on a topic-field (see built-in-:ref:`internal scope template`). when this option is set, you can use one of your own templates instead. that template should accept two template-parameters: ``topic_name`` and ``field_in_md`` specifying which topic should be subscribed and which field should be plottet. this could be used for example to have scope processes started on a different-node than the manager-gui: .. code-block:: lnc instance #... scope_process_template: my_scope template my_scope(topic_name, field_in_md) use_template: internal scope template("%(topic_name)", "%(field_in_md)") del flags: forward_x11_to_gui add environment: DISPLAY=:0 node: my_display_debug_node ( :doc:`x11_connections` explains how X11 display selection and authentication work, including ``DISPLAY``, ``XAUTHORITY``, X cookies, and when the :ref:`process/forward_x11` or :ref:`process/forward_x11_to_gui` flags can set this up automatically ) .. _instance/notebook_process_template: notebook_process_template ------------------------- ln_manager provides an internal process-template to instantiate notebook-processes (see built-in-:ref:`internal notebook template`). when this option is set, you can use one of your own templates instead. the template should accept two template-parameters: ``filename`` and ``title`` that specifies which notebook file to open and which title should be displayed in the titlebar. The built-in notebook template uses ``forward_x11_to_gui``. Custom templates that intentionally hard-code a different X display should remove that inherited flag before setting their own ``DISPLAY`` / ``XAUTHORITY`` values. also compare :ref:`instance/scope_process_template`. .. _instance/vncserver_process_template: vncserver_process_template -------------------------- ln_manager provides an internal process-template to instantiate private VNC X servers for authenticated web-UI users (see built-in-:ref:`internal vncserver template`). These servers are used when the manager runs without a local X display and a web-UI user starts a process with :ref:`process/forward_x11_to_gui`. The template must accept three template parameters: * ``username``: the authenticated web-UI username * ``display``: the allocated X11 display number without the leading ``:`` * ``vnc_port``: the matching VNC TCP port, normally ``5900 + display`` The manager first looks for a user-specific template named ``_for_``. If that template does not exist, it falls back to the generic ``vncserver_process_template``. Example: .. code-block:: lnc instance #... vncserver_process_template: my_vncserver template my_vncserver(username, display, vnc_port) use_template: internal vncserver template("%(username)", "%(display)", "%(vnc_port)") command+: -geometry 1600x1000 template my_vncserver_for_alice(username, display, vnc_port) use_template: internal vncserver template("%(username)", "%(display)", "%(vnc_port)") command+: -geometry 1920x1080 The default template starts ``Xvnc`` or ``Xtigervnc`` on the manager host, listens for VNC only on localhost, and disables VNC passwords because the browser reaches it through the authenticated manager web port. It marks the process ready when TigerVNC reports ``Listening for VNC connections`` and uses ``-UseBlacklist=0``. It also starts a window manager through ``~/.vnc/xstartup``. To choose a different window manager, first customize ``~/.vnc/xstartup`` for the user running the VNC server process. If that is not enough, provide your own ``vncserver_process_template``. If ``~/.vnc/xstartup`` does not exist, the default template creates one using the first available window manager from ``metacity``, ``xfwm4``, ``openbox``, ``mutter``, and ``i3``. This file is created on the host where the VNC server process runs. With custom remote VNC templates, ensure that the remote host has the intended ``~/.vnc/xstartup`` or that the home directory is shared with the manager host. vte_font -------- font used for process-output widgets. defaults to ``Monospace``. can be any valid `Pango FontDescription`_. .. _Pango FontDescription: https://lazka.github.io/pgi-docs/Pango-1.0/classes/FontDescription.html#Pango.FontDescription.from_string vte_color_style --------------- defines which color scheme should be used by VTE widgets. default is ``holo_flo``. possible values are: * ``linux`` * ``rxvt`` * ``tango`` * ``xterm`` * ``zenburn`` * ``solarized_light`` * ``solarized_dark`` * ``holo`` * ``holo_flo`` compare https://rmc-github.robotic.dlr.de/common/links_and_nodes/blob/master/python/links_and_nodes_manager/color_styles.py gen_message_definition_path --------------------------- ln-clients can dynamically generate new message-definitions and register them with the ln-manager. they will be stored on disc such that it is possible to re-use that md even if that generator process is not yet started again. for this we need a dedicated directory, the default is ``~/ln_message_definitions/gen``. this directory has to be a sub-directory of some already known message-definition search-path. see :ref:`global/add_message_definition_dir` and :envvar:`LN_MESSAGE_DEFINITION_DIRS`. ln-manager checks the effective message-definition search path after startup and after each config reload. if the same message-definition name is found in more than one file with different contents, the manager rejects the configuration because the first search-path match would otherwise silently shadow the later definitions. use the ``disable_message_definition_conflict_check`` instance flag only if this compatibility check must be skipped. when that flag is set and conflicting message definitions exist, the manager falls back to the normal lookup behavior and uses the contents from the first matching message definition in the effective search path. default_notebook_path --------------------- this setting should specify a directory where context-dependant-notebook files shall be stored. it defaults to be a ``.notebooks``-directory within the same directory as your top-level ln-manager config file. allow_x11_tcp_connect --------------------- when set to ``true``, ln_manager will tell processes which use :ref:`process/forward_x11`, or :ref:`process/forward_x11_to_gui` with a directly reachable GUI display host, to try to reach the X-server directly without using any tcp-forwardings. for this to work the X-server has to be listening to tcp-connection from remote hosts (see :ref:`Accessing the X Server from a client ` ). otherwise, the default value of ``false`` will let ln-manager create tcp-forwardings as soon as a remote process needs X11 forwarding for one of those flags. open_scope_on_parameter_double_click ------------------------------------ the default value is taken from the environment variable :envvar:`LN_OPEN_SCOPE_ON_PARAMETER_DOUBLE_CLICK`, if that variable is not set a value of ``true`` is used. when set to ``true`` double clicking on a parameter name within the parameter-tab of the ln-manager gui, will tell the parameter-block to start publishing its parameters and then ln-manager tries to open a scope process to plot this parameter. see also :ref:`internal scope template` and :ref:`gui_reference/opening_a_scope`. do_not_try_uids_of_clients -------------------------- default value is ``false``: when ln-manager needs a connection to an ln_daemon on a host it will first try to get an ln_daemon with the configured user-id (e.g. via :ref:`hosts/expected_user_id` or :ref:`hosts/expected_user`). if there is no daemon running for this user, ln-manager will try all observed user-id's that were reported from connected ln-clients on that host. setting this to ``true`` will disable this feature and will only connect to daemons where the user is an "exact" match. this is only of interesst if you have processes / ln-clients that run with different user-id's. do_lock_daemons_with_unexpected_uids ------------------------------------ usually ln-manager will lock all unlocked-daemons immediately after the connection is established. but this will only be done for daemons with an "expected" user-id as configured via :ref:`hosts/expected_user_id` or :ref:`hosts/expected_user`. if ``do_not_try_uids_of_clients`` is set to ``false`` (the default) the connected daemon might use an "unexpected" user-id and ln-manager would not try to lock this daemon. when setting this to ``true``, ln-manager will also lock daemons with "unexpected" user-ids. this only has effect if ``do_not_try_uids_of_clients`` is ``false`` and if you have processes / ln-clients that run with different user-id's. daemon-locking can also be disabled on a per-host basis, by setting :ref:`hosts/daemon_private_key_file` to ``none``. .. _default_resource_limits: default_resource_limits ----------------------- sets a default value for process-:ref:`process/default_resource_limits`. check_all_states_after_daemon_connect ------------------------------------- if set to ``true`` will cause all configured states of a host to be *checked* as soon as a connection is established. (default: ``false`` since version 0.13.11) .. versionadded:: 0.13.0 pid_file -------- defaults to be not set. when set, should be a filename where ln-manager shall write its own process-id into. this is useful when started e.g. from systemd or other init scripts to be able to check whether ln-manager is already/still running. ln-manager will write this file AFTER the listening socket for client-connections is established. flags ----- is a comma-separated list of the following flags: * ``disable_all_vte`` disable the default-use of `VTE`_ widget to display process output. * ``no_shmv3`` disable use of new v3 shared-memory implementation on linux. (should not be used) * ``disable_forward_x11_to_gui_fallback`` disable the automatic fallback where web-UI starts of processes using :ref:`process/forward_x11` use the authenticated user's private web X display when the manager itself has no ``DISPLAY`` environment variable. * ``disable_message_definition_conflict_check`` disable the startup/reload check that rejects conflicting message definitions with the same name but different contents. * ``log_store_stack`` append a stacktrace to each log-message. this is useful when debugging ln_manager. example: .. code-block:: lnc instance #... flags: log-store-stack, disable_all_vte .. _VTE: https://wiki.gnome.org/Apps/Terminal/VTE