.. _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 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/default_change_user_to: default_change_user_to ---------------------- sets a default value for hosts-:ref:`hosts/default_change_user_to`. .. _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)") 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` flag 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. also compare :ref:`instance/scope_process_template`. 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`. 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 have the :ref:`forward_x11 `-process flag set to try to reach the X-server directly without using any tcp-forwardings (when manager-host is directly reachable for that process). 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 has the ``forward_x11`` flag set. 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) * ``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