
fail2ban.server.actions module
******************************

class class fail2ban.server.actions.Actions(jail)

   Bases: "fail2ban.server.jailthread.JailThread", "_abcoll.Mapping"

   Handles jail actions.

   This class handles the actions of the jail. Creation, deletion or
   to actions must be done through this class. This class is based on
   the Mapping type, and the *add* method must be used to add new
   actions. This class also starts and stops the actions, and fetches
   bans from the jail executing these bans via the actions.

   Parameters:
      **jail: Jail**

         The jail of which the actions belongs to.

   -[ Attributes ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "daemon"   | A boolean value indicating whether this thread is a daemon thread (True) or not (False).   |
   +------------+--------------------------------------------------------------------------------------------+
   | "ident"    | Thread identifier of this thread or None if it has not been started.                       |
   +------------+--------------------------------------------------------------------------------------------+
   | "name"     | A string used for identification purposes only.                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "status"(  | Status of current and total ban counts and current banned IP list.                         |
   | [flavor])  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   +-----------+---------------------------------------------------+
   | active    | (bool) Control the state of the thread.           |
   +-----------+---------------------------------------------------+
   | idle      | (bool) Control the idle state of the thread.      |
   +-----------+---------------------------------------------------+
   | sleeptime | (int) The time the thread sleeps for in the loop. |
   +-----------+---------------------------------------------------+

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "add"(nam  | Adds a new action.                                                                         |
   | e[, pytho  |                                                                                            |
   | nModule,   |                                                                                            |
   | initOpts]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "get"((k[  |                                                                                            |
   | ,d]) ->    |                                                                                            |
   | D[k] if k  |                                                                                            |
   | in D, ...) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "getBanTi  |                                                                                            |
   | me"()      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "getName"  |                                                                                            |
   | ()         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "isAlive"  | Return whether the thread is alive.                                                        |
   | ()         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "isDaemon  |                                                                                            |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "is_alive  | Return whether the thread is alive.                                                        |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "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"(...)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "join"([t  | Wait until the thread terminates.                                                          |
   | imeout])   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "keys"(()  |                                                                                            |
   | -> list of |                                                                                            |
   | D's keys)  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "removeBa  | Removes banned IP calling actions' unban method                                            |
   | nnedIP"(i  |                                                                                            |
   | p)         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "run"()    | Main loop for Threading.                                                                   |
   +------------+--------------------------------------------------------------------------------------------+
   | "setBanTi  |                                                                                            |
   | me"(value) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "setDaemo  |                                                                                            |
   | n"(daemon  |                                                                                            |
   | ic)        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "setName"  |                                                                                            |
   | (name)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start"()  | Sets active flag and starts thread.                                                        |
   +------------+--------------------------------------------------------------------------------------------+
   | "status"(  | Status of current and total ban counts and current banned IP list.                         |
   | [flavor])  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "stop"()   | Sets *active* property to False, to flag run method to return.                             |
   +------------+--------------------------------------------------------------------------------------------+
   | "values"(  |                                                                                            |
   | () -> list |                                                                                            |
   | of D's     |                                                                                            |
   | values)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   add(name, pythonModule=None, initOpts=None)

      Adds a new action.

      Add a new action if not already present, defaulting to standard
      *CommandAction*, or specified Python module.

      Parameters:
         **name** : str

            The name of the action.

         **pythonModule** : str, optional

            Path to Python file which must contain *Action* class.
            Default None, which means *CommandAction* is used.

         **initOpts** : dict, optional

            Options for Python Action, used as keyword arguments for
            initialisation. Default None.

      Raises:
         **ValueError**

            If action name already exists.

         **RuntimeError**

            If external Python module does not have *Action* class or
            does not implement necessary methods as per *ActionBase*
            abstract class.

   daemon

      A boolean value indicating whether this thread is a daemon
      thread (True) or not (False).

      This must be set before start() is called, otherwise
      RuntimeError is raised. Its initial value is inherited from the
      creating thread; the main thread is not a daemon thread and
      therefore all threads created in the main thread default to
      daemon = False.

      The entire Python program exits when no alive non-daemon threads
      are left.

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

   getBanTime()

   getName()

   ident

      Thread identifier of this thread or None if it has not been
      started.

      This is a nonzero integer. See the thread.get_ident() function.
      Thread identifiers may be recycled when a thread exits and
      another thread is created. The identifier is available even
      after the thread has exited.

   isAlive()

      Return whether the thread is alive.

      This method returns True just before the run() method starts
      until just after the run() method terminates. The module
      function enumerate() returns a list of all alive threads.

   isDaemon()

   is_alive()

      Return whether the thread is alive.

      This method returns True just before the run() method starts
      until just after the run() method terminates. The module
      function enumerate() returns a list of all alive threads.

   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

   join(timeout=None)

      Wait until the thread terminates.

      This blocks the calling thread until the thread whose join()
      method is called terminates -- either normally or through an
      unhandled exception or until the optional timeout occurs.

      When the timeout argument is present and not None, it should be
      a floating point number specifying a timeout for the operation
      in seconds (or fractions thereof). As join() always returns
      None, you must call isAlive() after join() to decide whether a
      timeout happened -- if the thread is still alive, the join()
      call timed out.

      When the timeout argument is not present or None, the operation
      will block until the thread terminates.

      A thread can be join()ed many times.

      join() raises a RuntimeError if an attempt is made to join the
      current thread as that would cause a deadlock. It is also an
      error to join() a thread before it has been started and attempts
      to do so raises the same exception.

   keys() -> list of D's keys

   name

      A string used for identification purposes only.

      It has no semantics. Multiple threads may be given the same
      name. The initial name is set by the constructor.

   removeBannedIP(ip)

      Removes banned IP calling actions' unban method

      Remove a banned IP now, rather than waiting for it to expire,
      even if set to never expire.

      Parameters:
         **ip** : str

            The IP address to unban

      Raises:
         **ValueError**

            If *ip* is not banned

   run()

      Main loop for Threading.

      This function is the main loop of the thread. It checks the jail
      queue and executes commands when an IP address is banned.

      Returns:
         bool

            True when the thread exits nicely.

   setBanTime(value)

   setDaemon(daemonic)

   setName(name)

   start()

      Sets active flag and starts thread.

   status(flavor='basic')

      Status of current and total ban counts and current banned IP
      list.

   stop()

      Sets *active* property to False, to flag run method to return.

   values() -> list of D's values
