.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "dunst 1"
.TH dunst 1 "2020-10-26" "1.5.0 (2020-07-23)" "Dunst Reference"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dunst \- A customizable and lightweight notification\-daemon
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
dunst [\-conf file] [\-font font] [\-geometry geom] [\-format fmt] [\-follow mode] [\-monitor n] [\-history_length n] ...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Dunst is a highly configurable and lightweight notification daemon.
.SH "COMMAND LINE OPTIONS"
.IX Header "COMMAND LINE OPTIONS"
.IP "\fB\-h/\-\-help\fR" 4
.IX Item "-h/--help"
List all command line flags
.IP "\fB\-conf/\-config file\fR" 4
.IX Item "-conf/-config file"
Use alternative config file.
.IP "\fB\-v/\-\-version\fR" 4
.IX Item "-v/--version"
Print version information.
.IP "\fB\-print\fR" 4
.IX Item "-print"
Print notifications to stdout. This might be useful for logging, setting up
rules or using the output in other scripts.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
An example configuration file is included (usually /usr/share/doc/dunst/dunstrc.gz).
To change the configuration, copy this file to ~/.config/dunst/dunstrc and edit
it accordingly.
.PP
The configuration is divided into sections in an ini-like format. The 'global'
section contains most general settings while the 'shortcuts' sections contains
all keyboard configuration and the 'experimental' section all the features that
have not yet been tested thoroughly.
.PP
Any section that is not one of the above is assumed to be a rule, see \s-1RULES\s0 for
more details.
.PP
For backwards compatibility reasons the section name 'frame' is considered bound
and can't be used as a rule.
.SS "Command line"
.IX Subsection "Command line"
Each configuration option in the global section can be overridden from the
command line by adding a single dash in front of it's name.
For example the font option can be overridden by running
.PP
.Vb 1
\& $ dunst \-font "LiberationSans Mono 4"
.Ve
.PP
Configuration options that take boolean values can only currently be set to
\&\*(L"true\*(R" through the command line via the same method. e.g.
.PP
.Vb 1
\& $ dunst \-shrink
.Ve
.PP
This is a known limitation of the way command line parameters are parsed and
will be changed in the future.
.PP
Available settings per section:
.SS "Global section"
.IX Subsection "Global section"
.IP "\fBmonitor\fR (default: 0)" 4
.IX Item "monitor (default: 0)"
Specifies on which monitor the notifications should be displayed in, count
starts at 0. See the \fBfollow\fR setting.
.IP "\fBfollow\fR (values: [none/mouse/keyboard] default: none)" 4
.IX Item "follow (values: [none/mouse/keyboard] default: none)"
Defines where the notifications should be placed in a multi-monitor setup. All
values except \fInone\fR override the \fBmonitor\fR setting.
.RS 4
.IP "\fBnone\fR" 4
.IX Item "none"
The notifications will be placed on the monitor specified by the \fBmonitor\fR
setting.
.IP "\fBmouse\fR" 4
.IX Item "mouse"
The notifications will be placed on the monitor that the mouse is currently in.
.IP "\fBkeyboard\fR" 4
.IX Item "keyboard"
The notifications will be placed on the monitor that contains the window with
keyboard focus.
.RE
.RS 4
.RE
.ie n .IP "\fBgeometry\fR (format: [{width}][x{height}][+/\-{x}[+/\-{y}]], default: ""0x0+0\-0"")" 4
.el .IP "\fBgeometry\fR (format: [{width}][x{height}][+/\-{x}[+/\-{y}]], default: ``0x0+0\-0'')" 4
.IX Item "geometry (format: [{width}][x{height}][+/-{x}[+/-{y}]], default: 0x0+0-0)"
The geometry of the window the notifications will be displayed in.
.RS 4
.IP "\fBwidth\fR" 4
.IX Item "width"
The width of the notification window in pixels. A negative value sets the width
to the screen width \fBminus the absolute value of the width\fR. If the width is
omitted then the window expands to cover the whole screen. If it's 0 the window
expands to the width of the longest message being displayed.
.IP "\fBheight\fR" 4
.IX Item "height"
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. If
\&\fBindicate_hidden\fR 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 \fBindicate_hidden\fR entry for more information.
.Sp
The physical(pixel) height of the notifications vary depending on the number of
lines that need to be displayed.
.Sp
See \fBnotification_height\fR for changing the physical height.
.IP "\fBx/y\fR" 4
.IX Item "x/y"
Respectively the horizontal and vertical offset in pixels from the corner
of the screen that the notification should be drawn at. For the horizontal(x)
offset, a positive value is measured from the left of the screen while a
negative one from the right. For the vertical(y) offset, a positive value is
measured from the top while a negative from the bottom.
.Sp
It's important to note that the positive and negative sign \fB\s-1DOES\s0\fR affect the
position even if the offset is 0. For example, a horizontal offset of +0 puts
the notification on the left border of the screen while a horizontal offset of
\&\-0 at the right border. The same goes for the vertical offset.
.RE
.RS 4
.RE
.IP "\fBindicate_hidden\fR (values: [true/false], default: true)" 4
.IX Item "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 \fBgeometry\fR) will be
shown \fBin place of the last notification slot\fR.
.Sp
Meaning that if this is enabled the number of visible notifications will be 1
less than what is specified in geometry, the last slot will be taken by the
hidden count.
.IP "\fBshrink\fR (values: [true/false], default: false)" 4
.IX Item "shrink (values: [true/false], default: false)"
Shrink window if it's smaller than the width. Will be ignored if width is 0.
.Sp
This is used mainly in order to have the shrinking benefit of dynamic width (see
geometry) while also having an upper bound on how long a notification can get
before wrapping.
.IP "\fBtransparency\fR (default: 0)" 4
.IX Item "transparency (default: 0)"
A 0\-100 range on how transparent the notification window should be, with 0
being fully opaque and 100 invisible.
.Sp
This setting will only work if a compositor is running.
.IP "\fBnotification_height\fR (default: 0)" 4
.IX Item "notification_height (default: 0)"
The minimum height of the notification window in pixels. If the text and
padding cannot fit in within the height specified by this value, the height
will be increased as needed.
.IP "\fBseparator_height\fR (default: 2)" 4
.IX Item "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.
.IP "\fBpadding\fR (default: 0)" 4
.IX Item "padding (default: 0)"
The distance in pixels from the content to the separator/border of the window
in the vertical axis
.IP "\fBhorizontal_padding\fR (default: 0)" 4
.IX Item "horizontal_padding (default: 0)"
The distance in pixels from the content to the border of the window
in the horizontal axis
.IP "\fBframe_width\fR (default: 0)" 4
.IX Item "frame_width (default: 0)"
Defines width in pixels of frame around the notification window. Set to 0 to
disable.
.IP "\fBframe_color color\fR (default: #888888)" 4
.IX Item "frame_color color (default: #888888)"
Defines color of the frame around the notification window. See \s-1COLORS.\s0
.IP "\fBseparator_color\fR (values: [auto/foreground/frame/#RRGGBB] default: auto)" 4
.IX Item "separator_color (values: [auto/foreground/frame/#RRGGBB] default: auto)"
Sets the color of the separator line between two notifications.
.RS 4
.IP "\fBauto\fR" 4
.IX Item "auto"
Dunst tries to find a color that fits the rest of the notification color
scheme automatically.
.IP "\fBforeground\fR" 4
.IX Item "foreground"
The color will be set to the same as the foreground color of the topmost
notification that's being separated.
.IP "\fBframe\fR" 4
.IX Item "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.
.IP "\fBanything else\fR" 4
.IX Item "anything else"
Any other value is interpreted as a color, see \s-1COLORS\s0
.RE
.RS 4
.RE
.IP "\fBsort\fR (values: [true/false], default: true)" 4
.IX Item "sort (values: [true/false], default: true)"
If set to true, display notifications with higher urgency above the others.
.IP "\fBidle_threshold\fR (default: 0)" 4
.IX Item "idle_threshold (default: 0)"
Don't timeout notifications if user is idle longer than this time.
See \s-1TIME FORMAT\s0 for valid times.
.Sp
Set to 0 to disable.
.Sp
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.
.ie n .IP "\fBfont\fR (default: ""Monospace 8"")" 4
.el .IP "\fBfont\fR (default: ``Monospace 8'')" 4
.IX Item "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.
.Sp
This options is parsed as a Pango font description.
.IP "\fBline_height\fR (default: 0)" 4
.IX Item "line_height (default: 0)"
The amount of extra spacing between text lines in pixels. Set to 0 to
disable.
.IP "\fBmarkup\fR (values: [full/strip/no], default: no)" 4
.IX Item "markup (values: [full/strip/no], default: no)"
Defines how markup in notifications is handled.
.Sp
It's important to note that markup in the format option will be parsed
regardless of what this is set to.
.Sp
Possible values:
.RS 4
.IP "\fBfull\fR" 4
.IX Item "full"
Allow a small subset of html markup in notifications
.Sp
.Vb 4
\& bold
\& italic
\& strikethrough
\& underline
.Ve
.Sp
For a complete reference see
.IP "\fBstrip\fR" 4
.IX Item "strip"
This setting is provided for compatibility with some broken
clients that send markup even though it's not enabled on the
server.
.Sp
Dunst will try to strip the markup but the parsing is simplistic so using this
option outside of matching rules for specific applications \fB\s-1IS GREATLY
DISCOURAGED\s0\fR.
.Sp
See \s-1RULES\s0
.IP "\fBno\fR" 4
.IX Item "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.
.RE
.RS 4
.RE
.ie n .IP "\fBformat\fR (default: ""%s %b"")" 4
.el .IP "\fBformat\fR (default: ``%s \f(CW%b\fR'')" 4
.IX Item "format (default: %s %b)"
Specifies how the various attributes of the notification should be formatted on
the notification window.
.Sp
Regardless of the status of the \fBmarkup\fR 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 '&'
.Sp
If '\en' is present anywhere in the format, it will be replaced with
a literal newline.
.Sp
If any of the following strings are present, they will be replaced with the
equivalent notification attribute.
.RS 4
.IP "\fB\f(CB%a\fB\fR appname" 4
.IX Item "%a appname"
.PD 0
.IP "\fB\f(CB%s\fB\fR summary" 4
.IX Item "%s summary"
.IP "\fB\f(CB%b\fB\fR body" 4
.IX Item "%b body"
.IP "\fB\f(CB%i\fB\fR iconname (including its path)" 4
.IX Item "%i iconname (including its path)"
.IP "\fB\f(CB%I\fB\fR iconname (without its path)" 4
.IX Item "%I iconname (without its path)"
.IP "\fB\f(CB%p\fB\fR progress value ([ 0%] to [100%])" 4
.IX Item "%p progress value ([ 0%] to [100%])"
.IP "\fB\f(CB%n\fB\fR progress value without any extra characters" 4
.IX Item "%n progress value without any extra characters"
.IP "\fB%%\fR Literal %" 4
.IX Item "%% Literal %"
.RE
.RS 4
.PD
.Sp
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.
.RE
.IP "\fBalignment\fR (values: [left/center/right], default: left)" 4
.IX Item "alignment (values: [left/center/right], default: left)"
Defines how the text should be aligned within the notification.
.IP "\fBvertical_alignment\fR (values: [top/center/bottom], default: center)" 4
.IX Item "vertical_alignment (values: [top/center/bottom], default: center)"
Defines how the text and icon should be aligned vertically within the
notification. If icons are disabled, this option has no effect.
.IP "\fBshow_age_threshold\fR (default: \-1)" 4
.IX Item "show_age_threshold (default: -1)"
Show age of message if message is older than this time.
See \s-1TIME FORMAT\s0 for valid times.
.Sp
Set to \-1 to disable.
.IP "\fBword_wrap\fR (values: [true/false], default: false)" 4
.IX Item "word_wrap (values: [true/false], default: false)"
Specifies how very long lines should be handled
.Sp
If it's set to false, long lines will be truncated and ellipsized.
.Sp
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.
.IP "\fBellipsize\fR (values: [start/middle/end], default: middle)" 4
.IX Item "ellipsize (values: [start/middle/end], default: middle)"
If word_wrap is set to false, specifies where truncated lines should be
ellipsized.
.IP "\fBignore_newline\fR (values: [true/false], default: false)" 4
.IX Item "ignore_newline (values: [true/false], default: false)"
If set to true, replace newline characters in notifications with whitespace.
.IP "\fBstack_duplicates\fR (values: [true/false], default: true)" 4
.IX Item "stack_duplicates (values: [true/false], default: true)"
If set to true, duplicate notifications will be stacked together instead of
being displayed separately.
.Sp
Two notifications are considered duplicate if the name of the program that sent
it, summary, body, icon and urgency are all identical.
.IP "\fBhide_duplicates_count\fR (values: [true/false], default: false)" 4
.IX Item "hide_duplicates_count (values: [true/false], default: false)"
Hide the count of stacked duplicate notifications.
.IP "\fBshow_indicators\fR (values: [true/false], default: true)" 4
.IX Item "show_indicators (values: [true/false], default: true)"
Show an indicator if a notification contains actions and/or open-able URLs. See
\&\s-1ACTIONS\s0 below for further details.
.IP "\fBicon_position\fR (values: [left/right/off], default: off)" 4
.IX Item "icon_position (values: [left/right/off], default: off)"
Defines the position of the icon in the notification window. Setting it to off
disables icons.
.IP "\fBmin_icon_size\fR (default: 0)" 4
.IX Item "min_icon_size (default: 0)"
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.
.Sp
Set to 0 to disable icon upscaling. (default)
.Sp
If \fBicon_position\fR is set to off, this setting is ignored.
.IP "\fBmax_icon_size\fR (default: 0)" 4
.IX Item "max_icon_size (default: 0)"
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.
.Sp
Set to 0 to disable icon downscaling. (default)
.Sp
If both \fBmin_icon_size\fR and \fBmax_icon_size\fR are enabled, the latter
gets the last say.
.Sp
If \fBicon_position\fR is set to off, this setting is ignored.
.ie n .IP "\fBicon_path\fR (default: ""/usr/share/icons/gnome/16x16/status/:/usr/share/icons/gnome/16x16/devices/"")" 4
.el .IP "\fBicon_path\fR (default: ``/usr/share/icons/gnome/16x16/status/:/usr/share/icons/gnome/16x16/devices/'')" 4
.IX Item "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.
.Sp
Dunst doesn't currently do any type of icon lookup outside of these
directories.
.IP "\fBsticky_history\fR (values: [true/false], default: true)" 4
.IX Item "sticky_history (values: [true/false], default: true)"
If set to true, notifications that have been recalled from history will not
time out automatically.
.IP "\fBhistory_length\fR (default: 20)" 4
.IX Item "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
\&\s-1HISTORY.\s0
.ie n .IP "\fBdmenu\fR (default: ""/usr/bin/dmenu"")" 4
.el .IP "\fBdmenu\fR (default: ``/usr/bin/dmenu'')" 4
.IX Item "dmenu (default: /usr/bin/dmenu)"
The command that will be run when opening the context menu. Should be either
a dmenu command or a dmenu-compatible menu.
.ie n .IP "\fBbrowser\fR (default: ""/usr/bin/firefox"")" 4
.el .IP "\fBbrowser\fR (default: ``/usr/bin/firefox'')" 4
.IX Item "browser (default: /usr/bin/firefox)"
The command that will be run when opening a \s-1URL.\s0 The \s-1URL\s0 to be opened will be
appended to the end of the value of this setting.
.IP "\fBalways_run_script\fR (values: [true/false] default: true]" 4
.IX Item "always_run_script (values: [true/false] default: true]"
Always run rule-defined scripts, even if the notification is suppressed with
format = "". See \s-1SCRIPTING.\s0
.ie n .IP "\fBtitle\fR (default: ""Dunst"")" 4
.el .IP "\fBtitle\fR (default: ``Dunst'')" 4
.IX Item "title (default: Dunst)"
Defines the title of notification windows spawned by dunst. (_NET_WM_NAME
property). There should be no need to modify this setting for regular use.
.ie n .IP "\fBclass\fR (default: ""Dunst"")" 4
.el .IP "\fBclass\fR (default: ``Dunst'')" 4
.IX Item "class (default: Dunst)"
Defines the class of notification windows spawned by dunst. (First part of
\&\s-1WM_CLASS\s0). There should be no need to modify this setting for regular use.
.IP "\fBstartup_notification\fR (values: [true/false], default: false)" 4
.IX Item "startup_notification (values: [true/false], default: false)"
Display a notification on startup. This is usually used for debugging and there
shouldn't be any need to use this option.
.IP "\fBverbosity\fR (values: 'crit', 'warn', 'mesg', 'info', 'debug' default 'mesg')" 4
.IX Item "verbosity (values: 'crit', 'warn', 'mesg', 'info', 'debug' default 'mesg')"
Do not display log messages, which have lower precedence than specified
verbosity. This won't affect printing notifications on the terminal. Use
the '\-print' option for this.
.IP "\fBforce_xinerama\fR (values: [true/false], default: false)" 4
.IX Item "force_xinerama (values: [true/false], default: false)"
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.
.Sp
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.
.IP "\fBcorner_radius\fR (default: 0)" 4
.IX Item "corner_radius (default: 0)"
Define the corner radius in pixels. A corner radius of 0 will result in
rectangular shaped notifications.
.Sp
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.
.Sp
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.
.IP "\fBmouse_left/middle/right_click\fR (values: [none/do_action/close_current/close_all])" 4
.IX Item "mouse_left/middle/right_click (values: [none/do_action/close_current/close_all])"
Defines action of mouse click.
.RS 4
.IP "\fBnone\fR" 4
.IX Item "none"
Don't do anything.
.IP "\fBdo_action\fR (default for mouse_middle_click)" 4
.IX Item "do_action (default for mouse_middle_click)"
If the notification has exactly one action, or one is marked as default, invoke it. If there are multiple and no default, open the context menu.
.IP "\fBclose_current\fR (default for mouse_left_click)" 4
.IX Item "close_current (default for mouse_left_click)"
Close current notification.
.IP "\fBclose_all\fR (default for mouse_right_click)" 4
.IX Item "close_all (default for mouse_right_click)"
Close all notifications.
.RE
.RS 4
.RE
.IP "\fBignore_dbusclose\fR (default: false)" 4
.IX Item "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.
.SS "Shortcut section \fB\s-1DEPRECATED SEE DUNSTCTL\s0\fP"
.IX Subsection "Shortcut section DEPRECATED SEE DUNSTCTL"
Keyboard shortcuts are defined in the following format: \*(L"Modifier+key\*(R" where the
modifier is one of ctrl,mod1,mod2,mod3,mod4 and key is any keyboard key.
.IP "\fBclose\fR" 4
.IX Item "close"
\&\fBcommand line flag\fR: \-key
.Sp
Specifies the keyboard shortcut for closing a notification.
.IP "\fBclose_all\fR" 4
.IX Item "close_all"
\&\fBcommand line flag\fR: \-all_key
.Sp
Specifies the keyboard shortcut for closing all currently displayed notifications.
.IP "\fBhistory\fR" 4
.IX Item "history"
\&\fBcommand line flag\fR: \-history_key
.Sp
Specifies the keyboard shortcut for recalling a single notification from history.
.IP "\fBcontext\fR" 4
.IX Item "context"
\&\fBcommand line flag\fR: \-context_key
.Sp
Specifies the keyboard shortcut that opens the context menu.
.SS "Urgency sections"
.IX Subsection "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, timeout, frame_color and
icon attributes can be modified.
.PP
The urgency sections are urgency_low, urgency_normal, urgency_critical for low,
normal and critical urgency respectively.
.PP
See the example configuration file for examples.
.PP
Additionally, you can override these settings via the following command line
flags:
.PP
Please note these flags may be removed in the future. See issue #328 in the bug
tracker for discussions (See \s-1REPORTING BUGS\s0).
.IP "\fB\-li/ni/ci icon\fR" 4
.IX Item "-li/ni/ci icon"
Defines the icon for low, normal and critical notifications respectively.
.Sp
Where \fIicon\fR is a path to an image file containing the icon.
.IP "\fB\-lf/nf/cf color\fR" 4
.IX Item "-lf/nf/cf color"
Defines the foreground color for low, normal and critical notifications respectively.
.Sp
See \s-1COLORS\s0 for the value format.
.IP "\fB\-lb/nb/cb color\fR" 4
.IX Item "-lb/nb/cb color"
Defines the background color for low, normal and critical notifications respectively.
.Sp
See \s-1COLORS\s0 for the value format.
.IP "\fB\-lfr/nfr/cfr color\fR" 4
.IX Item "-lfr/nfr/cfr color"
Defines the frame color for low, normal and critical notifications respectively.
.Sp
See \s-1COLORS\s0 for more information
.IP "\fB\-lto/nto/cto secs\fR" 4
.IX Item "-lto/nto/cto secs"
Defines the timeout time for low, normal and critical notifications
respectively.
See \s-1TIME FORMAT\s0 for valid times.
.SH "DUNSTCTL"
.IX Header "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. So see more see the dunstctl man
page.
.SH "HISTORY"
.IX Header "HISTORY"
Dunst saves a number of notifications (specified by \fBhistory_length\fR) in memory.
These notifications can be recalled (i.e. redisplayed) by pressing the
\&\fBhistory_key\fR (see the shortcuts section), whether these notifications will
time out like if they have been just send depends on the value of the
\&\fBsticky_history\fR setting.
.PP
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.
.SH "RULES"
.IX Header "RULES"
Rules allow the conditional modification of notifications. They are defined by
creating a section in the configuration file that has any name that is not
already used internally (i.e. any name other than 'global', 'experimental',
\&'frame', 'shortcuts', 'urgency_low', 'urgency_normal' and 'urgency_critical').
.PP
There are 2 parts in configuring a rule: Defining the filters that control when
a rule should apply and then the actions that should be taken when the rule is
matched.
.IP "\fBfiltering\fR" 4
.IX Item "filtering"
Notifications can be matched for any of the following attributes:
.RS 4
.ie n .IP """appname"" (discouraged, see desktop_entry)" 4
.el .IP "\f(CWappname\fR (discouraged, see desktop_entry)" 4
.IX Item "appname (discouraged, see 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.
.ie n .IP """body""" 4
.el .IP "\f(CWbody\fR" 4
.IX Item "body"
The body of the notification
.ie n .IP """category""" 4
.el .IP "\f(CWcategory\fR" 4
.IX Item "category"
The category of the notification as defined by the notification spec. See
https://developer.gnome.org/notification\-spec/#categories
.ie n .IP """desktop_entry""" 4
.el .IP "\f(CWdesktop_entry\fR" 4
.IX Item "desktop_entry"
GLib based applications export their desktop-entry name. In comparison to the appname,
the desktop-entry won't get localized.
.ie n .IP """icon""" 4
.el .IP "\f(CWicon\fR" 4
.IX Item "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.
.ie n .IP """match_transient""" 4
.el .IP "\f(CWmatch_transient\fR" 4
.IX Item "match_transient"
Match if the notification has been declared as transient by the client or by
some other rule.
.Sp
See \f(CW\*(C`set_transient\*(C'\fR for more details about this attribute.
.ie n .IP """msg_urgency""" 4
.el .IP "\f(CWmsg_urgency\fR" 4
.IX Item "msg_urgency"
Matches the urgency of the notification as set by the client or by some other
rule.
.ie n .IP """stack_tag""" 4
.el .IP "\f(CWstack_tag\fR" 4
.IX Item "stack_tag"
Matches the stack tag of the notification as set by the client or by some other
rule.
.Sp
See set_stack_tag for more information about stack tags.
.ie n .IP """summary""" 4
.el .IP "\f(CWsummary\fR" 4
.IX Item "summary"
Matches the summary, 'title', of the notification.
.RE
.RS 4
.Sp
\&\f(CW\*(C`msg_urgency\*(C'\fR is the urgency of the notification, it is named so to not conflict
with trying to modify the urgency.
.Sp
Instead of the appname filter, it's recommended to use the desktop_entry filter.
.Sp
To define a matching rule simply assign the specified value to the value that
should be matched, for example:
.Sp
.Vb 1
\& appname="notify\-send"
.Ve
.Sp
Matches only messages that were send via notify-send. If multiple filter
expressions are present, all of them have to match for the rule to be applied
(logical \s-1AND\s0).
.Sp
Shell-like globing is supported.
.RE
.IP "\fBmodifying\fR" 4
.IX Item "modifying"
The following attributes can be overridden:
.RS 4
.ie n .IP """background""" 4
.el .IP "\f(CWbackground\fR" 4
.IX Item "background"
The background color of the notification. See \s-1COLORS\s0 for possible values.
.ie n .IP """foreground""" 4
.el .IP "\f(CWforeground\fR" 4
.IX Item "foreground"
The background color of the notification. See \s-1COLORS\s0 for possible values.
.ie n .IP """format""" 4
.el .IP "\f(CWformat\fR" 4
.IX Item "format"
Equivalent to the \f(CW\*(C`format\*(C'\fR setting.
.ie n .IP """frame_color""" 4
.el .IP "\f(CWframe_color\fR" 4
.IX Item "frame_color"
The frame color color of the notification. See \s-1COLORS\s0 for possible values.
.ie n .IP """fullscreen""" 4
.el .IP "\f(CWfullscreen\fR" 4
.IX Item "fullscreen"
One of show, delay, or pushback.
.Sp
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.
.Sp
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.
.Sp
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.
.ie n .IP """new_icon""" 4
.el .IP "\f(CWnew_icon\fR" 4
.IX Item "new_icon"
Updates the icon of the notification, it should be a path to a valid image.
.ie n .IP """set_stack_tag""" 4
.el .IP "\f(CWset_stack_tag\fR" 4
.IX Item "set_stack_tag"
Sets the stack tag for the notification, notifications with the same (non-empty)
stack tag will replace each-other so only the newest one is visible. This can be
useful for example in volume or brightness notifications where only want one of
the same type visible.
.Sp
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.
.ie n .IP """set_transient""" 4
.el .IP "\f(CWset_transient\fR" 4
.IX Item "set_transient"
Sets whether the notification is considered transient.
Transient notifications will bypass the idle_threshold setting.
.Sp
By default notifications are _not_ considered transient but clients can set the
value of this by specifying the 'transient' hint when sending notifications.
.ie n .IP """timeout""" 4
.el .IP "\f(CWtimeout\fR" 4
.IX Item "timeout"
Equivalent to the \f(CW\*(C`timeout\*(C'\fR setting in the urgency sections.
.ie n .IP """urgency""" 4
.el .IP "\f(CWurgency\fR" 4
.IX Item "urgency"
This sets the notification urgency.
.Sp
\&\fB\s-1IMPORTANT NOTE\s0\fR: This currently \s-1DOES NOT\s0 re-apply the attributes from the
urgency_* sections. The changed urgency will only be visible in rules defined
later. Use \f(CW\*(C`msg_urgency\*(C'\fR to match it.
.ie n .IP """skip_display""" 4
.el .IP "\f(CWskip_display\fR" 4
.IX Item "skip_display"
Setting this to true will prevent the notification from being displayed
initially but will be saved in history for later viewing.
.RE
.RS 4
.Sp
As with the filtering attributes, each one corresponds to
the respective notification attribute to be modified.
.Sp
As with filtering, to make a rule modify an attribute simply assign it in the
rule definition.
.Sp
If the format is set to an empty string, the notification will not be
suppressed.
.RE
.SS "\s-1SCRIPTING\s0"
.IX Subsection "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.
.PP
When the script is called details of the notification that triggered it will be
passed via command line parameters in the following order: appname, summary,
body, icon, urgency.
.PP
Where icon is the absolute path to the icon file if there is one and urgency is
one of \*(L"\s-1LOW\*(R", \*(L"NORMAL\*(R"\s0 or \*(L"\s-1CRITICAL\*(R".\s0
.PP
If the notification is suppressed, the script will not be run unless
\&\fBalways_run_scripts\fR is set to true.
.PP
If '~/' occurs at the beginning of the script parameter, it will get replaced by the
users' home directory. If the value is not an absolute path, the directories in the
\&\s-1PATH\s0 variable will be searched for an executable of the same name.
.SH "COLORS"
.IX Header "COLORS"
Colors are interpreted as X11 color values. This includes both verbatim
color names such as \*(L"Yellow\*(R", \*(L"Blue\*(R", \*(L"White\*(R", etc as well as #RGB and #RRGGBB
values.
.PP
You may also specify a transparency component in #RGBA or #RRGGBBAA format.
.PP
\&\fB\s-1NOTE\s0\fR: '#' is interpreted as a comment, to use it the entire value needs to
be in quotes like so: separator_color=\*(L"#123456\*(R"
.SS "NOTIFY-SEND"
.IX Subsection "NOTIFY-SEND"
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.
.IP "notify-send \-h string:fgcolor:#ff4444" 4
.IX Item "notify-send -h string:fgcolor:#ff4444"
.PD 0
.IP "notify-send \-h string:bgcolor:#4444ff \-h string:fgcolor:#ff4444 \-h string:frcolor:#44ff44" 4
.IX Item "notify-send -h string:bgcolor:#4444ff -h string:fgcolor:#ff4444 -h string:frcolor:#44ff44"
.ie n .IP "notify-send \-h int:value:42 ""Working ...""" 4
.el .IP "notify-send \-h int:value:42 ``Working ...''" 4
.IX Item "notify-send -h int:value:42 Working ..."
.PD
.SH "ACTIONS"
.IX Header "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.
.PP
If \*(L"show_indicators\*(R" is true and a notification has an action, an \*(L"(A)\*(R" will be
prepended to the notification format. Likewise, an \*(L"(U)\*(R" 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 \s-1HAVE\s0 actions.
.PP
The \*(L"context\*(R" keybinding is used to interact with these actions, by showing a
menu of possible actions. This feature requires \*(L"dmenu\*(R" or a dmenu drop-in
replacement present.
.PP
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.
.SH "TIME FORMAT"
.IX Header "TIME FORMAT"
A time can be any decimal integer value suffixed with a time unit. If no unit
given, seconds (\*(L"s\*(R") is taken as default.
.PP
Time units understood by dunst are \*(L"ms\*(R", \*(L"s\*(R", \*(L"m\*(R", \*(L"h\*(R" and \*(L"d\*(R".
.PP
Example time: \*(L"1000ms\*(R" \*(L"10m\*(R"
.SH "MISCELLANEOUS"
.IX Header "MISCELLANEOUS"
Dunst can be paused via the `dunstctl set-paused true` command. To unpause dunst use
`dunstctl set-paused false`.
Alternatively you can send \s-1SIGUSR1\s0 and \s-1SIGUSR2\s0 to pause and unpause
respectively. For Example:
.IP "killall \-SIGUSR1 dunst # pause" 4
.IX Item "killall -SIGUSR1 dunst # pause"
.PD 0
.IP "killall \-SIGUSR2 dunst # resume" 4
.IX Item "killall -SIGUSR2 dunst # resume"
.PD
.PP
When paused dunst will not display any notifications but keep all notifications
in a queue. This can for example be wrapped around a screen locker (i3lock,
slock) to prevent flickering of notifications through the lock and to read all
missed notifications after returning to the computer.
.SH "FILES"
.IX Header "FILES"
\&\f(CW$XDG_CONFIG_HOME\fR/dunst/dunstrc
.PP
\&\-or\-
.PP
\&\f(CW$HOME\fR/.config/dunst/dunstrc
.SH "AUTHORS"
.IX Header "AUTHORS"
Written by Sascha Kruse
.SH "REPORTING BUGS"
.IX Header "REPORTING BUGS"
Bugs and suggestions should be reported on GitHub at https://github.com/dunst\-project/dunst/issues
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2013 Sascha Kruse and contributors (see \s-1LICENSE\s0 for licensing information)
.PP
If you feel that copyrights are violated, please send me an email.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdunstctl\fR\|(1), \fBdwm\fR\|(1), \fBdmenu\fR\|(1), \fBtwmn\fR\|(1), \fBnotify\-send\fR\|(1)