3.4. `hosts` section

hosts-sections can be used to specify per-host settings. these include ip-addresses, ln_daemon-start-commands, authentication settings and more, as described below.

it is not needed to always have a hosts-section, ln_manager will guess reasonable default values and will use the systems name-resolver to get ip-addresses when trying to contact remote hosts.

The left-hand side of a hosts entry should normally be a real physical host name: the name of a machine as known to DNS, SSH, /etc/hosts, or your local network documentation. The hosts section is the LN configuration’s place to describe physical machines and their interfaces. It can be used as a portable layer on top of /etc/hosts when a setup needs fixed interface names, fixed IP addresses, daemon start settings, or authentication settings.

Use node_map section if you want stable logical names such as nodeA, robot or camera_pc in process definitions while keeping the physical host names in one place.

syntax:

HOSTS_SECTION := "hosts\n" + HOST_SPEC*
HOST_SPEC := HOST_NAME + ": " + HOST_SETTINGS + "\n"
HOST_SETTINGS := HOST_SETTING + [ ", " + HOST_SETTING ]*
HOST_SETTING := SETTING-NAME + ":" + SETTING-VALUE

example:

hosts
localhost: process_start_rate_limit:5
rmc-mobilproxy: ens3:129.247.189.41, ens10:192.168.128.1

in this example, at most 5 processes per second will be started on localhost. for rmc-mobilproxy we specify two ip-addresses with assigned interface-names ens3 and ens10.

an ln-config file can have multiple hosts-sections. they will be merged – later ones can overwrite settings or add more interfaces.

valid settings:

3.4.1. <interface-name>

any <SETTING-NAME> that does not match one of the below listed, known settings, will be assumed to be an interface-name. <SETTING-VALUE> in this case has to be a valid IPv4-address in dotted-decimal form. example:

en0:129.247.189.41

the interface name is only used to refer to that interface. it doesn’t have to match the actual interface name.

3.4.2. process_start_rate_limit

this setting can be used to limit how many processes are started per second at most on this host. without this setting there is no limit. this can lead to an unresponsive system if you try to start many processes “at once”. example:

process_start_rate_limit:2

will only allow 2 processes to be started within the same second on this host.

3.4.3. add_process_default_template

registers a default use_template specification that is applied automatically to processes started on this host.

example:

add_process_default_template: shell with home("robot_home", "echo hello")

these host-local defaults are applied after the global add_process_default_template: ... directives. a process can disable them with the no_host_default_templates flag.

3.4.4. daemon_start_script

in case ln_manager can not contact an already running daemon, it will try to start a new one. this setting can be used to specify the command that should be used.

default is:

<LN_PREFIX>/bin/ln_daemon

where <LN_PREFIX> depends on how LN was installed on your system.

this default can be overwritten by environment variable LN_DAEMON_START to set a new site-local start-command (e.g., via conan’s package_info() method).

it can be set to special value none to NOT have the manager try to start a daemon here.

can also be set globally via instance-daemon_start_script.

3.4.5. daemon_log_file

when ln_manager starts a new ln_daemon for this host, pass -l <FILENAME> on the daemon command line so the daemon also writes its log output into that daemon-local file.

this only affects newly started daemons that ln_manager launches itself. it does not reconfigure already running daemons.

the filename is interpreted on the daemon host itself, not on the manager host.

example:

hosts
robot_pc: daemon_log_file:/var/log/ln/daemon.log

this is independent from the manager’s own log-file settings and from the in-memory daemon-log export used by the manager’s “save all” debug-info workflow.

3.4.6. additional_ssh_arguments

LN daemons on other nodes can be started on-demand via an SSH connection.

This option passes one or more additional arguments to append to the ssh-command line when ln_manager tries to start an ln_daemon on a remote host. default is empty. they will be appended to this ssh-command:

<SSH-BINARY> -l <USERNAME> -T -v -a -x \
  -o UserKnownHostsFile=/dev/null \
  -o StrictHostKeyChecking=no \
  -o PasswordAuthentication=no \
  -o PreferredAuthentications=gssapi-with-mic,publickey \
  -K <HOST-NAME-OR-IP> <CMD>

can also be set globally via instance-additional_ssh_arguments.

3.4.7. ssh_binary

this setting can be used to cause ln_manager to use a different binary than ssh for the ssh connection.

The manager tries to use this ssh-program when a new daemon process has to be started on a remote machine. (you want to adjust this settings especially when the manager runs on a windows host)

can also be set globally via instance-ssh_binary.

3.4.8. arch

