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)


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)


title: ext2(5)

summary: the second extended file system

text:
# ext2(5)

## NAME
ext2 - the second extended file system

ext3 - the third extended file system

ext4 - the fourth extended file system

## DESCRIPTION
The second, third, and fourth extended file systems, or ext2, ext3, and ext4 as they are commonly known, are Linux file systems that have historically been the default file system for many Linux distributions. They are general purpose file systems that have been designed for extensibility and backwards compatibility. In particular, file systems previously intended for use with the ext2 and ext3 file systems can be mounted using the ext4 file system driver, and indeed in many modern Linux distributions, the ext4 file system driver has been configured to handle mount requests for ext2 and ext3 file systems.

## FILE SYSTEM FEATURES
A file system formatted for ext2, ext3, or ext4 can have some collection of the following file system feature flags enabled. Some of these features are not supported by all implementations of the ext2, ext3, and ext4 file system drivers, depending on Linux kernel version in use. On other operating systems, such as the GNU/HURD or FreeBSD, only a very restrictive set of file system features may be supported in their implementations of ext2.

64bit

Enables the file system to be larger than 2^32 blocks. This feature is set automatically, as needed, but it can be useful to specify this feature explicitly if the file system might need to be resized larger than 2^32 blocks, even if it was smaller than that threshold when it was originally created. Note that some older kernels and older versions of e2fsprogs will not support file systems with this ext4 feature enabled.

bigalloc

This ext4 feature enables clustered block allocation, so that the unit of allocation is a power of two number of blocks. That is, each bit in the what had traditionally been known as the block allocation bitmap now indicates whether a cluster is in use or not, where a cluster is by default composed of 16 blocks. This feature can decrease the time spent on doing block allocation and brings smaller fragmentation, especially for large files. The size can be specified using the mke2fs -C option.

Warning: The bigalloc feature is still under development, and may not be fully supported with your kernel or may have various bugs. Please see the web page http://ext4.wiki.kernel.org/index.php/Bigalloc for details. May clash with delayed allocation (see nodelalloc mount option).

This feature requires that the extent feature be enabled.

casefold

This ext4 feature provides file system level character encoding support for directories with the casefold (+F) flag enabled. This feature is name-preserving on the disk, but it allows applications to lookup for a file in the file system using an encoding equivalent version of the file name.

dir_index

Use hashed b-trees to speed up name lookups in large directories. This feature is supported by ext3 and ext4 file systems, and is ignored by ext2 file systems.

dir_nlink

Normally, ext4 allows an inode to have no more than 65,000 hard links. This applies to regular files as well as directories, which means that there can be no more than 64,998 subdirectories in a directory (because each of the '.' and '..' entries, as well as the directory entry for the directory in its parent directory counts as a hard link). This feature lifts this limit by causing ext4 to use a link count of 1 to indicate that the number of hard links to a directory is not known when the link count might exceed the maximum count limit.

ea_inode

Normally, a file's extended attributes and associated metadata must fit within the inode or the inode's associated extended attribute block. This feature allows the value of each extended attribute to be placed in the data blocks of a separate inode if necessary, increasing the limit on the size and number of extended attributes per file.

encrypt

Enables support for file-system level encryption of data blocks and file names. The inode metadata (timestamps, file size, user/group ownership, etc.) is not encrypted.

This feature is most useful on file systems with multiple users, or where not all files should be encrypted. In many use cases, especially on single-user systems, encryption at the block device layer using dm-crypt may provide much better security.

ext_attr

This feature enables the use of extended attributes. This feature is supported by ext2, ext3, and ext4.

extent

This ext4 feature allows the mapping of logical block numbers for a particular inode to physical blocks on the storage device to be stored using an extent tree, which is a more efficient data structure than the traditional indirect block scheme used by the ext2 and ext3 file systems. The use of the extent tree decreases metadata block overhead, improves file system performance, and decreases the needed to run e2fsck(8) on the file system. (Note: both extent and extents are accepted as valid names for this feature for historical/backwards compatibility reasons.)

