overlay-rule-spec.txt

overlay-rule-spec.txt

Overlay injection rules spec
============================

An overlay rule file is a UTF-8 (no BOM) text file.
Each line is separated by \n (LF) or \r\n (CRLF).
Everything after # in a line is ignored, this allows
# to be used for line comments.

Each line in an overlay rule file defines a rule.

Some characters are special, and must be escaped to
be part of a rule with their literal meaning. These
are:
     \* means literal *
     \\ means literal \
     \! means literal !
     \< means literal <

Rules are by default treated as basenames of files,
such as "mumble.exe". If a rule contains a slash or a
literal backslash, the entry will be treated as an
absolute path, instead of a basename.

Rules can contain the character *. This is a glob pattern.
When matching a rule with a glob pattern in it, the glob
pattern can match anything. Rules with glob patterns in
them are treated as absolute.

For example, if the current process is
    "C:\Program Files\Mumble\mumble.exe"
A rule written as follows:
    "*Mumble*"
will match it.

By default, everything is blacklisted. That is, the logic
is whitelist-based.

Rules can be prefixed with operators.
The following operators are defined:

 ! (Not Operator)

   Negates the expression (DO NOT ALLOW <rule>)

 < (Parent Operator)

   Requires that the rule shall be matched against
   the filename of the parent's executable rather
   than the filename of the process's own executable.
   (ALLOW ONLY IF PARENT'S FILENAME MATCHES <rule>)

For example, to allow the overlay into all games launched
via Steam, you could construct a rule such as:

    <Steam.exe # Parent is Steam

To allow all Steam games except Half-Life 2:

    <Steam.exe # Parent is Steam
    !hl2.exe # ...but is not hl2.exe

By default, the rule list is treated as a whitelist.
However, it is easy to invert the logic to create a
blacklist instead:

    * # Allow everything
    !chrome.exe # Except Chrome

It is also easy to whitelist all games found in D:\MyGames:

    D:\\MyGames* # Only show the overlay in games that live in D:\MyGames
    
The rule file is evaluated from top to bottom, and only once all rules
have been evaluated, the result of whether or not a game should have the
overlay injected into it is known.

Old-style Mumble blacklist in the new syntax
============================================

As an example, here is Mumble's old blacklist formulated
in the new rule syntax:

    # Mumble default blacklist
    * # Allow all
    !iexplore.exe
    !ieuser.exe
    !vlc.exe
    !crimecraft.exe
    !dbgview.exe
    !opera.exe
    !chrome.exe
    !acrord32.exe
    !explorer.exe
    !wmpnscfg.exe
    !firefox.exe
    !thunderbird.exe
    !instantbird.exe
    !wlmail.exe # Windows Live Suite (mshtml.dll)
    !msnmsgr.exe
    !MovieMaker.exe
    !WLXPhotoGallery.exe
    !psi.exe # Secunia PSI (uses mshtml.dll)
    !Photoshop.exe
    !blender.exe
    !googleearth.exe
    !XBMC.exe # http://xbmc.org/
    !BOXEE.exe # http://www.boxee.tv/
    !hammer.exe # VALVE Hammer Editor
    !hlmv.exe # Half-Life Model Viewer
    !hlfaceposer.exe # Face Poser (from Source SDK)
    !LoLLauncher.exe # League of Legends Launcher/Patcher
    !acrobat.exe # Adobe Acrobat
    !Steam.exe # Prevent invisible hooking
    !RzSynapse.exe # Prevent invisible hooking - Razer Synapse (settings online synchronization)
    !IpOverUsbSvc.exe # Windows Phone IP over USB Transport
    !Origin.exe # EA Origin
    !HydraSysTray.exe # Razer Hydra system tray
    !devenv.exe # Microsoft Visual Studio
    !spotify.exe # Spotify
    !FarCry4.exe # Far Cry 4 x64 overlay crash: https://github.com/mumble-voip/mumble/issues/1514
    !EpicGamesLauncher.exe # Epic, Unreal Tournament launcher
    !dwm.exe # Windows Desktop Window Manager
    !MouseKeyboardCenter.exe
    !outlook.exe

Proposed new default Mumble overlay rules
=========================================

Here is a new proposed default overlay rule file for Mumble.
It allows games from popular game launchers, but keeps our old
blacklist intact:

    # Allow games launched through these launchers
    <Steam.exe # Steam
    <EALaunchHelper.exe # Origin
    <Battle.net.exe # Battle.net
    <GalaxyClient.exe # GOG Galaxy

    # Disallow blacklisted
    !iexplore.exe
    !ieuser.exe
    !vlc.exe
    !crimecraft.exe
    !dbgview.exe
    !opera.exe
    !chrome.exe
    !acrord32.exe
    !explorer.exe
    !wmpnscfg.exe
    !firefox.exe
    !thunderbird.exe
    !instantbird.exe
    !wlmail.exe # Windows Live Suite (mshtml.dll)
    !msnmsgr.exe
    !MovieMaker.exe
    !WLXPhotoGallery.exe
    !psi.exe # Secunia PSI (uses mshtml.dll)
    !Photoshop.exe
    !blender.exe
    !googleearth.exe
    !XBMC.exe # http://xbmc.org/
    !BOXEE.exe # http://www.boxee.tv/
    !hammer.exe # VALVE Hammer Editor
    !hlmv.exe # Half-Life Model Viewer
    !hlfaceposer.exe # Face Poser (from Source SDK)
    !LoLLauncher.exe # League of Legends Launcher/Patcher
    !acrobat.exe # Adobe Acrobat
    !Steam.exe # Prevent invisible hooking
    !RzSynapse.exe # Prevent invisible hooking - Razer Synapse (settings online synchronization)
    !IpOverUsbSvc.exe # Windows Phone IP over USB Transport
    !Origin.exe # EA Origin
    !HydraSysTray.exe # Razer Hydra system tray
    !devenv.exe # Microsoft Visual Studio
    !spotify.exe # Spotify
    !FarCry4.exe # Far Cry 4 x64 overlay crash: https://github.com/mumble-voip/mumble/issues/1514
    !EpicGamesLauncher.exe # Epic, Unreal Tournament launcher
    !dwm.exe # Windows Desktop Window Manager
    !MouseKeyboardCenter.exe
    !outlook.exe