<!-- $Id: mod_time.html,v 1.4 2002/03/27 22:46:41 tj Exp tj $ --> <!-- $Source: /home/tj/proftpd/modules/doc/RCS/mod_time.html,v $ --> <html> <head> <title>ProFTPD module mod_time</title> </head> <body bgcolor=white> <hr><br> <center> <h2><b>ProFTPD module <code>mod_time</code></b></h2> </center> <hr><br> This module is contained in the <code>mod_time.c</code> file, found <a href="http://www.castaglia.org/proftpd/">here</a>, for ProFTPD 1.2.x, and is not compiled by default. Installation instructions can be found <a href="#Installation">here</a>. <p> This module is designed to allow for limiting FTP commands based on the time of day and/or the day of the week. A more detailed explanation of the <a href="#Usage">usage</a> of this module follows the directive explanations. <p> The most current version of <code>mod_time</code> can be found at: <pre> <a href="http://www.castaglia.org/proftpd/">http://www.castaglia.org/proftpd/</a> </pre> <h2>Author</h2> <p> Please contact TJ Saunders <tj <i>at</i> castaglia.org> with any questions, concerns, or suggestions regarding this module. <h2>Thanks</h2> <p> <i>2001-09-28</i>: Thanks to Ian Marsh <ian.marsh <i>at</i> hants.gov.uk> for helping to debug by supplying platform details for a bug causing segfaults. <h2>Directives</h2> <ul> <li><a href="#ClassCommandTimes">ClassCommandTimes</a> <li><a href="#CommandTimes">CommandTimes</a> <li><a href="#DisplayAfterHours">DisplayAfterHours</a> <li><a href="#GroupCommandTimes">GroupCommandTimes</a> <li><a href="#NamedTime">NamedTime</a> <li><a href="#UserCommandTimes">UserCommandTimes</a> </ul> <hr> <h2><a name="ClassCommandTimes">ClassCommandTimes</a></h2> <strong>Syntax:</strong> ClassCommandTimes <em>class-expression|* command-expression named-times</em><br> <strong>Default:</strong> None<br> <strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code>, <code><Directory></code>, .ftpaccess<br> <strong>Module:</strong> mod_time<br> <strong>Compatibility:</strong> 1.2.2 and later <p> This directive applies a comma-delimited list of <code>NamedTime</code>s, in their given order, to any of the commands in <em>command-expression</em>, for the users belonging to classes given by <em>class-expression</em>. Any of the listed FTP commands from those users that do not occur with the <code>NamedTime</code>s' time limits will be denied. <p> A <em>class-expression</em> of "*" will match any class. <p> The <em>command-expression</em> may be composed of a comma-delimited list of FTP commands to be restricted by time, as well as the meta-command groups of <code><Limit></code>, such as <code>DIRS</code>, <code>READ</code>, <code>WRITE</code>, <code>LOGIN</code>, and <code>ALL</code>. An additional meta-command group, <code>NONE</code>, is available for configuring no restrictions, to be used to relax restrictions imposed by other <code>mod_time</code> directives. <p> See also: <a href="#CommandTimes">CommandTimes</a>, <a href="#GroupCommandTimes">GroupCommandTimes</a>, <a href="#NamedTime">NamedTime</a>, <a href="#UserCommandTimes">UserCommandTimes</a> <p> <hr> <h2><a name="CommandTimes">CommandTimes</a></h2> <strong>Syntax:</strong> CommandTimes <em>command-expression named-times</em><br> <strong>Default:</strong> None<br> <strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code>, <code><Directory></code><br> <strong>Module:</strong> mod_time<br> <strong>Compatibility:</strong></a> 1.2.2 and later <p> This directive applies a comma-delimited list of <code>NamedTime</code>s, in their given order, to any of the commands in <em>command-expression</em>, for the users belonging to classes given by <em>class-expression</em>. Any of the listed FTP commands from those users that do not occur with the <code>NamedTime</code>s' time limits will be denied. <p> The <em>command-expression</em> may be composed of a comma-delimited list of FTP commands to be restricted by time, as well as the meta-command groups of <code><Limit></code>, such as <code>DIRS</code>, <code>READ</code>, <code>WRITE</code>, <code>LOGIN</code>, and <code>ALL</code>. An additional meta-command group, <code>NONE</code>, is available for configuring no restrictions, to be used to relax restrictions imposed by other <code>mod_time</code> directives. <p> See also: <a href="#ClassCommandTimes">ClassCommandTimes</a>, <a href="#GroupCommandTimes">GroupCommandTimes</a>, <a href="#NamedTime">NamedTime</a>, <a href="#UserCommandTimes">UserCommandTimes</a> <p> <hr> <h2><a name="DisplayAfterHours">DisplayAfterHours</a></h2> <strong>Syntax:</strong> DisplayAfterHours <em>filename</em><br> <strong>Default:</strong> None<br> <strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code><br> <strong>Module:</strong> mod_time<br> <strong>Compatibility:</strong></a> 1.2.2 and later <p> The <code>DisplayAfterHours</code> directive configures an ASCII text filename which will be displayed to the user should they issue a command that is restricted by a time limit, and the command occurs outside the allowed time limits. <p> <code>DisplayAfterHours</code> supports most of the same "magic cookies" as the <code>DisplayFirstChdir</code> directive, as well as one "magic cookie" specific to <code>mod_time</code>: <pre> %c Current FTP command </pre> <p> See Also: <a href="http://www.proftpd.org/docs/configuration.html#DisplayFirstChdir">DisplayFirstChdir</a> <p> <hr> <h2><a name="GroupCommandTimes">GroupCommandTimes</a></h2> <strong>Syntax:</strong> GroupCommandTimes <em>group-expression|* command-expression named-times</em><br> <strong>Default:</strong> None<br> <strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code>, <code><Directory></code>, .ftpaccess<br> <strong>Module:</strong> mod_time<br> <strong>Compatibility:</strong></a> 1.2.2 and later <p> This directive applies a comma-delimited list of <code>NamedTime</code>s, in their given order, to any of the commands in <em>command-expression</em>, for the users belonging to classes given by <em>class-expression</em>. Any of the listed FTP commands from those users that do not occur with the <code>NamedTime</code>s' time limits will be denied. <p> A <em>group-expression</em> of "*" will match any group. <p> The <em>command-expression</em> may be composed of a comma-delimited list of FTP commands to be restricted by time, as well as the meta-command groups of <code><Limit></code>, such as <code>DIRS</code>, <code>READ</code>, <code>WRITE</code>, <code>LOGIN</code>, and <code>ALL</code>. An additional meta-command group, <code>NONE</code>, is available for configuring no restrictions, to be used to relax restrictions imposed by other <code>mod_time</code> directives. <p> See also: <a href="#ClassCommandTimes">ClassCommandTimes</a>, <a href="#CommandTimes">CommandTimes</a>, <a href="#NamedTime">NamedTime</a>, <a href="#UserCommandTimes">UserCommandTimes</a> <p> <hr> <h2><a name="NamedTime">NamedTime</a></h2> <strong>Syntax:</strong> NamedTime <em>nickname [!]hours [!]days|*</em><br> <strong>Default:</strong> None<br> <strong>Context:</strong> server config<br> <strong>Module:</strong> mod_time<br> <strong>Compatibility:</strong></a> 1.2.2 and later <p> The <em>nickname</em> parameter is used by the other <code>mod_time</code> directives, as part of their <em>named-time</em> parameters, when looking for applicable <code>NamedTime</code>s, and is case-sensitive. <p> The <em>hours</em> argument must be formatted like this: <code>hh:mm:ss-hh:mm:ss</code>. Two digits are required for each number; single numbers such as 5 would need to appear as <code>05</code>. All times are given according to a 24-hour clock. An <em>hours</em> parameter prefixed with a <code>!</code> means every time <i>except</i> that range specified by the parameter. <p> As per <code>crontab(5)</code> entries, the days of the week are given in integers, in the following manner: Sunday is the first day of the week (0, and 7) through Saturday (6). As with the <em>hours</em> parameter, a <em>days</em> parameter prefixed with a <code>!</code> means all days <i>except</i> the given days. The <em>days</em> parameter must be formatted as a range, <i>e.g.</i> <code>1-6</code>, or as a list of specific days, <i>e.g.</i> <code>0,3,4,5</code>. A range and a list may occur in the same parameter, <i>e.g.</i> <code>1-4,6</code>. A value of * is shorthand for "all days". <p> <hr> <h2><a name="UserCommandTimes">UserCommandTimes</a></h2> <strong>Syntax:</strong> UserCommandTimes <em>user-expression|* command-expression named-times</em><br> <strong>Default:</strong> None<br> <strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code>, <code><Directory></code>, .ftpaccess<br> <strong>Module:</strong> mod_time<br> <strong>Compatibility:</strong></a> 1.2.2 and later <p> This directive applies a comma-delimited list of <code>NamedTime</code>s, in their given order, to any of the commands in <em>command-expression</em>, for the users belonging to classes given by <em>class-expression</em>. Any of the listed FTP commands from those users that do not occur with the <code>NamedTime</code>s' time limits will be denied. <p> A <em>user-expression</em> of "*" will match any user. <p> The <em>command-expression</em> may be composed of a comma-delimited list of FTP commands to be restricted by time, as well as the meta-command groups of <code><Limit></code>, such as <code>DIRS</code>, <code>READ</code>, <code>WRITE</code>, <code>LOGIN</code>, and <code>ALL</code>. An additional meta-command group, <code>NONE</code>, is available for configuring no restrictions, to be used to relax restrictions imposed by other <code>mod_time</code> directives. <p> See also: <a href="#ClassCommandTimes">ClassCommandTimes</a>, <a href="#CommandTimes">CommandTimes</a>, <a href="#GroupCommandTimes">GroupCommandTimes</a> <a href="#NamedTime">NamedTime</a>, <p> <hr><br> <p> <h2><a name="Usage">Usage</a></h2> <p> To use <code>mod_time</code>'s functionality, you must first define some time limits using the <code>NamedTime</code> directive. These <code>NamedTime</code>s are the building blocks for the rest of <code>mod_time</code>'s directives. <p> For example, to define a <code>NamedTime</code> for "normal business hours", you would use a directive like this: <pre> NamedTime normal-hours 08:00:00-17:00:00 1-5 </pre> which creates a <code>NamedTime</code> called "normal-hours" that is applicable from 8 AM to 5 PM, Monday through Friday. <p> Conversely, if you wanted a <code>NamedTime</code> for everything <i>outside</i> of these normal hours, you could use something like this: <pre> NamedTime after-hours !08:00:00-17:00:00 0,6 </pre> After defining your <code>NamedTime</code>s, you then use the <code>UserCommandTimes</code>, <code>GroupCommandTimes</code>, <code>ClassCommandTimes</code>, and <code>CommandTimes</code> configuration directives to apply those times to FTP commands, for the given user, group, class, or to everyone. <p> To apply your "normal business hours" to everyone, use this: <pre> CommandTimes ALL normal-hours </pre> However, if you want to allow user <code>friend</code> to do anything at any time, but still restrict everyone else, you would use these directives, in addition to the above <code>CommandTime</code>s directive: <pre> NamedTime all-hours 00:00:00-23:59:59 * UserCommandTimes friend ALL all-hours </pre> or, without the use of an "all-hours" <code>NamedTime</code>: <pre> UserCommandTimes friend NONE normal-hours </pre> When searching for <code>NamedTime</code>s that apply to a given connection, the limits are <b>always</b> searched in this order: <pre> UserCommandTimes GroupCommandTimes ClassCommandTimes CommandTimes </pre> Thus the time restrictions for user <code>friend</code> would be found and used first while everyone else would see the global restriction. <p> If, for example, you wanted to use multiple <code>NamedTime</code>s to apply to some commands, you can chain them together in a comma-delimited list, like so: <pre> NamedTime morning-hours 07:00:00-11:00:00 * NamedTime evening-hours 16:00:00-20:00:00 * GroupCommandTimes timed-group1,timed-group2 READ morning-hours,evening-hours </pre> This will allow users that appear either in <i>timed-group1</i> or <i>timed-group2</i> to download files during the 4-hour windows of the morning or evening <code>NamedTime</code>s. <p> When an FTP command is denied, a message will be returned to the client. If no <code>DisplayAfterHours</code> directive is in effect, <code>mod_time</code> will then check for a configured <code>AccessDenyMsg</code>, and use that if present. If neither of these two directives is applicable, a default "%c is not allowed at this time" will be returned to the client, where <code>%c</code> expands to the FTP command issued. <p> A special note about the <em>user-expression</em>s, <em>group-expression</em>s, and <em>class-expression</em>s used by <code>mod_time</code> configuration directives: they are <b>not</b> like other proftpd expressions, which are Boolean AND expressions -- <code>mod_time</code> expressions are Boolean OR expressions. Some might chide me for not following the pattern already used by current directives and for seeding possible confusion. However, I felt that the use of OR expressions to be so useful, particularly in the case of <em>user-</em> and <em>class-expression</em>s, as to outweight the potential confusion. Briefly, for the normal AND expressions to evaluate to true, every component must be true; for <em>user-</em> and <em>class-expression</em>s, this does not make much sense, as a logged in user can logically only belong to one user, one class. Using OR expressions, <i>any</i> component that is true will cause the expression to be true. This means that you need to be careful with those <code>!user</code>, <code>!group</code> or <code>!class</code> components, for any user that is not the given user, or is not a member of the given group, or is not classified in the given class, will match. <p> This modules honors the <code>TimesGMT</code>, <code>AccessDenyMsg</code>, and <code>UserAlias</code> configuration directives. <p> <hr><br> <p> <hr><br> <h2><a name="Installation">Installation</a></h2> To install <code>mod_time</code>, copy the <code>mod_time.c</code> file into <pre> <i>proftpd-dir</i>/contrib/ </pre> after unpacking the latest proftpd-1.2 source code. Then follow the usual steps for using third-party modules in proftpd: <pre> ./configure --with-modules=mod_time make make install </pre> Author: <i>$Author: tj $</i><br> Last Updated: <i>$Date: 2002/03/27 22:46:41 $</i><br> <br><hr> <font size=2><b><i> © Copyright 2000-2002 TJ Saunders<br> All Rights Reserved<br> </i></b></font> <hr><br> </body> </html>
