From bde70ebc003e2afffc44a0f0ba2223730f85f356 Mon Sep 17 00:00:00 2001 From: Cyril Jaquier Date: Wed, 7 Mar 2007 20:54:32 +0000 Subject: [PATCH] - Added more comments git-svn-id: https://fail2ban.svn.sourceforge.net/svnroot/fail2ban/trunk@556 a942ae1a-1317-0410-a47c-b1dcaea8d605 --- server/action.py | 88 +++++++++++++++++++++++++++++++++++++++++++++++ server/actions.py | 23 +++++++++++++ server/mytime.py | 26 ++++++++++++++ 3 files changed, 137 insertions(+) diff --git a/server/action.py b/server/action.py index f7b5458e..10dfd479 100644 --- a/server/action.py +++ b/server/action.py @@ -54,18 +54,48 @@ class Action: self.__actionStop = '' logSys.debug("Created Action") + ## + # Sets the action name. + # + # @param name the name of the action + def setName(self, name): self.__name = name + ## + # Returns the action name. + # + # @return the name of the action + def getName(self): return self.__name + ## + # Sets a "CInfo". + # + # CInfo are statically defined properties. They can be definied by + # the user and are used to set e-mail addresses, port, host or + # anything that should not change during the life of the server. + # + # @param key the property name + # @param value the property value + def setCInfo(self, key, value): self.__cInfo[key] = value + ## + # Returns a "CInfo". + # + # @param key the property name + def getCInfo(self, key): return self.__cInfo[key] + ## + # Removes a "CInfo". + # + # @param key the property name + def delCInfo(self, key): del self.__cInfo[key] @@ -86,6 +116,14 @@ class Action: def getActionStart(self): return self.__actionStart + ## + # Executes the action "start" command. + # + # Replaces the tags in the action command with value of "cInfo" + # and executes the resulting command. + # + # @return True if the command succeeded + def execActionStart(self): startCmd = Action.replaceTag(self.__actionStart, self.__cInfo) return Action.executeCmd(startCmd) @@ -107,6 +145,11 @@ class Action: def getActionBan(self): return self.__actionBan + ## + # Executes the action "ban" command. + # + # @return True if the command succeeded + def execActionBan(self, aInfo): return self.__processCmd(self.__actionBan, aInfo) @@ -127,6 +170,11 @@ class Action: def getActionUnban(self): return self.__actionUnban + ## + # Executes the action "unban" command. + # + # @return True if the command succeeded + def execActionUnban(self, aInfo): return self.__processCmd(self.__actionUnban, aInfo) @@ -164,10 +212,25 @@ class Action: def getActionStop(self): return self.__actionStop + ## + # Executes the action "stop" command. + # + # Replaces the tags in the action command with value of "cInfo" + # and executes the resulting command. + # + # @return True if the command succeeded + def execActionStop(self): stopCmd = Action.replaceTag(self.__actionStop, self.__cInfo) return Action.executeCmd(stopCmd) + ## + # Replaces tags in query with property values in aInfo. + # + # @param query the query string with tags + # @param aInfo the properties + # @return a string + @staticmethod def replaceTag(query, aInfo): """ Replace tags in query @@ -179,6 +242,19 @@ class Action: string = string.replace("
", '\n') return string + ## + # Executes a command with preliminary checks and substitutions. + # + # Before executing any commands, executes the "check" command first + # in order to check if prerequirements are met. If this check fails, + # it tries to restore a sane environnement before executing the real + # command. + # Replaces "aInfo" and "cInfo" in the query too. + # + # @param cmd The command to execute + # @param aInfo Dynamic properties + # @return True if the command succeeded + def __processCmd(self, cmd, aInfo = None): """ Executes an OS command. """ @@ -209,6 +285,18 @@ class Action: return Action.executeCmd(realCmd) + ## + # Executes a command. + # + # We need a shell here because commands are mainly shell script. They + # contain pipe, redirection, etc. + # + # @todo Force the use of bash!? + # @todo Kill the command after a given timeout + # + # @param realCmd the command to execute + # @return True if the command succeeded + @staticmethod def executeCmd(realCmd): logSys.debug(realCmd) diff --git a/server/actions.py b/server/actions.py index a18d2f4f..a332a46c 100644 --- a/server/actions.py +++ b/server/actions.py @@ -56,22 +56,45 @@ class Actions(JailThread): ## The ban manager. self.__banManager = BanManager() + ## + # Adds an action. + # + # @param name The action name + def addAction(self, name): action = Action(name) self.__actions.append(action) + ## + # Removes an action. + # + # @param name The action name + def delAction(self, name): for action in self.__actions: if action.getName() == name: self.__actions.remove(action) break + ## + # Returns an action. + # + # Raises a KeyError exception if the action does not exist. + # + # @param name the action name + # @return the action + def getAction(self, name): for action in self.__actions: if action.getName() == name: return action raise KeyError + ## + # Returns the last defined action. + # + # @return The last defined action. + def getLastAction(self): action = self.__actions.pop() self.__actions.append(action) diff --git a/server/mytime.py b/server/mytime.py index 57fee41e..2b7dfd0a 100644 --- a/server/mytime.py +++ b/server/mytime.py @@ -26,14 +26,35 @@ __license__ = "GPL" import time +## +# MyTime class. +# +# This class is a wrapper around time.time() and time.gmtime(). When +# performing unit test, it is very useful to get a fixed value from these +# functions. +# Thus, time.time() and time.gmtime() should never be called directly. +# This wrapper should be called instead. The API are equivalent. + class MyTime: myTime = None + ## + # Sets the current time. + # + # Use None in order to always get the real current time. + # + # @param t the time to set or None + @staticmethod def setTime(t): MyTime.myTime = t + ## + # Equivalent to time.time() + # + # @return time.time() if setTime was called with None + @staticmethod def time(): if MyTime.myTime == None: @@ -41,6 +62,11 @@ class MyTime: else: return MyTime.myTime + ## + # Equivalent to time.gmtime() + # + # @return time.gmtime() if setTime was called with None + @staticmethod def gmtime(): if MyTime.myTime == None: