systemd.time

title: systemd.time(7)

summary: Time and date specifications

text:
# systemd.time(7)

## NAME
systemd.time - Time and date specifications

## DESCRIPTION
In systemd, timestamps, time spans, and calendar events are displayed and may be specified in closely related syntaxes.

## DISPLAYING TIME SPANS
Time spans refer to time durations. On display, systemd will present time spans as a space-separated series of time values each suffixed by a time unit. Example:

```
2h 30min
```

All specified time values are meant to be added up. The above hence refers to 150 minutes. Display is locale-independent, only English names for the time units are used.

## PARSING TIME SPANS
When parsing, systemd will accept the same time span syntax. Separating spaces may be omitted. The following time units are understood:

•usec, us, μs

•msec, ms

•seconds, second, sec, s

•minutes, minute, min, m

•hours, hour, hr, h

•days, day, d

•weeks, week, w

•months, month, M (defined as 30.44 days)

•years, year, y (defined as 365.25 days)

If no time unit is specified, generally seconds are assumed, but some exceptions exist and are marked as such. In a few cases "ns", "nsec" is accepted too, where the granularity of the time span permits this. Parsing is generally locale-independent, non-English names for the time units are not accepted.

Examples for valid time span specifications:

```
2 h
2hours
48hr
1y 12month
55s500ms
300ms20s 5day
```

One can use the timespan command of systemd-analyze(1) to normalise a textual time span for testing and validation purposes.