this can be an arbitrary string that will be passed to newly started ln_daemons. daemons will report this arch when ln_manager connects them. this can be used in process`-sections as runtime-variable ``$(ARCH) e.g. in the command:-field.

3.4.9. daemon_private_key_file

Specifies a private key to use for user-authentication towards daemons. This should be a DSA private key in PEM format as used by OpenSSH. Unlocked daemons will be locked with this private key on connection.

Note

to disable daemon authentication set daemon_public_key_file: none in the hosts-line for that respective host. might look like this:

hosts
miiwa2-server: daemon_public_key_file: none, expected_user: l_mobil

you should disable authentication only for hosts where you don’t login with your personal credentials. usually hosts where many people share the same local user-account (like l_mobil) and only if those local user-accounts do not store any sensitive data.

Note

LN instances use daemons, which are owned by users

LN is designed so that users start LN instances, which start and use LN daemons to communicate between LN manager, clients, and hosts. A user can start an arbitrary number of differently named LN instances at the same time, which will in turn (using system-provided arbiter processes) start any needed LN daemons on the corresponding nodes. All the daemons which are started by such instances belong to that user, and are designed to be controlled only by this user. By default, they therefore cannot be accessed by other users, and also won’t accept commands from other user IDs. This is designed that way for security and safety reasons.

To protect daemons from being used by unauthorized users/managers, they are by default started with a public-key (see daemon_public_key_file below) on their command line (see Starting LN daemons).

Note

Use of public-key authentication for accessing LN daemons

By default, the LN daemons which are started by the LN manager will be locked so that they cannot be accessed without authorization. For this, so-called public key authentication is used: A key pair is generated with one public and one matching private key. The manager which starts an LN daemon sends a public key to the daemon after starting it. When connecting again, any LN manager has to authenticate itself for the daemon by proving that it has a matching private key.

This is done by challenge-response authentication: The LN daemon sends some random data to the LN manager, and the LN manager signs that data with the corresponding private key, and sends it back. The daemon can then check the validity of this signature with the specified public-key.

This is considered to provide a state-of-the-art authentication mechanism. Due to the used set-up, reading/sniffing a cleartext TCP connection does not provide reasonable information about the private key!

But beware: it all depends on how secret your private key really is! Make sure only authorized users can read that key-file!

Warning

This does not cause the daemon-manager connection to be encrypted!

The only use of this authentication is to protect daemons from being used by unauthorized users. While starting a new daemon might make use of the ssh command, the data links in the LN system are not encrypted.

For those daemons the manager needs to know the matching private-key to authenticate itself against the daemon.

The default name is $HOME/.ssh/id_dsa_ln_daemons. If no such default key file is found, and authentication is not explicitly disabled, one with that name is automatically generated and used. The whole process should normally work automatically without any specific user intervention or configuration (apart from possibly setting up an SSH connection for automatically starting daemons).

Alternatively, keys pairs can be generated manually and stored in two files, one file for the public key, and one file for the private key. This config opion allows to specify a different public key by its file name. Currently only DSA keys in PEM-format are supported (like the ones created with OpenSSH’s ssh-keygen -m PEM -t dsa).

This can also be set globally via instance - see daemon_private_key_file.

For disabling this authentication, see the next section daemon_public_key_file.

Changing the key file for a given LN instance requires to either stop the daemon via the LN manager before stopping the manager, or to manually kill and then restart the daemon, which then updates the authentication key to the new value.

see also:

3.4.10. daemon_public_key_file

public key to use for user-authentication towards daemons. should be a DSA-encoded public key as used by OpenSSH. ln_manager will pass this public key to ln-daemons to lock them and for them to verify signatures from managers trying to authenticate themselfes. $HOME/.ssh/id_dsa_ln_daemons.pub. The value can be set to none or None to disable manager-daemon authentication for this host. You can also set it to never to disable authentication and never allow this daemon to be locked in future. (this can be useful for shared daemons on shared systems with shared user-accounts)

Warning

Disabling authentication allows to execute arbitrary commands via the daemon, including retrieval of private user data and uncontrolled movements of robots.

For safety and security reasons, this should not be done when the host controls robotic actors, or is a networked host which has access to any private or confidential data.

When the manager needs to start a new daemon and this config-key is specified, the manager passes this filename via an command line option to the newly started daemon. The file must be visible and accessible for the daemon.

Daemons started with a public key require managers to authenticate themselves with a matching private key. See daemon_private_key_file.

can also be set globally via instance - see daemon_public_key_file.

3.4.11. preferred_network

if a host is reachable via multiple networks, this setting can be used force the use of the named network.

3.4.12. expected_user

when ln_manager is contacting ln_daemons, it defaults to expect the daemon to be running as the same user. use this setting if you want to override this, e.g. if the remote host only has some few local users.

can also be set globally via instance-default_expected_user.

3.4.13. expected_user_id

similar as expected_user this can be used to require a specify user-id from the remote ln_daemon.

3.4.14. arbiter_port

ln_daemons will always start an arbiter-process per host if there is not already one running. this arbiter is usually expected to run behind port-number 54376.

3.4.15. default_change_user_to

if the ln_daemon itself is running with root-rights, this setting can be used to switch to a different user when starting processes where no specific change_user_to-setting was specified.

can also be set globally via instance-default_change_user_to.

3.4.16. requires_tunnel

this setting is useful if some other state or process has to be UP or ready before ln_manager is allowed to try to contact this host. this can be used to bring up a new interface (possibly a vpn) or start other kind of tunnels. <SETTING-VALUE> should be the name of a process or state in your config.

3.4.17. filesystems

a list of file-system names this host has access to.

Note

this is not yet used for anything.

3.4.18. lookup_aliases

boolean, whether or not to use domain-name-system to search for aliases of this host. set to false if you use host-names that are not registered with your domain-name-system:

hosts
arbitrary-name: lookup_aliases:false, ...

this will speedup ln_manager startup as it doesn’t has to wait for your DNS/name-lookup to answer.

you can see which names are looked up if you set the LN_DEBUG environment variable to 1 before starting the ln_manager.

3.4.19. skip_fw_test

boolean, default: false

whether to skip the check if this host has a firewall blocking incoming UDP or TCP connections. if skip_fw_test:false, a few UDP packets will be sent and a TCP connection established the first time the ln_manager connects it. currently this is only done in “reverse direction” as the “forward direction” is assumed to work after we made a successful connection to that daemon… (and that test can only be done when the ln_daemon connection was successful).

this will generate an error message in ln_managers log if there is a firewall detected.

3.5. `node_map` section

node_map maps logical LN node names to physical host names.

syntax:

NODE_MAP_SECTION := "node_map\n" + NODE_MAP_ENTRY*
NODE_MAP_ENTRY := NODE_NAME + ": " + HOST_NAME + "\n"

example:

node_map
camera_pc: workstation01
robot: rover_host

This is useful when process or state definitions should refer to stable logical node names, while the actual host names may differ between deployments.

A typical small setup keeps physical machines in the hosts section and uses logical node names only for process placement:

hosts
workstation01: eth0:10.0.0.11
rover_host: eth0:10.0.0.42

node_map
nodeA: workstation01
robot: rover_host

process status check
node: robot
command: /bin/date

In this example, node: robot starts the process on the physical host rover_host. If the robot computer changes later, only the node_map entry has to change; the process can keep using node: robot.

For beginner configurations, prefer this separation:

hosts describes physical host names and physical interfaces
network section member_interfaces normally refers to those physical host/interface names
node_map gives logical names to physical hosts
process node: settings use the logical names from node_map

Behavior details:

each entry maps one node name to exactly one host name
mapping a node name to a comma-separated host list is a syntax error
when ln_manager resolves a node: ... value, it first looks in node_map and only falls back to treating the value directly as a host name when no mapping exists
node-map names are also visible during config string evaluation, so %(robot) evaluates to the mapped host name if robot exists in node_map

3.6. `custom_start_tools` section

custom_start_tools adds or updates named entries in ln_manager’s process start-tool selector.

syntax:

CUSTOM_START_TOOLS_SECTION := "custom_start_tools\n" + TOOL_ENTRY*
TOOL_ENTRY := TOOL_NAME + ": " + COMMAND + "\n"

example:

custom_start_tools
rr: /usr/bin/rr record
perf: /usr/bin/perf stat

Each entry defines the command prefix to use before the actual process command when that tool is selected in the GUI.

Behavior details:

the left-hand side is the user-visible tool name
the right-hand side is the command prefix to prepend when starting the process
later entries with the same tool name overwrite earlier ones
this section extends the built-in list of start tools rather than replacing it

3.4. hosts section

3.4.1. <interface-name>

3.4.2. process_start_rate_limit

3.4.3. add_process_default_template

3.4.4. daemon_start_script

3.4.5. daemon_log_file

3.4.6. additional_ssh_arguments

3.4.7. ssh_binary

3.4.8. arch

3.4.9. daemon_private_key_file

3.4.10. daemon_public_key_file

3.4.11. preferred_network

3.4.12. expected_user

3.4.13. expected_user_id

3.4.14. arbiter_port

3.4.15. default_change_user_to

3.4.16. requires_tunnel

3.4.17. filesystems

3.4.18. lookup_aliases

3.4.19. skip_fw_test

3.5. node_map section

3.6. custom_start_tools section

3.4. `hosts` section

3.5. `node_map` section

3.6. `custom_start_tools` section