dunst

package: dunst

title: dunst(5)

summary: dunst configuration file

text:
# dunst(5)

## NAME
dunstrc - dunst configuration file

## DESCRIPTION
The configuration is divided into sections in an ini-like format. Every section starts with the section's name in square brackets. After that is a list of key-value pairs that specify the settings. Whitespace is purely cosmetic and doesn't change the result.

The "global" section contains the general settings applying to all of dunst. The rest of the settings can be specified via rules and can be located in any section. These rules can change a notification based on its properties. There are filtering rules and modifying rules. Filtering rules specify what notifications the rule applies to. Modifying rules specify changes to the matching notifications. Some special sections have implied filters that cannot be changed. For example, the "global" section has no filters: it applies to all notifications.

See RULES for more details.

The "experimental" section contains experimental and unstable settings. These options can change in breaking ways between releases. If you find a problem with these new features, make sure to report it.

### Global section
default_pause_level (values: [0-100], default: 0)

Specify a pause level to be set on dunst startup. Notifications are only shown if their urgency level is higher than the pause level. See override_pause_level for more information.

monitor (default: 0)

Specifies on which monitor the notifications should be displayed in, either by name or by number, starting from 0. See the follow setting.

follow (values: [none/mouse/keyboard], default: none)

Defines where the notifications should be placed in a multi-monitor setup. All values except none override the monitor setting. On Wayland there is no difference between mouse and keyboard focus. When either of them is used, the compositor will choose an output. This will generally be the output last interacted with.

none

The notifications will be placed on the monitor specified by the monitor setting.

mouse

The notifications will be placed on the monitor that the mouse is currently in.

keyboard

The notifications will be placed on the monitor that contains the window with keyboard focus.

enable_posix_regex (default: false)

When set to true (recommended), you can use POSIX regular expressions for filtering rules. It uses the POSIX Extended Regular Expression syntax: https://en.m.wikibooks.org/wiki/Regular_Expressions/POSIX-Extended_Regular_Expressions. If this is set to false (not recommended), dunst will use fnmatch(3) for matching strings. Dunst doesn't pass any flags to fnmatch, so you cannot make use of extended patterns.

The POSIX syntax is more powerful and will eventually become the default. The main differences between POSIX and fnmatch(3) is that POSIX uses ".*" for wildcards instead of "*" and POSIX allows for partial matches without needing wildcards. This means that the pattern "abc" will match all strings that contain "abc", like "abcdef".

geometry DEPRECATED

This setting is deprecated and removed. It's split up into width, height, origin, notification_limit and offset. For quickly transitioning to the new syntax, you can take the numbers from your old geometry config as follows:

geometry = <width>x<height>+<offset> In the new config you can then set the following variables (make sure to remove any negative signs)

```
    width = <width>
    height = <height>
    offset = <offset>
    origin = top-right # or top-left, or any other direction you prefer

```

width

The width of the notification window in pixels. This can be a single number to specify a constant width or two numbers for the minimum and maximum width. The notification will expand from the minimum width as neccesary. Examples:

```
    width = 300      # constant width of 300
    width = (0, 300) # width between 0 and 300

```

When setting a width bigger than the screen, dunst will clamp the width to the screen width. So if you want the notifcation to stretch the entire screen dynamically, you may set the width to a high enough number, which none of your screens exceed (e.g. 10000).

height

The height of each notification in pixels. This can be a single number to specify a constant height or two numbers for the minimum and maximum width. The notification will expand from the minimum height as neccesary. Examples:

```
    height = 300      # constant height of 300
    height = (0, 300) # height between 0 and 300

```

Note that unlike width, different notifications can have diffrent height values.

Dunst v1.11 and older do not support a dynamic height and height accepts a single value whose behaviour is equivalent to (0, value).

notification_limit (default: 20)

The number of notifications that can appear at one time. When this limit is reached any additional notifications will be queued and displayed when the currently displayed ones either time out or are manually dismissed. The value 0 means no limit. If indicate_hidden is true, then the specified limit is reduced by 1 and the last notification is a message informing how many hidden notifications are waiting to be displayed. See the indicate_hidden entry for more information.

origin (default: top-right)

The origin of the notification window on the screen. It can then be moved with offset. Origin can be one of:

```
    top-left
    top-center
    top-right
    bottom-left
    bottom-center
    bottom-right
    left-center
    center
    right-center

```

offset (format: (horizontal, vertical), default: (10, 50))

Respectively the horizontal and vertical offset in pixels from the corner of the screen specified by origin. A negative offset will lead to the notification being off screen. Examples:

```
    origin = top-right
    offset = (10, 300) # a margin of 10 pixels from the right and 300 pixels from the top

```

Dunst v1.11 and older use the syntax NxN instead (X offset x Y offset). For backwards compatibility this syntax is also accepted.

```
    offset = 10x300

```

scale (default: 0) (X11 only)

Specifies a scale factor for dimensions to adapt notifications to HiDPI screens. This scales the notification geometry and it's contents. It is not recommended to use a fractional scaling factor, as this may result in things being one pixel off. Try to use a whole number scaling factor and adjust the font size and other sizes as needed. If 0 is specified, the scale factor is auto-detected.

progress_bar (values: [true/false], default: true)

When an integer value is passed to dunst as a hint (see NOTIFY-SEND), a progress bar will be drawn at the bottom of the notification. This behavior can be turned off by setting this setting to false.

progress_bar_horizontal_alignment (values: [left/center/right], default: center)

Horizontal alignment of the progress bar. The progress bar will always keep a distance of horizontal_padding from the edge of the notification.

progress_bar_height (default: 10)

The height of the progress bar in pixel. This includes the frame. Make sure this value is bigger than twice the frame width.

progress_bar_min_width (default: 150)

The minimum width of the progress bar in pixels. The notification is rescaled to fit the bar.

progress_bar_max_width (default: 300)

The maximum width of the progress bar in pixels. The notification is resized to fit the progress bar.

progress_bar_frame_width (default: 1)

The frame width of the progress bar in pixels. This value should be smaller than half of the progress bar height.

progress_bar_corner_radius (default: 0)

The corner radius of the progress bar in pixels. Gives the progress bar rounded corners. Set to 0 to disable. This setting will be ignored if progress_bar_corners is set to none.

progress_bar_corners (default: all)

Define which corners to round when drawing the progress bar. If progress_bar_corner_radius is set to 0 this option will be ignored. See the corners setting for the value format.

icon_corner_radius (default: 0)

The corner radius of the icon image in pixels. Gives the icon rounded corners. Set to 0 to disable. This setting will be ignored if icon_corners is set to none.

icon_corners (default: all)

Define which corners to round when drawing the icon image. If icon_corner_radius is set to 0 this option will be ignored. See the corners setting for the value format.

indicate_hidden (values: [true/false], default: true)

If this is set to true, a notification indicating how many notifications are not being displayed due to the notification limit (see notification_limit) will be shown in place of the last notification slot. Meaning that if this is enabled the number of visible notifications will be 1 less than what is specified by notification_limit, the last slot will be taken by the hidden count.

transparency (default: 0) (X11 only)

A 0-100 range on how transparent the notification window should be, with 0 being fully opaque and 100 invisible. This will affect the whole window. To make only parts of a window transparent set the alpha channel in a color, see COLORS.

To make windows transparent on wayland, set the transparent part of a color, see COLORS.

This setting will only work if a compositor is running.

separator_height (default: 2)

The height in pixels of the separator between notifications, if set to 0 there will be no separating line between notifications. This setting will be ignored if gap_size is greater than 0.

padding (default: 8)

The distance in pixels from the content to the separator/border of the window in the vertical axis.

horizontal_padding (default: 8)

The distance in pixels from the content to the border of the window in the horizontal axis.

text_icon_padding (default: 0)

The distance in pixels from the text to the icon (or vice versa) in the horizontal axis. Setting this to a non-zero value overwrites any padding that horizontal_padding was adding between the notification text and icon.

So for example setting

```
    text_icon_padding=10
    horizontal_padding=10

```

is equivalent to

```
    text_icon_padding=0
    horizontal_padding=10

```

frame_width (default: 3)

Defines width in pixels of frame around the notification window. Set to 0 to disable.

gap_size (default: 0)

Size of gap to display between notifications. If value is greater than 0, separator_height will be ignored and a border of size frame_width will be drawn around each notification instead.

This setting requires a compositor and any applications displayed between the gaps are not currently clickable.

