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

class 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.

   -[ Notes ]-

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

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "ban"(aIn  | Executed when a ban occurs.                                                                |
   | fo)        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start"()  | Executed when the jail/action is started.                                                  |
   +------------+--------------------------------------------------------------------------------------------+
   | "stop"()   | Executed when the jail/action is stopped.                                                  |
   +------------+--------------------------------------------------------------------------------------------+
   | "unban"(a  | Executed when a ban expires.                                                               |
   | Info)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   ban(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 class fail2ban.server.action.CallingMap(*args, **kwargs)

   Bases: "_abcoll.MutableMapping"

   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"(() |                                                                                            |
   | -> None.   |                                                                                            |
   | Remove all |                                                                                            |
   | items from |                                                                                            |
   | D.)        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "copy"()   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "get"((k[  |                                                                                            |
   | ,d]) ->    |                                                                                            |
   | D[k] if k  |                                                                                            |
   | in D, ...) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "items"(() |                                                                                            |
   | -> list of |                                                                                            |
   | D's (key,  |                                                                                            |
   | value)     |                                                                                            |
   | pairs,     |                                                                                            |
   | ...)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "iteritem  |                                                                                            |
   | s"(() ->   |                                                                                            |
   | an         |                                                                                            |
   | iterator   |                                                                                            |
   | over the   |                                                                                            |
   | (key, ...) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "iterkeys  |                                                                                            |
   | "(() -> an |                                                                                            |
   | iterator   |                                                                                            |
   | over the   |                                                                                            |
   | keys of D) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "itervalu  |                                                                                            |
   | es"(...)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "keys"(()  |                                                                                            |
   | -> list of |                                                                                            |
   | D's keys)  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "pop"((k[  | If key is not found, d is returned if given, otherwise KeyError is raised.                 |
   | ,d]) -> v, |                                                                                            |
   | ...)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "popitem"  | as a 2-tuple; but raise KeyError if D is empty.                                            |
   | (() -> (k, |                                                                                            |
   | v), ...)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "setdefau  |                                                                                            |
   | lt"((k[,d  |                                                                                            |
   | ]) -> D.g  |                                                                                            |
   | et(k,d),   |                                                                                            |
   | ...)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "update"(  | If E present and has a .keys() method, does:     for k in E: D[k] = E[k]                   |
   | ([E, ...)  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "values"(  |                                                                                            |
   | () -> list |                                                                                            |
   | of D's     |                                                                                            |
   | values)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   clear() -> None.  Remove all items from D.

   copy()

   get(k[, d]) -> D[k] if k in D, else d.  d defaults to None.

   items() -> list of D's (key, value) pairs, as 2-tuples

   iteritems() -> an iterator over the (key, value) items of D

   iterkeys() -> an iterator over the keys of D

   itervalues() -> an iterator over the values of D

   keys() -> list of D's keys

   pop(k[, d]) -> v, remove specified key and return the corresponding value.

      If key is not found, d is returned if given, otherwise KeyError
      is raised.

   popitem() -> (k, v), remove and return some (key, value) pair

      as a 2-tuple; but raise KeyError if D is empty.

   setdefault(k[, d]) -> D.get(k,d), also set D[k]=d if k not in D

   update([E], **F) -> None.  Update D from mapping/iterable E and F.

      If E present and has a .keys() method, does:     for k in E:
      D[k] = E[k] If E 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() -> list of D's values

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

   Bases: "fail2ban.server.action.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 ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "actionba  | The command used when a ban occurs.                                                        |
   | n"         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "actionst  | The command executed on start of the jail/action.                                          |
   | art"       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "actionst  | The command executed when the jail/actions stops.                                          |
   | op"        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "actionun  | The command used when an unban occurs.                                                     |
   | ban"       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "timeout"  | Time out period in seconds for execution of commands.                                      |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "ban"(aIn  | Executes the "actionban" command.                                                          |
   | fo)        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "escapeTa  | Escape characters which may be used for command injection.                                 |
   | g"(value)  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "executeC  | Executes a command.                                                                        |
   | md"(realC  |                                                                                            |
   | md[,       |                                                                                            |
   | timeout])  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "replaceT  | Replaces tags in *query* with property values.                                             |
   | ag"(query, |                                                                                            |
   | aInfo)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start"()  | Executes the "actionstart" command.                                                        |
   +------------+--------------------------------------------------------------------------------------------+
   | "stop"()   | Executes the "actionstop" command.                                                         |
   +------------+--------------------------------------------------------------------------------------------+
   | "substitu  | Sort out tag definitions within other tags.                                                |
   | teRecursi  |                                                                                            |
   | veTags"(t  |                                                                                            |
   | ags)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "unban"(a  | Executes the "actionunban" command.                                                        |
   | Info)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   actionban

      The command used when a ban occurs.

   actioncheck

      The command used to check the environment.

      This is used prior to a ban taking place to ensure the
      environment is appropriate. If this check fails, *stop* and
      *start* is executed prior to the check being called again.

   actionstart

      The command executed on start of the jail/action.

   actionstop

      The command executed when the jail/actions stops.

   actionunban

      The command used when an unban occurs.

   ban(aInfo)

      Executes the "actionban" 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.

   static 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)

      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.

   classmethod replaceTag(query, aInfo)

      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.

   classmethod substituteRecursiveTags(tags)

      Sort out tag definitions within other tags. Since v.0.9.2
      supports embedded interpolation (see test cases for examples).

      so:             becomes: a = 3           a = 3 b = <a>_3       b
      = 3_3

      Parameters:
         **tags** : dict

            Dictionary of tags(keys) and their values.

      Returns:
         dict

            Dictionary of tags(keys) and their values, with tags
            within the values recursively replaced.

   timeout

      Time out period in seconds for execution of commands.

   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.
