From 00456b8270aed2a0c1c2433f19c676ef52fe938d Mon Sep 17 00:00:00 2001
From: sebres <serg.brester@sebres.de>
Date: Tue, 11 Jul 2017 14:00:15 +0200
Subject: [PATCH] review: documentation, small enhancement of `fail2ban-client`
 to test time abbreviation format:

fail2ban-client --str2sec 1d12h30m
---
 fail2ban/client/fail2bancmdline.py       |  7 ++++-
 fail2ban/tests/fail2banclienttestcase.py |  3 ++
 man/jail.conf.5                          | 36 ++++++++++++++++++++++--
 3 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/fail2ban/client/fail2bancmdline.py b/fail2ban/client/fail2bancmdline.py
index 3a3cedcd..f213d037 100644
--- a/fail2ban/client/fail2bancmdline.py
+++ b/fail2ban/client/fail2bancmdline.py
@@ -111,6 +111,7 @@ class Fail2banCmdLine():
 		output("    -f                      start server in foreground")
 		output("    --async                 start server in async mode (for internal usage only, don't read configuration)")
 		output("    --timeout               timeout to wait for the server (for internal usage only, don't read configuration)")
+		output("    --str2sec <STRING>      convert time abbreviation format to seconds")
 		output("    -h, --help              display this help message")
 		output("    -V, --version           print the version")
 
@@ -158,6 +159,10 @@ class Fail2banCmdLine():
 			elif o == "--timeout":
 				from ..server.mytime import MyTime
 				self._conf["timeout"] = MyTime.str2seconds(opt[1])
+			elif o == "--str2sec":
+				from ..server.mytime import MyTime
+				output(MyTime.str2seconds(opt[1]))
+				return True
 			elif o in ["-h", "--help"]:
 				self.dispUsage()
 				return True
@@ -179,7 +184,7 @@ class Fail2banCmdLine():
 			# Reads the command line options.
 			try:
 				cmdOpts = 'hc:s:p:xfbdtviqV'
-				cmdLongOpts = ['loglevel=', 'logtarget=', 'syslogsocket=', 'test', 'async', 'timeout=', 'help', 'version']
+				cmdLongOpts = ['loglevel=', 'logtarget=', 'syslogsocket=', 'test', 'async', 'timeout=', 'str2sec=', 'help', 'version']
 				optList, self._args = getopt.getopt(self._argv[1:], cmdOpts, cmdLongOpts)
 			except getopt.GetoptError:
 				self.dispUsage()
diff --git a/fail2ban/tests/fail2banclienttestcase.py b/fail2ban/tests/fail2banclienttestcase.py
index 3e046042..caacf63c 100644
--- a/fail2ban/tests/fail2banclienttestcase.py
+++ b/fail2ban/tests/fail2banclienttestcase.py
@@ -416,6 +416,9 @@ class Fail2banClientTest(Fail2banClientServerBase):
 		self.pruneLog()
 		self.execSuccess((), "-vq", "-V")
 		self.assertLogged("Fail2Ban v" + fail2bancmdline.version)
+		self.pruneLog()
+		self.execSuccess((), "--str2sec", "1d12h30m")
+		self.assertLogged("131400")
 
 	@with_tmpdir
 	def testClientDump(self, tmp):
diff --git a/man/jail.conf.5 b/man/jail.conf.5
index a43346e1..a8afe53c 100644
--- a/man/jail.conf.5
+++ b/man/jail.conf.5
@@ -231,10 +231,10 @@ IP will not be banned if command returns successfully (exit code 0).
 Like ACTION FILES, tags like <ip> are can be included in the ignorecommand value and will be substituted before execution. Currently only <ip> is supported however more will be added later.
 .TP
 .B bantime
-effective ban duration (in seconds).
+effective ban duration (in seconds or time abbreviation format).
 .TP
 .B findtime
-time interval (in seconds) before the current time where failures will count towards a ban.
+time interval (in seconds or time abbreviation format) before the current time where failures will count towards a ban.
 .TP
 .B maxretry
 number of failures that have to occur in the last \fBfindtime\fR seconds to ban then IP.
@@ -278,6 +278,38 @@ action = smtp.py[dest=chris@example.com, actname=smtp-chris]
          smtp.py[dest=sally@example.com, actname=smtp-sally]
 .fi
 
+.SH "TIME ABBREVIATION FORMAT"
+The time entries in fail2ban configuration (like \fBfindtime\fR or \fBbantime\fR) can be provided as integer in seconds or as string using special abbreviation format (e. g. \fB600\fR is the same as \fB10m\fR).
+
+.TP
+.B Abbreviation tokens:
+
+.RS
+.nf
+years?, yea?, yy?
+months?, mon?
+weeks?, wee?, ww?
+days?, da, dd?
+hours?, hou?, hh?
+minutes?, min?, mm?
+seconds?, sec?, ss?
+
+The question mark (?) means the optional character, so \fBday\fR as well as \fBdays\fR can be used.
+.fi
+.RE
+
+You can combine multiple tokens in format (separated with space resp. without separator), e. g.: \fB1y 6mo\fR or \fB1d12h30m\fR.
+.br
+Note that tokens \fBm\fR as well as \fBmm\fR means minutes, for month use abbreviation \fBmo\fR or \fBmon\fR.
+
+The time format can be tested using \fBfail2ban-client\fR:
+
+.RS
+.nf
+fail2ban-client --str2sec 1d12h
+.fi
+.RE
+
 .SH "ACTION CONFIGURATION FILES (\fIaction.d/*.conf\fB)"
 Action files specify which commands are executed to ban and unban an IP address.