1=head1 NAME 2 3dunst - configuration file 4 5=head1 DESCRIPTION 6 7An example configuration file is included (usually /usr/local/etc/dunst/dunstrc). Note: 8this was previously /usr/local/share/dunst/dunstrc. 9To change the configuration, copy this file to ~/.config/dunst/dunstrc and edit 10it accordingly. 11 12The configuration is divided into sections in an ini-like format. The 'global' 13section contains most general settings while the setions 'urgency_low', 14'urgency_normal' and 'urgency_critical' are for low, normal and critical urgency 15notifications respectively. The 'shortcuts' section (deprecated) contains all 16keyboard configuration and the 'experimental' section all the features that have 17not yet been tested thoroughly. 18 19Any section that is not one of the above is assumed to be a rule, see RULES for 20more details. 21 22For backwards compatibility reasons the section name 'frame' is considered bound 23and can't be used as a rule. 24 25=head2 Global section 26 27=over 4 28 29=item B<monitor> (default: 0) 30 31Specifies on which monitor the notifications should be displayed in, count 32starts at 0. See the B<follow> setting. 33 34=item B<follow> (values: [none/mouse/keyboard] default: none) 35 36Defines where the notifications should be placed in a multi-monitor setup. All 37values except I<none> override the B<monitor> setting. 38 39On Wayland there is no difference between mouse and keyboard focus. When either 40of the is used, the compositor will choose an output. This will generally be 41the output last interacted with. 42 43=over 4 44 45=item B<none> 46 47The notifications will be placed on the monitor specified by the B<monitor> 48setting. 49 50=item B<mouse> 51 52The notifications will be placed on the monitor that the mouse is currently in. 53 54=item B<keyboard> 55 56The notifications will be placed on the monitor that contains the window with 57keyboard focus. 58 59=back 60 61=item B<geometry> (format: [{width}][x{height}][+/-{x}[+/-{y}]], default: "0x0+0-0") 62 63The geometry of the window the notifications will be displayed in. 64 65=over 4 66 67=item B<width> 68 69The width of the notification window in pixels. A negative value sets the width 70to the screen width B<minus the absolute value of the width>. If the width is 71omitted then the window expands to cover the whole screen. If it's 0 the window 72expands to the width of the longest message being displayed. 73 74=item B<height> 75 76The number of notifications that can appear at one time. When this 77limit is reached any additional notifications will be queued and displayed when 78the currently displayed ones either time out or are manually dismissed. If 79B<indicate_hidden> is true, then the specified limit is reduced by 1 and the 80last notification is a message informing how many hidden notifications are 81waiting to be displayed. See the B<indicate_hidden> entry for more information. 82 83The physical(pixel) height of the notifications vary depending on the number of 84lines that need to be displayed. 85 86See B<notification_height> for changing the physical height. 87 88=item B<x/y> 89 90Respectively the horizontal and vertical offset in pixels from the corner 91of the screen that the notification should be drawn at. For the horizontal(x) 92offset, a positive value is measured from the left of the screen while a 93negative one from the right. For the vertical(y) offset, a positive value is 94measured from the top while a negative from the bottom. 95 96It's important to note that the positive and negative sign B<DOES> affect the 97position even if the offset is 0. For example, a horizontal offset of +0 puts 98the notification on the left border of the screen while a horizontal offset of 99-0 at the right border. The same goes for the vertical offset. 100 101=back 102 103=item B<progress_bar> (values: [true/false], default: true) 104 105When an integer value is passed to dunst as a hint (see B<NOTIFY-SEND>), a 106progress bar will be drawn at the bottom of the notification. This 107behavior can be turned off by setting this setting to false. 108 109=item B<progress_bar_height> (default: 10) 110 111The height of the progress bar in pixel. This includes the frame. Make sure 112this value is bigger than twice the frame width. 113 114=item B<progress_bar_min_width> (default: 150) 115 116The minimum width of the progress bar in pixels. The notification is rescaled 117to fit the bar. 118 119=item B<progress_bar_max_width> (default: 300) 120 121The maximum width of the progress bar in pixels. The notification is resized 122to fit the progress bar. 123 124=item B<progress_bar_frame_width> (default: 1) 125 126The frame width of the progress bar in pixels. This value should be smaller 127than half of the progress bar height. 128 129=item B<indicate_hidden> (values: [true/false], default: true) 130 131If this is set to true, a notification indicating how many notifications are 132not being displayed due to the notification limit (see B<geometry>) will be 133shown B<in place of the last notification slot>. 134 135Meaning that if this is enabled the number of visible notifications will be 1 136less than what is specified in geometry, the last slot will be taken by the 137hidden count. 138 139=item B<shrink> (values: [true/false], default: false) 140 141Shrink window if it's smaller than the width. Will be ignored if width is 0. 142 143This is used mainly in order to have the shrinking benefit of dynamic width (see 144geometry) while also having an upper bound on how long a notification can get 145before wrapping. 146 147=item B<transparency> (default: 0) 148 149A 0-100 range on how transparent the notification window should be, with 0 150being fully opaque and 100 invisible. 151 152This setting will only work if a compositor is running. 153 154=item B<notification_height> (default: 0) 155 156The minimum height of the notification window in pixels. If the text and 157padding cannot fit in within the height specified by this value, the height 158will be increased as needed. 159 160=item B<separator_height> (default: 2) 161 162The height in pixels of the separator between notifications, if set to 0 there 163will be no separating line between notifications. 164 165=item B<padding> (default: 0) 166 167The distance in pixels from the content to the separator/border of the window 168in the vertical axis 169 170=item B<horizontal_padding> (default: 0) 171 172The distance in pixels from the content to the border of the window 173in the horizontal axis 174 175=item B<text_icon_padding> (default: 0) 176 177The distance in pixels from the text to the icon (or vice versa) 178in the horizontal axis. 179 180Setting this to a non-zero value overwrites any padding that horizontal_padding was adding between the notification text and icon. 181 182So for example setting 183 184 text_icon_padding=10 185 horizontal_padding=10 186 187is equivalent to 188 189 text_icon_padding=0 190 horizontal_padding=10 191 192=item B<frame_width> (default: 0) 193 194Defines width in pixels of frame around the notification window. Set to 0 to 195disable. 196 197=item B<frame_color color> (default: #888888) 198 199Defines color of the frame around the notification window. See COLORS. 200 201=item B<separator_color> (values: [auto/foreground/frame/#RRGGBB] default: auto) 202 203Sets the color of the separator line between two notifications. 204 205=over 4 206 207=item B<auto> 208 209Dunst tries to find a color that fits the rest of the notification color 210scheme automatically. 211 212=item B<foreground> 213 214The color will be set to the same as the foreground color of the topmost 215notification that's being separated. 216 217=item B<frame> 218 219The color will be set to the frame color of the notification with the highest 220urgency between the 2 notifications that are being separated. 221 222=item B<anything else> 223 224Any other value is interpreted as a color, see COLORS 225 226=back 227 228=item B<sort> (values: [true/false], default: true) 229 230If set to true, display notifications with higher urgency above the others. 231 232=item B<idle_threshold> (default: 0) 233 234Don't timeout notifications if user is idle longer than this time. 235See TIME FORMAT for valid times. 236 237Set to 0 to disable. 238 239A client can mark a notification as transient to bypass this setting and timeout 240anyway. Use a rule with 'set_transient = no' to disable this behavior. 241 242Note: this doesn't work on xwayland. 243 244=item B<layer> (Wayland only) 245 246One of bottom, top or overlay. 247 248Place dunst notifications on the selected layer. Using overlay 249will cause notifications to be displayed above fullscreen windows, though 250this may also occur at top depending on your compositor. 251 252In Wayland, Notifications won't be delayed when in fullscreen (like when 253setting B<fullscreen> to pushback in X11). This is a Wayland limitation. 254 255The bottom layer is below all windows and above the background. 256 257Default: overlay 258 259=item B<force_xwayland> (values: [true/false], default: false) (Wayland only) 260 261Force the use of X11 output, even on a wayland compositor. This setting 262has no effect when not using a Wayland compositor. 263 264=item B<font> (default: "Monospace 8") 265 266Defines the font or font set used. Optionally set the size as a decimal number 267after the font name and space. 268Multiple font options can be separated with commas. 269 270This options is parsed as a Pango font description. 271 272=item B<line_height> (default: 0) 273 274The amount of extra spacing between text lines in pixels. Set to 0 to 275disable. 276 277=item B<markup> (values: [full/strip/no], default: no) 278 279Defines how markup in notifications is handled. 280 281It's important to note that markup in the format option will be parsed 282regardless of what this is set to. 283 284Possible values: 285 286=over 4 287 288=item B<full> 289 290Allow a small subset of html markup in notifications 291 292 <b>bold</b> 293 <i>italic</i> 294 <s>strikethrough</s> 295 <u>underline</u> 296 297For a complete reference see 298<https://developer.gnome.org/pango/stable/pango-Markup.html> 299 300=item B<strip> 301 302This setting is provided for compatibility with some broken 303clients that send markup even though it's not enabled on the 304server. 305 306Dunst will try to strip the markup but the parsing is simplistic so using this 307option outside of matching rules for specific applications B<IS GREATLY 308DISCOURAGED>. 309 310See RULES 311 312=item B<no> 313 314Disable markup parsing, incoming notifications will be treated as 315plain text. Dunst will not advertise that it can parse markup if this is set as 316a global setting. 317 318=back 319 320=item B<format> (default: "%s %b") 321 322Specifies how the various attributes of the notification should be formatted on 323the notification window. 324 325Regardless of the status of the B<markup> setting, any markup tags that are 326present in the format will be parsed. Note that because of that, if a literal 327ampersand (&) is needed it needs to be escaped as '&' 328 329If '\n' is present anywhere in the format, it will be replaced with 330a literal newline. 331 332If any of the following strings are present, they will be replaced with the 333equivalent notification attribute. 334 335=over 4 336 337=item B<%a> appname 338 339=item B<%s> summary 340 341=item B<%b> body 342 343=item B<%i> iconname (including its path) 344 345=item B<%I> iconname (without its path) 346 347=item B<%p> progress value ([ 0%] to [100%]) 348 349=item B<%n> progress value without any extra characters 350 351=item B<%%> Literal % 352 353=back 354 355If any of these exists in the format but hasn't been specified in the 356notification (e.g. no icon has been set), the placeholders will simply be 357removed from the format. 358 359=item B<alignment> (values: [left/center/right], default: left) 360 361Defines how the text should be aligned within the notification. 362 363=item B<vertical_alignment> (values: [top/center/bottom], default: center) 364 365Defines how the text and icon should be aligned vertically within the 366notification. If icons are disabled, this option has no effect. 367 368=item B<show_age_threshold> (default: -1) 369 370Show age of message if message is older than this time. 371See TIME FORMAT for valid times. 372 373Set to -1 to disable. 374 375=item B<word_wrap> (values: [true/false], default: false) 376 377Specifies how very long lines should be handled 378 379If it's set to false, long lines will be truncated and ellipsized. 380 381If it's set to true, long lines will be broken into multiple lines expanding 382the notification window height as necessary for them to fit. 383 384=item B<ellipsize> (values: [start/middle/end], default: middle) 385 386If word_wrap is set to false, specifies where truncated lines should be 387ellipsized. 388 389=item B<ignore_newline> (values: [true/false], default: false) 390 391If set to true, replace newline characters in notifications with whitespace. 392 393=item B<stack_duplicates> (values: [true/false], default: true) 394 395If set to true, duplicate notifications will be stacked together instead of 396being displayed separately. 397 398Two notifications are considered duplicate if the name of the program that sent 399it, summary, body, icon and urgency are all identical. 400 401=item B<hide_duplicate_count> (values: [true/false], default: false) 402 403Hide the count of stacked duplicate notifications. 404 405=item B<show_indicators> (values: [true/false], default: true) 406 407Show an indicator if a notification contains actions and/or open-able URLs. See 408ACTIONS below for further details. 409 410=item B<icon_position> (values: [left/right/off], default: off) 411 412Defines the position of the icon in the notification window. Setting it to off 413disables icons. 414 415=item B<min_icon_size> (default: 0) 416 417Defines the minimum size in pixels for the icons. 418If the icon is larger than or equal to the specified value it won't be affected. 419If it's smaller then it will be scaled up so that the smaller axis is equivalent 420to the specified size. 421 422Set to 0 to disable icon upscaling. (default) 423 424If B<icon_position> is set to off, this setting is ignored. 425 426=item B<max_icon_size> (default: 0) 427 428Defines the maximum size in pixels for the icons. 429If the icon is smaller than or equal to the specified value it won't be affected. 430If it's larger then it will be scaled down so that the larger axis is equivalent 431to the specified size. 432 433Set to 0 to disable icon downscaling. (default) 434 435If both B<min_icon_size> and B<max_icon_size> are enabled, the latter 436gets the last say. 437 438If B<icon_position> is set to off, this setting is ignored. 439 440=item B<icon_path> (default: "/usr/local/share/icons/gnome/16x16/status/:/usr/local/share/icons/gnome/16x16/devices/") 441 442Can be set to a colon-separated list of paths to search for icons to use with 443notifications. 444 445Dunst doesn't currently do any type of icon lookup outside of these 446directories. 447 448=item B<sticky_history> (values: [true/false], default: true) 449 450If set to true, notifications that have been recalled from history will not 451time out automatically. 452 453=item B<history_length> (default: 20) 454 455Maximum number of notifications that will be kept in history. After that limit 456is reached, older notifications will be deleted once a new one arrives. See 457HISTORY. 458 459=item B<dmenu> (default: "/usr/local/bin/dmenu") 460 461The command that will be run when opening the context menu. Should be either 462a dmenu command or a dmenu-compatible menu. 463 464=item B<browser> (default: "/usr/local/bin/firefox") 465 466The command that will be run when opening a URL. The URL to be opened will be 467appended to the end of the value of this setting. 468 469=item B<always_run_script> (values: [true/false] default: true] 470 471Always run rule-defined scripts, even if the notification is suppressed with 472format = "". See SCRIPTING. 473 474=item B<title> (default: "Dunst") 475 476Defines the title of notification windows spawned by dunst. (_NET_WM_NAME 477property). There should be no need to modify this setting for regular use. 478 479=item B<class> (default: "Dunst") 480 481Defines the class of notification windows spawned by dunst. (First part of 482WM_CLASS). There should be no need to modify this setting for regular use. 483 484=item B<startup_notification> (values: [true/false], default: false) 485 486Display a notification on startup. This is usually used for debugging and there 487shouldn't be any need to use this option. 488 489=item B<verbosity> (values: 'crit', 'warn', 'mesg', 'info', 'debug' default 'mesg') 490 491Do not display log messages, which have lower precedence than specified 492verbosity. This won't affect printing notifications on the terminal. Use 493the '-print' option for this. 494 495=item B<force_xinerama> (values: [true/false], default: false) (X11 only) 496 497Use the Xinerama extension instead of RandR for multi-monitor support. This 498setting is provided for compatibility with older nVidia drivers that do not 499support RandR and using it on systems that support RandR is highly discouraged. 500 501By enabling this setting dunst will not be able to detect when a monitor is 502connected or disconnected which might break follow mode if the screen layout 503changes. 504 505=item B<corner_radius> (default: 0) 506 507Define the corner radius in pixels. A corner radius of 0 will result in 508rectangular shaped notifications. 509 510By enabling this setting the outer border and the frame will be shaped. 511If you have multiple notifications, the whole window is shaped, not every 512single notification. 513 514To avoid the corners clipping the icon or text the corner radius will be 515automatically lowered to half of the notification height if it exceeds it. 516 517=item B<mouse_left/middle/right_click> (values: [none/do_action/close_current/close_all]) 518 519Defines action of mouse click. 520 521=over 4 522 523=item B<none> 524 525Don't do anything. 526 527=item B<do_action> (default for mouse_middle_click) 528 529If 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. 530 531=item B<close_current> (default for mouse_left_click) 532 533Close current notification. 534 535=item B<close_all> (default for mouse_right_click) 536 537Close all notifications. 538 539=back 540 541 542=item B<ignore_dbusclose> (default: false) 543 544Ignore the dbus closeNotification message. This is useful to enforce the timeout 545set by dunst configuration. Without this parameter, an application may close 546the notification sent before the user defined timeout. 547 548=back 549 550=head2 Shortcut section B<DEPRECATED SEE DUNSTCTL> (X11 only) 551 552Keyboard shortcuts are defined in the following format: "Modifier+key" where the 553modifier is one of ctrl,mod1,mod2,mod3,mod4 and key is any keyboard key. 554 555=over 4 556 557=item B<close> 558 559B<command line flag>: -key <key> 560 561Specifies the keyboard shortcut for closing a notification. 562 563=item B<close_all> 564 565B<command line flag>: -all_key <key> 566 567Specifies the keyboard shortcut for closing all currently displayed notifications. 568 569=item B<history> 570 571B<command line flag>: -history_key <key> 572 573Specifies the keyboard shortcut for recalling a single notification from history. 574 575=item B<context> 576 577B<command line flag>: -context_key <key> 578 579Specifies the keyboard shortcut that opens the context menu. 580 581=back 582 583=head2 Urgency sections 584 585The urgency sections work in a similar way to rules and can be used to specify 586attributes for the different urgency levels of notifications (low, normal, 587critical). Currently only the background, foreground, hightlight, timeout, 588frame_color and icon attributes can be modified. 589 590The urgency sections are urgency_low, urgency_normal, urgency_critical for low, 591normal and critical urgency respectively. 592 593See the example configuration file for examples. 594 595Additionally, you can override these settings via the following command line 596flags: 597 598Please note these flags may be removed in the future. See issue #328 in the bug 599tracker for discussions (See REPORTING BUGS). 600 601=over 4 602 603=item B<-li/ni/ci icon> 604 605Defines the icon for low, normal and critical notifications respectively. 606 607Where I<icon> is a path to an image file containing the icon. 608 609=item B<-lf/nf/cf color> 610 611Defines the foreground color for low, normal and critical notifications respectively. 612 613See COLORS for the value format. 614 615=item B<-lb/nb/cb color> 616 617Defines the background color for low, normal and critical notifications respectively. 618 619See COLORS for the value format. 620 621=item B<-lh/nh/ch color> 622 623Defines the highlight color for low, normal and critical notifications respectively. 624 625See COLORS for the value format. 626 627=item B<-lfr/nfr/cfr color> 628 629Defines the frame color for low, normal and critical notifications respectively. 630 631See COLORS for more information 632 633=item B<-lto/nto/cto secs> 634 635Defines the timeout time for low, normal and critical notifications 636respectively. 637See TIME FORMAT for valid times. 638 639=back 640 641=head1 DUNSTCTL 642 643Dunst now contains a command line control command that can be used to interact 644with it. It supports all functions previously done only via keyboard shortcuts 645but also has a lot of extra functionality. So see more see dunstctl(1). 646 647=head1 HISTORY 648 649Dunst saves a number of notifications (specified by B<history_length>) in memory. 650These notifications can be recalled (i.e. redisplayed) by calling 651B<dunstctl history> (see dunstctl(1)). Whether these notifications will time out 652like if they have been just send depends on the value of the B<sticky_history> 653setting. 654 655Past notifications are redisplayed in a first-in-last-out order, meaning that 656pressing the history key once will bring up the most recent notification that 657had been closed/timed out. 658 659=head1 WAYLAND 660 661Dunst has Wayland support since version 1.6.0. Because the Wayland protocol 662is more focused on security, some things that are possible in X11 are not 663possible in Wayland. Those differences are reflected in the configuration. 664The main things that change are that dunst on Wayland cannot use global 665hotkeys (they are deprecated anyways, use dunstctl) and it cannot detect 666if an application is fullscreen. If you want to see notifications when in 667fullscreen, set B<layer = overlay> in the global options. 668 669Note that the same limitations exist when using xwayland. 670If something doesn't quite work in Wayland, please file a bug report. In the 671mean time, you can try if the X11 output does work on wayland. Use 672B<force_xwayland = true> for that. 673 674If you have your dunst notifications on the same side of your display as your 675status bar, you might notice that your notifications appear a bit higher or 676lower than on X11. This is because the notification cannot be placed on top of 677your status bar. The notifications are placed relative to your status bar, 678making them appear higher or lower by the height of your status bar. We cannot 679do anything about that behavior, so you will need to change your B<geometry> 680variable accordingly. 681 682=head1 RULES 683 684Rules allow the conditional modification of notifications. They are defined by 685creating a section in the configuration file that has any name that is not 686already used internally (i.e. any name other than 'global', 'experimental', 687'frame', 'shortcuts', 'urgency_low', 'urgency_normal' and 'urgency_critical'). 688 689There are 2 parts in configuring a rule: Defining the filters that control when 690a rule should apply and then the actions that should be taken when the rule is 691matched. 692 693=over 4 694 695=item B<filtering> 696 697Notifications can be matched for any of the following attributes: 698 699=over 4 700 701=item C<appname> (discouraged, see desktop_entry) 702 703The name of the application as reported by the client. Be aware that the name 704can often differ depending on the locale used. 705 706=item C<body> 707 708The body of the notification 709 710=item C<category> 711 712The category of the notification as defined by the notification spec. See 713https://developer.gnome.org/notification-spec/#categories 714 715=item C<desktop_entry> 716 717GLib based applications export their desktop-entry name. In comparison to the appname, 718the desktop-entry won't get localized. 719 720=item C<icon> 721 722The icon of the notification in the form of a file path. Can be empty if no icon 723is available or a raw icon is used instead. 724 725=item C<match_transient> 726 727Match if the notification has been declared as transient by the client or by 728some other rule. 729 730See C<set_transient> for more details about this attribute. 731 732=item C<msg_urgency> 733 734Matches the urgency of the notification as set by the client or by some other 735rule. 736 737=item C<stack_tag> 738 739Matches the stack tag of the notification as set by the client or by some other 740rule. 741 742See set_stack_tag for more information about stack tags. 743 744=item C<summary> 745 746Matches the summary, 'title', of the notification. 747 748=back 749 750C<msg_urgency> is the urgency of the notification, it is named so to not conflict 751with trying to modify the urgency. 752 753Instead of the appname filter, it's recommended to use the desktop_entry filter. 754 755 756To define a matching rule simply assign the specified value to the value that 757should be matched, for example: 758 759 appname="notify-send" 760 761Matches only messages that were send via notify-send. If multiple filter 762expressions are present, all of them have to match for the rule to be applied 763(logical AND). 764 765Shell-like globing is supported. 766 767=item B<modifying> 768 769The following attributes can be overridden: 770 771=over 4 772 773=item C<background> 774 775The background color of the notification. See COLORS for possible values. 776 777=item C<foreground> 778 779The foreground color of the notification. See COLORS for possible values. 780 781=item C<highlight> 782 783The highlight color of the notification. This color is used for coloring the 784progress bar. See COLORS for possible values. 785 786=item C<format> 787 788Equivalent to the C<format> setting. 789 790=item C<frame_color> 791 792The frame color color of the notification. See COLORS for possible values. 793 794=item C<fullscreen> (X11 only) 795 796One of show, delay, or pushback. 797 798This attribute specifies how notifications are handled if a fullscreen window 799is focused. By default it's set to show so notifications are being shown. 800 801Other possible values are delay: Already shown notifications are continued to be 802displayed until they are dismissed or time out but new notifications will be 803held back and displayed when the focus to the fullscreen window is lost. 804 805Or pushback which is equivalent to delay with the difference that already 806existing notifications are paused and hidden until the focus to the fullscreen 807window is lost. 808 809See B<layer> to change fullscreen behavior in Wayland 810 811Default: show 812 813=item C<new_icon> 814 815Updates the icon of the notification, it should be a path to a valid image. 816 817=item C<set_stack_tag> 818 819Sets the stack tag for the notification, notifications with the same (non-empty) 820stack tag will replace each-other so only the newest one is visible. This can be 821useful for example in volume or brightness notifications where you only want one of 822the same type visible. 823 824The stack tag can be set by the client with the 'synchronous', 825'private-synchronous' 'x-canonical-private-synchronous' or the 826'x-dunst-stack-tag' hints. 827 828=item C<set_transient> 829 830Sets whether the notification is considered transient. 831Transient notifications will bypass the idle_threshold setting. 832 833By default notifications are _not_ considered transient but clients can set the 834value of this by specifying the 'transient' hint when sending notifications. 835 836=item C<timeout> 837 838Equivalent to the C<timeout> setting in the urgency sections. 839 840=item C<urgency> 841 842This sets the notification urgency. 843 844B<IMPORTANT NOTE>: This currently DOES NOT re-apply the attributes from the 845urgency_* sections. The changed urgency will only be visible in rules defined 846later. Use C<msg_urgency> to match it. 847 848=item C<skip_display> 849 850Setting this to true will prevent the notification from being displayed 851initially but will be saved in history for later viewing. 852 853=back 854 855As with the filtering attributes, each one corresponds to 856the respective notification attribute to be modified. 857 858As with filtering, to make a rule modify an attribute simply assign it in the 859rule definition. 860 861If the format is set to an empty string, the notification will not be 862suppressed. 863 864=back 865 866=head2 SCRIPTING 867 868Within rules you can specify a script to be run every time the rule is matched 869by assigning the 'script' option to the name of the script to be run. 870 871When the script is called details of the notification that triggered it will be 872passed via environment variables. The following variables are available: 873B<DUNST_APP_NAME>, B<DUNST_SUMMARY>, B<DUNST_BODY>, B<DUNST_ICON_PATH>, 874B<DUNST_URGENCY>, B<DUNST_ID>, B<DUNST_PROGRESS>, B<DUNST_CATEGORY>, 875B<DUNST_STACK_TAG>, B<DUNST_URLS>, B<DUNST_TIMEOUT>, B<DUNST_TIMESTAMP> 876and B<DUNST_STACK_TAG>. 877 878Another, less recommended way to get notifcations details from a script is via 879command line parameters. These are passed to the script in the following order: 880B<appname>, B<summary>, B<body>, B<icon_path>, B<urgency>. 881 882Where B<DUNST_ICON_PATH> or B<icon_path> is the absolute path to the icon file 883if there is one. B<DUNST_URGENCY> or B<urgency> is one of "LOW", "NORMAL" or 884"CRITICAL". B<DUNST_URLS> is a newline-separated list of urls associated with 885the notification. 886 887Note that some variables may be empty. 888 889If the notification is suppressed, the script will not be run unless 890B<always_run_scripts> is set to true. 891 892If '~/' occurs at the beginning of the script parameter, it will get replaced by the 893users' home directory. If the value is not an absolute path, the directories in the 894PATH variable will be searched for an executable of the same name. 895 896=head1 COLORS 897 898Colors are interpreted as X11 color values. This includes both verbatim 899color names such as "Yellow", "Blue", "White", etc as well as #RGB and #RRGGBB 900values. 901 902You may also specify a transparency component in #RGBA or #RRGGBBAA format. 903 904B<NOTE>: '#' is interpreted as a comment, to use it the entire value needs to 905be in quotes like so: separator_color="#123456" 906 907=head2 NOTIFY-SEND 908 909dunst is able to get different colors for a message via notify-send. 910In order to do that you have to add a hint via the -h option. 911The progress value can be set with a hint, too. 912 913=over 4 914 915=item notify-send -h string:fgcolor:#ff4444 916 917=item notify-send -h string:bgcolor:#4444ff -h string:fgcolor:#ff4444 -h string:frcolor:#44ff44 918 919=item notify-send -h int:value:42 "Working ..." 920 921=back 922 923=head1 ACTIONS 924 925Dunst allows notifiers (i.e.: programs that send the notifications) to specify 926actions. Dunst has support for both displaying indicators for these, and 927interacting with these actions. 928 929If "show_indicators" is true and a notification has an action, an "(A)" will be 930prepended to the notification format. Likewise, an "(U)" is prepended to 931notifications with URLs. It is possible to interact with notifications that 932have actions regardless of this setting, though it may not be obvious which 933notifications HAVE actions. 934 935The "context" keybinding is used to interact with these actions, by showing a 936menu of possible actions. This feature requires "dmenu" or a dmenu drop-in 937replacement present. 938 939Alternatively, you can invoke an action with a middle click on the notification. 940If there is exactly one associated action, or one is marked as default, that one 941is invoked. If there are multiple, the context menu is shown. The same applies 942to URLs when there are no actions. 943 944=head1 TIME FORMAT 945 946A time can be any decimal integer value suffixed with a time unit. If no unit 947given, seconds ("s") is taken as default. 948 949Time units understood by dunst are "ms", "s", "m", "h" and "d". 950 951Example time: "1000ms" "10m" 952 953=head1 MISCELLANEOUS 954 955Dunst can be paused via the `dunstctl set-paused true` command. To unpause dunst use 956`dunstctl set-paused false`. 957Alternatively you can send SIGUSR1 and SIGUSR2 to pause and unpause 958respectively. For Example: 959 960=over 4 961 962=item killall -SIGUSR1 dunst # pause 963 964=item killall -SIGUSR2 dunst # resume 965 966=back 967 968When paused dunst will not display any notifications but keep all notifications 969in a queue. This can for example be wrapped around a screen locker (i3lock, 970slock) to prevent flickering of notifications through the lock and to read all 971missed notifications after returning to the computer. 972 973=head1 FILES 974 975These are the places where dunst will look for a configuration file. They are 976listed here in order and if dunst finds one of them, it will stop looking for 977more. 978 979$XDG_CONFIG_HOME/dunst/dunstrc 980 981$HOME/.config/dunst/dunstrc 982 983-or- 984 985$XDG_CONFIG_HOME/dunst/dunstrc 986 987/usr/local/etc/xdg/dunst/dunstrc 988 989=over 4 990 991=item /usr/local/etc/dunst/dunstrc 992 993This is where the default config file is located 994 995=back 996 997=head1 AUTHORS 998 999Written by Sascha Kruse <knopwob@googlemail.com> 1000 1001=head1 REPORTING BUGS 1002 1003Bugs and suggestions should be reported on GitHub at https://github.com/dunst-project/dunst/issues 1004 1005=head1 COPYRIGHT 1006 1007Copyright 2013 Sascha Kruse and contributors (see LICENSE for licensing information) 1008 1009If you feel that copyrights are violated, please send me an email. 1010 1011=head1 SEE ALSO 1012 1013dunstctl(1), dwm(1), dmenu(1), twmn(1), notify-send(1) 1014