separator_color (values: [auto/foreground/frame/#RRGGBB], default: frame)

Sets the color of the separator line between two notifications.

auto

Dunst tries to find a color that fits the rest of the notification color scheme automatically.

foreground

The color will be set to the same as the foreground color of the topmost notification that's being separated.

frame

The color will be set to the frame color of the notification with the highest urgency between the 2 notifications that are being separated.

anything else

Any other value is interpreted as a color, see COLORS.

sort (values: [true/false/id/urgency_ascending/urgency_descending/update], default: true)

If set to true or urgency_descending, display notifications with higher urgency above the others. critical first, then normal, then low. If set to false or id, sort notifications by id.

If set to urgency_ascending, notifications are sorted by urgency, low first, then normal, then critical.

If set to update, notifications are sorted by their update_time. So the most recent is always at the top. This means that if you set sort to update, and stack_duplicates to true, the duplicate will always be at the top.

When the notification window is at the bottom of the screen, this order is automatically reversed.

idle_threshold (default: 0)

Don't timeout notifications if user is idle longer than this time. See TIME FORMAT for valid times. Set to 0 to disable.

A client can mark a notification as transient to bypass this setting and timeout anyway. Use a rule with 'set_transient = no' to disable this behavior.

Note: this doesn't work on xwayland.

layer (values: [bottom/top/overlay], default: overlay) (Wayland only)

Place dunst notifications on the selected layer. Using overlay will cause notifications to be displayed above fullscreen windows, though this may also occur at top depending on your compositor. The bottom layer is below all windows and above the background.

force_xwayland (values: [true/false], default: false) (Wayland only)

Force the use of X11 output, even on a wayland compositor. This setting has no effect when not using a Wayland compositor. This setting will be ignored if dunst was compiled without X11 support.

font (default: "Monospace 8")

Defines the font or font set used. Optionally set the size as a decimal number after the font name and space. Multiple font options can be separated with commas. This options is parsed as a Pango font description. More information on the string format can be found here https://docs.gtk.org/Pango/type_func.FontDescription.from_string.html.

line_height (default: 0)

The amount of extra spacing between text lines in pixels. Set to 0 to disable.

format (default: "<b>%s</b>\n%b")

Specifies how the various attributes of the notification should be formatted on the notification window. Regardless of the status of the markup setting, any markup tags that are present in the format will be parsed. Note that because of that, if a literal ampersand (&) is needed it needs to be escaped as '&'.

If '\n' or '\t' is present anywhere in the format, it will be replaced with a literal newline or tab respectively.

If any of the following strings are present, they will be replaced with the equivalent notification attribute.

For a complete markup reference, see <https://docs.gtk.org/Pango/pango_markup.html>.

%a appname

%s summary

%b body

%c category

%S stack_tag

%i iconname (including its path)

%I iconname (without its path)

%p progress value ([ 0%] to [100%])

%n progress value without any extra characters

%% literal %

If any of these exists in the format but hasn't been specified in the notification (e.g. no icon has been set), the placeholders will simply be removed from the format.

vertical_alignment (values: [top/center/bottom], default: center)

Defines how the text and icon should be aligned vertically within the notification.

show_age_threshold (default: 60)

Show age of message if message is older than this time. See TIME FORMAT for valid times. Set to -1 to disable.

ignore_newline (values: [true/false], default: false)

If set to true, replace newline characters in notifications with whitespace.

stack_duplicates (values: [true/false], default: true)

If set to true, duplicate notifications will be stacked together instead of being displayed separately. Two notifications are considered duplicate if the name of the program that sent it, summary, body, icon and urgency are all identical.

hide_duplicate_count (values: [true/false], default: false)

Hide the count of stacked duplicate notifications.

show_indicators (values: [true/false], default: true)

Show an indicator if a notification contains actions and/or open-able URLs. See ACTIONS below for further details.

icon_path (default: "/usr/share/icons/gnome/16x16/status/:/usr/share/icons/gnome/16x16/devices/")

Can be set to a colon-separated list of paths to search for icons to use with notifications. Dunst doens't search outside of these direcories. For a recursive icon lookup system, see enable_recursive_icon_lookup. This new system will eventually replace icon_path search.

icon_theme (default: "Adwaita", example: "Adwaita, breeze")

Comma-separated list of names of the themes to use for looking up icons. This has to be the name of the directory in which the theme is located, not the human-friendly name of the theme. So for example, the theme Breeze Dark is located in /usr/share/icons/breeze-dark. In this case you have to set the theme to breeze-dark. The first theme in the list is the most important. Only if the icon cannot be found in that theme, the next theme will be tried.

Dunst will look for the themes in XDG_DATA_HOME/icons and $XDG_DATA_DIRS/icons as specified in the icon theme specification: https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html.

If the theme inherits from other themes, they will be used as a backup.

This setting is not enabled by default. See enable_recursive_icon_lookup for how to enable it.

enable_recursive_icon_lookup (default: false)

This setting enables the new icon lookup method. This new system will eventually be the old icon lookup. Currently icons are looked up in the icon_path. Since the icon_path wasn't recursive, one had to add a ton of paths to this list. This has been drastically simplified by the new lookup method. Now you only have to set icon_theme to the name of the theme you want. To enable this new behaviour, set enable_recursive_icon_lookup to true in the [global] section. See the respective settings for more details.

sticky_history (values: [true/false], default: true)

If set to true, notifications that have been recalled from history will not time out automatically.

history_length (default: 20)

Maximum number of notifications that will be kept in history. After that limit is reached, older notifications will be deleted once a new one arrives. See HISTORY.

dmenu (default: "/usr/bin/dmenu -p dunst")

The command that will be run when opening the context menu. Should be either a dmenu command or a dmenu-compatible menu.

browser (default: "/usr/bin/xdg-open")

The command that will be run when opening a URL. The URL to be opened will be appended to the end of the value of this setting.

always_run_script (values: [true/false] default: true]

Always run rule-defined scripts, even if the notification is suppressed with "format = """. See SCRIPTING.

title (default: "Dunst") (X11 only)

Defines the title (_NET_WM_NAME property) of notification windows spawned by dunst. There should be no need to modify this setting for regular use.

class (default: "Dunst") (X11 only)

Defines the class (WM_CLASS first part) of notification windows spawned by dunst. There should be no need to modify this setting for regular use.

force_xinerama (values: [true/false], default: false) (X11 only)

Use the Xinerama extension instead of RandR for multi-monitor support. This setting is provided for compatibility with older nVidia drivers that do not support RandR and using it on systems that support RandR is highly discouraged. By enabling this setting dunst will not be able to detect when a monitor is connected or disconnected which might break follow mode if the screen layout changes.

corner_radius (default: 0)

Define the corner radius in pixels. A corner radius of 0 will result in rectangular shaped notifications. By enabling this setting the outer border and the frame will be shaped. If you have multiple notifications, the whole window is shaped, not every single notification, unless if gaps are enabled (see gaps_size).

To avoid the corners clipping the icon or text the corner radius will be automatically lowered to half of the notification height if it exceeds it.

This setting will be ignored if corners is set to none.

corners (values: [none/all/bottom-right/bottom-left/top-right/top-left/top/bottom/left/right], default: all)

Comma-separated list of the corners to round when drawing the window. If the corner radius is set to 0 this option will be ignored.

mouse_[left/middle/right]_click (values: [none/do_action/close_current/close_all/context/context_all])

Defines action of mouse click. A touch input in Wayland acts as a mouse left click. A list of values, separated by commas, can be specified for multiple actions to be executed in sequence. Defaults:

- "mouse_left_click=close_current"

- "mouse_middle_click=do_action, remove_current"

- "mouse_right_click=close_all"

none

Don't do anything.

do_action

Invoke the action determined by the action_name rule. If there is no such action, open the context menu.

open_url

If the notification has exactly one url, open it. If there are multiple ones, open the context menu.

close_current

Close current notification.

close_all

Close all notifications.

context

Open context menu for the notification.

context_all

Open context menu for all notifications.

ignore_dbusclose (default: false)

Ignore the dbus CloseNotification message. This is useful to enforce the timeout set by dunst configuration. Without this parameter, an application may close the notification sent before the user defined timeout.

override_pause_level (values: [0-100], default: 0)

A notification will appear whenever notification's override_pause_level is greater than the paused level. Setting this to values other than 0 allows you to create partial pause modes, where more urgent notifications get through, but less urgent stay paused. For example, when you can set a low battery notification's override_pause_level to 60 and then set dunst's pause level to 60. This will cause dunst to only show battery level notification (and other notifications with override_pause_level >= 60), while suspending others.

### Keyboard shortcuts (X11 only)
Keyboard shortcuts are defined in the following format: "Modifier+key" where the modifier is one of ctrl,mod1,mod2,mod3,mod4 and key is any keyboard key.

Note that the keyboard shortcuts have been moved to the global section of the config for consistency with other settings.

Alternatively you can also define shortcuts inside your window manager and bind them to dunstctl(1) commands.

Wayland does not allow applications to listen to global keyboard events, so this feature can be implemented only for X.

close

Specifies the keyboard shortcut for closing a notification.

close_all

Specifies the keyboard shortcut for closing all currently displayed notifications.

history

Specifies the keyboard shortcut for recalling a single notification from history.

context

Specifies the keyboard shortcut that opens the context menu.

### Urgency sections
The urgency sections work in a similar way to rules and can be used to specify attributes for the different urgency levels of notifications (low, normal, critical). Currently only the background, foreground, hightlight, timeout, frame_color and icon attributes can be modified.

The urgency sections are urgency_low, urgency_normal, urgency_critical for low, normal and critical urgency respectively.

See the example configuration file for examples.

Old version of dunst allowed changing the colors of different urgencies through command line options. This has been long removed in favour of RULES, see issue #328.

### Experimental section
per_monitor_dpi (default: false)

Use different DPI for each monitor. This setting is currently implemented only for X11.

pause_on_mouse_over (default: false)

Pause notification timeout when hovering with the mouse pointer. This setting is currently implemented only for Wayland.

enable_pcre_regex (default: false)

Use PCRE regular expressions for filtering rules. For more information see https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions. This setting overrides enable_posix_regex.

## DUNSTCTL
Dunst now contains a command line control command that can be used to interact with it. It supports all functions previously done only via keyboard shortcuts but also has a lot of extra functionality. For more information, see dunstctl(1).

## HISTORY
Dunst saves a number of notifications (specified by history_length) in memory. These notifications can be recalled (i.e. redisplayed) by calling dunstctl history (see dunstctl(1)). Whether these notifications will time out like if they have been just send depends on the value of the sticky_history setting. Actions are invalidated once the notification is closed, so you cannot execute that action when you bring back a notification from history.

Past notifications are redisplayed in a first-in-last-out order, meaning that pressing the history key once will bring up the most recent notification that had been closed/timed out.

## WAYLAND
Dunst has Wayland support since version 1.6.0. Because the Wayland protocol is more focused on security, some things that are possible in X11 are not possible in Wayland. Those differences are reflected in the configuration. The main things that change are that dunst on Wayland cannot use global hotkeys, use dunstctl instead.

Some dunst features on Wayland might need your compositor to support a certain protocol. Dunst will warn you if an optional feature isn't supported and will disable the corresponding functionality.

Fullscreen detection works on wayland with some limitations (see fullscreen). If you want notifications to appear over fullscreen windows, set layer = overlay in the global options.

Note that the same limitations exist when using XWayland.

If something doesn't quite work in Wayland, please file a bug report. In the mean time, you can try if the X11 output does work on wayland. Use force_xwayland = true for that.

If you have your dunst notifications on the same side of your display as your status bar, you might notice that your notifications appear a bit higher or lower than on X11. This is because the notification cannot be placed on top of your status bar. The notifications are placed relative to your status bar, making them appear higher or lower by the height of your status bar. We cannot do anything about that behavior.

Note that dunst creates a "desktop layer" using the layer shell protocol and not a regular Wayland window. This has some limitations like stated above. For example you can't set a window title/class.

## RULES
Rules allow the conditional modification of notifications. They can be located in a section with any name, even the special sections. The special sections do not allow filters to be added, since they have implied filters by default.

'global'

No filters, matches all notifications.

'urgency_low', 'urgency_normal' and 'urgency_critical'

Matches low, normal or critical urgency respectively.

There are 2 parts in configuring a rule: Defining the filters that controls when a rule should apply and then the actions that should be taken when the rule is matched. It's also possible to not specify any filters, in which case the rule will match all notifications.

Rules are applied in order of appearance. Beware: if a notification is changed by a rule, it may affect if it's being matched by a later rule.

filtering

With filtering rules you can match notifications to apply rules to only a subset of notifications. For filtering rules that filter based on strings you can use regular expressions. It's recommended to set enable_posix_regex to true. You can then use the POSIX Extended Regular Expression syntax: https://en.m.wikibooks.org/wiki/Regular_Expressions/POSIX-Extended_Regular_Expressions. Eventually enable_posix_regex will be enabled by default.

A matching rule is made by assigning a filter attribute to the value you want to match. Shell-like globbing is supported when matching values.

If multiple filter expressions are present, all of them have to match for the rule to be applied (logical AND).

An example of rule that only operates on messages sent by notify-send is:

```
    appname="notify-send"

```

The allowed attributes are listed below.

"appname" (see also desktop_entry)

The name of the application as reported by the client. Be aware that the name can often differ depending on the locale used. It's recommended to use the "desktop_entry" filter instead.

"body"

The body of the notification

"category"

The category of the notification as defined by the notification spec. See https://specifications.freedesktop.org/notification-spec/latest/categories.html.

"desktop_entry"

GLib based applications export their desktop-entry name. In comparison to the appname, the desktop-entry won't get localized.

"icon"

The icon of the notification in the form of a file path. Can be empty if no icon is available or a raw icon is used instead. This setting is not to be confused with the icon setting in the urgency section.

"match_transient"

Match if the notification has been declared as transient by the client or by some other rule. See "set_transient" for more details about this attribute.

"match_dbus_timeout"

Matches the dbus timeout of the notification as set by the client or by some other rule. See "override_dbus_timeout" for more details about this attribute.

"msg_urgency"

Matches the urgency of the notification as set by the client or by some other rule. It is named so to not conflict with trying to modify the urgency.

"stack_tag"

Matches the stack tag of the notification as set by the client or by some other rule. See set_stack_tag for more information about stack tags.

"summary"

Matches the summary, 'title', of the notification.

modifying

A modifying rule, similarly to a filtering one, is made by assigning a value to a notification attribute in the rule definition. The following attributes can be overridden:

"background"

The background color of the notification. See COLORS for possible values.

"foreground"

The foreground color of the notification. See COLORS for possible values.

"highlight"

The highlight color of the notification. This color is used for coloring the progress bar. See COLORS for possible values. You can also set additional color values (as a comma-separated list) to define a linear gradient spanning all the length of the progress bar.

"format"

Equivalent to the "format" setting.

"frame_color"

The frame color color of the notification. See COLORS for possible values.

"fullscreen" (values: [delay/show/pushback/suppress], default: show)

This attribute specifies how notifications are handled if a fullscreen window is focused. By default it's set to show so notifications are being shown. Other possible values are delay: already shown notifications are continued to be displayed until they are dismissed or time out but new notifications will be held back and displayed when the focus to the fullscreen window is lost.

Or pushback which is equivalent to delay with the difference that already existing notifications are paused and hidden until the focus to the fullscreen window is lost.

There is additionally the suppress value. Existing notifications will be closed when entering fullscreen and new notifications will go straight to history. This is similar to pushback without redisplaying after leaving fullscreen mode.

On Wayland, if follow is set to mouse or keyboard, the output where the notification is located cannot be determined. So dunst will delay or pushback if any of the outputs is fullscreen. Since the fullscreen protocol is fairly new, you will need a recent version of a compositor that supports it. At the time of writing, you will need the git version of sway. See also layer to change if notifications appear above fullscreen windows in Wayland.

"min_icon_size" (default: 32)

Defines the minimum size in pixels for the icons. If the icon is larger than or equal to the specified value it won't be affected. If it's smaller then it will be scaled up so that the smaller axis is equivalent to the specified size. When using recursive icon lookup (see enable_recursive_icon_lookup), all icons from a theme will be this size.

If icon_position is set to off, this setting is ignored.

"max_icon_size" (default: 128)

Defines the maximum size in pixels for the icons. If the icon is smaller than or equal to the specified value it won't be affected. If it's larger then it will be scaled down so that the larger axis is equivalent to the specified size. Set to 0 to disable icon downscaling.

If both min_icon_size and max_icon_size are enabled, the latter gets the last say.

If icon_position is set to off, this setting is ignored.

"new_icon"

Updates the icon of the notification, it should be a path or a name for a valid image. This overrides the icon that was sent with dunstify or another notification tool. Expansion of the argument is carried out using wordexp(3) with command substitution disabled.

"icon_position" (values: [left/right/top/off], default: left)

Defines the position of the icon in the notification window. Setting it to off disables icons.

"default_icon"

Sets the default icon of the notification, it should be a path or a name for a valid image. This does not override the icon that was sent with dunstify or another notification tool. Expansion of the argument is carried out using wordexp(3) with command substitution disabled.

"set_stack_tag"

Sets the stack tag for the notification, notifications with the same (non-empty) stack tag and the same appid will replace each-other so only the newest one is visible. This can be useful for example in volume or brightness notifications where you only want one of the same type visible. The stack tag can be set by the client with the 'synchronous', 'private-synchronous' 'x-canonical-private-synchronous' or the 'x-dunst-stack-tag' hints.

"set_transient"

Sets whether the notification is considered transient. Transient notifications will bypass the idle_threshold setting. By default notifications are _not_ considered transient but clients can set the value of this by specifying the 'transient' hint when sending notifications.

"set_category"

Sets the category of the notification. For a list of standard categories see https://specifications.freedesktop.org/notification-spec/latest/categories.html.

"timeout"

Equivalent to the "timeout" setting in the urgency sections.

"override_dbus_timeout"

Overrides the timeout specified in dbus. This takes precedence over "timeout".

"urgency"

This sets the notification urgency. IMPORTANT NOTE: This currently DOES NOT re-apply the attributes from the urgency_* sections. The changed urgency will only be visible in rules defined later. Use "msg_urgency" to match it.

"override_pause_level"

See override_pause_level.

"skip_display"

Setting this to true will prevent the notification from being displayed initially but will be saved in history for later viewing.

"history_ignore"

Setting this to true will display the notification initially, but stop it from being recalled via the history.

"action_name" (default: "default")

Sets the name of the action to be invoked on do_action. If not specified, the action set as default action or the only available action will be invoked.

"word_wrap" (values: [true/false], default: true)

Specifies whether to wrap the text if the lines get longer than the maximum notification width. If it's set to true, long lines will be broken into multiple lines expanding the notification window height as necessary for them to fit. If the text doesn't fit in the window, it will be ellipsize according to ellipsize.

"ellipsize" (values: [start/middle/end], default: middle)

Specifies where truncated lines should be ellipsized.

"alignment" (values: [left/center/right], default: left)

Defines how the text should be aligned within the notification.

"hide_text" (values: [true/false], default: false)

Setting this to true will skip displaying any text related to the notification. The notification icon and progress bar will still be displayed. This option may be useful for notifications where an icon or progress bar may be sufficient information for the notification, such as audio volume or brightness level.

"markup" (values: [full/strip/no], default: no)

Defines how markup in notifications is handled. It's important to note that markup in the format option will be parsed regardless of what this is set to.

Possible values:

full

Allow a small subset of html markup in notifications

```
    <b>bold</b>
    <i>italic</i>
    <s>strikethrough</s>
    <u>underline</u>

```

For a complete reference see https://docs.gtk.org/Pango/pango_markup.html.

strip

This setting is provided for compatibility with some broken clients that send markup even though it's not enabled on the server. Dunst will try to strip the markup but the parsing is simplistic so using this option outside of matching rules for specific applications IS GREATLY DISCOURAGED.

See RULES for matching specific broken clients.

no

Disable markup parsing, incoming notifications will be treated as plain text. Dunst will not advertise that it can parse markup if this is set as a global setting.

### SCRIPTING
Within rules you can specify a script to be run every time the rule is matched by assigning the 'script' option to the name of the script to be run.

When the script is called details of the notification that triggered it will be passed via environment variables. The following variables are available: DUNST_APP_NAME, DUNST_SUMMARY, DUNST_BODY, DUNST_ICON_PATH, DUNST_URGENCY, DUNST_ID, DUNST_PROGRESS, DUNST_CATEGORY, DUNST_STACK_TAG, DUNST_URLS, DUNST_TIMEOUT, DUNST_TIMESTAMP, and DUNST_DESKTOP_ENTRY.

Another, less recommended way to get notifcations details from a script is via command line parameters. These are passed to the script in the following order: appname, summary, body, icon_path, urgency.

Where DUNST_ICON_PATH or icon_path is the absolute path to the icon file if there is one. DUNST_URGENCY or urgency is one of "LOW", "NORMAL" or "CRITICAL". DUNST_URLS is a newline-separated list of urls associated with the notification.

Note that some variables may be empty.

If the notification is suppressed, the script will not be run unless always_run_script is set to true.

The script parameter is expanded according to wordexp(3) with command substitution disabled. If the expanded value is not an absolute path, the directories in the PATH variable will be searched for an executable of the same name.

## COLORS
Colors are values with the format #RGB or #RRGGBB.

You may also specify a transparency component by using the format #RGBA or #RRGGBBAA.

NOTE: '#' is interpreted as a comment, to use it the entire value needs to be quoted. For example:

```
    separator_color="#123456"
```

## NOTIFY-SEND HINTS
Dunst is able to get different colors for a message via notify-send. In order to do that you have to add a hint via the -h option. The progress value can be set with a hint, too.

Note: Dunstify is compatible with notify-send and all of these settings work the same way.

All the accepted hints are listed below.

See RULES for more detailed explanations for some options.

fgcolor (type: string)

Foreground color.

bgcolor (type: string)

Background color.

frcolor (type: string)

Frame color.

hlcolor (type: string or string array)

Highlight color.

value (type: int or uint)

Progress value.

image-path (type: string)

Icon name. This may be a path or just the icon name. The alias image_path is also supported.

image-data (type: variant)

A stream of raw image data. The aliases image_data and icon_data are also supported.

category (type: string)

The category.

desktop-entry (type: string)

The desktop entry.

transient (type: int or boolean)

The transient value.

x-dunst-stack-tag (type: string)

The stack tag of the notification. A tagged notification will replace an earlier notification with the same tag.

x-canonical-private-synchronous (type: string)

Alias for x-dunst-stack-tag.

Some examples:

```
    notify-send -h string:fgcolor:#ff4444 "hello"
    notify-send -h string:bgcolor:#4444ff -h string:fgcolor:#ff4444 -h string:frcolor:#44ff44 ":)"
    notify-send -h int:value:42 "Working ..."
    notify-send -h string:x-canonical-private-synchronous:volume "Muted"
```

## ACTIONS
Dunst allows notifiers (i.e.: programs that send the notifications) to specify actions. Dunst has support for both displaying indicators for these, and interacting with these actions.

If "show_indicators" is true and a notification has an action, an "(A)" will be prepended to the notification format. Likewise, an "(U)" is prepended to notifications with URLs. It is possible to interact with notifications that have actions regardless of this setting, though it may not be obvious which notifications HAVE actions.

The "context" keybinding is used to interact with these actions, by showing a menu of possible actions. This feature requires "dmenu" or a dmenu drop-in replacement present.

Alternatively, you can invoke an action with a middle click on the notification. If there is exactly one associated action, or one is marked as default, that one is invoked. If there are multiple, the context menu is shown. The same applies to URLs when there are no actions.

## TIME FORMAT
A time can be any decimal integer value suffixed with a time unit. If no unit given, seconds ("s") is taken as default.

Time units understood by dunst are "ms", "s", "m", "h" and "d".

Example time: "1000ms", "10m".

## REPORTING BUGS
Bugs and suggestions should be reported on GitHub at https://github.com/dunst-project/dunst/issues.

## COPYRIGHT
Copyright 2011-2014 Sascha Kruse

Copyright 2014-2026 Dunst contributors

Dunst is released under the BSD 3-Clause License, see LICENSE for more information.

If you feel that copyrights are violated, please send an email to the maintainers.

## SEE ALSO
dunst(1), dunstctl(1), dmenu(1), notify-send(1), dunstify(1)


dwarfs-format

package: dwarfs-tools

title: dwarfs-format(5)

summary: DwarFS File System Format v2\.5

text:
# dwarfs-format(5)

## NAME
dwarfs-format - DwarFS File System Format v2.5

## DESCRIPTION
This document describes the DwarFS file system format, version 2.5.

## TERMINOLOGY

### High-Level Terms

- DwarFS image or DwarFS file system image: A file that contains a DwarFS file system. DwarFS archive is another commonly used term.

- Section: A contiguous part of a DwarFS image that contains either file system data or metadata. Each section has a header with a magic, version number, type, length and hashes for integrity checking.

- Header: An optional, arbitrary prefix before the first section of a DwarFS image. Typically, this is a shell script or other executable that intends to use the bundled DwarFS image. The DwarFS binary tools use an efficient algorithm to automatically skip this header.

- Block: A section of type BLOCK that contains file data. There can be an arbitrary number of BLOCK sections in a DwarFS image.

- Metadata: A section of type METADATA_V2 that contains all metadata to interpret the file system. Without the metadata, the structure of the file system is completely lost and all you will have is a collection of shredded bits and pieces of file data with no association to the original files.

- Inode: An entry in the inodes list in the metadata. Each inode represents a file system object, i.e. a directory, regular file, symlink, device, socket or pipe.

- Directory Entry: An entry in the dir_entries list in the metadata. Each directory entry associates a name with an inode number. Directory entries are grouped by directory using the directories list. Also, within a single directory, the entries are sorted asciibetically by name.

- Chunk: A part of a file that references a contiguous range of bytes in a single BLOCK. Each regular file inode references a list of chunks that, when concatenated, make up the contents of the file.

- Shared File: A regular file that shares its contents with one or more other regular files. This is similar to hardlinks, but on a "file level" instead of an "inode level". Each shared file has its own inode, but the inodes reference the same list of chunks through the shared_files_table.

### Internal Terms and Types

- file_view: An abstraction representing a single file in a file system and allowing read access to its contents. The exact mechanism to access the file contents is implementation-defined. Different implementation have different trade-offs in terms of memory usage, speed and error handling. For example, the default on 64-bit systems is to memory-map the entire file. While this is usually extremely fast, there are no means for gracefully handling I/O errors and they will typically result in the process crashing with a bus error (SIGBUS). On 32-bit systems, the default is to only memory-map "segments" of the file at a time. This limits the amount of address space used, bus uses more system calls and is thus slower. On either platform, it is also possible to use an implementation that reads data into allocated buffers. This is the slowest option and the one that will use the most process memory, but it is the only option that allows for graceful handling of I/O errors.

- file_extent: Using a file_view, you can iterate over the "extents" of a file. Extents are contiguous ranges of either data or holes. In sparse files, holes are ranges of zeros that do not actually occupy any space in the file system. This allows the code to efficiently skip over these holes if possible.

- file_segment: A contiguous range of data within a file. You can get a file_segment either directly from a file_view (using offset and size), or by using file_extent::segments() to iterate over a range of segments given the preferred segment size and an optional overlap between segments. A file_segment is always backed by contiguous memory representing the corresponding range of data in the file.

- Fragments are contiguous ranges of categorized file data. A categorizer can split each file into a sequence of fragments, each of which will be assigned a category. For example, the pcmaudio_categorizer will typically split an audio file into a pcmaudio/metadata fragment at the start, followed by a pcmaudio/waveform fragment, optionally followed by pcmaudio/metadata if there's any trailing metadata. The fragments from each category will be processed as separate streams: that is, all pcmaudio/metadata fragments will be ordered (e.g. by similarity) and the fed into the segmenter, which will further split each fragment into "chunks" (these are the chunks that will eventually be stored in the chunk_table in the metadata).

- Chunks are the smallest entity of contiguous file data that DwarFS manages. The segmenter splits data into chunks, adding references to data it has already seen if possible.

## FILE STRUCTURE
A DwarFS file system image is just a sequence of sections, optionally prefixed by a "header", which is typically some sort of shell script or other executable that intends to use the "bundled" DwarFS image.

Each section in the DwarFS image has the following format:

```
     ┌───┬───┬───┬───┬───┬───┬───┬───┐
0x00 │'D'│'W'│'A'│'R'│'F'│'S'│MAJ│MIN│  MAJ=0x02, MIN=0x05 for v2.5

     ├───┴───┴───┴───┴───┴───┴───┴───┤
0x08 │                               │  Used for full (slow) integrity

     ├─ SHA-512/256 integrity hash  ─┤  check with `dwarfsck`.
0x10 │  over the remainder of the    │

     ├─ section data, starting at   ─┤
0x18 │  offset 0x28.                 │

     ├─                             ─┤
0x20 │                               │

     ├───────────────────────────────┤
0x28 │  XXH3-64 hash over remainder  │  Used for fast integrity check.

     ├───────────────┬───────┬───────┤
0x30 │Section Number │SecType│CompAlg│  All integer fields are in LE

     ├───────────────┴───────┴───────┤  byte order.
0x38 │   Length of remaining data    │

     ├───────────────────────────────┤
0x40 │                               │

     │ Section data compressed using │

     │ CompAlg algorithm.            │

     │                               │

     │                               │

     │                               │

     └───────────────────────────────┘
```

A couple of notes:

- No padding is added between sections.

- The list of sections can easily be traversed by using the length field to skip to the start of the next section.

- Corruption can easily be detected using the XXH3-64 hash. Computation of this hash is so fast that it is in fact checked every single time a file system section is loaded.

- Integrity can furthermore be checked using the SHA-512/256 hash. This is much slower, but should rarely be needed.

- All header fields, except for the magic and version number, are protected by the hashes.

- In case of corruption, sections can easily be retrieved by scanning for the magic. The version number can be recovered by looking at all sections and choosing the majority. The explicit section number helps to recover data if multiple sections are missing.

- A major version number change will render the format incompatible.

- A minor version number change will be backwards compatible, i.e. an old program will refuse to read a file system with a minor version larger than the one it supports. However, a new program can still read all file systems with a smaller minor version number, although very old versions may at some point no longer be supported.

### Header Detection
In order to access the file system data when it is prefixed by a header, the size of the header must be known. It can either be given to the tools or the FUSE driver explicitly (using e.g. the --image-offset or -o offset options), or it can be determined automatically (by passing auto as the argument to the aforementioned options).

Automatic detection works by scanning the file for the section header magic (DWARFS) and validating the match by looking up the second section header using the length of the first section and also checking its magic. It is rather unlikely that a file is created accidentally that would pass this check, although one could be crafted manually without any problems.

### Section Types
Currently, the following different section types are defined:

BLOCK (0)

A block of data. This is where all file data is stored. There can be an arbitrary number of sections of this type. The file data in these BLOCKs can only be interpreted using the metadata section. The metadata contains a list of chunks for each file, each of which references a small part of the data in a single BLOCK.

METADATA_V2_SCHEMA (7)

The schema ../frozen/thrift/lib/thrift/frozen.thrift used to layout the METADATA_V2 section contents. This is stored in "compact" thrift encoding. The metadata cannot be read without the schema, as it defines the exact bit widths used to store each metadata field.

METADATA_V2 (8)

This section contains the bulk of the metadata. It's essentially just a collection of bit-packed arrays and structures. The exact layout of each list and structure depends on the actual data and is stored separately in METADATA_V2_SCHEMA. The metadata format is defined in metadata.thrift ../thrift/metadata.thrift and the binary format that derives from that definition uses Frozen2 ../frozen/thrift/lib/cpp2/frozen/Frozen.h. Frozen2 is not only extremely space efficient, it also allows accessing huge data structures directly through memory-mapping.

SECTION_INDEX (9)

The section index is, well, an index of all sections in the file system. If present (creation of the index can be suppressed with --no-section-index), this is required to be the last section. Each entry in the section index is a 64-bit value with the upper 16 bits being the section type and the lower 48 bits being the offset relative to the first section. That is, the section index is independent of whether or not a header is present before the first section. The whole point of the section index is to avoid having to build an index by visiting all section headers. Since the offsets in the index are sorted, the section index is always stored uncompressed, and the section index must be the last section, you can find the start of the section index by reading the last 64-bit value from the image file, checking if the upper 16 bits match the SECTION_INDEX type, and then add the image offset (header size) to the lower 48 bits. At that position in the file, you should find a valid section header for the section index.

HISTORY (10)

File system history information as defined thrift/history.thrift. This is stored in "compact" thrift encoding. Zero or more history sections are supported. This section type is purely informational and not needed to read the DwarFS image.

### Compression Algorithms
DwarFS supports a wide range of section compression algorithms, some of which require additional metadata. The full list of supported algorithms is defined in dwarfs/compression.h ../include/dwarfs/compression.h.

For compression algorithms with metadata, the metadata is defined in thrift/compression.thrift ../thrift/compression.thrift. The metadata is stored in "compact" thrift encoding at the beginning of the section, just after the header.

## METADATA FORMAT
Here is a high-level overview of how all the bits and pieces relate to each other:

```
═════════════           ┌─────────────────────────────────────────────────────────────────────────┐

 DwarFS v2.5            │                                                                         │
═════════════           │         ┌───────────────────────────────────────────┐                   │

                        │         │                                           │                   │

          dir_entries[] ▼         │              inodes[]                     │   directories[]   │
╔════╗   ┌────────────────┐       │  S_IFDIR ──►┌───────────────────┐         │  ┌────────────────┴─┐
║root╟──►│ name_index:  0 │       │             │ mode_index:     0 ├──────┐  └─►│ parent_entry:  0 │
╚════╝   │ inode_num:   0 ├───────┴────────────►│ owner_index:    0 │      │     │ first_entry:   1 │

         ├────────────────┤                     │ group_index:    0 │      │     | self_entry:    0 |

     ┌───┤ name_index:  2 │                     │ *time_offset: 417 │      │     ├──────────────────┤
┌────┼───┤ inode_num:   5 ├───────┐             │ *time_subsec:  13 │      │     │ parent_entry:  0 │
│    │   ├────────────────┤       │             │ nlink_minus_1:  0 │      │     │ first_entry:  11 │
│ ┌──┼───┤ name_index:  3 │       │             ├───────────────────┤      │     | self_entry:    1 |
│ │  │   │ inode_num:   9 ├────┐  │             │        ...        │      │     ├──────────────────┤
│ │  │   ├────────────────┤    │  │  S_IFLNK ──►├───────────────────┤      │     │ parent_entry:  5 │
│ │  │   │                │    │  │             │ mode_index:     2 │      │     │ first_entry:  12 │
│ │  │   │      ...       │    │  └────────────►│ owner_index:    2 │      │     | self_entry:    7 |
│ │  │   │                │    │                │ group_index:    0 │      │     ├──────────────────┤
│ │  │   └────────────────┘    │                │ *time_offset: 298 │      │     │       ...        │
│ │  │                         │                │ *time_subsec:  88 │      │     └──────────────────┘
│ │  │                         │                │ nlink_minus_1:  0 │      │
│ │  │    names[]              │                ├───────────────────┤      │      modes[]
│ │  │   ┌────────────┐        │                │        ...        │      │     ┌─────────────┐
│ │  │   │ "lib"      │        │     S_IFREG ──►├───────────────────┤      └────►│   0040775   │
│ │  │   ├────────────┤        │     (unique)   │ mode_index:     1 │            ├─────────────┤
│ │  │   │ "ls"       │        ├───────────────►│ owner_index:    0 ├──────┐     │   0100644   │
│ │  │   ├────────────┤        │                │ group_index:    0 │      │     ├─────────────┤
│ │  └──►│ "share"    │        │                │ *time_offset: 298 │      │     │     ...     │
│ │      ├────────────┤        │                │ *time_subsec:  94 │      │     └─────────────┘
│ └─────►│ "usr"      │        │                │ nlink_minus_1:  2 │      │
│        ├────────────┤        │                ├───────────────────┤      │      uids[]
│        │ "words"    │        │                │        ...        │      │     ┌─────────────┐
│        ├────────────┤        │     S_IFREG ──►├───────────────────┤      └────►│       0     │
│        │    ...     │        │  ┌──(shared)   │ mode_index:     4 │            ├─────────────┤
▼        └────────────┘        │  │             │ owner_index:    2 │            │    1000     │
(inode-off)                    │  │             │ group_index:    1 ├──────┐     ├─────────────┤
│                              │  │             │ *time_offset: 298 │      │     │     ...     │
│         symlink_table[]      │  │             │ *time_subsec:  38 │      │     └─────────────┘
│        ┌────────────┐        │  │             │ nlink_minus_1:  0 │      │
│        │      1     ├───┐    │  │             ├───────────────────┤      │      gids[]
│        ├────────────┤   │    │  │             │        ...        │      │     ┌─────────────┐
└───────►│      0     │   │    │  │  S_IFBLK ──►├───────────────────┤      │     │       0     │

         ├────────────┤   │    │  │  S_IFCHR    │                   │      │     ├─────────────┤

         │    ...     │   │  ┌─┼──┼─────────────┤        ...        │      └────►│     100     │

         └────────────┘   │  │ │  │             │                   │            ├─────────────┤

                          │  │ │  │ S_IFSOCK ──►├───────────────────┤            │     ...     │

                          │  │ │  │  S_IFIFO    │                   │            └─────────────┘

          symlinks[]      │  │ │  │             │        ...        │

         ┌────────────┐   │  │ │  │             │                   │

         │ "../foo"   │   │  │ │  │             └───────────────────┘                 chunks[]

         ├────────────┤   │  │ │  │                                                  ┌──────────────┐

         │ "foo/bar"  │◄──┘  │ │  │                                            ┌────►│ block:     0 │

         ├────────────┤      │ └──┼──────────►(inode-off)                      │     │ offset: 1698 │

         │    ...     │      │    │                │            chunk_table[]  │     │ size:   1012 │

         └────────────┘      ▼    ▼                │           ┌─────────────┐ │     ├──────────────┤

                   (inode-off)    (inode-off)      └──────────►│      0      ├─┘ ┌──►│ block:     0 │

                             │    │                            ├─────────────┤   │   │ offset: 1604 │

          devices[]          │    │      shared_files_table[]  │      1      ├───┘   │ size:     94 │

         ┌────────────┐      │    │     ┌───────────┐          ├─────────────┤       ├──────────────┤

         │   0x0107   │      │    └────►│     0     ├───┬─────►│      2      ├───┬──►│ block:     0 │

         ├────────────┤      │          ├───────────┤   │      ├─────────────┤   │   │ offset:    0 │

         │   0x0502   │◄─────┘          │     0     ├───┘      │      2      ├───┘   │ size:   1517 │

         ├────────────┤                 ├───────────┤          ├─────────────┤       ├──────────────┤

         │    ...     │                 │    ...    │          │     ...     │       │     ...      │

         └────────────┘                 └───────────┘          └─────────────┘       └──────────────┘
```

Thanks to the bit-packing, fields that are unused or only contain a single (zero) value, e.g. a group_index that's always zero because all files belong to the same group, does not occupy any space in the metadata section.

To ensure reproducibility (i.e. being able to generate bit-identical file system images when running mkdwarfs multiple times on the same input), the names, symlinks, modes, uids, and gids tables are always sorted in ascending order. The order of the remaining tables is deterministic, but dependent on the ordering algorithm used when building the file system image.

### Features
Up until v0.7.2, there were quite regular bumps to the minor version of the DwarFS format. This was a bit annoying, since it meant you could not upgrade mkdwarfs without also upgrading the FUSE driver, as an old driver would reject new file system images. The v0.7.3 release made two changes to address this:

- Any new section types would be ignored as long as the minor version number is unchanged. This means that new features that require new sections can be added without breaking backwards compatibility.

- New features, even ones that break compatibility, can be added without the need to bump the minor version number by adding a feature flag in the metadata (the features set). Each release knows which features it can support, and if it encounters a feature it doesn't know, it will refuse to mount the file system.

There's one small version gap that needs to be mentioned for completeness. Since v0.7.3 did not increment the minor version, releases v0.7.0 to v0.7.2 cat accept file system images with any features set. In practice, however, they will likely bail out because these releases do not accept unknown section types, and by default mkdwarfs has been adding HISTORY sections since v0.7.3. In hindsight, we should have bumped the accepted minor version in v0.7.3, but keep the written minor version the same until actually adding a feature. v0.14.0 finally increments the accepted minor version, and v0.16.0 will increment the written minor version, so long term this gap will be closed.

### Determining Inode Offsets
Before you can start traversing the metadata, you need to determine the offsets for symlinks, regular files, devices etc. in the inodes list. The index into this list is the inode_num from dir_entries, but you can perform direct lookups based on the inode number as well. The inodes list is strictly in the following order:

- directory inodes (S_IFDIR)

- symlink inodes (S_IFLNK)

- regular unique file inodes (S_IFREG)

- regular shared file inodes (S_IFREG)

- character/block device inodes (S_IFCHR, S_IFBLK)

- socket/pipe inodes (S_IFSOCK, S_IFIFO)

The offsets can thus be found by using a binary search with a predicate on the inode mode. The shared file offset can be found by subtracting the length of shared_files_table from the total number of regular files.

### Unique and Shared File Inodes
The difference between unique and shared file inodes is that there is only one unique file inode that references a particular index in the chunk_table, whereas there are multiple shared file inodes that will reference the same index. This is how DwarFS implements file-level de-duplication beyond hardlinks. Hardlinks share the same inode. Duplicate files that are not hardlinked each have a unique inode, but still reference the same content through the chunk_table.

The shared_files_table provides the necessary indirection that maps a shared file inode to a chunk_table index.

### Sparse Files
DwarFS can optionally support sparse files since v0.14.0. However, images created with sparse file support will not be backwards compatible.

Sparse file data is stored as usual. Holes are stored in the chunk_table using a "special" block index. In a file system with N blocks, the highest valid block index is N-1. Holes are stored using the block index N. This is cheaper than having to allocate an extra bit per chunk to indicate whether it's a data or a hole chunk. The block index used to encode a hole chunk is stored in the metadata as hole_block_index.

Since holes can get quite large, their size is encoded in both the size and offset fields of the corresponding chunk_table entry. While the offset field values are typically randomly distributed, the size field value distribution is usually skewed towards small values. Thus it makes sense to store the hole size as follows:

```
chunk.offset = hole_size % BLOCK_SIZE
chunk.size   = hole_size / BLOCK_SIZE
```

With large BLOCK_SIZE values, the chunk.size field will usually occupy a few bits less than the chunk.offset field. In order to prevent a single large hole from excessively widening the storage used for chunk.size, we use a separate list large_hole_size to store the sizes of holes that are larger than a certain threshold (that is derived from the block size). The index into this list will be stored in chunk.size, indicated by setting chunk.offset to BLOCK_SIZE - 1.

### Traversing the Metadata
You typically start at the root directory which is at dir_entries[0], inodes[0] and directories[0]. Note that the root directory implicitly has no name, so that dir_entries[0].name_index should not be used.

To determine the contents of a directory, we determine the range of entries from directories[inode_num].first_entry to directories[inode_num + 1].first_entry. If both values are equal, the directory is empty. Otherwise, we can look up the entries in dir_entries[].

So for directory inodes, you can directly index into directories using the inode number.

For link inodes, you can index into symlink_table, but you have to adjust the index for the link inode offset determined before:

```
link_index = symlink_table[inode_num - link_inode_offset]
```

With that, you can look up the contents of the symlink:

```
contents = symlinks[link_index]
```

For unique regular file inodes, you can index into chunk_table after adjusting the index:

```
chunk_index = inode_num - file_inode_offset
```

For shared regular file inodes, you can index into the (unpacked) shared_files_table:

```
shared_index = shared_files[inode_num - file_inode_offset - num_unique_files]
```

Then, you can index into chunk_table, but you need to adjust the index once more:

```
chunk_index = shared_index + num_unique_files
```

The range of chunks that make up a regular file inode is chunk_table[chunk_index] to chunk_table[chunk_index + 1]. If these values are equal, the file is empty. Otherwise, you need to look up the range of chunks in chunks.

Each chunk references a range of bytes in one file system BLOCK. These need to be concatenated to produce the file contents.

Both chunk_table and directories have a sentinel entry at the end to make sure you can perform range lookups for all indices.

Last but not least, to read the device id for a device inode, you can index into devices:

```
device_id = devices[inode_num - device_inode_offset]
```

## OPTIONALLY PACKED STRUCTURES
The overview above assumes metadata without any additional packing, which can be produced using:

```
mkdwarfs --pack-metadata=none,plain
```

However, this isn't the default, and parts of the metadata are likely stored in a packed format. These are mostly easy to unpack.

### Shared Files Table Packing
The shared_files_table can be stored in a packed format that only encodes the number of shared links to a chunk_table index. As the minimum number of links is always 2 (otherwise it wouldn't be shared), the numbers in the packed format are additionally offset by 2. So for example, a packed table like

```
[0, 3, 1, 0, 1]
```

would unpack to:

```
[0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 3, 3, 4, 4, 4]
```

The packed format is used when options.packed_shared_files_table is true.

### Directories Packing
The directories table, when stored in packed format, omits all parent_entry fields and uses delta compression for the first_entry fields.

In order to unpack all information, you first have to delta- decompress the first_entry fields, then traverse the whole directory tree once to fill in the parent_entry fields. This sounds like a lot of work, but it's actually reasonably fast. For example, for a file system with 15 million entries in 90,000 directories, reconstructing the directories takes only about 50 milliseconds.

The packed format is used when options.packed_directories is true.

### Chunk Table Packing
The chunk_table can also be stored delta-compressed and must be unpacked accordingly.

The packed format is used when options.packed_chunk_table is true.

### Hardlink Count Table
This isn't really "packing" per se, but more of an optimization. Hardlink counts (i.e. stat.st_nlink) can always be reconstructed by traversing the dir_entries and counting how many times each inode is referenced. This is reasonably fast, but can still cause a noticeable delay when mounting file systems with millions of entries (e.g. about 300ms for 10 million entries). It also uses 4 bytes per inode temporarily to store these counts.

However, correct hardlink counts are necessary, otherwise the fact that two directory entries reference the same inode can be very confusing to applications.

So by default, unless --no-hardlink-table is passed to mkdwarfs, the nlink_minus_one field will be populated for each inode. The inodes_have_nlink option will signal whether or not this field is valid. If it is not valid, the hardlink count table will be built each time the file system is mounted.

The reason for calling the field nlink_minus_one is that inodes must have at least one link, and storing only zeroes for a field requires no space at all. So, if the input to mkdwarfs has no hardlinks, there's no metadata overhead at all. (And that's what the inodes_have_nlink option is for: it helps determine if the fields are all zero because they were never set, or because the hardlink counts are actually all one.)

### Names and Symlinks String Table Packing
Both the names and symlinks tables can be stored in a packed format in compact_names and compact_symlinks.

There are two separate packing schemes which can be combined. If none of these schemes is active, the difference between e.g. names and compact_names is that the former is stored as a "proper" list, whereas the latter is stored as a single string plus an index of offsets. As lists of strings store both offset and length for each element, this already saves the storage for the length fields, which can easily be determined from the offsets at run-time.

If the packed_index scheme is used in addition, the index is stored delta-compressed.

Last but not least, the individual strings can be compressed as well. The fsst library https://github.com/cwida/fsst allows for compression of short strings with random access and is typically able to reduce the overall size of the string tables by 50%, using a dictionary that is only a few hundred bytes long. If a symtab is set for the string table, this compression is used. Note that in this case, the index refers to the position and length in the compressed string.

It's recommended to decompress the strings using the official FSST code, which is highly optimized and very fast. The rest of this section explains how to decompress the names manually, just to document all parts of the DwarFS format; you can skip to the next section if you're using the fsst library.

Decoding an FSST compressed string is very simple: each byte is a code, codes 00 to FE are an index into a string table, with each entry being a string 1-8 bytes in length, which are copied into the target buffer; code FF is an escape character, indicating that the following byte should be copied into the target buffer as-is. For example, if the contents of the string table were ["FS", "war", "!", "D"], the byte sequence 03 01 00 02 decodes to "DwarFS!".

The string table is constructed from the symtab record as follows:

Bytes 0 to 7 are the header and are of the form 01 ll xx xx 0A 14 34 01; bytes 2 and 3 store encoder parameters; they can be ignored. Byte 1 (ll) stores the number of codes, this information is redundant and can also be ignored, but it could be used as an additional sanity check if so desired. The rest is fixed and if any of those bytes are different, symtab should be considered to be corrupt.

Byte 8 should always be 00. If it's 01, it means the data was compressed as zero-terminated strings and requires slightly different decoding of symtab (described at the end of this section for completeness); DwarFS doesn't use zero-terminated strings; hence, in the following paragraphs we assume it's zero.

Bytes 9 to 16 are the histogram of string lengths in the string table: byte 9 is the number of 1-byte strings, byte 10 the number of 2-byte strings and so on. The sum of those values is always identical to byte 1 in the header.

The remaining bytes are the contents of the string table, but it starts with all the 2-byte strings concatenated, followed by all 3-byte strings, and so on until the 8-byte strings are followed by all 1-byte strings. The indices are assigned sequentially: the first entry read gets index 0, the second index 1, and so on.

For example, the string table used earlier would be stored as follows: the histogram would start with 02 01 01 with the rest being zeros, followed by the ASCII string "FSwar!D".

This concludes the description of FSST decompression. As mentioned earlier, byte 8 in the header should always be 00, but if it were 01, there are only 2 differences that need to be noted: entry zero in the string table is fixed to the 1-byte "\0" string, and that value is not stored in the symtab. However it is still counted in the histogram; so to construct the string table, the first code assigned has to be 1, not 0 and the first entry in the histogram has to be decremented by 1.

### Binary Metadata Format Details
The binary metadata is stored using Frozen2 ../frozen/thrift/lib/cpp2/frozen/Frozen.h. This format is, unfortunately, not really documented. Also, as of now, there is only a C++ implementation to read or write this format.

To interpret the binary data in the METADATA_V2 section, both the thrift definitions in metadata.thrift ../thrift/metadata.thrift and the schema ../frozen/thrift/lib/thrift/frozen.thrift from the METADATA_V2_SCHEMA section are needed.

You can inspect the schema using dwarfsck in two different ways. First, as a "raw" schema dump:

```
$ dwarfsck image.dwarfs -d schema_raw_dump
Schema {

  4: fileVersion (i32) = 1,

  1: relaxTypeChecks (bool) = true,

  2: layouts (map) = map<i16,struct>[44] {

    0 -> Layout {

      1: size (i32) = 0,

      2: bits (i16) = 6,

      3: fields (map) = map<i16,struct>[0] {

      },

      4: typeName (string) = "",

    },

    1 -> Layout {

      1: size (i32) = 0,

      2: bits (i16) = 5,

      3: fields (map) = map<i16,struct>[0] {

      },

      4: typeName (string) = "",

    },

    2 -> Layout {

      1: size (i32) = 0,

      2: bits (i16) = 12,

      3: fields (map) = map<i16,struct>[0] {

      },

      4: typeName (string) = "",

    },

    3 -> Layout {

      1: size (i32) = 0,

      2: bits (i16) = 11,

      3: fields (map) = map<i16,struct>[0] {

      },

      4: typeName (string) = "",

    },

    4 -> Layout {

      1: size (i32) = 0,

      2: bits (i16) = 23,

      3: fields (map) = map<i16,struct>[2] {

        2 -> Field {

          1: layoutId (i16) = 2,

          2: offset (i16) = 0,

        },

        3 -> Field {

          1: layoutId (i16) = 3,

          2: offset (i16) = -12,

        },

      },

      4: typeName (string) = "",

    },

    5 -> Layout {

      1: size (i32) = 0,

      2: bits (i16) = 11,

      3: fields (map) = map<i16,struct>[3] {

        1 -> Field {

          1: layoutId (i16) = 0,

          2: offset (i16) = -5,

        },

        2 -> Field {

          1: layoutId (i16) = 1,

          2: offset (i16) = 0,

        },

        3 -> Field {

          1: layoutId (i16) = 4,

          2: offset (i16) = 0,

        },

      },

      4: typeName (string) = "",

    },
[...]

    43 -> Layout {

      1: size (i32) = 36,

      2: bits (i16) = 282,

      3: fields (map) = map<i16,struct>[19] {

        1 -> Field {

          1: layoutId (i16) = 5,

          2: offset (i16) = 0,

        },

        2 -> Field {

          1: layoutId (i16) = 8,

          2: offset (i16) = -11,

        },

        3 -> Field {

          1: layoutId (i16) = 12,

          2: offset (i16) = -23,

        },
[...]

      },

      4: typeName (string) = "",

    },

  },

  3: rootLayout (i16) = 43,
}
```

To make any sense of this, you need to look at the metadata.thrift ../thrift/metadata.thrift with the explicit knowledge that the rootLayout in the schema refers to the struct metadata in the thrift IDL. With that in mind, you can now see that the struct metadata itself uses 36 bytes (or 282 bits) of storage. By definition, these bytes are located at the start of the METADATA_V2 section data. Note that these sizes are solely defined by the schema; another DwarFS image may store the struct metadata in fewer or more bits.

You can also line up the fields map in the Layout of struct metadata with the fields from the thrift IDL. While the names of the struct members can change, the numeric id never changes. So you can see that field 1 refers to the chunks member. You can also see that the layout for that field is 5, which can be looked up again in the layouts map of the schema.

The tricky bit is that layout 5 does not refer to the struct chunk in the IDL, but actually to the list<chunk>. A list (or an ArrayLayout in Frozen2) is represented using 3 fields: distance (1), count (2) and item (3). count is just the actual length of the list/array/vector. distance is the offset at which the data for the list starts. And item finally refers to the layout for the struct chunk, in this case 4.

Layout 4 contains 2 out of the 3 members of struct chunk: offset (2) and size (3). The first member, block, is missing simply because there is only one block in the DwarFS image we're looking at. Thus, no bits are used to represent the block member in struct chunk. For offset, 12 bits are allocated per item and for size, 11 bits are allocated.

Now, if we look at a hex dump of the METADATA_V2 section, we have enough context to navigate the data:

```
            v offset 0

            91 ac 55 b6  3e 2b 1a b2 c8 24 69 92  |......U.>+...$i.|

             |  |

             |  `-- 0b10101100

             |     vvv     ^^^ -> 0b100100 = distance = 36

             `-- 0b10010001

                      ^^^^^ count = 17
be 82 f7 0b 00 00 73 fa  c3 2e db 6e 4b 7e 17 3e  |......s....nK~.>|

                         v offset 36
6c 0d 77 b9 51 ef eb 02  a6 2a 00 4b 15 40 2d d0  |l.w.Q....*.K.@-.|

                          |  |  |

                          |  |  `- 0b00000000

                          |  `---- 0b00101010  0b00000000010 = size = 2

                          `------- 0b10100110  0b101010100110 = offset = 2726
0f 53 05 80 aa 02 70 55  04 88 aa 00 3c 55 00 aa  |.S....pU....<U..|
```

The bits are read starting from the LSB of the first byte (i.e. little- endian). We know that the data starts with the root layout, and the root layout starts with the ArrayLayout for list<chunk>. We know that the count is represented using 5 bits starting at offset 0. Reading the actual bits, we find that there are 17 chunks stored in the metadata. Reading the 6 distance bits starting at an offset of 5 bits (negative offsets are "bits", while positive offsets are "bytes"), we find that the 17 chunks are stored starting at the 36th byte.

If we move to that location and read 12 bits for the chunk offset and 11 bits of the chunk size, we find that the first chunk is 2 bytes from offset 2726 in block 0.

Another option to look at the schema is via frozen_layout:

```
$ dwarfsck image.dwarfs -d frozen_layout
36 byte (with 282 bits) ::dwarfs::thrift::metadata::metadata

  chunks @ start

    11 bit range of std::vector<dwarfs::thrift::metadata::chunk, std::allocator<dwarfs::thrift::metadata::chunk> >

      distance @ bit 5

        6 bit packed unsigned unsigned long

      count @ start

        5 bit packed unsigned unsigned long

      item @ start

        23 bit ::dwarfs::thrift::metadata::chunk

          block @ start

            empty packed unsigned unsigned int

          offset @ start

            12 bit packed unsigned unsigned int

          size @ bit 12

            11 bit packed unsigned unsigned int

  directories @ bit 11

    12 bit range of std::vector<dwarfs::thrift::metadata::directory, std::allocator<dwarfs::thrift::metadata::directory> >

      distance @ bit 5

        7 bit packed unsigned unsigned long

      count @ start

        5 bit packed unsigned unsigned long

      item @ start

        12 bit ::dwarfs::thrift::metadata::directory

          parent_entry @ start

            6 bit packed unsigned unsigned int

          first_entry @ bit 6

            6 bit packed unsigned unsigned int

          self_entry @ start

            empty packed unsigned unsigned int
[...]
```

This makes a lot more sense now that we've already looked at the raw schema dump. This representation already associates the types from the thrift IDL with the layouts in the schema.

## AUTHOR
Written by Marcus Holland-Moritz.

## COPYRIGHT
Copyright (C) Marcus Holland-Moritz.

## SEE ALSO
mkdwarfs(1) mkdwarfs.md, dwarfs(1) dwarfs.md, dwarfsextract(1) dwarfsextract.md, dwarfsck(1) dwarfsck.md

branch: sisyphus


title: e2fsck.conf(5)

summary: Configuration file for e2fsck

text:
# e2fsck.conf(5)

## NAME
e2fsck.conf - Configuration file for e2fsck

## DESCRIPTION
e2fsck.conf is the configuration file for e2fsck(8). It controls the default behavior of e2fsck(8) while it is checking ext2, ext3, or ext4 file systems.

The e2fsck.conf file uses an INI-style format. Stanzas, or top-level sections, are delimited by square braces: [ ]. Within each section, each line defines a relation, which assigns tags to values, or to a subsection, which contains further relations or subsections. An example of the INI-style format used by this configuration file follows below:

[section1]

tag1 = value_a

tag1 = value_b

tag2 = value_c

[section 2]

tag3 = {

subtag1 = subtag_value_a

subtag1 = subtag_value_b

subtag2 = subtag_value_c

}

tag1 = value_d

tag2 = value_e

}

Comments are delimited by a semicolon (';') or a hash ('#') character at the beginning of the comment, and are terminated by the end of line character.

Tags and values must be quoted using double quotes if they contain spaces. Within a quoted string, the standard backslash interpretations apply: "\n" (for the newline character), "\t" (for the tab character), "\b" (for the backspace character), and "\\" (for the backslash character).

The following stanzas are used in the e2fsck.conf file. They will be described in more detail in future sections of this document.

[options]

This stanza contains general configuration parameters for e2fsck's behavior.

[defaults]

Contains relations which define the default parameters used by e2fsck(8). In general, these defaults may be overridden by command-line options provided by the user.

[problems]

This stanza allows the administrator to reconfigure how e2fsck handles various file system inconsistencies.

[scratch_files]

This stanza controls when e2fsck will attempt to use scratch files to reduce the need for memory.

## THE [options] STANZA
The following relations are defined in the [options] stanza.

allow_cancellation

If this relation is set to a boolean value of true, then if the user interrupts e2fsck using ^C, and the file system is not explicitly flagged as containing errors, e2fsck will exit with an exit status of 0 instead of 32. This setting defaults to false.

accept_time_fudge

Unfortunately, due to Windows' unfortunate design decision to configure the hardware clock to tick localtime, instead of the more proper and less error-prone UTC time, many users end up in the situation where the system clock is incorrectly set at the time when e2fsck is run.

Historically this was usually due to some distributions having buggy init scripts and/or installers that didn't correctly detect this case and take appropriate countermeasures. Unfortunately, this is occasionally true even today, usually due to a buggy or misconfigured virtualization manager or the installer not having access to a network time server during the installation process. So by default, we allow the superblock times to be fudged by up to 24 hours. This can be disabled by setting accept_time_fudge to the boolean value of false. This setting defaults to true.

broken_system_clock

The e2fsck(8) program has some heuristics that assume that the system clock is correct. In addition, many system programs make similar assumptions. For example, the UUID library depends on time not going backwards in order for it to be able to make its guarantees about issuing universally unique ID's. Systems with broken system clocks, are well, broken. However, broken system clocks, particularly in embedded systems, do exist. E2fsck will attempt to use heuristics to determine if the time can not be trusted; and to skip time-based checks if this is true. If this boolean is set to true, then e2fsck will always assume that the system clock can not be trusted.

buggy_init_scripts

This boolean relation is an alias for accept_time_fudge for backwards compatibility; it used to be that the behavior defined by accept_time_fudge above defaulted to false, and buggy_init_scripts would enable superblock time field to be wrong by up to 24 hours. When we changed the default, we also renamed this boolean relation to accept_time_fudge.

clear_test_fs_flag

This boolean relation controls whether or not e2fsck(8) will offer to clear the test_fs flag if the ext4 file system is available on the system. It defaults to true.

defer_check_on_battery

This boolean relation controls whether or not the interval between file system checks (either based on time or number of mounts) should be doubled if the system is running on battery. This setting defaults to true.

indexed_dir_slack_percentage

When e2fsck(8) repacks a indexed directory, reserve the specified percentage of empty space in each leaf nodes so that a few new entries can be added to the directory without splitting leaf nodes, so that the average fill ratio of directories can be maintained at a higher, more efficient level. This relation defaults to 20 percent.

inode_count_fullmap

If this boolean relation is true, trade off using memory for speed when checking a file system with a large number of hard-linked files. The amount of memory required is proportional to the number of inodes in the file system. For large file systems, this can be gigabytes of memory. (For example a 40TB file system with 2.8 billion inodes will consume an additional 5.7 GB memory if this optimization is enabled.) This setting defaults to false.

log_dir

If the log_filename or problem_log_filename relations contains a relative pathname, then the log file will be placed in the directory named by the log_dir relation.

log_dir_fallback

This relation contains an alternate directory that will be used if the directory specified by log_dir is not available or is not writable.

log_dir_wait

If this boolean relation is true, them if the directories specified by log_dir or log_dir_fallback are not available or are not yet writable, e2fsck will save the output in a memory buffer, and a child process will periodically test to see if the log directory has become available after the boot sequence has mounted the requested file system for reading/writing. This implements the functionality provided by logsave(8) for e2fsck log files.

log_filename

This relation specifies the file name where a copy of e2fsck's output will be written. If certain problem reports are suppressed using the max_count_problems relation, (or on a per-problem basis using the max_count relation), the full set of problem reports will be written to the log file. The filename may contain various percent-expressions (%D, %T, %N, etc.) which will be expanded so that the file name for the log file can include things like date, time, device name, and other run-time parameters. See the LOGGING section for more details.

max_count_problems

This relation specifies the maximum number of problem reports of a particular type will be printed to stdout before further problem reports of that type are squelched. This can be useful if the console is slow (i.e., connected to a serial port) and so a large amount of output could end up delaying the boot process for a long time (potentially hours).

no_optimize_extents

If this boolean relation is true, do not offer to optimize the extent tree by reducing the tree's width or depth. This setting defaults to false.

problem_log_filename

This relation specifies the file name where a log of problem codes found by e2fsck be written. The filename may contain various percent-expressions (%D, %T, %N, etc.) which will be expanded so that the file name for the log file can include things like date, time, device name, and other run-time parameters. See the LOGGING section for more details.

readahead_mem_pct

Use this percentage of memory to try to read in metadata blocks ahead of the main e2fsck thread. This should reduce run times, depending on the speed of the underlying storage and the amount of free memory. There is no default, but see readahead_kb for more details.

readahead_kb

Use this amount of memory to read in metadata blocks ahead of the main checking thread. Setting this value to zero disables readahead entirely. By default, this is set the size of two block groups' inode tables (typically 4MiB on a regular ext4 file system); if this amount is more than 1/50th of total physical memory, readahead is disabled.

report_features

If this boolean relation is true, e2fsck will print the file system features as part of its verbose reporting (i.e., if the -v option is specified)

report_time

If this boolean relation is true, e2fsck will run as if the options -tt are always specified. This will cause e2fsck to print timing statistics on a pass by pass basis for full file system checks.

report_verbose

If this boolean relation is true, e2fsck will run as if the option -v is always specified. This will cause e2fsck to print some additional information at the end of each full file system check.

## THE [defaults] STANZA
The following relations are defined in the [defaults] stanza.

undo_dir

This relation specifies the directory where the undo file should be stored. It can be overridden via the E2FSPROGS_UNDO_DIR environment variable. If the directory location is set to the value none, e2fsck will not create an undo file.

## THE [problems] STANZA
Each tag in the [problems] stanza names a problem code specified with a leading "0x" followed by six hex digits. The value of the tag is a subsection where the relations in that subsection override the default treatment of that particular problem code.

Note that inappropriate settings in this stanza may cause e2fsck to behave incorrectly, or even crash. Most system administrators should not be making changes to this section without referring to source code.

Within each problem code's subsection, the following tags may be used:

description

This relation allows the message which is printed when this file system inconsistency is detected to be overridden.

preen_ok

This boolean relation overrides the default behavior controlling whether this file system problem should be automatically fixed when e2fsck is running in preen mode.

max_count

This integer relation overrides the max_count_problems parameter (set in the options section) for this particular problem.

no_ok

This boolean relation overrides the default behavior determining whether or not the file system will be marked as inconsistent if the user declines to fix the reported problem.

no_default

This boolean relation overrides whether the default answer for this problem (or question) should be "no".

preen_nomessage

This boolean relation overrides the default behavior controlling whether or not the description for this file system problem should be suppressed when e2fsck is running in preen mode.

no_nomsg

This boolean relation overrides the default behavior controlling whether or not the description for this file system problem should be suppressed when a problem forced not to be fixed, either because e2fsck is run with the -n option or because the force_no flag has been set for the problem.

force_no

This boolean option, if set to true, forces a problem to never be fixed. That is, it will be as if the user problem responds 'no' to the question of 'should this problem be fixed?'. The force_no option even overrides the -y option given on the command-line (just for the specific problem, of course).

not_a_fix

This boolean option, it set to true, marks the problem as one where if the user gives permission to make the requested change, it does not mean that the file system had a problem which has since been fixed. This is used for requests to optimize the file system's data structure, such as pruning an extent tree.

## THE [scratch_files] STANZA
The following relations are defined in the [scratch_files] stanza.

directory

If the directory named by this relation exists and is writeable, then e2fsck will attempt to use this directory to store scratch files instead of using in-memory data structures.

numdirs_threshold

If this relation is set, then in-memory data structures will be used if the number of directories in the file system are fewer than amount specified.

dirinfo

This relation controls whether or not the scratch file directory is used instead of an in-memory data structure for directory information. It defaults to true.

icount

This relation controls whether or not the scratch file directory is used instead of an in-memory data structure when tracking inode counts. It defaults to true.

## LOGGING
E2fsck has the facility to save the information from an e2fsck run in a directory so that a system administrator can review its output at their leisure. This allows information captured during the automatic e2fsck preen run, as well as a manually started e2fsck run, to be saved for posterity. This facility is controlled by the log_filename, log_dir, log_dir_fallback, and log_dir_wait relations in the [options] stanza.

The filename in log_filename may contain the following percent-expressions that will be expanded as follows.

%d

The current day of the month

%D

The current date; this is a equivalent of %Y%m%d

%h

The hostname of the system.

%H

The current hour in 24-hour format (00..23)

%m

The current month as a two-digit number (01..12)

%M

The current minute (00..59)

%N

The name of the block device containing the file system, with any directory pathname stripped off.

%p

The pid of the e2fsck process

%s

The current time expressed as the number of seconds since 1970-01-01 00:00:00 UTC

%S

The current second (00..59)

%T

The current time; this is equivalent of %H%M%S

%u

The name of the user running e2fsck.

%U

This percent expression does not expand to anything, but it signals that any following date or time expressions should be expressed in UTC time instead of the local timezone.

%y

The last two digits of the current year (00..99)

%Y

The current year (i.e., 2012).

## EXAMPLES
The following recipe will prevent e2fsck from aborting during the boot process when a file system contains orphaned files. (Of course, this is not always a good idea, since critical files that are needed for the security of the system could potentially end up in lost+found, and starting the system without first having a system administrator check things out may be dangerous.)

[problems]

0x040002 = {

preen_ok = true

description = "@u @i %i. "

}

The following recipe will cause an e2fsck logfile to be written to the directory /var/log/e2fsck, with a filename that contains the device name, the hostname of the system, the date, and time: e.g., "e2fsck-sda3.server.INFO.20120314-112142". If the directory containing /var/log is located on the root file system which is initially mounted read-only, then the output will be saved in memory and written out once the root file system has been remounted read/write. To avoid too much detail from being written to the serial console (which could potentially slow down the boot sequence), only print no more than 16 instances of each type of file system corruption.

[options]

max_count_problems = 16

log_dir = /var/log/e2fsck

log_filename = e2fsck-%N.%h.INFO.%D-%T

log_dir_wait = true

## FILES
/etc/e2fsck.conf

The configuration file for e2fsck(8).

## SEE ALSO
e2fsck(8)