Internally, systemd generally operates with microsecond time granularity, while the default time unit in user-configurable time spans is usually seconds (see above). This disparity becomes visible when comparing the same settings in the (high-level) unit file syntax with the matching (more low-level) D-Bus properties (which are what systemctl(1)'s show command displays). The former typically are suffixed with "...Sec" to indicate the default unit of seconds, the latter are typically suffixed with "...USec" to indicate the underlying low-level time unit, even if they both encapsulate the very same settings.

## DISPLAYING TIMESTAMPS
Timestamps refer to specific, unique points in time. On display, systemd will format these in the local timezone as follows:

```
Fri 2012-11-23 23:02:15 CET
```

The weekday is printed in the abbreviated English language form. The formatting is locale-independent.

In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via the "UTC" timezone specifier in the output.

In some cases timestamps are shown with microsecond granularity. In this case, the sub-second remainder is separated by a full stop from the seconds component.

## PARSING TIMESTAMPS
When parsing, systemd will accept a similar syntax, but some fields can be omitted, and the space between the date and time can be replaced with a "T" (à la the RFC 3339[1] profile of ISO 8601); thus, in CET, the following are all identical: "Fri 2012-11-23 23:02:15 CET", "Fri 2012-11-23T23:02:15", "2012-11-23T23:02:15 CET", "2012-11-23 23:02:15".

The timezone defaults to the current timezone if not specified explicitly. It may be given after a space, like above, in which case it can be: "UTC", an entry in the installed IANA timezone database (e.g. "CET", "Asia/Tokyo", where the complete list can be obtained with timedatectl list-timezones (see timedatectl(1))), or "±05", "±0530", "±05:30", "Z".

It may also be affixed directly to the timestamp, in which case it must correspond to one of the formats defined in the RFC 3339[1] profile of ISO 8601: "±05:30" or "Z". Thus, the following are also identical to the above: "2012-11-23T23:02:15+01:00", "2012-11-23 22:02:15Z".

A timestamp can start with a field containing a weekday, which can be in an abbreviated ("Wed") or non-abbreviated ("Wednesday") English language form (case does not matter), regardless of the locale. However, if a weekday is specified and does not match the date, the timestamp is rejected.

If the date is omitted, it defaults to today. If the time is omitted, it defaults to 00:00:00. Fractional seconds can be specified down to 1µs precision. The seconds field can also be omitted, defaulting to 0.

There are special tokens that can be used in place of timestamps: "now" may be used to refer to the current time (or of the invocation of the command that is currently executed). "today", "yesterday", and "tomorrow" refer to 00:00:00 of the current day, the day before, or the next day, respectively.

Relative times are also accepted: a time span (see above) prefixed with "+" is evaluated to the current time plus the specified time span. Correspondingly, a time span that is prefixed with "-" is evaluated to the current time minus the specified time span. Instead of prefixing the time span with "+" or "-", it may also be suffixed with a space and the word "left" or "ago".

Finally, an integer prefixed with "@" is evaluated relative to the UNIX epoch – 1970-01-01 00:00:00 UTC.

Examples for valid timestamps and their normalized form (assuming the current time was 2012-11-23 18:15:22 and the timezone was UTC+8, for example "TZ=:Asia/Shanghai"):

```
  Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13

      2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13

  2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13

     2012-11-23T11:12:13Z → Fri 2012-11-23 19:12:13

   2012-11-23T11:12+02:00 → Fri 2012-11-23 17:12:00

               2012-11-23 → Fri 2012-11-23 00:00:00

                 12-11-23 → Fri 2012-11-23 00:00:00

                 11:12:13 → Fri 2012-11-23 11:12:13

                    11:12 → Fri 2012-11-23 11:12:00

                      now → Fri 2012-11-23 18:15:22

                    today → Fri 2012-11-23 00:00:00

                today UTC → Fri 2012-11-23 16:00:00

                yesterday → Fri 2012-11-22 00:00:00

                 tomorrow → Fri 2012-11-24 00:00:00
tomorrow Pacific/Auckland → Thu 2012-11-23 19:00:00

                 +3h30min → Fri 2012-11-23 21:45:22

                      -5s → Fri 2012-11-23 18:15:17

                11min ago → Fri 2012-11-23 18:04:22

              @1395716396 → Tue 2014-03-25 03:59:56
```

Note that timestamps displayed by remote systems with a non-matching timezone are usually not parsable locally, as the timezone component is not understood (unless it happens to be "UTC").

Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated by a full stop from the seconds component. Example:

```
2014-03-25 03:59:56.654563
```

In some cases, systemd will display a relative timestamp (relative to the current time, or the time of invocation of the command) instead of or in addition to an absolute timestamp as described above. A relative timestamp is formatted as follows:

```
2 months 5 days ago
```

Note that a relative timestamp is also accepted where a timestamp is expected (see above).

Use the timestamp command of systemd-analyze(1) to validate and normalize timestamps for testing purposes.

## CALENDAR EVENTS
Calendar events may be used to refer to one or more points in time in a single expression. They form a superset of the absolute timestamps explained above:

```
Thu,Fri 2012-*-1,5 11:12:13
```

The above refers to 11:12:13 of the first or fifth day of any month of the year 2012, but only if that day is a Thursday or Friday.

The weekday specification is optional. If specified, it should consist of one or more English language weekday names, either in the abbreviated (Wed) or non-abbreviated (Wednesday) form (case does not matter), separated by commas. Specifying two weekdays separated by ".." refers to a range of continuous weekdays. "," and ".." may be combined freely.

In the date and time specifications, any component may be specified as "*" in which case any value will match. Alternatively, each component can be specified as a list of values separated by commas. Values may be suffixed with "/" and a repetition value, which indicates that the value itself and the value plus all multiples of the repetition value are matched. Two values separated by ".." may be used to indicate a range of values; ranges may also be followed with "/" and a repetition value, in which case the expression matches all times starting with the start value, and continuing with all multiples of the repetition value relative to the start value, ending at the end value the latest.

A date specification may use "~" to indicate the last day in a month. For example, "*-02~03" means "the third last day in February," and "Mon *-05~07/1" means "the last Monday in May."

The seconds component may contain decimal fractions both in the value and the repetition. All fractions are rounded to 6 decimal places.

Either time or date specification may be omitted, in which case 00:00:00 and *-*-* is implied, respectively. If the seconds component is not specified, ":00" is assumed.

Timezone can be specified as the literal string "UTC", or the local timezone, similar to the supported syntax of timestamps (see above), or the timezone in the IANA timezone database format (also see above).

The following special expressions may be used as shorthands for longer normalized forms:

```
    minutely → *-*-* *:*:00

      hourly → *-*-* *:00:00

       daily → *-*-* 00:00:00

     monthly → *-*-01 00:00:00

      weekly → Mon *-*-* 00:00:00

      yearly → *-01-01 00:00:00

   quarterly → *-01,04,07,10-01 00:00:00
semiannually → *-01,07-01 00:00:00
```

Examples for valid timestamps and their normalized form:

```
  Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00

      Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00

                    Wed *-1 → Wed *-*-01 00:00:00

           Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00

                 Wed, 17:48 → Wed *-*-* 17:48:00
Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03

                *-*-7 0:0:0 → *-*-07 00:00:00

                      10-15 → *-10-15 00:00:00

        monday *-12-* 17:00 → Mon *-12-* 17:00:00

  Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45

       12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00

            12..14:10,20,30 → *-*-* 12..14:10,20,30:00

  mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45

             03-05 08:05:40 → *-03-05 08:05:40

                   08:05:40 → *-*-* 08:05:40

                      05:40 → *-*-* 05:40:00

     Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40

           Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40

           2003-03-05 05:40 → 2003-03-05 05:40:00

 05:40:23.4200004/3.1700005 → *-*-* 05:40:23.420000/3.170001

             2003-02..04-05 → 2003-02..04-05 00:00:00

       2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC

                 2003-03-05 → 2003-03-05 00:00:00

                      03-05 → *-03-05 00:00:00

                     hourly → *-*-* *:00:00

                      daily → *-*-* 00:00:00

                  daily UTC → *-*-* 00:00:00 UTC

                    monthly → *-*-01 00:00:00

                     weekly → Mon *-*-* 00:00:00

    weekly Pacific/Auckland → Mon *-*-* 00:00:00 Pacific/Auckland

                     yearly → *-01-01 00:00:00

                   annually → *-01-01 00:00:00

                      *:2/3 → *-*-* *:02/3:00
```

Calendar events are used by timer units, see systemd.timer(5) for details.

Use the calendar command of systemd-analyze(1) to validate and normalize calendar time specifications for testing purposes. The tool also calculates when a specified calendar event would occur next.

## SEE ALSO
systemd(1), journalctl(1), systemd.timer(5), systemd.unit(5), systemd.directives(7), systemd-analyze(1)

## NOTES
1.

RFC 3339

https://tools.ietf.org/html/rfc3339


systemd.v

package: systemd

title: systemd.v(7)

summary: Directory with Versioned Resources

text:
# systemd.v(7)

## NAME
systemd.v - Directory with Versioned Resources

## DESCRIPTION
In various places systemd components accept paths whose trailing components have the ".v/" suffix, pointing to a directory. These components will then automatically look for suitable files inside the directory, do a version comparison and open the newest file found (by version). Available since version v256. Specifically, two expressions are supported:

•When looking for files with a suffix .SUFFIX, and a path ...PATH/NAME.SUFFIX.v/ is specified, then all files ...PATH/NAME.SUFFIX.v/NAME_*.SUFFIX are enumerated, filtered, sorted and the newest file used. The primary sorting key is the variable part, here indicated by the wildcard "*".

•When a path ...PATH.v/NAME___.SUFFIX is specified (i.e. the penultimate component of the path ends in ".v" and the final component contains a triple underscore), then all files ...PATH.v/NAME_*.SUFFIX are enumerated, filtered, sorted and the newest file used (again, by the variable part, here indicated by the wildcard "*").

To illustrate this in an example, consider a directory /var/lib/machines/mymachine.raw.v/, which is populated with three files:

•mymachine_7.5.13.raw

•mymachine_7.5.14.raw

•mymachine_7.6.0.raw

Invoke a tool such as systemd-nspawn(1) with a command line like the following:

```
# systemd-nspawn --image=/var/lib/machines/mymachine.raw.v --boot
```

Then this would automatically be resolved to the equivalent of:

```
# systemd-nspawn --image=/var/lib/machines/mymachine.raw.v/mymachine_7.6.0.raw --boot
```

Much of systemd's functionality that expects a path to a disk image or OS directory hierarchy support the ".v/" versioned directory mechanism, for example systemd-nspawn(1), systemd-dissect(1) or the RootDirectory=/RootImage= settings of service files (see systemd.exec(5)).

Use the systemd-vpick(1) tool to resolve ".v/" paths from the command line, for example for usage in shell scripts.

## FILTERING AND SORTING
The variable part of the filenames in the ".v/" directories are filtered and compared primarily with a version comparison, implementing Version Format Specification[1]. However, additional rules apply:

•If the variable part is suffixed by one or two integer values ("tries left" and "tries done") in the formats +LEFT or +LEFT-DONE, then these indicate usage attempt counters. The idea is that each time before a file is attempted to be used, its "tries left" counter is decreased, and the "tries done" counter increased (simply by renaming the file). When the file is successfully used (which for example could mean for an OS image: successfully booted) the counters are removed from the file name, indicating that the file has been validated to work correctly. This mechanism mirrors the boot assessment counters defined by Automatic Boot Assessment[2]. Any filenames with no boot counters or with a non-zero "tries left" counter are sorted before filenames with a zero "tries left" counter.

•Preceding the use counters (if they are specified), an optional CPU architecture identifier may be specified in the filename (separated from the version with an underscore), as defined in the architecture vocabulary of the ConditionArchitecture= unit file setting, as documented in systemd.unit(5). Files whose name indicates an architecture not supported locally are filtered and not considered for the version comparison.

•The rest of the variable part is the version string.

Or in other words, the files in the ".v/" directories should follow one of these naming structures:

•NAME_VERSION.SUFFIX

•NAME_VERSION_ARCHITECTURE.SUFFIX

•NAME_VERSION+LEFT.SUFFIX

•NAME_VERSION+LEFT-DONE.SUFFIX

•NAME_VERSION_ARCHITECTURE+LEFT.SUFFIX

•NAME_VERSION_ARCHITECTURE+LEFT-DONE.SUFFIX

## EXAMPLE
Here's a more comprehensive example, further extending the one described above. Consider a directory /var/lib/machines/mymachine.raw.v/, which is populated with the following files:

•mymachine_7.5.13.raw

•mymachine_7.5.14_x86-64.raw

•mymachine_7.6.0_arm64.raw

•mymachine_7.7.0_x86-64+0-5.raw

Now invoke the following command on an x86-64 machine:

```
$ systemd-vpick --suffix=.raw /var/lib/machines/mymachine.raw.v/
```

This would resolve the specified path to /var/lib/machines/mymachine.raw.v/mymachine_7.5.14_x86-64.raw. Explanation: even though mymachine_7.7.0_x86-64+0-5.raw has the newest version, it is not preferred because its tries left counter is zero. And even though mymachine_7.6.0_arm64.raw has the second newest version it is also not considered in this case, because we operate on an x86_64 system and the image is intended for arm64 CPUs. Finally, the mymachine_7.5.13.raw image is not considered because it is older than mymachine_7.5.14_x86-64.raw.

## SEE ALSO
systemd(1), systemd-vpick(1), systemd-nspawn(1), systemd-dissect(1), systemd.exec(5), systemd-sysupdate(8)

## NOTES
1.

Version Format Specification

https://uapi-group.org/specifications/specs/version_format_specification/

2.

Automatic Boot Assessment

https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT/


systemd-boot

package: systemd-boot-efi

title: systemd-boot(7)

summary: A simple UEFI boot manager

text:
# systemd-boot(7)

## NAME
systemd-boot, sd-boot - A simple UEFI boot manager

## DESCRIPTION
systemd-boot (short: sd-boot) is a simple UEFI boot manager. It provides a textual menu to select the entry to boot and an editor for the kernel command line. systemd-boot supports systems with UEFI firmware only.

systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at /efi/, /boot/, or /boot/efi/ during OS runtime, as well as from the Extended Boot Loader partition (XBOOTLDR) if it exists (usually mounted to /boot/). Configuration file fragments, kernels, initrds and other EFI images to boot generally need to reside on the ESP or the Extended Boot Loader partition. Linux kernels must be built with CONFIG_EFI_STUB to be able to be directly executed as an EFI image. During boot systemd-boot automatically assembles a list of boot entries from the following sources:

•Boot entries defined with Boot Loader Specification[1] Type #1 description files located in /loader/entries/ on the ESP and the Extended Boot Loader Partition. These usually describe Linux kernel images with associated initrd images, but alternatively may also describe other arbitrary EFI executables.

•Unified kernel images, Boot Loader Specification[1] Type #2, which are executable EFI binaries in /EFI/Linux/ on the ESP and the Extended Boot Loader Partition.

•The Microsoft Windows EFI boot manager, if installed.

•The Apple macOS boot manager, if installed.

•The EFI Shell binary, if installed.

•A "Reboot Into Firmware Interface" option, if supported by the UEFI firmware.

•Secure Boot variables enrollment if the UEFI firmware is in setup-mode and files are provided on the ESP.

systemd-boot supports the following features:

•Basic boot manager configuration changes (such as timeout configuration, default boot entry selection, ...) may be made directly from the boot loader UI at boot-time, as well as during system runtime with EFI variables.

•The boot manager integrates with the systemctl command to implement features such as systemctl reboot --boot-loader-entry=... (for rebooting into a specific boot menu entry, i.e. "reboot into Windows") and systemctl reboot --boot-loader-menu=... (for rebooting into the boot loader menu), by implementing the Boot Loader Interface[2]. See systemctl(1) for details.

•An EFI variable set by the boot loader informs the OS about the EFI System Partition used during boot. This is then used to automatically mount the correct EFI System Partition to /efi/ or /boot/ during OS runtime. See systemd-gpt-auto-generator(8) for details.

•The boot manager provides information about the boot time spent in UEFI firmware using the Boot Loader Interface[2]. This information can be displayed using systemd-analyze(1).

•The boot manager implements boot counting and automatic fallback to older, working boot entries on failure. See Automatic Boot Assessment[3].

•The boot manager optionally reads a random seed from the ESP partition, combines it with a 'system token' stored in a persistent EFI variable and derives a random seed to use by the OS as entropy pool initialization, providing a full entropy pool during early boot.

•The boot manager allows for Secure Boot variables to be enrolled if the UEFI firmware is in setup-mode. Additionally, variables can be automatically enrolled if configured.

bootctl(1) may be used from a running system to locate the ESP and the Extended Boot Loader Partition, list available entries, and install systemd-boot itself.

kernel-install(8) may be used to copy kernel images onto the ESP or the Extended Boot Loader Partition and to generate description files compliant with the Boot Loader Specification.

systemd-stub(7) may be used as UEFI boot stub for executed kernels, which is useful to show graphical boot splashes before transitioning into the Linux world. It is also capable of automatically picking up auxiliary credential files (for boot parameterization) and system extension images, as companion files to the booted kernel images.

## KEY BINDINGS
The following keys may be used in the boot menu:

↑ (Up), ↓ (Down), j, k, PageUp, PageDown, Home, End

Navigate up/down in the entry list Added in version 239.

↵ (Enter), → (Right)

Boot selected entry Added in version 239.

d

Make selected entry the default An EFI variable is set to allow this setting to persist.

Added in version 239.

e

Edit the kernel command line for selected entry Added in version 239.

+, t

Increase the timeout before default entry is booted An EFI variable is set to allow this setting to persist.

Added in version 239.

-, T

Decrease the timeout An EFI variable is set to allow this setting to persist.

Added in version 239.

r

Change screen resolution, skipping any unsupported modes. An EFI variable is set to allow this setting to persist.

Added in version 250.

R

Reset screen resolution to firmware or configuration file default. An EFI variable is set to allow this setting to persist.

Added in version 250.

p

Print status Added in version 250.

h, ?, F1

Show a help screen Added in version 239.

f

Reboot into firmware interface. For compatibility with the keybindings of several firmware implementations this operation may also be reached with F2, F10, Del and Esc.

Added in version 250.

Shift+o

Power off the system. Added in version 255.

Shift+b

Reboot the system. Added in version 255.

The following keys may be pressed during bootup or in the boot menu to directly boot a specific entry:

l

Linux Added in version 239.

w

Windows Added in version 239.

a

macOS Added in version 239.

s

EFI shell Added in version 239.

1, 2, 3, 4, 5, 6, 7, 8, 9

Boot entry number 1 ... 9 Added in version 239.

The boot menu is shown when a non-zero menu timeout has been configured. If the menu timeout has been set to zero, hold down a key (space is recommended) before the boot loader initializes to bring up the boot menu. Note that depending on the firmware implementation the time window where key presses are accepted before the boot loader initializes might be short. If the window is missed, reboot and try again, possibly repeatedly pressing a suitable key; on most systems it should be possible to hit the time window after a few attempts. Keys other than the space bar may be used, except for the keys listed above. If showing the menu on demand doesn't work well, consider setting a non-zero timeout to show the boot menu unconditionally. Some desktop environments might offer an option to boot directly into the boot menu, which also avoids the problem altogether. Alternatively, use the command line systemctl reboot --boot-loader-menu= with a non-zero value from the shell.

In the editor, most keys simply insert themselves, but the following keys may be used to perform additional actions:

← (Left), → (Right), Home, End

Navigate left/right Added in version 239.

Esc, Ctrl+c

Abort the edit and quit the editor Added in version 239.

Ctrl+k

Clear the command line forwards Added in version 239.

Ctrl+w, Alt+Backspace

Delete word backwards Added in version 239.

Ctrl+Del, Alt+d

Delete word forwards Added in version 239.

↵ (Enter)

Boot entry with the edited command line Added in version 239.

Note that unless configured otherwise in the UEFI firmware, systemd-boot will use the US keyboard layout, so key labels might not match for keys like +/-.

## FILES
The files systemd-boot processes generally reside on the UEFI ESP which is usually mounted to /efi/, /boot/ or /boot/efi/ during OS runtime. It also processes files on the Extended Boot Loader partition which is typically mounted to /boot/, if it exists.

systemd-boot reads runtime configuration such as the boot timeout and default entry from /loader/loader.conf on the ESP (in combination with data read from EFI variables). See loader.conf(5).

Boot entry description files following the Boot Loader Specification[1] are read from /loader/entries/ on the ESP and the Extended Boot Loader partition.

Unified kernel boot entries following the Boot Loader Specification[1] are read from /EFI/Linux/ on the ESP and the Extended Boot Loader partition.

Optionally, a random seed for early boot entropy pool provisioning is stored in /loader/random-seed in the ESP.

During initialization, sd-boot automatically loads all driver files placed in the /EFI/systemd/drivers/ directory of the ESP. The files placed there must have an extension of the EFI architecture ID followed by .efi (e.g. for x86-64 this means a suffix of x64.efi). This may be used to automatically load file system drivers and similar, to extend the native firmware support.

Enrollment of Secure Boot variables can be performed manually or automatically if files are available under /loader/keys/NAME/{db,dbx,KEK,PK}.auth, NAME being the display name for the set of variables in the menu. If one of the sets is named auto then it might be enrolled automatically depending on whether "secure-boot-enroll" is set to force or not.

## EFI VARIABLES
The following EFI variables are defined, and may be set or read by systemd-boot for communication between the boot loader and the OS. The vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4f" is used in all cases.

LoaderBootCountPath

If boot counting is enabled, contains the path to the file in whose name the boot counters are encoded. Set by the boot loader. systemd-bless-boot.service(8) uses this information to mark a boot as successful as determined by the successful activation of the boot-complete.target target unit. Added in version 240.

LoaderConfigTimeout, LoaderConfigTimeoutOneShot

The menu timeout in seconds. Read by the boot loader. LoaderConfigTimeout is maintained persistently, while LoaderConfigTimeoutOneShot is a one-time override which is read once (in which case it takes precedence over LoaderConfigTimeout) and then removed. LoaderConfigTimeout may be manipulated with the t/T keys, see above. Added in version 240.

LoaderConfigConsoleMode

The numerical menu console mode. Read by the boot loader. LoaderConfigConsoleMode is maintained persistently. LoaderConfigConsoleMode may be manipulated with the r/R keys, see above. Added in version 250.

LoaderDevicePartUUID

Contains the partition UUID of the partition the boot loader has been started from on the current boot (usually an EFI System Partition). Set by the boot loader. (Note that systemd-stub(7) will set this too, if not set yet, to support systems that boot directly into a unified kernel image, bypassing any boot loader.) systemd-gpt-auto-generator(8) uses this information to automatically find the disk booted from, in order to discover various other partitions on the same disk automatically. Added in version 220.

LoaderEntries

A list of the identifiers of all discovered boot loader entries. Set by the boot loader. Added in version 240.

LoaderEntryDefault, LoaderEntryOneShot

The identifier of the default boot loader entry. Can be set in the OS and the boot loader. LoaderEntryOneShot sets the default entry for the next boot only, while LoaderEntryDefault sets it persistently for all future boots. bootctl(1)'s set-default and set-oneshot commands make use of these variables. The boot loader modifies LoaderEntryDefault on request, when the d key is used, see above. Added in version 240.

LoaderEntryLastBooted

The identifier of the boot loader entry last attempted. Set and read by the boot loader, only when /loader/loader.conf has default set to "@saved". See loader.conf(5). The boot loader will ensure LoaderEntryLastBooted is up-to date for every boot, updating it as needed and will omit changing it all together when LoaderEntryOneShot is set.

The boot loader reads the variable, which takes higher priority than LoaderEntryDefault. The variable is ignored when LoaderEntryOneShot is set.

LoaderEntryLastBooted cannot be used as indication that the last boot was successful or not.

Added in version 250.

LoaderEntrySelected

The identifier of the boot loader entry currently being booted. Set by the boot loader. Added in version 240.

LoaderFeatures

A set of flags indicating the features the boot loader supports. Set by the boot loader. Use bootctl(1) to view this data. Added in version 240.

LoaderFirmwareInfo, LoaderFirmwareType

Brief firmware information. Set by the boot loader. Use bootctl(1) to view this data. Added in version 240.

LoaderImageIdentifier

The file system path to the EFI executable of the boot loader for the current boot, relative to the partition's root directory (i.e. relative to the partition indicated by LoaderDevicePartUUID, see above). Set by the boot loader. (Note that systemd-stub will set this too, if not set yet, to support systems that directly boot into a unified kernel image, bypassing any boot loader.) Use bootctl(1) to view this data. Added in version 220.

LoaderInfo

Brief information about the boot loader. Set by the boot loader. Use bootctl(1) to view this data. Added in version 240.

LoaderTimeExecUSec, LoaderTimeInitUSec, LoaderTimeMenuUsec

Information about the time spent in various parts of the boot loader. Set by the boot loader. Use systemd-analyze(1) to view this data. Added in version 240.

LoaderSystemToken

A binary random data field, that is used for generating the random seed to pass to the OS (see above). Note that this random data is generally only generated once, during OS installation, and is then never updated again. Added in version 243.

Many of these variables are defined by the Boot Loader Interface[2].

## SMBIOS TYPE 11 STRINGS
systemd-boot can be configured using SMBIOS Type 11 strings. Applicable strings consist of a name, followed by "=", followed by the value. Unless systemd-boot detects it is running inside a confidential computing environment, systemd-boot will search the table for a string with a specific name, and if found, use its value. The following strings are read:

io.systemd.boot.kernel-cmdline-extra

If set, the value of this string is added to the list of kernel command line arguments for Boot Loader Specification Type 1 entries that are measured in PCR12 and passed to the kernel. Added in version 256.

## BOOT COUNTING
systemd-boot implements a simple boot counting mechanism on top of the Boot Loader Specification[1], for automatic and unattended fallback to older kernel versions/boot loader entries when a specific entry continuously fails. Any boot loader entry file and unified kernel image file that contains a "+" followed by one or two numbers (if two they need to be separated by a "-"), before the .conf or .efi suffix is subject to boot counting: the first of the two numbers ('tries left') is decreased by one on every boot attempt, the second of the two numbers ('tries done') is increased by one (if 'tries done' is absent it is considered equivalent to 0). Depending on the current value of these two counters the boot entry is considered to be in one of three states:

1.If the 'tries left' counter of an entry is greater than zero the entry is considered to be in 'indeterminate' state. This means the entry has not completed booting successfully yet, but also has not been determined not to work.

2.If the 'tries left' counter of an entry is zero it is considered to be in 'bad' state. This means no further attempts to boot this item will be made (that is, unless all other boot entries are also in 'bad' state), as all attempts to boot this entry have not completed successfully.

3.If the 'tries left' and 'tries done' counters of an entry are absent it is considered to be in 'good' state. This means further boot counting for the entry is turned off, as it successfully booted at least once. The systemd-bless-boot.service(8) service moves the currently booted entry from 'indeterminate' into 'good' state when a boot attempt completed successfully.

Generally, when new entries are added to the boot loader, they first start out in 'indeterminate' state, i.e. with a 'tries left' counter greater than zero. The boot entry remains in this state until either it managed to complete a full boot successfully at least once (in which case it will be in 'good' state) — or the 'tries left' counter reaches zero (in which case it will be in 'bad' state).

Example: let's say a boot loader entry file foo.conf is set up for 3 boot tries. The installer will hence create it under the name foo+3.conf. On first boot, the boot loader will rename it to foo+2-1.conf. If that boot does not complete successfully, the boot loader will rename it to foo+1-2.conf on the following boot. If that fails too, it will finally be renamed foo+0-3.conf by the boot loader on next boot, after which it will be considered 'bad'. If the boot succeeds however the entry file will be renamed to foo.conf by the OS, so that it is considered 'good' from then on.

The boot menu takes the 'tries left' counter into account when sorting the menu entries: entries in 'bad' state are ordered at the beginning of the list, and entries in 'good' or 'indeterminate' at the end. The user can freely choose to boot any entry of the menu, including those already marked 'bad'. If the menu entry to boot is automatically determined, this means that 'good' or 'indeterminate' entries are generally preferred (as the bottom item of the menu is the one booted by default), and 'bad' entries will only be considered if there are no 'good' or 'indeterminate' entries left.

The kernel-install(8) kernel install framework optionally sets the initial 'tries left' counter to the value specified in /etc/kernel/tries when a boot loader entry is first created.

## USING SYSTEMD-BOOT IN VIRTUAL MACHINES
When using qemu with OVMF (UEFI Firmware for virtual machines) the -kernel switch works not only for linux kernels, but for any EFI binary, including sd-boot and unified linux kernels. Example command line for loading systemd-boot on x64:

qemu-system-x86_64 [ ... ] -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi

systemd-boot will detect that it was started directly instead of being loaded from ESP and will search for the ESP in that case, taking into account boot order information from the hypervisor (if available).

## SEE ALSO
bootctl(1), loader.conf(5), systemd-bless-boot.service(8), systemd-boot-random-seed.service(8), kernel-install(8), systemd-stub(7), Boot Loader Specification[1], Boot Loader Interface[2], TPM2 PCR Measurements Made by systemd[4]

## NOTES
1.

Boot Loader Specification

https://uapi-group.org/specifications/specs/boot_loader_specification

2.

Boot Loader Interface

https://systemd.io/BOOT_LOADER_INTERFACE

3.

Automatic Boot Assessment

https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT

4.

TPM2 PCR Measurements Made by systemd

https://systemd.io/TPM2_PCR_MEASUREMENTS


term

package: termutils

title: term(7)

text:
# term(7)

## NAME
term - conventions for naming terminal types

## DESCRIPTION
The environment variable TERM should normally contain the type name of the terminal, console or display-device type you are using. This information is critical for all screen-oriented programs, including your editor and mailer.

A default TERM value will be set on a per-line basis by either /etc/inittab (e.g., System-V-like Unices) or /etc/ttys (BSD Unices). This will nearly always suffice for workstation and microcomputer consoles.

If you use a dialup line, the type of device attached to it may vary. Older Unix systems pre-set a very dumb terminal type like “dumb” or “dialup” on dialup lines. Newer ones may pre-set “vt100”, reflecting the prevalence of DEC VT100-compatible terminals and personal-computer emulators.

Modern telnets pass your TERM environment variable from the local side to the remote one. There can be problems if the remote terminfo or termcap entry for your type is not compatible with yours, but this situation is rare and can almost always be avoided by explicitly exporting “vt100” (assuming you are in fact using a VT100-superset console, terminal, or terminal emulator).

In any case, you are free to override the system TERM setting to your taste in your shell profile. The tset(1) utility may be of assistance; you can give it a set of rules for deducing or requesting a terminal type based on the tty device and baud rate.

Setting your own TERM value may also be useful if you have created a custom entry incorporating options (such as visual bell or reverse-video) which you wish to override the system default type for your line.

Terminal type descriptions are stored as files of capability data underneath /usr/share/terminfo. To browse a list of all terminal names recognized by the system, do

toe | more

from your shell. These capability files are in a binary format optimized for retrieval speed (unlike the old text-based termcap format they replace); to examine an entry, you must use the infocmp(1M) command. Invoke it as follows:

infocmp entry_name

where entry_name is the name of the type you wish to examine (and the name of its capability file the subdirectory of /usr/share/terminfo named for its first letter). This command dumps a capability file in the text format described by terminfo(5).

The first line of a terminfo(5) description gives the names by which terminfo knows a terminal, separated by “|” (pipe-bar) characters with the last name field terminated by a comma. The first name field is the type's primary name, and is the one to use when setting TERM. The last name field (if distinct from the first) is actually a description of the terminal type (it may contain blanks; the others must be single words). Name fields between the first and last (if present) are aliases for the terminal, usually historical names retained for compatibility.

There are some conventions for how to choose terminal primary names that help keep them informative and unique. Here is a step-by-step guide to naming terminals that also explains how to parse them:

First, choose a root name. The root will consist of a lower-case letter followed by up to seven lower-case letters or digits. You need to avoid using punctuation characters in root names, because they are used and interpreted as filenames and shell meta-characters (such as !, $, *, ?, etc.) embedded in them may cause odd and unhelpful behavior. The slash (/), or any other character that may be interpreted by anyone's file system (\, $, [, ]), is especially dangerous (terminfo is platform-independent, and choosing names with special characters could someday make life difficult for users of a future port). The dot (.) character is relatively safe as long as there is at most one per root name; some historical terminfo names use it.

The root name for a terminal or workstation console type should almost always begin with a vendor prefix (such as hp for Hewlett-Packard, wy for Wyse, or att for AT&T terminals), or a common name of the terminal line (vt for the VT series of terminals from DEC, or sun for Sun Microsystems workstation consoles, or regent for the ADDS Regent series. You can list the terminfo tree to see what prefixes are already in common use. The root name prefix should be followed when appropriate by a model number; thus vt100, hp2621, wy50.

The root name for a PC-Unix console type should be the OS name, i.e., linux, bsdos, freebsd, netbsd. It should not be console or any other generic that might cause confusion in a multi-platform environment! If a model number follows, it should indicate either the OS release level or the console driver release level.

The root name for a terminal emulator (assuming it does not fit one of the standard ANSI or vt100 types) should be the program name or a readily recognizable abbreviation of it (i.e., versaterm, ctrm).

Following the root name, you may add any reasonable number of hyphen-separated feature suffixes.

2p

Has two pages of memory. Likewise 4p, 8p, etc.

mc

Magic-cookie. Some terminals (notably older Wyses) can only support one attribute without magic-cookie lossage. Their base entry is usually paired with another that has this suffix and uses magic cookies to support multiple attributes.

-am

Enable auto-margin (right-margin wraparound).

-m

Mono mode - suppress color support.

-na

No arrow keys - termcap ignores arrow keys which are actually there on the terminal, so the user can use the arrow keys locally.

-nam

No auto-margin - suppress am capability.

-nl

No labels - suppress soft labels.

-nsl

No status line - suppress status line.

-pp

Has a printer port which is used.

-rv

Terminal in reverse video mode (black on white).

-s

Enable status line.

-vb

Use visible bell (flash) rather than beep.

-w

Wide; terminal is in 132-column mode.

Conventionally, if your terminal type is a variant intended to specify a line height, that suffix should go first. So, for a hypothetical FuBarCo model 2317 terminal in 30-line mode with reverse video, best form would be fubar-30-rv (rather than, say, “fubar-rv-30”).

Terminal types that are written not as standalone entries, but rather as components to be plugged into other entries via use capabilities, are distinguished by using embedded plus signs rather than dashes.

Commands which use a terminal type to control display often accept a -T option that accepts a terminal name argument. Such programs should fall back on the TERM environment variable when no -T option is specified.

## FILES
/usr/share/terminfo

compiled terminal description database

/etc/inittab

tty line initialization (AT&T-like Unices)

/etc/ttys

tty line initialization (BSD-like Unices)

## PORTABILITY
For maximum compatibility with older System V Unices, names and aliases should be unique within the first 14 characters.

## SEE ALSO
curses(3X), term(5), terminfo(5)


tigmanual

package: tig

title: tigmanual(7)

summary: text\-mode interface for Git

text:
# tigmanual(7)

## NAME
tigmanual - text-mode interface for Git

## SYNOPSIS

```
tig        [options] [revisions] [--] [paths]
tig show   [options] [revisions] [--] [paths]
tig blame  [options] [rev] [--] path
tig status
tig <      [Git command output]
```

## DESCRIPTION
This is the manual for Tig, the ncurses-based text-mode interface for git. Tig allows you to browse changes in a Git repository and can additionally act as a pager for output of various Git commands. When used as a pager, it will display input from stdin and colorize it.

When browsing repositories, Tig uses the underlying Git commands to present the user with various views, such as summarized commit log and showing the commit with the log message, diffstat, and the diff.

## CALLING CONVENTIONS

### Pager Mode
If stdin is a pipe, any log or diff options will be ignored and the pager view will be opened loading data from stdin. The pager mode can be used for colorizing output from various Git commands.

Example on how to colorize the output of git-show(1):

```
$ git show | tig
```

### Git Command Options
All Git command options specified on the command line will be passed to the given command and all will be shell quoted before they are passed to the shell.

Note If you specify options for the main view, you should not use the --pretty option as this option will be set automatically to the format expected by the main view.

Example on how to view a commit and show both author and committer information:

```
$ tig show --pretty=fuller
```

See the section on specifying revisions for an introduction to revision options supported by the Git commands. For details on specific Git command options, refer to the man page of the command in question.

## THE VIEWER
The display consists of a status window on the last line of the screen and one or more views. The default is to only show one view at a time but it is possible to split both the main and log view to also show the commit diff.

If you are in the log view and press Enter when the current line is a commit line, such as:

```
commit 4d55caff4cc89335192f3e566004b4ceef572521
```

You will split the view so that the log view is displayed in the top window and the diff view in the bottom window. You can switch between the two views by pressing Tab. To maximize the log view again, simply press l.

### Views
Various views of a repository are presented. Each view is based on output from an external command, most often git log, git diff, or git show.

The main view

Is the default view, and it shows a one line summary of each commit in the chosen list of revisions. The summary includes author date, author, and the first line of the log message. Additionally, any repository references, such as tags, will be shown.

The log view

Presents a more rich view of the revision log showing the whole log message and the diffstat.

The reflog view

Presents a view of the reflog allowing to navigate the repo history.

The diff view

Shows either the diff of the current working tree, that is, what has changed since the last commit, or the commit diff complete with log message, diffstat and diff.

The tree view

Lists directory trees associated with the current revision allowing subdirectories to be descended or ascended and file blobs to be viewed.

The blob view

Displays the file content or "blob" of data associated with a file name.

The blame view

Displays the file content annotated or blamed by commits.

The refs view

Displays the branches, remotes and tags in the repository.

The status view

Displays status of files in the working tree and allows changes to be staged/unstaged as well as adding of untracked files.

The stage view

Displays diff changes for staged or unstaged files being tracked or file content of untracked files.

The stash view

Displays the list of stashes in the repository.

The grep view

Displays a list of files and all the lines that matches a search pattern.

The pager view

Is used for displaying both input from stdin and output from Git commands entered in the internal prompt.

The help view

Displays a quick reference of key bindings.

### Browsing State and User-defined Commands
The viewer keeps track of both what head and commit ID you are currently viewing. The commit ID will follow the cursor line and change every time you highlight a different commit. Whenever you reopen the diff view it will be reloaded, if the commit ID changed. The head ID is used when opening the main and log view to indicate from what revision to show history.

Some of the commands used or provided by Tig can be configured. This goes for some of the environment variables as well as the external commands. These user-defined commands can use arguments that refer to the current browsing state by using one of the following variables.

Table 1. Browsing state variables

%(head)

The currently viewed head ID. Defaults to HEAD

%(commit)

The currently selected commit ID.

%(blob)

The currently selected blob ID.

%(branch)

The currently selected branch name.

%(remote)

The currently selected remote name. For remote branches %(branch) will contain the branch name.

%(tag)

The currently selected tag name.

%(refname)

The currently selected reference name including the remote name for remote branches.

%(stash)

The currently selected stash name.

%(directory)

The current directory path in the tree view or "." if undefined.

%(file)

The currently selected file.

%(file_old)

The old filename of the currently selected file.

%(lineno)

The currently selected line number. Defaults to 0.

%(lineno_old)

The currently selected line number, before the diff was applied. Defaults to 0.

%(ref)

The reference given to blame or HEAD if undefined.

%(revargs)

The revision arguments passed on the command line.

%(fileargs)

The file arguments passed on the command line.

%(cmdlineargs)

All other options passed on the command line.

%(diffargs)

Options from diff-options or TIG_DIFF_OPTS used by the diff and stage view.

%(blameargs)

Options from blame-options used by the blame view.

%(logargs)

Options from log-options used by the log view.

%(mainargs)

Options from main-options used by the main view.

%(prompt)

Prompt for the argument value. Optionally specify a custom prompt using "%(prompt Enter branch name: )"

%(text)

The text column of the currently selected line.

%(repo:head)

The name of the checked out branch, e.g. master

%(repo:head-id)

The commit ID of the checked out branch.

%(repo:remote)

The remote associated with the checked out branch, e.g. origin/master.

%(repo:cdup)

The path to change directory to the repository root, e.g. ../

%(repo:prefix)

The path prefix of the current work directory, e.g subdir/.

%(repo:git-dir)

The path to the Git directory, e.g. /src/repo/.git.

%(repo:worktree)

The worktree path, if defined.

%(repo:is-inside-work-tree)

Whether Tig is running inside a work tree, either true or false.

Example user-defined commands:

•Allow to amend the last commit:

```
bind generic + !git commit --amend
```

•Copy commit ID to clipboard:

```
bind generic 9 @sh -c "echo -n %(commit) | xclip -selection c"
```

•Add/edit notes for the current commit used during a review:

```
bind generic T !git notes edit %(commit)
```

•Enter Git’s interactive add for fine-grained staging of file content:

```
bind generic I !git add -i %(file)
```

•Rebase current branch on top of the selected branch:

```
bind refs 3 !git rebase -i %(branch)
```

### Title Windows
Each view has a title window which shows the name of the view, current commit ID if available, and where the view is positioned:

```
[main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61             1%
```

By default, the title of the current view is highlighted using bold font. For long loading views (taking over 3 seconds) the time since loading started will be appended:

```
[main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 loading 5s 0%
```

## ENVIRONMENT VARIABLES
Several options related to the interface with Git can be configured via environment options.

### Configuration Files
Upon startup, Tig first reads the system wide configuration file ({sysconfdir}/tigrc by default) and then proceeds to read the user’s configuration file (~/.tigrc or $XDG_CONFIG_HOME/tig/config by default). The paths to either of these files can be overridden through the following environment variables:

TIGRC_USER

Path of the user configuration file.

TIGRC_SYSTEM

Path of the system wide configuration file.

### History Files
If compiled with readline support, Tig writes a persistent command and search history to ~/.tig_history or $XDG_DATA_HOME/tig/history.

### Repository References
Commits that are referenced by tags and branch heads will be marked by the reference name surrounded by [ and ]:

```
2006-03-26 19:42 Petr Baudis         | [cogito-0.17.1] Cogito 0.17.1
```

If you want to limit what branches are shown, say only show branches named master or those which start with the feature/ prefix, you can do it by setting the following variable:

```
$ TIG_LS_REMOTE="git ls-remote . master feature/*" tig
```

Or set the variable permanently in your environment.

TIG_LS_REMOTE

Command for retrieving all repository references. The command should output data in the same format as git-ls-remote(1). Defaults to:

```
git ls-remote .
```

### Diff options
It is possible to alter how diffs are shown by the diff view. If for example you prefer to have commit and author dates shown as relative dates, use:

```
$ TIG_DIFF_OPTS="--relative-date" tig
```

Or set the variable permanently in your environment.

## DEFAULT KEYBINDINGS
Below the default key bindings are shown.

### View Switching
Key

Action

m

Switch to main view.

d

Switch to diff view.

l

Switch to log view.

p

Switch to pager view.

t

Switch to (directory) tree view.

f

Switch to (file) blob view.

g

Switch to grep view.

b

Switch to blame view.

r

Switch to refs view.

y

Switch to stash view.

h

Switch to help view

s

Switch to status view

c

Switch to stage view

### View Manipulation
Key

Action

q

Close view, if multiple views are open it will jump back to the previous view in the view stack. If it is the last open view it will quit. Use Q to quit all views at once.

Enter

This key is "context sensitive" depending on what view you are currently in. When in log view on a commit line or in the main view, split the view and show the commit diff. In the diff view pressing Enter will simply scroll the view one line down.

Tab

Switch to next view.

R

Reload and refresh the current view.

O

Maximize the current view to fill the whole display.

Up

This key is "context sensitive" and will move the cursor one line up. However, if you opened a split view it will change the cursor to point to the previous commit in the parent view and update the child view to display it. If you prefer this key to move the cursor or scroll within the diff view instead, use bind diff <Up> move-up or bind diff <Up> scroll-line-up, respectively.

Down

Similar to Up but will move down.

,

Move to parent. In the tree view, this means switch to the parent directory. In the blame view it will load blame for the parent commit. For merges the parent is queried.

### View Specific Actions
Key

Action

u

Update status of file. In the status view, this allows you to add an untracked file or stage changes to a file for next commit (similar to running git-add <filename>). In the stage view, when pressing this on a diff chunk line stages only that chunk for next commit, when not on a diff chunk line all changes in the displayed diff are staged.

M

Resolve unmerged file by launching git-mergetool(1). Note, to work correctly this might require some initial configuration of your preferred merge tool. See the manpage of git-mergetool(1).

!

Checkout file with unstaged changes. This will reset the file to contain the content it had at last commit.

1

Stage single diff line.

@

Move to next chunk in the stage view.

]

Increase the diff context.

[

Decrease the diff context.

### Cursor Navigation
Key

Action

k

Move cursor one line up.

j

Move cursor one line down.

PgUp, -

Move cursor one page up.

PgDown, Space

Move cursor one page down.

Home

Jump to first line.

End

Jump to last line.

### Scrolling
Key

Action

Insert

Scroll view one line up.

Delete

Scroll view one line down.

ScrollBack

Scroll view one page up.

ScrollFwd

Scroll view one page down.

Left

Scroll view one column left.

Right

Scroll view one column right.

|

Scroll view to the first column.

### Searching
Key

Action

/

Search the view. Opens a prompt for entering search regexp to use.

?

Search backwards in the view. Also prompts for regexp.

n

Find next match for the current search regexp.

N

Find previous match for the current search regexp.

The format for patterns is either POSIX.2 “extended” REs or PCRE / PCRE2 if Tig was compiled with PCRE / PCRE2 support (check with tig -v). See the manpage of re_format(7) or pcrepattern(3) / pcre2pattern(3).

Case sensitivity can be controlled with variable ignore-case.

### Misc
Key

Action

Q

Quit.

<C-L>

Redraw screen.

z

Stop all background loading. This can be useful if you use Tig in a repository with a long history without limiting the revision log.

v

Show version.

o

Open option menu

\#

Toggle line numbers on/off.

D

Toggle date display on/off/relative/relative-compact/custom

A

Toggle author display on/off/abbreviated/email/email user name.

G

Toggle revision graph visualization on/off.

~

Toggle (line) graphics mode

F

Toggle reference display on/off (tag and branch names).

W

Toggle ignoring whitespace on/off for diffs

X

Toggle commit ID display on/off

%

Toggle file filtering in order to see the full diff instead of only the diff concerning the currently selected file.

^

Toggle revision filtering in the main view.

$

Toggle highlighting of commit title overflow.

H

Go to the HEAD commit.

:

Open prompt. This allows you to specify what command to run and also to jump to a specific line, e.g. :23

e

Open file in editor.

### Prompt
Key

Action

:<number>

Jump to the specific line number, e.g. :80.

:<sha>

Jump to a specific commit, e.g. :2f12bcc.

:<x>

Execute the corresponding key binding, e.g. :q.

:!<command>

Execute a system command in a pager, e.g. :!git log -p.

:<action>

Execute a Tig command, e.g. :edit.

:goto <rev>

Jump to a specific revision, e.g. :goto %(commit)^2 to goto the current commit’s 2nd parent or :goto some/branch to goto the commit denoting the branch some/branch.

:save-display <file>

Save current display to <file>.

:save-options <file>

Save current options to <file>.

:save-view <file>

Save view info to <file> (for testing purposes).

:script <file>

Execute commands from <file>.

:exec <flags><args...>

Execute command using <args> with external user-defined command option flags defined in <flags>.

:echo <args...>

Display text in the status bar.

### External Commands
For more custom needs, external commands provide a way to easily execute a script or program. They are bound to keys and use information from the current browsing state, such as the current commit ID. Tig comes with the following built-in external commands:

Keymap

Key

Action

main

C

git cherry-pick %(commit)

status

C

git commit

generic

G

git gc

## REVISION SPECIFICATION
This section describes various ways to specify what revisions to display or otherwise limit the view to. Tig does not itself parse the described revision options so refer to the relevant Git man pages for further information. Relevant man pages besides git-log(1) are git-diff(1) and git-rev-list(1).

You can tune the interaction with Git by making use of the options explained in this section. For example, by configuring the environment variable described in the section on diff options.

### Limit by Path Name
If you are interested only in those revisions that made changes to a specific file (or even several files) list the files like this:

```
$ tig Makefile README
```

To avoid ambiguity with Tig’s subcommands or repository references such as tag names, be sure to separate file names from other Git options using "--". So if you have a file named status it will clash with the status subcommand, and thus you will have to use:

```
$ tig -- status
```

### Limit by Date or Number
To speed up interaction with Git, you can limit the amount of commits to show both for the log and main view. Either limit by date using e.g. --since=1.month or limit by the number of commits using -n400.

If you are only interested in changes that happened between two dates you can use:

```
$ tig --after="May 5th" --before="2006-05-16 15:44"
```

Note If you want to avoid having to quote dates containing spaces you can use "." instead, e.g. --after=May.5th.

### Limiting by Commit Ranges
Alternatively, commits can be limited to a specific range, such as "all commits between tag-1.0 and tag-2.0". For example:

```
$ tig tag-1.0..tag-2.0
```

This way of commit limiting makes it trivial to only browse the commits which haven’t been pushed to a remote branch. Assuming origin is your upstream remote branch, using:

```
$ tig origin..HEAD
```

will list what will be pushed to the remote branch. Optionally, the ending HEAD can be left out since it is implied.

### Limiting by Reachability
Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits reachable from tag-2.0 but not from tag-1.0". Where reachability refers to what commits are ancestors (or part of the history) of the branch or tagged revision in question.

If you prefer to specify which commit to preview in this way use the following:

```
$ tig tag-2.0 ^tag-1.0
```

You can think of ^ as a negation operator. Using this alternate syntax, it is possible to further prune commits by specifying multiple branch cut offs.

### Combining Revisions Specification
Revision options can to some degree be combined, which makes it possible to say "show at most 20 commits from within the last month that changed files under the Documentation/ directory."

```
$ tig --since=1.month -n20 -- Documentation/
```

### Examining All Repository References
In some cases, it can be useful to query changes across all references in a repository. An example is to ask "did any line of development in this repository change a particular file within the last week". This can be accomplished using:

```
$ tig --all --since=1.week -- Makefile
```

## MORE INFORMATION
Please visit Tig’s home page[1] or main Git repository[2] for information about new releases and how to report bugs and feature requests.

## COPYRIGHT
Copyright (c) 2006-2024 Jonas Fonseca <jonas.fonseca@gmail.com[3]>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

## SEE ALSO
Manpages:

•tig(1)

•tigrc(5)

## NOTES
1.

home page

https://jonas.github.io/tig

2.

main Git repository

https://github.com/jonas/tig

3.

jonas.fonseca@gmail.com

mailto:jonas.fonseca@gmail.com


timew-config

package: timewarrior

title: timew-config(7)

text:
# timew-config(7)

## NAME
timew-config - Timewarrior configuration file and override options

## SYNOPSIS
timew rc.<name>=<value> <command>

## DESCRIPTION
Timewarrior stores its configuration in the user's home directory in ~/.timewarrior/timewarrior.cfg. This file contains a mix of rules and configuration settings. Note that the TIMEWARRIORDB environment variable can be set to override this location. The values 'true', '1', 'y', 'yes' and 'on' are all equivalent and enable a setting. Any other value means disable the setting. Default values may be overridden by timewarrior.cfg values, which may in turn be overridden on the command line using: rc.<name>=<value>

For example, to turn off verbose mode:

rc.verbose=0

Note that hints can also do this (:quiet).

## CONFIGURATION
confirmation

Determines whether harmful operations require interactive confirmation.

May be overridden by the ':yes' hint.

Default value is 'yes'.

verbose

Determines whether Timewarrior generates feedback.

May be overridden by the ':quiet' hint.

Default value is 'yes'.

debug

Determines whether diagnostic debugging information is shown.

Useful for troubleshooting, but not for general use.

Default value is 'off'.

debug.indicator

The debug output prefix string.

Default value is '>>'.


timew-dates

title: timew-dates(7)

summary: date formats supported by Timewarrior

text:
# timew-dates(7)

## NAME
timew-dates - date formats supported by Timewarrior

## DESCRIPTION
Timewarrior supports the following date formats based on ISO-8601:

<extended-date> [T <extended-time>] Extended date, optional extended time

<date> [T <time>] Date, optional time

<extended-time> Extended time

<time> Time

extended-date:

YYYY-MM-DD Year, month, day

YYYY-MM Year, month, 1st

YYYY-DDD Year, Julian day 001-366

YYYY-WwwD Year, week number, day number

YYYY-Www Year, week number, day 1

extended-time:

hh:mm[:ss]Z Hours, minutes, optional seconds, UTC

hh:mm[:ss][+/-hh:mm] Hours, minutes, optional seconds, TZ

date:

YYYYMMDD Year, month, day

YYYYWww Year, week number, day number

YYYYDDD Year, Julian day 001-366

time:

hhmm[ss]Z Hour, minutes, optional seconds, UTC

hhmm[ss][+/-hh[mm]] Hour, minutes, optional seconds, TZ

Examples:

2016-06-09T08:12:00Z

2016-06T08:12:00+01:00

2016-06T08:12Z

2016-161

2016-W244

2016-W24

20160609T081200Z

2016W24

8:12:00Z

0812-0500

In addition to the standard date formats, the following are supported:

now Current date and time

today Current date at 0:00:00

yesterday Yesterday at 0:00:00

tomorrow Tomorrow at 0:00:00 (midnight tonight)

<day-of-week> Previous named day at 0:00:00

<month-of-year> Previous 1st of the month at 0:00:00

hh:mm[:ss][am|a|pm|p] Short time format

Nst, Nnd, Nrd, Nth Previous 1st, 2nd, 3rd ...

<epoch> POSIX time

later 2038-01-18T0:00:00 (Y2K38)

someday 2038-01-18T0:00:00 (Y2K38)

sopd, eopd Start/end of previous day

sod, eod Start/end of current day

sond, eond Start/end of next day

sopw, eopw Start/end of previous week

sow, eow Start/end of current week

sonw, eonw Start/end of next week

sopww, eopww Start/end of previous work week (mon - fri)

soww, eoww Start/end of current work week (mon - fri)

sonww, eonww Start/end of next work week (mon - fri)

sopm, eopm Start/end of previous month

som, eom Start/end of current month

sonm, eonm Start/end of next month

sopq, eopq Start/end of previous quarter

soq, eoq Start/end of current quarter

sonq, eonq Start/end of next quarter

sopy, eopy Start/end of previous year

soy, eoy Start/end of current year

sony, eony Start/end of next year

easter Easter Sunday

eastermonday Easter Monday

ascension Ascension

pentecost Pentecost

goodfriday Good Friday

midsommar midnight, 1st Saturday after 20th June

midsommarafton midnight, 1st Friday after 19th June

juhannus midnight, 1st Friday after 19th June

Examples:

8am

24th

monday

august

## SEE ALSO
timew-durations(7), timew-hints(7)


timew-dom

title: timew-dom(7)

summary: Timewarrior DOM

text:
# timew-dom(7)

## NAME
timew-dom - Timewarrior DOM

## DESCRIPTION
Supported DOM references are:

dom.tag.count Count of all tags

dom.tag.1 Nth tag used

dom.active '1' if there is active tracking, otherwise '0'

dom.active.tag.count Count of active tags

dom.active.tag.1 Active Nth tag

dom.active.start Active start timestamp (ISO Extended local date)

dom.active.duration Active elapsed (ISO Period)

dom.active.json Active interval as JSON

dom.tracked.count Count of tracked intervals

dom.tracked.1.tag.count Count of active tags

dom.tracked.1.tag.1 Tracked Nth, Nth tag

dom.tracked.1.start Tracked Nth, start time

dom.tracked.1.end Tracked Nth, end time, blank if closed

dom.tracked.1.duration Tracked Nth, elapsed

dom.tracked.1.json Tracked Nth, interval as JSON

dom.rc.<name> Configuration setting


timew-durations

title: timew-durations(7)

text:
# timew-durations(7)

## NAME
timew-durations - duration formats supported by Timewarrior

## DESCRIPTION
Timewarrior supports the following duration formats based on ISO-8601:

'P' [nn 'Y'] [nn 'M'] [nn 'D'] ['T' [nn 'H'] [nn 'M'] [nn 'S']]

PnnW

Examples:

P1Y 1 year

P1.5M 1.5 months

PT1S 1 second

PT4.5H 4.5 hours

PT4H30M 4.5 hours

P600D 600 days

P3W 3 weeks

P1Y1DT1H1M1S 1 year and 25 hours, 61 seconds (imprecise term)

Note that the year and month terms are imprecise, being defined as 365d and 30d respectively. For precision use the other terms.

In addition to the standard duration formats, the following are supported:

n[.n]<unit>

Where the <unit> is one of:

annual

biannual

bimonthly

biweekly

biyearly

daily

days, day, d

fortnight

hours, hour, hrs, hr, h

minutes, minute, mins, min

monthly, months, month, mnths, mths, mth, mos, mo, m

quarterly, quarters, quarter, qrtrs, qtr, q

semiannual

sennight

seconds, second, secs, sec, s

weekdays

weekly, weeks, week, wks, wk, w

yearly, years, year, yrs, yr, y

Examples:

1hour 60 minutes

1.5h 90 minutes

3mo 3 months

10d 10 days

Note that the year, quarter and month terms are imprecise, being defined as 365d, 91d and 30d respectively. For precision use the other terms.


timew-hints

title: timew-hints(7)

summary: Timewarrior hints

text:
# timew-hints(7)

## NAME
timew-hints - Timewarrior hints

## DESCRIPTION
Timewarrior supports hints, which are single-word command line features that start with a colon like this:

:week

Hints serve several purposes. This example is a shortcut for the date range that defines the current week.

Other hints, such as:

:quiet

Are ways to control the behavior of Timewarrior, in this case eliminating all forms of feedback, for purposes of automation.

The supported hints are:

:quiet Turns off all feedback. For automation

:debug Runs in debug mode, shows many runtime details

:yes Overrides confirmation by answering 'yes' to the questions

:color Force color on, even if not connected to a TTY

:nocolor Force color off, even if connected to a TTY

:blank Leaves tracked time out of a report

:fill Expand time to fill surrounding available gap

:adjust Automatically correct overlaps

:ids Displays interval ID numbers in the summary report

Range hints provide convenient shortcuts to date ranges:

:yesterday The 24 hours of the previous day

:day The 24 hours of the current day

:week This week

:month This month

:quarter This quarter

:year This year

:lastweek Last week

:lastmonth Last month

:lastquarter Last quarter

:lastyear Last year

:monday Previous monday

:tuesday Previous tuesday

:wednesday Previous wednesday

:thursday Previous thursday

:friday Previous friday

:saturday Previous saturday

:sunday Previous sunday


timew-ranges

title: timew-ranges(7)

text:
# timew-ranges(7)

## NAME
timew-ranges - date and time ranges supported by Timewarrior

## DESCRIPTION
An interval defines a block of time that is tracked. The syntax for specifying an interval is flexible, and may be one of:

[from] <date>

[from] <date> to/- <date>

[from] <date> for <duration>

<duration> before/after <date>

<duration> ago

[for] <duration>

Examples are:

from 9:00

from 9am - 11am

from 9:00:00 to 11:00

from 9:00 for 2h

2h after 9am

2h before 11:00

2h ago

for 2h

An interval is said to be 'closed' if there is both a start and end, and 'open' if there is no end date.


tntnet.properties

package: tntnet

title: tntnet.properties(7)

summary: configuration-file for tntnet (8)

text:
# tntnet.properties(7)

## NAME
tntnet.properties - configuration-file for tntnet (8)

## DESCRIPTION
tntnet(8) uses cxxtools for logging and is configured in the configuration-file tntnet.properties.

Because cxxtools is a meta-logging-library, which can be compiled to use different logging-libraries, the content of tntnet.properties is dependend of the underlying logging-library. Cxxtool has a built-in logging-library as default, which is documented here.

### format
The format of tntnet.properties is line-based. A line consists of a variable-name followed by a equals-symbol and a value. Lines, which does not follow this format and lines, which start with a hash (#), are ignored. It is recomended to prefix non-empty comments with a hash to make clear, that it is a comment.

### level
The logging-library has 5 levels for logging: fatal, error, warn, info and debug. Fatal has the highers priority and "debug" the lowest.

### category
Each log-message has a category. Categories are hierarchical. Names of subcategories are devided by a dot.

### log-message
Each log-message has a level and a category. If the level of the message is higher or equal to the level of the category, the message is logged. To assign a level to a category put a line with the word "logger", a dot, the category, the symbol "=" and the category into tntnet.properties. Only the first letter of the value is checked and case is ignored, so e.g. info can be specified with INFO, info, I or even ixxxx. If no level is specified for the current category, the upper category is checked. If nothing is found, the default level is used. The default level is specified by the variable "rootLogger". If no rootLogger is specified, the level error is used.

### destination
If nothing else is specified, log-messages are printed to standard-output. To redirect output to a file, specify the filename with the variable file.

The cxxtools-logger can limit the size of the log-file by rolling log-files. If the limit is reached, the current file is renamed by appending ".1" to it. If there is already a file with that name, this file is renamed to "*.2" and so on, until the maximum backupfile limit is reached. The oldest file is deleted then. To specify the maximum file size, set the variable maxfilesize. The value specified here can be postfixed with 'k' or 'M' to specify kBytes or MBytes. The maximum fileindex backed up is set with maxbackupindex.

Log-messages can be sent to another host in the network with udp. This is done by specifying a hostname and a port with the variable host. The value must be a hostname, followed by a ':' and a port. Each log-message is sent in a single udp-message.

## EXAMPLES

### logging to standard-output:
rootLogger=INFO

logger.tntnet=WARN

### logging to a file with rolling file and a background-flusher:
rootLogger=INFO

logger.tntnet=WARN

file=tntnet.log

maxfilesize=1MB

maxbackupindex=10

### logging to another host
rootLogger=INFO

logger.tntnet=WARN

host=pluto.tntnet.org:1234

## AUTHOR
This manual page was written by Tommi Mäkitalo <tommi@tntnet.org>.

## SEE ALSO
tntnet(8)


tntnet.xml

title: tntnet.xml(7)

summary: configuration file for

text:
# tntnet.xml(7)

## NAME
tntnet.xml - configuration file for tntnet(8)

## DESCRIPTION
Tntnet is configured using a xml file. The name of the file is tntnet.xml. The root node of tntnet.xml should be tntnet while it is not checked. Most of the settings are just single values. They are described here in alphabetical order.

## SETTINGS
This section describes the variables, used by Tntnet (8).

<accessLog>filename</accessLog>

Writes a log entry for each request in a common format. This format is compatible with most log file analyze systems for http servers.

The log file has the fields: peer-ip - username [time] "http-method query-string HTTP/major-version.minor-version" http-return-code content-size "referer" "user-agent"

The username, referer and user-agent may be '-' when the value is not available. Also the content-size can be empty in some cases.

Example

```
<accessLog>/var/log/tntnet/access.log</accessLog
```

<bufferSize>bytes</bufferSize>

Specifies the number of bytes sent in a single system-call. This does not limit anything in application-level. It does not affect e.g. savepoints or exception-handling. Component-output is collected completely and then passed in chunks of bufferSize bytes to the operating system.

The default value is 16384.

<comppath> [ <entry>path1</entry> ] </comppath>

comppath specifies, where tntnet should search for webapplications. Tntnet searches first in the current directory and then in each directory, you specify here, until a library is found. You can repeat the directive as many times as desired to add more entries. If it is not found, the next mappings entry is tried.

Example

```
<comppath>

  <entry>/usr/local/lib/tntnet</entry>

  <entry>/usr/local/share/tntnet</entry>
</comppath>
```

<chroot>directory</chroot>

Does a chroot(2)-system call on startup, which locks the process into the directory at system-level.

Example

```
<chroot>/var/tntnet</chroot>
```

<daemon>0|1</daemon>

If this flag is set to 1, Tntnet forks at startup and terminates the parent-process on successful initialization.

<dir>directory</dir>

Changes the current working directory of the process on startup.

Example

```
<dir>/var/tntnet</dir>
```

<enableCompression>yes|no</enableCompression>

Specifies, if Tntnet should use gzip-compression at http-level. By default Tntnet use compression. A http-client like a web browser can send a header "Accept-Encoding", to tell Tntnet, that it would accept compressed data. Tntnet then can decide, if it use compression. When the body is complete, Tntnet tries to compress the body. If the data can be compressed by more than 10%, Tntnet sends this compressed data. With this flag, this feature can be turned off.

Compression slows down processing but reduces the network-load. Normally the size of html-pages can be compressed by about 70%, while Tntnet slows down by up to 30%.

Example

```
<enableCompression>no</enableCompression>
```

<errorLog>filename</errorLog>

Redirects stderr to the specified file when tntnet runs as a daemon. If ErrorLog is not set stderr is redirected to /dev/null.

Example

```
<errorLog>/var/log/tntnet/error.log</errorLog>
```

<group>unix-group-id</group>

Changes the group under which tntnet runs.

The user is changes using the system call setgid(2), which is only allowed, when tntnet starts as root user.

Example

```
<group>tntnet-group</group>
```

<keepAliveTimeout>milliseconds</keepAliveTimeout>

Sets the timeout for keep-alive requests.

Tntnet tries to do keep-alive-requests wherever possible. This has the effect, that tntnet can receive multiple requests within a single tcp-connection. The connection times out after KeepAliveTimeout milliseconds. The timeout defaults to 15000ms.

Example

```
<keepAliveTimeout>300000</keepAliveTimeout>
```

<keepAliveMax>number</keepAliveMax>

Sets the maximum number of request per tcp-connection. This defaults to 100.

Example

```
<keepAliveTimeout>10</keepAliveTimeout>
```

<listeners>listener definition</listeners>

Specifies, on which local interfaces tntnet waits for connections. There can be more than one Listen-directives, in which case tntnet waits on every address.

See separate section Listeners

<logging>listener definition</logging>

Configures logging. See separate section logging

<listenRetry>number</listenRetry>

On startup Tntnet calls listen on the specified port. When the systemcall returns with an error, Tntnet tries again and fails after the specified number of attempts.

The default number is 5.

Example

```
<listenRetry>10</listenRetry>
```

<listenBacklog>number</listenBacklog>

The system-call listen(3p) needs a parameter backlog, which specifies, how many pending connections the operating-system should queue before it starts to ignore new request. The value is configurable here.

The default value is 16.

Example

```
<ListenBacklog>64</ListenBacklog>
```

<mappings>urlmappings</mappings>

This is the most important setting for tntnet. It specifies, which components schould be called on which urls.

For details see the section Url mapping.

<maxUrlMapCache>number</maxUrlMapCache>

Mapping urls to components is done using regular expressions. Executing these expressions is quite expensive while the number of different urls is quite limited in typical web applications. Hence tntnet caches the results.

The caching algorithm is very simple. Tntnet just collects the results in a map. When the maximum size of the list is reached, it is cleared. This makes management of the cache very cheap.

This setting sets the maximum number of entries in the map.

If you see frequently a warning message, that the cache is cleared, you may consider increasing the size.

The default value is 8192.

Example

```
<maxUrlMapCache>32768</maxUrlMapCache>
```

<maxRequestSize>number</maxRequestSize>

This directive limits the size of the request. After number Bytes the connection is just closed. This prevents denial-of-service-attacks through long requests. Every request is read into memory, so it must fit into it. Bear in mind, that if you use file-upload-fields a request might be larger than just a few bytes.

The value defaults to 0, which means, that there is no limit at all.

Example

```
<maxRequestSize>65536</maxRequestSize>
```

<maxRequestTime>seconds</maxRequestTime>

In daemon mode tntnet has a watchdog, which restarts tntnet when the maximum request time is exceeded. This happens, when a request is in a endless loop or otherwise hangs. Restarting tntnet looses all active sessions and the currently running requests. Therefore the timeout should be well long enough for the longes request.

The default value is 600 seconds, which is normally much longer than a http request should run. If the Timeout is set to 0, the watchdog is deactivated.

Example

```
<maxRequestTime>1200</maxRequestTime>
```

<minThreads>number</minThreads>

Tntnet uses a dynamic pool of worker-threads, which wait for incoming requests. MinThreads specifies, how many worker threads there have to be. This defaults to 5.

Example

```
<minThreads>10</minThreads>
```

<minCompressSize>number</minCompressSize>

Http-compression for replies smaller than this are not compressed at all.

The default value for this is 1024.

Example

```
<minCompressSize>256</minCompressSize>
```

<mimeDb>filename</mimeDb>

Specify filename for mime db. The default is /etc/mime.types.

The format of the file is just like this /etc/mime.types. A mime type is followed after white space by a list of file extensions delimited by white space.

<maxThreads>number</maxThreads>

Tntnet uses a dynamic pool of worker-threads, which wait for incoming requests. maxThreads limits the number of threads.

The default is 100.

Example

```
<maxThreads>200</maxThreads>
```

<pidFile>filename</pidFile>

When run in daemon-mode, tntnet writes the process-id of the monitor-process to filename. When the monitor-process is deactivated, the pid of the worker-process is written. This ensures, that sending a sigkill to the the stored process-id stops tntnet.

Example

```
<pidFile>/var/run/tntnet.pid</pidFile>
```

<queueSize>number</queueSize>

Tntnet has a request-queue, where new requests wait for service. This sets a maximum size of this queue, after wich new requests are not accepted.

The default value is 1000.

Example

```
<queueSize>50</queueSize>
```

<sessionTimeout>seconds</sessionTimeout>

This sets the number of seconds without requests after which a sesssion is timed out.

The default value is 300 seconds.

Example

```
<sessionTimeout>600</sessionTimeout>
```

<socketReadTimeout>milliseconds</socketReadTimeout>

A worker-thread waits for some milliseconds on incoming data. If there is no data, the job is put into a queue and another thread waits with poll(2) on incoming data on multiple sockets. The workerthreads are freed and they can respond to other requests quickly. The default value is 10 milliseconds, which is good for normal operation. A value of 0 results in non-blocking read. If timeout is reached, this does not mean, that the socket is closed. A small timeout reduces contextswitches on slow connections.

Example

```
<socketReadTimeout>0</socketReadTimeout>
```

<socketWriteTimeout>milliseconds</socketWriteTimeout>

This defines the time, how long the workerthreads wait on write. If the timeout is exceeded, the socket is closed and the browser might not get all data. The default value is 10000 milliseconds.

Example

```
<socketWriteTimeout>20000</socketWriteTimeout>
```

<threadStartDelay>ms</threadStartDelay>

When additional worker threads are needed tntnet waits the number of milliseconds before it starts additional threads to prevent high load when starting many threads at once.

The default value is 10ms.

Example

```
<threadStartDelay>1000</threadStartDelay>
```

<user>username</user>

Changes the user under which tntnet answers requests.

The user is changes using the system call setuid(2), which is only allowed, when tntnet starts as root user.

Example

```
<user>www-data</user>
```

## URL MAPPING
Tntnet is a web server, which receives http requests from a http client and answers them. A http request has a url and other attributes, which are used to decide, how the answer should look like. This is done my mapping urls to components.

A component is something, which generates a http reply. They are normally generated with the ecpp compiler ecppc(1). The ecppc compiler generated C++ classes with component names. The classes are compiled and linked into a shared library. Both the component name and the shared library name is needed to identify a component.

The component identifier is a string built from the component name, the @ character and the shared library name. A example is myclass@myapplication. This tells tntnet: load shared library myapplication and call the component with the name myclass in that library, which creates the reply to the request.

To tell tntnet, which component to call, url mappings must be configured.

Configuration is done in the xml section <mappings>. Multiple mappings can be configured there. A mapping has a condition and a target. Tntnet looks in the list of mappings for the first mapping, where the condition is met and uses that to call the component. The component may return either a reply - then the request is done or a special value DECLINED, which tells tntnet to continue in the list and look for the next mapping, where the condition is met.

The component, which returns DECLINED may already have generated part of the request. This is preserved for the next mapping. A common use case is to write a special component, which just checks the user name and password. If the user name and password is valid, DECLINED is returned and tntnet calls the next mapping where the condition is met.

Also when the condition is met, but the component could not be loaded, tntnet continues with the next mapping.

When the end of the list is reached and no mapping returned a http reply code, tntnet replies with http not found (404) error.

So how these mapping are specified then?

The mapping contains 3 kind of nodes:

conditions

Multiple conditions can be specified. All conditions must be met when the mapping is to be used.

The most important is <url>, which contains a extended regular expression (see regex(7) for details). This expression is checked against the url of the request. If the url tag is omitted, the mapping is used for every url.

The condition <vhost> specifies the virtual host, for which this mapping is valid. When this is specified, the mapping is only valid for requests, where the virtual host matches the setting. The value is also a extended regular expression. Note, that a dot matches any character in regular expressions, which may be irritating here. If you want to specify a mapping for the all hosts of the domain tntnet.org, you have to set <vhost>tntnet\.org$</vhost>. Also the dollar sign at the end is important, since it matches the end of the string. Otherwise the mapping would be also valid for a virtual host like tntnet.org.foo.com, which may not be what you meant.

The condition method specifies the http method for which the mapping should be considered. Again a extended regular expression is used.

The condition ssl is a boolean value. The value should be 0 or 1. The setting checks, whether this mapping should be used depending on ssl. If the value is 1, the condition is met, when the request is sent via ssl. If the value is 0, the condition is met, when the request is sent without ssl.

target

The mapping node contains a node <target>, which contains the component name, which is to be called when the conditions are met.

The target may contain back references to the regular expression in the <url> condition. Parts of the regular expression may be in brackets. In the target $1 is replaced with the first bracketed expression, $2 with the second and so on.

This node is mandatory.

parameters

When the condition is met, additional parameters may be passed to the called component. There are 2 nodes for this.

The node <pathinfo> can be requested in the component using request.getPathInfo(). If the node is not set, the url is set as path info.

The node <args> contains additional parameters, which can be passed to the component. The node can have any number of nodes with values. The tags are used as a parameter name and the content as the value. The method request.getArg(name) returns the value of the specified name. When the node is not set, the method returns a empty string. Optionally a diffrent default value can be passed to the method as an additional parameter like request.getArg(name,defaultValue).

For compatibility reasons with older tntnet request.getArg accepts a numeric argument. Previously the arguments did not have names but were accessed by index. To emulate this, request.getArg with a numeric argument translates the number into the name "argnumber". So accessing request.getArg(2) returns the value of the argument with the name arg2. Accessing a numeric argument equal or greater than the number of arguments (the first is number 0) used to be not allowed. Now a empty string is returned.

Example

```
<mappings>

  <!-- map / to index@myapp -->

  <mapping>

    <target>index@myapp</target>

    <url>^/$</url>

    <pathinfo>index.html</pathinfo>

  </mapping>

  <!-- map /comp.* or /comp to comp@myapp -->

  <mapping>

    <target>action@myapp</target>

    <url></url>               <!-- any url -->

    <method>POST</method>     <!-- but only on method POST -->

    <vhost>localhost</vhost>  <!-- and host header must be localhost -->

    <ssl>1</ssl>              <!-- and ssl is enabled -->

  </mapping>

  <mapping>

    <target>$1@myapp</target>

    <url>^/([^.]+)(\.(.+))?</url>

    <args>

      <extension>$2</extension>

    </args>

  </mapping>
</mappings>
```

## LISTENERS
The section <listeners> specifies the ip addresses and ports, where tntnet waits for incoming requests. Multiple listeners may be defined, when tntnet should listen on multiple ip addresses or ports.

Each listener is defined in a node <listener>. A listener must have a subnode <ip> and <port>. The node <ip> may contain a ip address or hostname or may be left empty. If the node is empty, any interface is used. The <port> must contain the numeric port number.

The ip address may be a IPv4 or IPv6 address.

Optionally a tag <certificate> may be added. This enables ssl on the interface and specifies the ssl host certificate for the interface. Note that tntnet can be built without ssl support. In that case the certificate is just ignored and unencrypted http is used here.

Example

```
<listeners>

  <listener>

    <ip></ip>

    <port>80</port>

  </listener>

  <listener>

    <ip></ip>

    <port>443</port>

    <!-- a certificate enables ssl -->

    <certificate>tntnet.pem</certificate>

  </listener>
</listeners>
```

## AUTHOR
This manual page was written by Tommi Mäkitalo tommi@tntnet.org.

## SEE ALSO
tntnet (1)