fail2ban.server.database module
*******************************

class fail2ban.server.database.Fail2BanDb(filename, purgeAge=86400, outDatedFactor=3)

   Bases: "object"

   Fail2Ban database for storing persistent data.

   This allows after Fail2Ban is restarted to reinstated bans and to
   continue monitoring logs from the same point.

   This will either create a new Fail2Ban database, connect to an
   existing, and if applicable upgrade the schema in the process.

   Parameters:
      **filename** : str
         File name for SQLite3 database, which will be created if
         doesn't already exist.

      **purgeAge** : int
         Purge age in seconds, used to remove old bans from database
         during purge.

   Attributes:
      "filename"
         File name of SQLite3 database file.

      "purgeage"
         Purge age in seconds.

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "addBan"(c | Add a ban to the database.                                                                 |
   | ur, jail,  |                                                                                            |
   | ticket)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "addJail"( | Adds a jail to the database.                                                               |
   | cur, jail) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "addLog"(c | Adds a log to the database.                                                                |
   | ur, jail,  |                                                                                            |
   | container) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "delAllJai | Deletes all jails from the database.                                                       |
   | ls"(cur)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "delBan"(c | Delete a single or multiple tickets from the database.                                     |
   | ur, jail,  |                                                                                            |
   | *args)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "delJail"( | Deletes a jail from the database.                                                          |
   | cur, jail) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "getBans"( | Get bans from the database.                                                                |
   | **kwargs)  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "getBansMe | Get bans from the database, merged into single ticket.                                     |
   | rged"([ip, |                                                                                            |
   | jail,      |                                                                                            |
   | bantime])  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "getCurren | Reads tickets (with merged info) currently affected from ban from the database.            |
   | tBans"([ja |                                                                                            |
   | il, ip, fo |                                                                                            |
   | rbantime,  |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "getJailNa | Get name of jails in database.                                                             |
   | mes"(cur[, |                                                                                            |
   | enabled])  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "getJourna | Get journal position from database.                                                        |
   | lPos"(cur, |                                                                                            |
   | jail,      |                                                                                            |
   | name[,     |                                                                                            |
   | time,      |                                                                                            |
   | iso])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "getLogPat | Gets all the log paths from the database.                                                  |
   | hs"(cur[,  |                                                                                            |
   | jail])     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "purge"(cu | Purge old bans, jails and log files from database.                                         |
   | r)         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "updateDb" | Update an existing database, called during initialisation.                                 |
   | (cur,      |                                                                                            |
   | version)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "updateJou | Updates last position (as time) of journal.                                                |
   | rnal"(cur, |                                                                                            |
   | jail,      |                                                                                            |
   | name,      |                                                                                            |
   | time, iso) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "updateLog | Updates hash and last position in log file.                                                |
   | "(cur,     |                                                                                            |
   | jail,      |                                                                                            |
   | container) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   +--------------+------------+
   | **close**    |            |
   +--------------+------------+
   | **createDb** |            |
   +--------------+------------+
   | **getBan**   |            |
   +--------------+------------+
   | **repairDB** |            |
   +--------------+------------+

   Raises:
      sqlite3.OperationalError
         Error connecting/creating a SQLite3 database.

      RuntimeError
         If exisiting database fails to update to new schema.

   addBan(cur, jail, ticket)

      Add a ban to the database.

      Parameters:
         **jail** : Jail
            Jail in which the ban has occurred.

         **ticket** : BanTicket
            Ticket of the ban to be added.

   addJail(cur, jail)

      Adds a jail to the database.

      Parameters:
         **jail** : Jail
            Jail to be added to the database.

   addLog(cur, jail, container)

      Adds a log to the database.

      Parameters:
         **jail** : Jail
            Jail that log is being monitored by.

         **container** : FileContainer
            File container of the log file being added.

      Returns:
         int
            If log was already present in database, value of last
            position in the log file; else *None*

   close()

   createDb(cur, incremental=False)

   delAllJails(cur)

      Deletes all jails from the database.

   delBan(cur, jail, *args)

      Delete a single or multiple tickets from the database.

      Parameters:
         **jail** : Jail
            Jail in which the ticket(s) should be removed.

         **args** : list of IP
            IPs to be removed, if not given all tickets of jail will
            be removed.

   delJail(cur, jail)

      Deletes a jail from the database.

      Parameters:
         **jail** : Jail
            Jail to be removed from the database.

   property filename

      File name of SQLite3 database file.

   getBan(cur, ip, jail=None, forbantime=None, overalljails=None, fromtime=None)

   getBans(**kwargs)

      Get bans from the database.

      Parameters:
         **jail** : Jail
            Jail that the ban belongs to. Default *None*; all jails.

         **bantime** : int
            Ban time in seconds, such that bans returned would still
            be valid now.  Negative values are equivalent to *None*.
            Default *None*; no limit.

         **ip** : str
            IP Address to filter bans by. Default *None*; all IPs.

      Returns:
         list
            List of >>`<<Ticket`s for bans stored in database.

   getBansMerged(ip=None, jail=None, bantime=None)

      Get bans from the database, merged into single ticket.

      This is the same as *getBans*, but bans merged into single
      ticket.

      Parameters:
         **jail** : Jail
            Jail that the ban belongs to. Default *None*; all jails.

         **bantime** : int
            Ban time in seconds, such that bans returned would still
            be valid now. Negative values are equivalent to *None*.
            Default *None*; no limit.

         **ip** : str
            IP Address to filter bans by. Default *None*; all IPs.

      Returns:
         list or Ticket
            Single ticket representing bans stored in database per IP
            in a list. When *ip* argument passed, a single *Ticket* is
            returned.

   getCurrentBans(jail=None, ip=None, forbantime=None, fromtime=None, correctBanTime=True, maxmatches=None)

      Reads tickets (with merged info) currently affected from ban
      from the database.

      There are all the tickets corresponding parameters jail/ip,
      forbantime, fromtime (normally now).

      If correctBanTime specified (default True) it will fix the
      restored ban-time  (and therefore endOfBan) of the ticket
      (normally it is ban-time of jail as maximum) for all tickets
      with ban-time greater (or persistent).

   getJailNames(cur, enabled=None)

      Get name of jails in database.

      Currently only used for testing purposes.

      Returns:
         set
            Set of jail names.

   getJournalPos(cur, jail, name, time=0, iso=None)

      Get journal position from database.

      Parameters:
         **jail** : Jail
            Jail of which the journal belongs to.

         **name, time, iso**
            Journal name (typically systemd-journal) and last known
            time.

      Returns:
         int (or float)
            Last position (as time) if it was already present in
            database; else *None*

   getLogPaths(cur, jail=None)

      Gets all the log paths from the database.

      Currently only for testing purposes.

      Parameters:
         **jail** : Jail
            If specified, will only reutrn logs belonging to the jail.

      Returns:
         set
            Set of log paths.

   purge(cur)

      Purge old bans, jails and log files from database.

   property purgeage

      Purge age in seconds.

   repairDB()

   updateDb(cur, version)

      Update an existing database, called during initialisation.

      A timestamped backup is also created prior to attempting the
      update.

   updateJournal(cur, jail, name, time, iso)

      Updates last position (as time) of journal.

      Parameters:
         **jail** : Jail
            Jail of which the journal belongs to.

         **name, time, iso**
            Journal name (typically systemd-journal) and last known
            time.

   updateLog(cur, jail, container)

      Updates hash and last position in log file.

      Parameters:
         **jail** : Jail
            Jail of which the log file belongs to.

         **container** : FileContainer
            File container of the log file being updated.

fail2ban.server.database.commitandrollback(f)