extra_isize

This ext4 feature reserves a specific amount of space in each inode for extended metadata such as nanosecond timestamps and file creation time, even if the current kernel does not currently need to reserve this much space. Without this feature, the kernel will reserve the amount of space for features it currently needs, and the rest may be consumed by extended attributes. For this feature to be useful the inode size must be 256 bytes in size or larger.

filetype

This feature enables the storage of file type information in directory entries. This feature is supported by ext2, ext3, and ext4.

flex_bg

This ext4 feature allows the per-block group metadata (allocation bitmaps and inode tables) to be placed anywhere on the storage media. In addition, mke2fs will place the per-block group metadata together starting at the first block group of each "flex_bg group". The size of the flex_bg group can be specified using the -G option.

has_journal

Create a journal to ensure file system consistency even across unclean shutdowns. Setting the file system feature is equivalent to using the -j option with mke2fs or tune2fs. This feature is supported by ext3 and ext4, and ignored by the ext2 file system driver.

huge_file

This ext4 feature allows files to be larger than 2 terabytes in size.

inline_data

Allow data to be stored in the inode and extended attribute area.

journal_dev

This feature is enabled on the superblock found on an external journal device. The block size for the external journal must be the same as the file system which uses it.

The external journal device can be used by a file system by specifying the -J device=<external-device> option to mke2fs(8) or tune2fs(8).

large_dir

This feature increases the limit on the number of files per directory by raising the maximum size of directories and, for hashed b-tree directories (see dir_index), the maximum height of the hashed b-tree used to store the directory entries.

large_file

This feature flag is set automatically by modern kernels when a file larger than 2 gigabytes is created. Very old kernels could not handle large files, so this feature flag was used to prohibit those kernels from mounting file systems that they could not understand.

metadata_csum

This ext4 feature enables metadata checksumming. This feature stores checksums for all of the file system metadata (superblock, group descriptor blocks, inode and block bitmaps, directories, and extent tree blocks). The checksum algorithm used for the metadata blocks is different than the one used for group descriptors with the uninit_bg feature. These two features are incompatible and metadata_csum will be used preferentially instead of uninit_bg.

metadata_csum_seed

This feature allows the file system to store the metadata checksum seed in the superblock, which allows the administrator to change the UUID of a file system using the metadata_csum feature while it is mounted.

meta_bg

This ext4 feature allows file systems to be resized on-line without explicitly needing to reserve space for growth in the size of the block group descriptors. This scheme is also used to resize file systems which are larger than 2^32 blocks. It is not recommended that this feature be set when a file system is created, since this alternate method of storing the block group descriptors will slow down the time needed to mount the file system, and newer kernels can automatically set this feature as necessary when doing an online resize and no more reserved space is available in the resize inode.

mmp

This ext4 feature provides multiple mount protection (MMP). MMP helps to protect the file system from being multiply mounted and is useful in shared storage environments.

project

This ext4 feature provides project quota support. With this feature, the project ID of inode will be managed when the file system is mounted.

quota

