fail2ban.server.action module
*****************************

class fail2ban.server.action.ActionBase(jail, name)

   Bases: "object"

   An abstract base class for actions in Fail2Ban.

   Action Base is a base definition of what methods need to be in
   place to create a Python based action for Fail2Ban. This class can
   be inherited from to ease implementation. Required methods:

   * __init__(jail, name)

   * start()

   * stop()

   * ban(aInfo)

   * unban(aInfo)

   Called when action is created, but before the jail/actions is
   started. This should carry out necessary methods to initialise the
   action but not "start" the action.

   Parameters:
      **jail** : Jail
         The jail in which the action belongs to.

      **name** : str
         Name assigned to the action.

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "ban"(aInf | Executed when a ban occurs.                                                                |
   | o)         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "reban"(aI | Executed when a ban occurs.                                                                |
   | nfo)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start"()  | Executed when the jail/action is started.                                                  |
   +------------+--------------------------------------------------------------------------------------------+
   | "stop"()   | Executed when the jail/action is stopped.                                                  |
   +------------+--------------------------------------------------------------------------------------------+
   | "unban"(aI | Executed when a ban expires.                                                               |
   | nfo)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Notes ]-

   Any additional arguments specified in *jail.conf* or passed via
   *fail2ban-client* will be passed as keyword arguments.

   ban(aInfo)

      Executed when a ban occurs.

      Parameters:
         **aInfo** : dict
            Dictionary which includes information in relation to the
            ban.

   reban(aInfo)

      Executed when a ban occurs.

      Parameters:
         **aInfo** : dict
            Dictionary which includes information in relation to the
            ban.

   start()

      Executed when the jail/action is started.

   stop()

      Executed when the jail/action is stopped.

   unban(aInfo)

      Executed when a ban expires.

      Parameters:
         **aInfo** : dict
            Dictionary which includes information in relation to the
            ban.

class fail2ban.server.action.CallingMap(*args, **kwargs)

   Bases: "MutableMapping", "object"

   A Mapping type which returns the result of callable values.

   *CallingMap* behaves similar to a standard python dictionary, with
   the exception that any values which are callable, are called and
   the result is returned as the value. No error handling is in place,
   such that any errors raised in the callable will raised as usual.
   Actual dictionary is stored in property *data*, and can be accessed
   to obtain original callable values.

   Attributes:
      **data** : dict
         The dictionary data which can be accessed to obtain items
         uncalled

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "clear"()  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "get"(k[,d |                                                                                            |
   | ])         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "items"()  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "keys"()   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "pop"(k[,d | If key is not found, d is returned if given, otherwise KeyError is raised.                 |
   | ])         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "popitem"( | as a 2-tuple; but raise KeyError if D is empty.                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "setdefaul |                                                                                            |
   | t"(k[,d])  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "update"([ | If E present and has a .keys() method, does:     for k in E.keys(): D[k] = E[k] If E       |
   | E, ]**F)   | present and lacks .keys() method, does:     for (k, v) in E: D[k] = v In either case, this |
   |            | is followed by: for k, v in F.items(): D[k] = v                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "values"() |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   +----------------+------------+
   | **copy**       |            |
   +----------------+------------+
   | **getRawItem** |            |
   +----------------+------------+
   | **reset**      |            |
   +----------------+------------+

   CM_REPR_ITEMS = ()

   copy()

   data

   getRawItem(key)

   immutable

   reset(immutable=True)

   storage

