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 :external-access port api-key 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 :external-access-login [app] command can also be used to login.

Note

The server only binds to 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 X-Api-Key header with the Base64-encoded value of the API-key that was passed to the :external-access command. This header should be used for automations.

• An lnav_session_id cookie. This cookie will be set through the flow initiated by the :external-access-login [app] command that opens the /login URL using the configured external-opener. The /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:

• GET /api/version

  Get the version of the lnav instance.

• POST /api/exec

  Content-Type: text/x-lnav-script

  Execute an lnav script and receive the resulting output.

• POST /api/poll

  Content-Type: application/json

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

  • 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 view_states/log_selection field is the only stable field and refers to the focused message in the LOG view.

  • 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 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 :external-access-login [app] command. An app ID has the form <publisher>/<app-name> (e.g. lnav/api-test).

Creating an app can be done using the management CLI, like so:

lnav -m apps create mydash

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

Test Harness

The 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:

/apps

Application definitions
type	object
patternProperties
^([\w\-]+)$	/apps/<publisher>
	The publisher of the application
	type	object
	patternProperties
	^([\w\-]+)$	/apps/<publisher>/<app_name>
		The application definition
		type	object
		properties
		root	/apps/<publisher>/<app_name>/root
			The path to use as the root for files that are a part of this application. The path is relative to the location of the file containing this property.
			type	string
			pattern	[\w\-\.]+
		description	/apps/<publisher>/<app_name>/description
			A description of this application
			type	string
		additionalProperties	False
	additionalProperties	False
additionalProperties	False