Create quota inodes (inode #3 for userquota and inode #4 for group quota) and set them in the superblock. With this feature, the quotas will be enabled automatically when the file system is mounted.

Causes the quota files (i.e., user.quota and group.quota which existed in the older quota design) to be hidden inodes.

resize_inode

This file system feature indicates that space has been reserved so that the block group descriptor table can be extended while resizing a mounted file system. The online resize operation is carried out by the kernel, triggered by resize2fs(8). By default mke2fs will attempt to reserve enough space so that the file system may grow to 1024 times its initial size. This can be changed using the resize extended option.

This feature requires that the sparse_super or sparse_super2 feature be enabled.

sparse_super

This file system feature is set on all modern ext2, ext3, and ext4 file systems. It indicates that backup copies of the superblock and block group descriptors are present only in a few block groups, not all of them.

sparse_super2

This feature indicates that there will only be at most two backup superblocks and block group descriptors. The block groups used to store the backup superblock(s) and blockgroup descriptor(s) are stored in the superblock, but typically, one will be located at the beginning of block group #1, and one in the last block group in the file system. This feature is essentially a more extreme version of sparse_super and is designed to allow a much larger percentage of the disk to have contiguous blocks available for data files.

stable_inodes

Marks the file system's inode numbers and UUID as stable. resize2fs(8) will not allow shrinking a file system with this feature, nor will tune2fs(8) allow changing its UUID. This feature allows the use of specialized encryption settings that make use of the inode numbers and UUID. Note that the encrypt feature still needs to be enabled separately. stable_inodes is a "compat" feature, so old kernels will allow it.

uninit_bg

This ext4 file system feature indicates that the block group descriptors will be protected using checksums, making it safe for mke2fs(8) to create a file system without initializing all of the block groups. The kernel will keep a high watermark of unused inodes, and initialize inode tables and blocks lazily. This feature speeds up the time to check the file system using e2fsck(8), and it also speeds up the time required for mke2fs(8) to create the file system.

verity

Enables support for verity protected files. Verity files are readonly, and their data is transparently verified against a Merkle tree hidden past the end of the file. Using the Merkle tree's root hash, a verity file can be efficiently authenticated, independent of the file's size.

This feature is most useful for authenticating important read-only files on read-write file systems. If the file system itself is read-only, then using dm-verity to authenticate the entire block device may provide much better security.

## MOUNT OPTIONS
This section describes mount options which are specific to ext2, ext3, and ext4. Other generic mount options may be used as well; see mount(8) for details.

## Mount options for ext2
The `ext2' file system is the standard Linux file system. Since Linux 2.5.46, for most mount options the default is determined by the file system superblock. Set them with tune2fs(8).

acl|noacl

Support POSIX Access Control Lists (or not). See the acl(5) manual page.

bsddf|minixdf

Set the behavior for the statfs system call. The minixdf behavior is to return in the f_blocks field the total number of blocks of the file system, while the bsddf behavior (which is the default) is to subtract the overhead blocks used by the ext2 file system and not available for file storage. Thus % mount /k -o minixdf; df /k; umount /k

File System

1024-blocks

Used

Available

Capacity

Mounted on

/dev/sda6

2630655

86954

2412169

3%

/k

% mount /k -o bsddf; df /k; umount /k

File System

1024-blocks

Used

Available

Capacity

Mounted on

/dev/sda6

2543714

13

2412169

0%

/k

(Note that this example shows that one can add command line options to the options given in /etc/fstab.)

check=none or nocheck

No checking is done at mount time. This is the default. This is fast. It is wise to invoke e2fsck(8) every now and then, e.g. at boot time. The non-default behavior is unsupported (check=normal and check=strict options have been removed). Note that these mount options don't have to be supported if ext4 kernel driver is used for ext2 and ext3 file systems.

debug

Print debugging info upon each (re)mount.

errors={continue|remount-ro|panic}

Define the behavior when an error is encountered. (Either ignore errors and just mark the file system erroneous and continue, or remount the file system read-only, or panic and halt the system.) The default is set in the file system superblock, and can be changed using tune2fs(8).

grpid|bsdgroups and nogrpid|sysvgroups

These options define what group id a newly created file gets. When grpid is set, it takes the group id of the directory in which it is created; otherwise (the default) it takes the fsgid of the current process, unless the directory has the setgid bit set, in which case it takes the gid from the parent directory, and also gets the setgid bit set if it is a directory itself.

grpquota|noquota|quota|usrquota

The usrquota (same as quota) mount option enables user quota support on the file system. grpquota enables group quotas support. You need the quota utilities to actually enable and manage the quota system.

nouid32

Disables 32-bit UIDs and GIDs. This is for interoperability with older kernels which only store and expect 16-bit values.

oldalloc or orlov

Use old allocator or Orlov allocator for new inodes. Orlov is default.

resgid=n and resuid=n

The ext2 file system reserves a certain percentage of the available space (by default 5%, see mke2fs(8) and tune2fs(8)). These options determine who can use the reserved blocks. (Roughly: whoever has the specified uid, or belongs to the specified group.)

sb=n

Instead of using the normal superblock, use an alternative superblock specified by n. This option is normally used when the primary superblock has been corrupted. The location of backup superblocks is dependent on the file system's blocksize, the number of blocks per group, and features such as sparse_super.

Additional backup superblocks can be determined by using the mke2fs program using the -n option to print out where the superblocks exist, supposing mke2fs is supplied with arguments that are consistent with the file system's layout (e.g. blocksize, blocks per group, sparse_super, etc.).

The block number here uses 1 k units. Thus, if you want to use logical block 32768 on a file system with 4 k blocks, use "sb=131072".

user_xattr|nouser_xattr

Support "user." extended attributes (or not).

## Mount options for ext3
The ext3 file system is a version of the ext2 file system which has been enhanced with journaling. It supports the same options as ext2 as well as the following additions:

journal_dev=devnum/journal_path=path

When the external journal device's major/minor numbers have changed, these options allow the user to specify the new journal location. The journal device is identified either through its new major/minor numbers encoded in devnum, or via a path to the device.

norecovery/noload

Don't load the journal on mounting. Note that if the file system was not unmounted cleanly, skipping the journal replay will lead to the file system containing inconsistencies that can lead to any number of problems.

data={journal|ordered|writeback}

Specifies the journaling mode for file data. Metadata is always journaled. To use modes other than ordered on the root file system, pass the mode to the kernel as boot parameter, e.g. rootflags=data=journal.

journal

All data is committed into the journal prior to being written into the main file system.

ordered

This is the default mode. All data is forced directly out to the main file system prior to its metadata being committed to the journal.

writeback

Data ordering is not preserved – data may be written into the main file system after its metadata has been committed to the journal. This is rumoured to be the highest-throughput option. It guarantees internal file system integrity, however it can allow old data to appear in files after a crash and journal recovery.

data_err=ignore

Just print an error message if an error occurs in a file data buffer in ordered mode.

data_err=abort

Abort the journal if an error occurs in a file data buffer in ordered mode.

barrier=0 / barrier=1

This disables / enables the use of write barriers in the jbd code. barrier=0 disables, barrier=1 enables (default). This also requires an IO stack which can support barriers, and if jbd gets an error on a barrier write, it will disable barriers again with a warning. Write barriers enforce proper on-disk ordering of journal commits, making volatile disk write caches safe to use, at some performance penalty. If your disks are battery-backed in one way or another, disabling barriers may safely improve performance.

commit=nrsec

Start a journal commit every nrsec seconds. The default value is 5 seconds. Zero means default.

user_xattr

Enable Extended User Attributes. See the attr(5) manual page.

jqfmt={vfsold|vfsv0|vfsv1}

Apart from the old quota system (as in ext2, jqfmt=vfsold aka version 1 quota) ext3 also supports journaled quotas (version 2 quota). jqfmt=vfsv0 or jqfmt=vfsv1 enables journaled quotas. Journaled quotas have the advantage that even after a crash no quota check is required. When the quota file system feature is enabled, journaled quotas are used automatically, and this mount option is ignored.

usrjquota=aquota.user|grpjquota=aquota.group

For journaled quotas (jqfmt=vfsv0 or jqfmt=vfsv1), the mount options usrjquota=aquota.user and grpjquota=aquota.group are required to tell the quota system which quota database files to use. When the quota file system feature is enabled, journaled quotas are used automatically, and this mount option is ignored.

## Mount options for ext4
The ext4 file system is an advanced level of the ext3 file system which incorporates scalability and reliability enhancements for supporting large file system.

The options journal_dev, journal_path, norecovery, noload, data, commit, orlov, oldalloc, [no]user_xattr, [no]acl, bsddf, minixdf, debug, errors, data_err, grpid, bsdgroups, nogrpid, sysvgroups, resgid, resuid, sb, quota, noquota, nouid32, grpquota, usrquota, usrjquota, grpjquota, and jqfmt are backwardly compatible with ext3 or ext2.

journal_checksum | nojournal_checksum

The journal_checksum option enables checksumming of the journal transactions. This will allow the recovery code in e2fsck and the kernel to detect corruption in the kernel. It is a compatible change and will be ignored by older kernels.

journal_async_commit

Commit block can be written to disk without waiting for descriptor blocks. If enabled older kernels cannot mount the device. This will enable 'journal_checksum' internally.

barrier=0 / barrier=1 / barrier / nobarrier

These mount options have the same effect as in ext3. The mount options "barrier" and "nobarrier" are added for consistency with other ext4 mount options. The ext4 file system enables write barriers by default.

inode_readahead_blks=n

This tuning parameter controls the maximum number of inode table blocks that ext4's inode table readahead algorithm will pre-read into the buffer cache. The value must be a power of 2. The default value is 32 blocks.

stripe=n

Number of file system blocks that mballoc will try to use for allocation size and alignment. For RAID5/6 systems this should be the number of data disks * RAID chunk size in file system blocks.

delalloc

Deferring block allocation until write-out time.

nodelalloc

Disable delayed allocation. Blocks are allocated when data is copied from user to page cache.

max_batch_time=usec

Maximum amount of time ext4 should wait for additional file system operations to be batch together with a synchronous write operation. Since a synchronous write operation is going to force a commit and then a wait for the I/O complete, it doesn't cost much, and can be a huge throughput win, we wait for a small amount of time to see if any other transactions can piggyback on the synchronous write. The algorithm used is designed to automatically tune for the speed of the disk, by measuring the amount of time (on average) that it takes to finish committing a transaction. Call this time the "commit time". If the time that the transaction has been running is less than the commit time, ext4 will try sleeping for the commit time to see if other operations will join the transaction. The commit time is capped by the max_batch_time, which defaults to 15000 µs (15 ms). This optimization can be turned off entirely by setting max_batch_time to 0.

min_batch_time=usec

This parameter sets the commit time (as described above) to be at least min_batch_time. It defaults to zero microseconds. Increasing this parameter may improve the throughput of multi-threaded, synchronous workloads on very fast disks, at the cost of increasing latency.

journal_ioprio=prio

The I/O priority (from 0 to 7, where 0 is the highest priority) which should be used for I/O operations submitted by kjournald2 during a commit operation. This defaults to 3, which is a slightly higher priority than the default I/O priority.

abort

Simulate the effects of calling ext4_abort() for debugging purposes. This is normally used while remounting a file system which is already mounted.

auto_da_alloc|noauto_da_alloc

Many broken applications don't use fsync() when replacing existing files via patterns such as fd = open("foo.new")/write(fd,...)/close(fd)/ rename("foo.new", "foo")

or worse yet

fd = open("foo", O_TRUNC)/write(fd,...)/close(fd).

If auto_da_alloc is enabled, ext4 will detect the replace-via-rename and replace-via-truncate patterns and force that any delayed allocation blocks are allocated such that at the next journal commit, in the default data=ordered mode, the data blocks of the new file are forced to disk before the rename() operation is committed. This provides roughly the same level of guarantees as ext3, and avoids the "zero-length" problem that can happen when a system crashes before the delayed allocation blocks are forced to disk.

noinit_itable

Do not initialize any uninitialized inode table blocks in the background. This feature may be used by installation CD's so that the install process can complete as quickly as possible; the inode table initialization process would then be deferred until the next time the file system is mounted.

init_itable=n

The lazy itable init code will wait n times the number of milliseconds it took to zero out the previous block group's inode table. This minimizes the impact on system performance while the file system's inode table is being initialized.

discard/nodiscard

Controls whether ext4 should issue discard/TRIM commands to the underlying block device when blocks are freed. This is useful for SSD devices and sparse/thinly-provisioned LUNs, but it is off by default until sufficient testing has been done.

block_validity/noblock_validity

This option enables/disables the in-kernel facility for tracking file system metadata blocks within internal data structures. This allows multi-block allocator and other routines to quickly locate extents which might overlap with file system metadata blocks. This option is intended for debugging purposes and since it negatively affects the performance, it is off by default.

dioread_lock/dioread_nolock

Controls whether or not ext4 should use the DIO read locking. If the dioread_nolock option is specified ext4 will allocate uninitialized extent before buffer write and convert the extent to initialized after IO completes. This approach allows ext4 code to avoid using inode mutex, which improves scalability on high speed storages. However this does not work with data journaling and dioread_nolock option will be ignored with kernel warning. Note that dioread_nolock code path is only used for extent-based files. Because of the restrictions this options comprises it is off by default (e.g. dioread_lock).

max_dir_size_kb=n

This limits the size of the directories so that any attempt to expand them beyond the specified limit in kilobytes will cause an ENOSPC error. This is useful in memory-constrained environments, where a very large directory can cause severe performance problems or even provoke the Out Of Memory killer. (For example, if there is only 512 MB memory available, a 176 MB directory may seriously cramp the system's style.)

i_version

Enable 64-bit inode version support. This option is off by default.

nombcache

This option disables use of mbcache for extended attribute deduplication. On systems where extended attributes are rarely or never shared between files, use of mbcache for deduplication adds unnecessary computational overhead.

prjquota

The prjquota mount option enables project quota support on the file system. You need the quota utilities to actually enable and manage the quota system. This mount option requires the project file system feature.

## FILE ATTRIBUTES
The ext2, ext3, and ext4 file systems support setting the following file attributes on Linux systems using the chattr(1) utility:

a - append only

A - no atime updates

d - no dump

D - synchronous directory updates

i - immutable

S - synchronous updates

u - undeletable

In addition, the ext3 and ext4 file systems support the following flag:

j - data journaling

Finally, the ext4 file system also supports the following flag:

e - extents format

For descriptions of these attribute flags, please refer to the chattr(1) man page.

## KERNEL SUPPORT
This section lists the file system driver (e.g., ext2, ext3, ext4) and upstream kernel version where a particular file system feature was supported. Note that in some cases the feature was present in earlier kernel versions, but there were known, serious bugs. In other cases the feature may still be considered in an experimental state. Finally, note that some distributions may have backported features into older kernels; in particular the kernel versions in certain "enterprise distributions" can be extremely misleading.

filetype

ext2, 2.2.0

sparse_super

ext2, 2.2.0

large_file

ext2, 2.2.0

has_journal

ext3, 2.4.15

ext_attr

ext2/ext3, 2.6.0

dir_index

ext3, 2.6.0

resize_inode

ext3, 2.6.10 (online resizing)

64bit

ext4, 2.6.28

dir_nlink

ext4, 2.6.28

extent

ext4, 2.6.28

extra_isize

ext4, 2.6.28

flex_bg

ext4, 2.6.28

huge_file

ext4, 2.6.28

meta_bg

ext4, 2.6.28

uninit_bg

ext4, 2.6.28

mmp

ext4, 3.0

bigalloc

ext4, 3.2

quota

ext4, 3.6

inline_data

ext4, 3.8

sparse_super2

ext4, 3.16

metadata_csum

ext4, 3.18

encrypt

ext4, 4.1

metadata_csum_seed

ext4, 4.4

project

ext4, 4.5

ea_inode

ext4, 4.13

large_dir

ext4, 4.13

casefold

ext4, 5.2

verity

ext4, 5.4

stable_inodes

ext4, 5.5

## SEE ALSO
mke2fs(8), mke2fs.conf(5), e2fsck(8), dumpe2fs(8), tune2fs(8), debugfs(8), mount(8), chattr(1)