.. _ExternalAccess:

External Access (v0.14.0+)

The "External Access" feature opens a local HTTP port that can be used to interact with an lnav instance outside of the TUI. This feature can be enabled with the :ref:external_access command. Once the port is open, HTTP requests can be sent to access static files, execute commands, or poll for changes. When the external port is open, a globe icon (🌐) is displayed in the top-right corner. Clicking that icon will open a URL in a browser and log you into the server. The :ref:external_access_login command can also be used to login.

.. note:: The server only binds to :code:localhost, so it will not be accessible over the network. If you need to access lnav remotely, consider using SSH forwarding.

Authentication

All requests to lnav's external access server are authenticated. A request must have one of the following:

• An :code:X-Api-Key header with the Base64-encoded value of the API-key that was passed to the :code::external-access command. This header should be used for automations.
• An :code:lnav_session_id cookie. This cookie will be set through the flow initiated by the :ref:external_access_login command that opens the :code:/login URL using the configured :ref:external-opener<config_external_opener>. The :code:/login URL accepts a one-time-password query parameter and, if it matches, the session cookie will be created. A single one-time-password is possible at any time and sessions are only valid for the current invocation of lnav.

Endpoints

The following routes are available:

• | :code:GET /api/version

  Get the version of the lnav instance.

• | :code:POST /api/exec | :code:Content-Type: text/x-lnav-script

  Execute an lnav :ref:script<scripts> and receive the resulting output.

• | :code:POST /api/poll | :code:Content-Type: application/json

  Perform a long-poll of lnav's TUI state. The first request to this API should be a :code:null to get the current state. The response contains the following fields:

  • :code:next_input - Subsequent calls should send this object so the server knows when there has been a state-change with respect to this client. Currently, the :code:view_states/log_selection field is the only stable field and refers to the focused message in the LOG view.
  • :code:background_tasks - A list of background task progress updates.

Apps

To support custom user-interfaces on top of lnav, "apps" can be installed that are reachable via the external access server. These browser-based apps can provide a rich interface for executing queries and presenting their results. For example, a dashboard for :code:access_log files can display multiple charts for interesting request statistics. Apps are reachable from the landing page for the external access server or you can open one directly by passing its ID to the :ref:external_access_login command. An app ID has the form :code:<publisher>/<app-name> (e.g. :code:lnav/api-test).

Creating an app can be done using the :ref:management CLI<management_cli>, like so:

.. code-block:: bash

lnav -m apps create mydash

This command creates a directory in the :file:configs directory and populates it with the necessary configuration file and a sample :file:index.md file.

Test Harness ^^^^^^^^^^^^

The :code:lnav/api-test app is included by default as a demonstration of the external access server APIs.

Reference ^^^^^^^^^

The following are the configuration properties necessary to define an app:

.. jsonschema:: ../schemas/config-v1.schema.json#/properties/apps