3.3. `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:

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.

3.3.1. 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)

3.3.2. 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)")

3.3.3. 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.

3.3.4. 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:

#...
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

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 push_name_prefix-directive this can be further reduced like this:

instance
#...
enable_auto_groups: true

push_name_prefix: groupA

process proc1
#...
process proc2
#...
process groupAB/proc3
#...

pop_name_prefix

process groupC/proc4
#...

Added in version 0.8.5.

3.3.5. log_file

when set, all log messages generated by ln_manager will be written to the named text file (utf-8).

3.3.6. 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.

3.3.7. 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 <log_file>.<YYMMDD>_<HHMMSS> and so on. when there are already N files, the oldest will be deleted.

example:

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.<YYMMDD>_<HHMMSS>.

3.3.8. 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 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 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:

instance
#...
manager_log_history_size: 20000

3.3.9. 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 save all debug-info workflow; for that, see manager_log_history_size.

consider using a log file instead of further increasing this number of GUI items.

3.3.10. 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 save all debug-info workflow to include more daemon-side context.

setting this to 0 disables retention of daemon log messages in memory.

example:

instance
#...
daemon_log_history_size: 5000

3.3.11. webui_auth_file

optional filename for the built-in browser UI authentication file.

For the full browser UI setup and usage guide, see LN Manager Web UI.

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 <username> <password> pair per line, for example:

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 <webui_auth_file>.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:

instance
# ...
webui_auth_file: %(env HOME)/.config/ln_manager/webui.keys

3.3.12. groups_opened_default

when set to false all groups will be displayed in a “closed” state after manager startup.

3.3.13. 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.

3.3.14. daemon_private_key_file

sets a default value for hosts-daemon_private_key_file.

3.3.15. daemon_public_key_file

sets a default value for hosts-daemon_public_key_file.

3.3.16. additional_ssh_arguments

sets a default value for hosts-additional_ssh_arguments.

3.3.17. ssh_binary

sets a default value for hosts-ssh_binary.

3.3.18. daemon_start_script

sets a default value for hosts-daemon_start_script.

3.3.19. default_change_user_to

sets a default value for hosts-default_change_user_to.

3.3.20. default_expected_user

sets a default value for hosts-expected_user.

3.3.21. 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-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:

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

( X11 Connections and Authentication explains how X11 display selection and authentication work, including DISPLAY, XAUTHORITY, X cookies, and when the forward_x11 flag can set this up automatically )

3.3.22. notebook_process_template

ln_manager provides an internal process-template to instantiate notebook-processes (see built-in-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 scope_process_template.

3.3.23. vte_font

font used for process-output widgets. defaults to Monospace. can be any valid Pango FontDescription.

3.3.24. 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

3.3.25. 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 add_message_definition_dir and LN_MESSAGE_DEFINITION_DIRS.

3.3.26. 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.

3.3.27. allow_x11_tcp_connect

when set to true, ln_manager will tell processes which have the 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 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.

3.3.28. open_scope_on_parameter_double_click

the default value is taken from the environment variable 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.

3.3.29. 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 expected_user_id or 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.

3.3.30. 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 expected_user_id or 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 daemon_private_key_file to none.

3.3.31. default_resource_limits

sets a default value for process-Setting resource limits.

3.3.32. 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)

Added in version 0.13.0.

3.3.33. 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.

3.3.34. 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:

instance
#...
flags: log-store-stack, disable_all_vte

3.3. instance section

3.3.1. name

3.3.2. manager

3.3.3. documentation

3.3.4. enable_auto_groups

3.3.5. log_file

3.3.6. log_file_size_limit

3.3.7. log_file_keep_count

3.3.8. manager_log_history_size

3.3.9. max_log_items

3.3.10. daemon_log_history_size

3.3.11. webui_auth_file

3.3.12. groups_opened_default

3.3.13. groups_sorted_default

3.3.14. daemon_private_key_file

3.3.15. daemon_public_key_file

3.3.16. additional_ssh_arguments

3.3.17. ssh_binary

3.3.18. daemon_start_script

3.3.19. default_change_user_to

3.3.20. default_expected_user

3.3.21. scope_process_template

3.3.22. notebook_process_template

3.3.23. vte_font

3.3.24. vte_color_style

3.3.25. gen_message_definition_path

3.3.26. default_notebook_path

3.3.27. allow_x11_tcp_connect

3.3.28. open_scope_on_parameter_double_click

3.3.29. do_not_try_uids_of_clients

3.3.30. do_lock_daemons_with_unexpected_uids

3.3.31. default_resource_limits

3.3.32. check_all_states_after_daemon_connect

3.3.33. pid_file

3.3.34. flags

3.3. `instance` section