Getting Started
***************

Installation
============

check `README.md` how to install LN.

.. only:: rmc

    .. RMC-specific section, which is only added when "-a -t rmc" is added to the
       sphinx-build command.
    .. for info on how this works, see:
       https://ourpython.com/python/how-can-i-configure-sphinx-to-conditionally-exclude-some-pages


    Environment setup on RMC systems
    ================================

    to setup your environment with our conan install you can do::

      conan install --requires=links_and_nodes_manager/[~2]@common/stable -of conan -pr:a $DLRRM_HOST_PLATFORM
      source conan/conanrun.sh

    Here, you should replace
    "links_and_nodes_manager/[~2]@common/stable" by the current LN
    version, which is "|DOCUMENTED_LN_MANAGER_VERSION|".


    See the :doc:`rmc_localguide` section in the Appendix for detailed further information.

    .. todo: maybe find simple/short cissy command

Test your Installation
======================

to test whether your LN install was successful and whether your environment is
setup correctly try to execute::

  python3 -c "import links_and_nodes"
  ln_manager --help

this should not output any errors and you should see the ln-manager help::

  2022-03-16 15:25:01.79 info    Manager:           ln_manager <source tree>
  2022-03-16 15:25:01.79 info    Manager:           python3.6 from /opt/python/osl153-x86_64/python3/stable/1.4.4/bin/python3.6 on linux-x86_64

  usage: ln_manager [-h] [GENERIC_OPTIONS] ( -c config_filename [NEW_MANAGER_OPTIONS] | --connect HOST_OR_IP:PORT )

  STARTUP MODE:
          -c config_filename      read configuration from given file and start a manager
          --connect HOST_OR_IP:PORT
                                  connect to an already running manager

  GENERIC_OPTIONS:
          -h                      show this usage info and exit
          --log-level LEVEL       sets the log-level. valid values are: debug, info, warning, error
          --without-gui           start without gui
          --webui                 start without GUI, open /lnm/ in browser
          --present               present manager window after startup
          --profile               collect cProfile data and write to ln_manager.stats
          --show-stats fn         read cProfile file fn and print stats
          --console               start command console
          --console-exec CMD      start console and execute CMD
          --mi-console            start command console in machine-interface-mode

  NEW_MANAGER_OPTIONS:
          -i instance_name        overwrite configured the name of this ln-instance!
          -p PORT                 overwrite configured manager listening port
          --start NAME            starts process/state or group NAME after manager startup (can be specified multiple times)
          --export-hosts SSHCFG   read given ln-config file (maybe only hosts.inc.lnc?) and generate ssh config file
          --isolated-test         use unique, generated instance-name & manager-port and use private ln_daemon on localhost


ln_manager Consoles
===================

ln_manager also provides interactive command-line consoles in addition to the
GUI.

``--console``
  starts a console intended for interactive use by a human.

``--mi-console``
  starts a console with a more machine-oriented interface. This is useful when
  driving ln_manager from scripts or other tools and when parsing replies and
  notifications programmatically.

Both modes are useful for lightweight remote control tasks such as inspecting
the current manager state, starting or stopping processes, reloading the
configuration, or attaching to process output without using the GUI.

You can either start a new manager with a console on the current terminal, or
connect a console to an already running manager.

For example, to start a new manager and use only the console without opening
the GTK GUI::

  ln_manager -c path/to/config.lnc --console --without-gui

To connect to an already running manager and open the machine-interface
console, specify the host name or IP address and port of that manager::

  ln_manager --connect HOST_OR_IP:PORT --mi-console

Inside the console, use ``help`` to list the available commands and
``help COMMAND`` to show command-specific usage information.

``--webui``
  starts without the GUI and opens the built-in ``/lnm/`` URL in the user's
  browser with ``xdg-open``. When combined with ``--connect``, it only opens
  that URL for the target manager and then exits immediately.