class fail2ban.server.action.CommandAction(jail, name)

   Bases: "ActionBase"

   A action which executes OS shell commands.

   This is the default type of action which Fail2Ban uses.

   Default sets all commands for actions as empty string, such no
   command is executed.

   Parameters:
      **jail** : Jail
         The jail in which the action belongs to.

      **name** : str
         Name assigned to the action.

   Attributes:
      **actionban**
      **actioncheck**
      **actionreban**
      **actionreload**
      **actionrepair**
      **actionstart**
      **actionstop**
      **actionunban**
      **timeout**
   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "ban"(aInf | Executes the given command ("actionban" or "actionreban").                                 |
   | o[, cmd])  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "clearAllP | Clear all lists/dicts parameters (used by reloading)                                       |
   | arams"()   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "consisten | Executes the invariant check with repair if expected (conditional).                        |
   | cyCheck"([ |                                                                                            |
   | beforeRepa |                                                                                            |
   | ir])       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "escapeTag | Escape characters which may be used for command injection.                                 |
   | "(value)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "executeCm | Executes a command.                                                                        |
   | d"(realCmd |                                                                                            |
   | [,         |                                                                                            |
   | timeout])  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "flush"()  | Executes the "actionflush" command.                                                        |
   +------------+--------------------------------------------------------------------------------------------+
   | "invalidat | Increments ban epoch of jail and this action, so already banned tickets would cause a re-  |
   | eBanEpoch" | ban for all tickets with previous epoch.                                                   |
   | ()         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "prolong"( | Executes the "actionprolong" command.                                                      |
   | aInfo)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "reban"(aI | Executes the "actionreban" command if available, otherwise simply repeat "actionban".      |
   | nfo)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "reload"(* | Executes the "actionreload" command.                                                       |
   | *kwargs)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "replaceDy | Replaces dynamical tags in *query* with property values.                                   |
   | namicTags" |                                                                                            |
   | (realCmd,  |                                                                                            |
   | aInfo[, es |                                                                                            |
   | capeVal])  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "replaceTa | Replaces tags in *query* with property values.                                             |
   | g"(query,  |                                                                                            |
   | aInfo[, co |                                                                                            |
   | nditional, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start"()  | Executes the "actionstart" command.                                                        |
   +------------+--------------------------------------------------------------------------------------------+
   | "stop"()   | Executes the "actionstop" command.                                                         |
   +------------+--------------------------------------------------------------------------------------------+
   | "unban"(aI | Executes the "actionunban" command.                                                        |
   | nfo)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   ESCAPE_CRE = re.compile('[\\\\#&;`|*?~<>\\^\\(\\)\\[\\]{}$\'"\\n\\r]')

   ESCAPE_VN_CRE = re.compile('\\W')

   ban(aInfo, cmd='<actionban>')

      Executes the given command ("actionban" or "actionreban").

      Replaces the tags in the action command with actions properties
      and ban information, and executes the resulting command.

      Parameters:
         **aInfo** : dict
            Dictionary which includes information in relation to the
            ban.

   property banEpoch

   clearAllParams()

      Clear all lists/dicts parameters (used by reloading)

   consistencyCheck(beforeRepair=None)

      Executes the invariant check with repair if expected
      (conditional).

   classmethod escapeTag(value)

      Escape characters which may be used for command injection.

      Parameters:
         **value** : str
            A string of which characters will be escaped.

      Returns:
         str
            *value* with certain characters escaped.

      -[ Notes ]-

      The following characters are escaped:

         \#&;`|*?~<>^()[]{}$'"

   static executeCmd(realCmd, timeout=60, **kwargs)

      Executes a command.

      Parameters:
         **realCmd** : str
            The command to execute.

         **timeout** : int
            The time out in seconds for the command.

      Returns:
         bool
            True if the command succeeded.

      Raises:
         OSError
            If command fails to be executed.

         RuntimeError
            If command execution times out.

   flush()

      Executes the "actionflush" command.

      Command executed in order to flush all bans at once (e. g. by
      stop/shutdown  the system), instead of unbanning of each single
      ticket.

      Replaces the tags in the action command with actions properties
      and executes the resulting command.

   invalidateBanEpoch()

      Increments ban epoch of jail and this action, so already banned
      tickets would cause a re-ban for all tickets with previous
      epoch.

   prolong(aInfo)

      Executes the "actionprolong" command.

      Replaces the tags in the action command with actions properties
      and ban information, and executes the resulting command.

      Parameters:
         **aInfo** : dict
            Dictionary which includes information in relation to the
            ban.

   reban(aInfo)

      Executes the "actionreban" command if available, otherwise
      simply repeat "actionban".

      Replaces the tags in the action command with actions properties
      and ban information, and executes the resulting command.

      Parameters:
         **aInfo** : dict
            Dictionary which includes information in relation to the
            ban.

   reload(**kwargs)

      Executes the "actionreload" command.

      Parameters:
         **kwargs** : dict
            Currently unused, because CommandAction do not support
            initOpts

         **Replaces the tags in the action command with actions
         properties**
         **and executes the resulting command.**
   classmethod replaceDynamicTags(realCmd, aInfo, escapeVal=None)

      Replaces dynamical tags in *query* with property values.

      Parameters:
         **query** : str
            String with tags.

         **aInfo** : dict
            Tags(keys) and associated values for substitution in
            query.

      Returns:
         str
            shell script as string or array with tags replaced (direct
            or as variables).

   classmethod replaceTag(query, aInfo, conditional='', addrepl=None, cache=None)

      Replaces tags in *query* with property values.

      Parameters:
         **query** : str
            String with tags.

         **aInfo** : dict
            Tags(keys) and associated values for substitution in
            query.

      Returns:
         str
            *query* string with tags replaced.

   start()

      Executes the "actionstart" command.

      Replace the tags in the action command with actions properties
      and executes the resulting command.

   stop()

      Executes the "actionstop" command.

      Replaces the tags in the action command with actions properties
      and executes the resulting command.

   unban(aInfo)

      Executes the "actionunban" command.

      Replaces the tags in the action command with actions properties
      and ban information, and executes the resulting command.

      Parameters:
         **aInfo** : dict
            Dictionary which includes information in relation to the
            ban.
