granicus.if.org Git - linux-pam/blob - doc/modules/pam_time.sgml

   1 <!--
   2    $Id$
   3
   4    This file was written by Andrew G. Morgan <morgan@kernel.org>
   5 -->
   6
   7 <sect1>Time control
   8
   9 <sect2>Synopsis
  10
  11 <p>
  12 <descrip>
  13
  14 <tag><bf>Module Name:</bf></tag>
  15 <tt/pam_time/
  16
  17 <tag><bf>Author:</bf></tag>
  18 Andrew G. Morgan <tt>&lt;morgan@kernel.org&gt;</tt>
  19
  20 <tag><bf>Maintainer:</bf></tag>
  21 Author
  22
  23 <tag><bf>Management groups provided:</bf></tag>
  24 account
  25
  26 <tag><bf>Cryptographically sensitive:</bf></tag>
  27
  28 <tag><bf>Security rating:</bf></tag>
  29
  30 <tag><bf>Clean code base:</bf></tag>
  31
  32 <tag><bf>System dependencies:</bf></tag>
  33 Requires a configuration file <tt>/etc/security/time.conf</tt>
  34
  35 <tag><bf>Network aware:</bf></tag>
  36 Through the <tt/PAM_TTY/ item only
  37
  38 </descrip>
  39
  40 <sect2>Overview of module
  41
  42 <p>
  43 Running a well regulated system occasionally involves restricting
  44 access to certain services in a selective manner.  This module offers
  45 some time control for access to services offered by a system.  Its
  46 actions are determined with a configuration file.  This module can be
  47 configured to deny access to (individual) users based on their name,
  48 the time of day, the day of week, the service they are applying for
  49 and their terminal from which they are making their request.
  50
  51 <sect2>Account component
  52
  53 <p>
  54 <descrip>
  55
  56 <tag><bf>Recognized arguments:</bf></tag>
  57
  58 <tag><bf>Description:</bf></tag>
  59
  60 This module bases its actions on the rules listed in its configuration
  61 file: <tt>/etc/security/time.conf</tt>.  Each rule has the following
  62 form,
  63 <tscreen>
  64 <em/services/<tt/;/<em/ttys/<tt/;/<em/users/<tt/;/<em/times/
  65 </tscreen>
  66 In words, each rule occupies a line, terminated with a newline or the
  67 beginning of a comment; a `<tt/#/'.  It contains four fields separated
  68 with semicolons, `<tt/;/'. The fields are as follows:
  69
  70 <p>
  71 <itemize>
  72 <item><em/services/ -
  73 a logic list of service names that are affected by this rule.
  74
  75 <item><em/ttys/ -
  76 a logic list of terminal names indicating those terminals covered by
  77 the rule.
  78
  79 <item><em/user/ -
  80 a logic list of usernames to which this rule applies
  81
  82 <p>
  83 By a logic list we mean a sequence of tokens (associated with the
  84 appropriate <tt/PAM_/ item), containing no more than one wildcard
  85 character; `<tt/*/', and optionally prefixed with a negation operator;
  86 `<tt/!/'. Such a sequence is concatenated with one of two logical
  87 operators: <tt/&amp;/ (logical AND) and <tt/|/ (logical OR).  Two
  88 examples are: <tt>!morgan&amp;!root</tt>, indicating that this rule
  89 does not apply to the user <tt>morgan</tt> nor to <tt>root</tt>; and
  90 <tt>tty*&amp;!ttyp*</tt>, which indicates that the rule applies only
  91 to console terminals but not pseudoterminals.
  92
  93 <item><em/times/ - a logic list of times at which this rule
  94 applies. The format of each element is a day/time-range. The days are
  95 specified by a sequence of two character entries.  For example,
  96 <tt/MoTuSa/, indicates Monday Tuesday and Saturday.  Note that
  97 repeated days are <em/unset/; <tt/MoTuMo/ indicates Tuesday, and
  98 <tt/MoWk/ means all weekdays bar Monday.  The two character
  99 combinations accepted are,
 100 <tscreen>
 101 <verb>
 102 Mo Tu We Th Fr Sa Su Wk Wd Al
 103 </verb>
 104 </tscreen>
 105 The last two of these being <em/weekend/ days and <em/all 7 days/ of
 106 the week respectively.
 107
 108 <p>
 109 The time range part is a pair of 24-hour times, <em/HHMM/, separated
 110 by a hyphen -- indicating the start and finish time for the rule.  If
 111 the finsish time is smaller than the start time, it is assumed to
 112 apply on the following day. For an example, <tt/Mo1800-0300/ indicates
 113 that the permitted times are Monday night from 6pm to 3am the
 114 following morning.
 115
 116 </itemize>
 117
 118 <p>
 119 Note, that the given time restriction is only applied when the first
 120 three fields are satisfied by a user's application for service.
 121
 122 <p>
 123 For convenience and readability a rule can be extended beyond a single
 124 line with a `<tt>&bsol;</tt><em/newline/'.
 125
 126 <tag><bf>Examples/suggested usage:</bf></tag>
 127
 128 The use of this module is initiated with an entry in the
 129 <bf/Linux-PAM/ configuration file of the following type:
 130 <tscreen>
 131 <verb>
 132 #
 133 # apply pam_time accounting to login requests
 134 #
 135 login   account  required       pam_time.so
 136 </verb>
 137 </tscreen>
 138 where, here we are applying the module to the <em/login/ application.
 139
 140 <p>
 141 Some examples of rules that can be placed in the
 142 <tt>/etc/security/time.conf</tt> configuration file are the following:
 143 <descrip>
 144
 145 <tag><tt>login ; tty* &amp; !ttyp* ; !root ; !Al0000-2400</tt></tag>
 146 all users except for <tt/root/ are denied access to console-login at
 147 all times.
 148
 149 <tag><tt>games ; * ; !waster ; Wd0000-2400 | Wk1800-0800</tt></tag>
 150 games (configured to use Linux-PAM) are only to be accessed out of
 151 working hours.  This rule does not apply to the user <tt/waster/.
 152
 153 </descrip>
 154
 155 <p>
 156 Note, currently there is no daemon enforcing the end of a session.
 157 This needs to be remedied.
 158
 159 <p>
 160 Poorly formatted rules are logged as errors using <tt/syslog(3)/.
 161
 162 </descrip>
 163
 164 <!--
 165 End of sgml insert for this module.
 166 -->