Configuration

The configuration for lnav is stored in the following JSON files where <lnav-home> refers to the location in the HOME directory where files are stored, either (~/.lnav or ~/.config/lnav):

  1. Builtin – The default configuration is shipped inside the lnav binary.

  2. /etc/lnav/configs/*/*.json – System-wide configuration files can be installed here to make it available to all users.

  3. <lnav-home>/configs/default/*.json – The default configuration files that are built into lnav are written to this directory with .sample appended. Removing the .sample extension and editing the file will allow you to do basic customizations.

  4. <lnav-home>/configs/*/*.json – Other directories that contain *.json files will be loaded on startup. This structure is convenient for installing lnav configurations, like from a git repository. The configs/installed directory is reserved for files that are installed using the -i flag (e.g. $ lnav -i /path/to/config.json).

  5. -I <path>/configs/*/*.json – Include directories passed on the command-line can have a configs directory that will also be searched.

  6. <lnav-home>/config.json – Contains local customizations that were done using the :config command.

A valid lnav configuration file must contain an object with the $schema property, like so:

{
    "$schema": "https://lnav.org/schemas/config-v1.schema.json"
}

Note

Log format definitions are stored separately in the ~/.lnav/formats directly. See the Log Formats chapter for more information.

Note

Configuration files are read in the above directory order and sorted by path name. The internal configuration is updated as files are parsed, so one file can overwrite the settings from another. You can use the Management CLI to get the final configuration and where the value came from for a particular configuration option.

Options

The following configuration options can be used to customize the lnav UI to your liking. The options can be changed using the :config command.

/ui/keymap

The name of the keymap to use.

type

string

/ui/theme

The name of the theme to use.

type

string

/ui/clock-format

The format for the clock displayed in the top-left corner using strftime(3) conversions

type

string

examples

%a %b %d %H:%M:%S %Z

/ui/dim-text

Reduce the brightness of text (useful for xterms). This setting can be useful when running in an xterm where the white color is very bright.

type

boolean

/ui/default-colors

Use default terminal background and foreground colors instead of black and white for all text coloring. This setting can be useful when transparent background or alternate color theme terminal is used.

type

boolean

Theme Definitions

User Interface themes are defined in a JSON configuration file. A theme is made up of the style definitions for different types of text in the UI. A definition can include the foreground/background colors and the bold/underline attributes. The style definitions are broken up into multiple categories for the sake of organization. To make it easier to write a definition, a theme can define variables that can be referenced as color values.

Variables

The vars object in a theme definition contains the mapping of variable names to color values. These variables can be referenced in style definitions by prefixing them with a dollar-sign (e.g. $black). The following variables can also be defined to control the values of the ANSI colors that are log messages or plain text:

ANSI colors

Variable Name

ANSI Escape

black

ESC[30m

red

ESC[31m

green

ESC[32m

yellow

ESC[33m

blue

ESC[34m

magenta

ESC[35m

cyan

ESC[36m

white

ESC[37m

Specifying Colors

Colors can be specified using hexadecimal notation by starting with a hash (e.g. #aabbcc) or using a color name as found at http://jonasjacek.github.io/colors/. If colors are not specified for a style, the values from the styles/text definition.

Note

When specifying colors in hexadecimal notation, you do not need to have an exact match in the XTerm 256 color palette. A best approximation will be picked based on the CIEDE2000 color difference algorithm.

Example

The following example sets the black/background color for text to a dark grey using a variable and sets the foreground to an off-white. This theme is incomplete, but it works enough to give you an idea of how a theme is defined. You can copy the code block, save it to a file in ~/.lnav/configs/installed/ and then activate it by executing :config /ui/theme example in lnav. For a more complete theme definition, see one of the definitions built into lnav, like monocai.

{
    "$schema": "https://lnav.org/schemas/config-v1.schema.json",
    "ui": {
        "theme-defs": {
            "example1": {
                "vars": {
                    "black": "#2d2a2e"
                },
                "styles": {
                    "text": {
                        "color": "#f6f6f6",
                        "background-color": "$black"
                    }
                }
            }
        }
    }
}

Reference

/ui/theme-defs/<theme_name>/vars

Variables definitions that are used in this theme.

type

object

patternProperties

  • ^(\w+)$

/ui/theme-defs/<theme_name>/vars/<var_name>

A theme variable definition

type

string

additionalProperties

False

/ui/theme-defs/<theme_name>/styles

Styles for log messages.

type

object

properties

  • identifier

/ui/theme-defs/<theme_name>/styles/identifier

Styling for identifiers in logs

style

  • text

/ui/theme-defs/<theme_name>/styles/text

Styling for plain text

style

  • selected-text

/ui/theme-defs/<theme_name>/styles/selected-text

Styling for text selected in a view

style

  • alt-text

/ui/theme-defs/<theme_name>/styles/alt-text

Styling for plain text when alternating

style

  • error

/ui/theme-defs/<theme_name>/styles/error

Styling for error messages

style

  • ok

/ui/theme-defs/<theme_name>/styles/ok

Styling for success messages

style

  • info

/ui/theme-defs/<theme_name>/styles/info

Styling for informational messages

style

  • warning

/ui/theme-defs/<theme_name>/styles/warning

Styling for warning messages

style

  • hidden

/ui/theme-defs/<theme_name>/styles/hidden

Styling for hidden fields in logs

style

  • cursor-line

/ui/theme-defs/<theme_name>/styles/cursor-line

Styling for the cursor line in the main view

style

  • disabled-cursor-line

/ui/theme-defs/<theme_name>/styles/disabled-cursor-line

Styling for the cursor line when it is disabled

style

  • adjusted-time

/ui/theme-defs/<theme_name>/styles/adjusted-time

Styling for timestamps that have been adjusted

style

  • skewed-time

/ui/theme-defs/<theme_name>/styles/skewed-time

Styling for timestamps that are different from the received time

style

  • file-offset

/ui/theme-defs/<theme_name>/styles/file-offset

Styling for a file offset

style

  • offset-time

/ui/theme-defs/<theme_name>/styles/offset-time

Styling for the elapsed time column

style

  • invalid-msg

/ui/theme-defs/<theme_name>/styles/invalid-msg

Styling for invalid log messages

style

  • popup

/ui/theme-defs/<theme_name>/styles/popup

Styling for popup windows

style

  • focused

/ui/theme-defs/<theme_name>/styles/focused

Styling for a focused row in a list view

style

  • disabled-focused

/ui/theme-defs/<theme_name>/styles/disabled-focused

Styling for a disabled focused row in a list view

style

  • scrollbar

/ui/theme-defs/<theme_name>/styles/scrollbar

Styling for scrollbars

style

  • h1

/ui/theme-defs/<theme_name>/styles/h1

Styling for top-level headers

style

  • h2

/ui/theme-defs/<theme_name>/styles/h2

Styling for 2nd-level headers

style

  • h3

/ui/theme-defs/<theme_name>/styles/h3

Styling for 3rd-level headers

style

  • h4

/ui/theme-defs/<theme_name>/styles/h4

Styling for 4th-level headers

style

  • h5

/ui/theme-defs/<theme_name>/styles/h5

Styling for 5th-level headers

style

  • h6

/ui/theme-defs/<theme_name>/styles/h6

Styling for 6th-level headers

style

  • hr

/ui/theme-defs/<theme_name>/styles/hr

Styling for horizontal rules

style

  • hyperlink

/ui/theme-defs/<theme_name>/styles/hyperlink

Styling for hyperlinks

style

  • list-glyph

/ui/theme-defs/<theme_name>/styles/list-glyph

Styling for glyphs that prefix a list item

style

  • breadcrumb

/ui/theme-defs/<theme_name>/styles/breadcrumb

Styling for the separator between breadcrumbs

style

  • table-border

/ui/theme-defs/<theme_name>/styles/table-border

Styling for table borders

style

  • table-header

/ui/theme-defs/<theme_name>/styles/table-header

Styling for table headers

style

  • quote-border

/ui/theme-defs/<theme_name>/styles/quote-border

Styling for quoted-block borders

style

  • quoted-text

/ui/theme-defs/<theme_name>/styles/quoted-text

Styling for quoted text blocks

style

  • footnote-border

/ui/theme-defs/<theme_name>/styles/footnote-border

Styling for footnote borders

style

  • footnote-text

/ui/theme-defs/<theme_name>/styles/footnote-text

Styling for footnote text

style

  • snippet-border

/ui/theme-defs/<theme_name>/styles/snippet-border

Styling for snippet borders

style

  • indent-guide

/ui/theme-defs/<theme_name>/styles/indent-guide

Styling for indent guide lines

style

additionalProperties

False

/ui/theme-defs/<theme_name>/syntax-styles

Styles for syntax highlighting in text files.

type

object

properties

  • inline-code

/ui/theme-defs/<theme_name>/syntax-styles/inline-code

Styling for inline code blocks

style

  • quoted-code

/ui/theme-defs/<theme_name>/syntax-styles/quoted-code

Styling for quoted code blocks

style

  • code-border

/ui/theme-defs/<theme_name>/syntax-styles/code-border

Styling for quoted-code borders

style

  • keyword

/ui/theme-defs/<theme_name>/syntax-styles/keyword

Styling for keywords in source files

style

  • string

/ui/theme-defs/<theme_name>/syntax-styles/string

Styling for single/double-quoted strings in text

style

  • comment

/ui/theme-defs/<theme_name>/syntax-styles/comment

Styling for comments in source files

style

  • doc-directive

/ui/theme-defs/<theme_name>/syntax-styles/doc-directive

Styling for documentation directives in source files

style

  • variable

/ui/theme-defs/<theme_name>/syntax-styles/variable

Styling for variables in text

style

  • symbol

/ui/theme-defs/<theme_name>/syntax-styles/symbol

Styling for symbols in source files

style

  • null

/ui/theme-defs/<theme_name>/syntax-styles/null

Styling for nulls in source files

style

  • ascii-control

/ui/theme-defs/<theme_name>/syntax-styles/ascii-control

Styling for ASCII control characters in source files

style

  • non-ascii

/ui/theme-defs/<theme_name>/syntax-styles/non-ascii

Styling for non-ASCII characters in source files

style

  • number

/ui/theme-defs/<theme_name>/syntax-styles/number

Styling for numbers in source files

style

  • type

/ui/theme-defs/<theme_name>/syntax-styles/type

Styling for types in source files

style

  • function

/ui/theme-defs/<theme_name>/syntax-styles/function

Styling for functions in source files

style

  • separators-references-accessors

/ui/theme-defs/<theme_name>/syntax-styles/separators-references-accessors

Styling for sigils in source files

style

  • re-special

/ui/theme-defs/<theme_name>/syntax-styles/re-special

Styling for special characters in regular expressions

style

  • re-repeat

/ui/theme-defs/<theme_name>/syntax-styles/re-repeat

Styling for repeats in regular expressions

style

  • diff-delete

/ui/theme-defs/<theme_name>/syntax-styles/diff-delete

Styling for deleted lines in diffs

style

  • diff-add

/ui/theme-defs/<theme_name>/syntax-styles/diff-add

Styling for added lines in diffs

style

  • diff-section

/ui/theme-defs/<theme_name>/syntax-styles/diff-section

Styling for diffs

style

  • spectrogram-low

/ui/theme-defs/<theme_name>/syntax-styles/spectrogram-low

Styling for the lower threshold values in the spectrogram view

style

  • spectrogram-medium

/ui/theme-defs/<theme_name>/syntax-styles/spectrogram-medium

Styling for the medium threshold values in the spectrogram view

style

  • spectrogram-high

/ui/theme-defs/<theme_name>/syntax-styles/spectrogram-high

Styling for the high threshold values in the spectrogram view

style

  • file

/ui/theme-defs/<theme_name>/syntax-styles/file

Styling for file names in source files

style

additionalProperties

False

/ui/theme-defs/<theme_name>/status-styles

Styles for the user-interface components.

type

object

properties

  • text

/ui/theme-defs/<theme_name>/status-styles/text

Styling for status bars

style

  • warn

/ui/theme-defs/<theme_name>/status-styles/warn

Styling for warnings in status bars

style

  • alert

/ui/theme-defs/<theme_name>/status-styles/alert

Styling for alerts in status bars

style

  • active

/ui/theme-defs/<theme_name>/status-styles/active

Styling for activity in status bars

style

  • inactive-alert

/ui/theme-defs/<theme_name>/status-styles/inactive-alert

Styling for inactive alert status bars

style

  • inactive

/ui/theme-defs/<theme_name>/status-styles/inactive

Styling for inactive status bars

style

  • title-hotkey

/ui/theme-defs/<theme_name>/status-styles/title-hotkey

Styling for hotkey highlights in titles

style

  • title

/ui/theme-defs/<theme_name>/status-styles/title

Styling for title sections of status bars

style

  • disabled-title

/ui/theme-defs/<theme_name>/status-styles/disabled-title

Styling for title sections of status bars

style

  • subtitle

/ui/theme-defs/<theme_name>/status-styles/subtitle

Styling for subtitle sections of status bars

style

  • info

/ui/theme-defs/<theme_name>/status-styles/info

Styling for informational messages in status bars

style

  • hotkey

/ui/theme-defs/<theme_name>/status-styles/hotkey

Styling for hotkey highlights of status bars

style

  • suggestion

/ui/theme-defs/<theme_name>/status-styles/suggestion

Styling for suggested values

style

additionalProperties

False

/ui/theme-defs/<theme_name>/log-level-styles

Styles for each log message level.

type

object

patternProperties

  • ^(trace | debug5 | debug4 | debug3 | debug2 | debug | info | stats | notice | warning | error | critical | fatal | invalid)$

/ui/theme-defs/<theme_name>/log-level-styles/<level>

style

additionalProperties

False

style

type

object

properties

  • color

/color

The foreground color value for this style. The value can be the name of an xterm color, the hexadecimal value, or a theme variable reference.

type

string

examples

#fff

Green

$black

  • background-color

/background-color

The background color value for this style. The value can be the name of an xterm color, the hexadecimal value, or a theme variable reference.

type

string

examples

#2d2a2e

Green

  • underline

/underline

Indicates that the text should be underlined.

type

boolean

  • bold

/bold

Indicates that the text should be bolded.

type

boolean

additionalProperties

False

Keymap Definitions

Keymaps in lnav map a key sequence to a command to execute. When a key is pressed, it is converted into a hex-encoded string that is looked up in the keymap. The command value associated with the entry in the keymap is then executed. Note that the “command” can be an lnav command, a SQL statement/query, or an lnav script. If an alt-msg value is included in the entry, the bottom-right section of the UI will be updated with the help text.

Note

Not all functionality is available via commands or SQL at the moment. Also, some hotkeys are not implemented via keymaps.

Key Sequence Encoding

Key presses are converted into a hex-encoded string that is used to lookup an entry in the keymap. Each byte of the keypress value is formatted as an x followed by the hex-encoding in lowercase. For example, the encoding for the £ key would be xc2xa3. To make it easier to discover the encoding for unassigned keys, lnav will print in the command prompt the :config command and JSON-Pointer for assigning a command to the key.

_images/key-encoding-prompt.png

Screenshot of the command prompt when an unassigned key is pressed.

Note

Since lnav is a terminal application, it can only receive keypresses that can be represented as characters or escape sequences. For example, it cannot handle the press of a modifier key.

Reference

/ui/keymap-defs/<keymap_name>

The keymap definitions

type

object

patternProperties

  • ^((?:x[0-9a-f]{2})+)$

/ui/keymap-defs/<keymap_name>/<key_seq>

Map of key codes to commands to execute. The field names are the keys to be mapped using as a hexadecimal representation of the UTF-8 encoding. Each byte of the UTF-8 should start with an ‘x’ followed by the hexadecimal representation of the byte.

type

object

properties

  • id

/ui/keymap-defs/<keymap_name>/<key_seq>/id

The identifier that can be used to refer to this key

type

string

  • command

/ui/keymap-defs/<keymap_name>/<key_seq>/command

The command to execute for the given key sequence. Use a script to execute more complicated operations.

type

string

examples

:goto next hour

pattern

^$|^[:|;].*

  • alt-msg

/ui/keymap-defs/<keymap_name>/<key_seq>/alt-msg

The help message to display after the key is pressed.

type

string

additionalProperties

False

additionalProperties

False

Log Handling

The handling of logs is largely determined by the log file formats, this section covers options that are not specific to a particular format.

Timezone Conversion (v0.12.0+)

Log messages that have a numeric timezone, like -03:00 or Z for UTC, will be converted to the local timezone as given by the TZ environment variable. For example, a timestamp ending in -03:00 will be treated as three hours behind UTC and then adjusted to the local timezone.

This behavior can be disabled by setting the /log/date-time/convert-zoned-to-local configuration property to false.

Watch Expressions (v0.11.0+)

Watch expressions can be used to fire an event when a log message matches a condition. You can then install a listener for these events and trigger an action to be performed. For example, to automate filtering based on identifiers, a watch expression can match messages that mention the ID and then a trigger can install a filter for that ID. Creating a watch expression is done by adding an entry into the /log/watch-expressions configuration tree. For example, to create a watch named “dhcpdiscover” that matches DHCPDISCOVER messages from the dhclient daemon, you would run the following:

:config /log/watch-expressions/dhcpdiscover/expr :log_procname = 'dhclient' AND startswith(:log_body, 'DHCPDISCOVER')

The watch expression can refer to column names in the log message by prefixing them with a colon. The expression is evaluated by passing the log message fields as bound parameters and not against a table. The easiest way to test out an expression is with the :mark-expr expr command, since it will behave similarly. After changing the configuration, you’ll need to restart lnav for the effect to take place. You can then query the lnav_events table to see any generated https://lnav.org/event-log-msg-detected-v1.schema.json events from the logs that were loaded:

;SELECT * FROM lnav_events

From there, you can create a SQLite trigger on the lnav_events table that will examine the event contents and perform an action. See the Events (v0.11.0+) section for more information on handling events.

Annotations (v0.12.0+)

Annotations are content generated by a script for a given log message and displayed along with the message, like comments and tags. Since the script is run asynchronously, it can do complex analysis without delaying loading or interrupting the viewing experience. An annotation is defined by a condition and a handler in the lnav configuration. The condition is tested against a log message to determine if the annotation is applicable. If it is, the handler script will be executed for that log message when the user runs the :annotate command.

Conditions are SQLite expressions like the ones passed to :filter-expr where the expression is appended to SELECT 1 WHERE. The expression can use bound variables that correspond to the columns that would be in the format table and are prefixed by a colon (:). For example, the standard log_opid table column can be access by using :log_opid.

Note

The expression is executed with bound variables because it can be applied to log messages from multiple formats. Writing an expression that could handle different formats would be more challenging. In this approach, variables for log message fields that are not part of a format will evaluate to NULL.

Handlers are executable script files that should be co-located with the configuration file that defined the annotation. The handler will be executed and a JSON object with log message data fed in on the standard input. The handler should then generate the annotation content on the standard output. The output is treated as Markdown, so the content can be styled as desired.

Reference

/log/watch-expressions/<watch_name>

A log message watch expression

type

object

properties

  • expr

/log/watch-expressions/<watch_name>/expr

The SQL expression to execute for each input line. If expression evaluates to true, a ‘log message detected’ event will be published.

type

string

  • enabled

/log/watch-expressions/<watch_name>/enabled

Indicates whether or not this expression should be evaluated during log processing.

type

boolean

additionalProperties

False

/log/annotations/<annotation_name>

type

object

properties

  • description

/log/annotations/<annotation_name>/description

A description of this annotation

type

string

  • condition

/log/annotations/<annotation_name>/condition

The SQLite expression to execute for a log message that determines whether or not this annotation is applicable. The expression is evaluated the same way as a filter expression

type

string

minLength

1

  • handler

/log/annotations/<annotation_name>/handler

The script to execute to generate the annotation content. A JSON object with the log message content will be sent to the script on the standard input

type

string

minLength

1

additionalProperties

False

Tuning

The following configuration options can be used to tune the internals of lnav to your liking. The options can be changed using the :config command.

/tuning/archive-manager

Settings related to opening archive files

type

object

properties

  • min-free-space

/tuning/archive-manager/min-free-space

The minimum free space, in bytes, to maintain when unpacking archives

type

integer

minimum

0

  • cache-ttl

/tuning/archive-manager/cache-ttl

The time-to-live for unpacked archives, expressed as a duration (e.g. ‘3d’ for three days)

type

string

examples

3d

12h

additionalProperties

False

/tuning/clipboard

Settings related to the clipboard

type

object

properties

  • impls

/tuning/clipboard/impls

Clipboard implementations

type

object

patternProperties

  • ^([\w\-]+)$

/tuning/clipboard/impls/<clipboard_impl_name>

Clipboard implementation

type

object

properties

  • test

/tuning/clipboard/impls/<clipboard_impl_name>/test

The command that checks

type

string

examples

command -v pbcopy

  • general

/tuning/clipboard/impls/<clipboard_impl_name>/general

Commands to work with the general clipboard

clip-commands

  • find

/tuning/clipboard/impls/<clipboard_impl_name>/find

Commands to work with the find clipboard

clip-commands

additionalProperties

False

additionalProperties

False

additionalProperties

False

/tuning/piper

Settings related to capturing piped data

type

object

properties

  • max-size

/tuning/piper/max-size

The maximum size of a capture file

type

integer

minimum

128

  • rotations

/tuning/piper/rotations

The number of rotated files to keep

type

integer

minimum

2

  • ttl

/tuning/piper/ttl

The time-to-live for captured data, expressed as a duration (e.g. ‘3d’ for three days)

type

string

examples

3d

12h

additionalProperties

False

clip-commands

Container for the commands used to read from and write to the system clipboard

type

object

properties

  • write

/write

The command used to write to the clipboard

type

string

examples

pbcopy

  • read

/read

The command used to read from the clipboard

type

string

examples

pbpaste

additionalProperties

False

/tuning/file-vtab

Settings related to the lnav_file virtual-table

type

object

properties

  • max-content-size

/tuning/file-vtab/max-content-size

The maximum allowed file size for the content column

type

integer

minimum

0

additionalProperties

False

/tuning/logfile

Settings related to log files

type

object

properties

  • max-unrecognized-lines

/tuning/logfile/max-unrecognized-lines

The maximum number of lines in a file to use when detecting the format

type

integer

minimum

1

additionalProperties

False

/tuning/remote/ssh

Settings related to the ssh command used to contact remote machines

type

object

properties

  • command

/tuning/remote/ssh/command

The SSH command to execute

type

string

  • transfer-command

/tuning/remote/ssh/transfer-command

Command executed on the remote host when transferring the file

type

string

  • start-command

/tuning/remote/ssh/start-command

Command executed on the remote host to start the tailer

type

string

  • flags

/tuning/remote/ssh/flags

The flags to pass to the SSH command

type

string

  • options

/tuning/remote/ssh/options

The options to pass to the SSH command

type

object

patternProperties

  • ^(\w+)$

/tuning/remote/ssh/options/<option_name>

Set an option to be passed to the SSH command

type

string

additionalProperties

False

  • config

/tuning/remote/ssh/config

The ssh_config options to pass to SSH with the -o option

type

object

patternProperties

  • ^(\w+)$

/tuning/remote/ssh/config/<config_name>

Set an SSH configuration value

type

string

additionalProperties

False

additionalProperties

False

/tuning/url-scheme

Settings related to custom URL handling

type

object

patternProperties

  • ^([a-z][\w\-\+\.]+)$

/tuning/url-scheme/<url_scheme>

Definition of a custom URL scheme

type

object

properties

  • handler

/tuning/url-scheme/<url_scheme>/handler

The name of the lnav script that can handle URLs with of this scheme. This should not include the ‘.lnav’ suffix.

type

string

pattern

^[\w\-]+(?!\.lnav)$

additionalProperties

False

additionalProperties

False