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

  • black

  • red

  • green

  • yellow

  • blue

  • magenta

  • cyan

  • white

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

  • 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

  • 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

additionalProperties

False

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

Styles for syntax highlighting in text files.

type

object

properties

  • 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

  • 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

/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

  • 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

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

Internal settings

type

object

properties

  • archive-manager

/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

additionalProperties

False