Configuration

The configuration for lnav is stored in the following JSON files in ~/.lnav:

  • config.json – Contains local customizations that were done using the :config command.

  • 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.

  • configs/installed/*.json – Contains configuration files installed using the -i flag (e.g. $ lnav -i /path/to/config.json).

  • 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.

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.

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

  • 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

  • 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

  • offset-time

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

Styling for hidden fields

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

additionalProperties

False

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

Styles for syntax highlighting in text files.

type

object

properties

  • 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

  • number

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

Styling for numbers 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

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

  • 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.

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.

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

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

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