File	Date	Author	Commit
Makefile	2012-10-08	jared	[b28e33] Initial commit
README	2012-10-13	jared	[9ca1e8] Updates to add readme instructions, add Upstart...
pam-duration.c	2012-10-08	jared	[b28e33] Initial commit
sample_duration.conf	2012-10-08	jared	[982865] Add sample configuration file for user orientat...
user-logger.conf	2012-10-13	jared	[9ca1e8] Updates to add readme instructions, add Upstart...
user_logger.py	2012-10-08	jared	[b28e33] Initial commit

Read Me

Background
===========

This project was born out of frustration that no similar project appears to
exist. pam_duration provides a way to limit the number of minutes a given user
is allowed to access a system on a given day of the week.  This is mostly
useful for parental control.

For example, suppose I have three kids: a fifteen year old, a ten year old,
and a five year old.  The fifteen year old needs access to the computer to work
on school reports and homework during the week, up to two hours per day, and is
allowed up to two hours per day on the weekend.  The ten year old needs access
to the computer to do homework during the week, but his homework requires much
less time on the computer, so he is granted one hour per day during the week.
He is granted 45 minutes per day on the weekend. The five year old gets half an
hour per day, any day of the week.

Existing PAM modules do not answer this need.  pam_duration provides a way to
do it.  So far it has only been tested on Ubuntu 12.04, since that's what I
run.

Related Work
-------------

There is a PAM module that restricts the hours of the day that users can log
in.  For example, it can specify that a user is allowed to log in between the
hours of 8 am and 5 pm.  It doesn't, however, provide a way to limit how much
time the user can spend logged in during those hours.

There is another project, Timekpr, that used to do the same thing this module
does, but timekpr has not been updated for some time, and is not very portable.
Specifically, it does not work with versions of Ubuntu that use the lightdm
login manager. The duration-limiting functions of timekpr also don't integrate
into the most prevalent authorization framework for Posix systems: PAM.

While pam_duration is not yet as user-friendly as Timekpr (for instance, it
does not yet provide notifications to the window manager that the user is about
to be logged off, and there is no GUI to configure how long users can log in on
what days), it should operate on many more systems. This program should run on
any POSIX system that supports PAM and has a Python 2.7 interpreter.


Code state
===========
pam_duration is functional, but unpolished. It needs work in the following
areas:

* Code to daemonize the python task-watching/killing service on startup on
  other Linux/Unix distributions. This will undoubtedly be OS/distribution
  dependent. An upstart script is provided.

* Smoother installation process: installing default config file if one doesn't
  already exist, creating directories, putting the shared object file in the
  right place for 32-bit systems, etc.

* More flexible installation locations for the config file and user time
  tracking logs. Right now the locations are pretty hard-coded.

* Messaging protocol to communicate with GUI clients to allow users warning
  that they're about to be shut down without the right to protest.

Minimum Requirements
=====================

For this project to work for you, you will need to have PAM installed and a
functional Python installation.  The user-task watcher/killer is written in
Python 2.7.  To build the system, you will need gcc installed.

Building
=========

Please read through all of the build instructions before beginning the build.

To build this on an Ubuntu system, you will need to install the libpam0g
development libarary:

$ sudo apt-get install libpam0g-dev

If you don't already have gcc installed, run the following:

$ sudo apt-get install build-essential

Then navigate to the directory where you unpacked the files and execute the
following:

$ sudo make install

This will do three things:
1. Build the PAM module
2. Install the PAM module
3. Add an Upstart job to start the user-task watcher/killer

If your operating system does not use Upstart (known distributions that do
are Ubuntu 11.10 and 12.04, and Red Hat Enterprise Linux 6), you will need to
tailor the Makefile to remove the last two commands under the "install" target.
It is possible to create a SysVInit script to start the user-logger.  I'm
looking for people who use a non-Upstart distribution to contribute scripts to
do it.

Configuration
==============

After installation, to make the system work, you need to do the following:

Add a line to /etc/pam.d/common_account. Above the "account ... pam_unix.so"
line, add the following line:

account required pam_duration.so

Add a file called /etc/security/duration.conf.  There is a sample configuration
file in the package, called sample_duration.conf.  The syntax of the file is
simple.  Each line describes access limitations for a single user, in the
following format:

username:Sunday:Monday:Tuesday:Wednesday:Thursday:Friday:Saturday

The username is the username for the user as it appears in /etc/passwd. Each of
the other fields is the duration in minutes that the user is allowed to be
logged in on that day.  Take the line below as an example:

bob:10:1441:120:120:30:1200:1441

The user bob is allowed to log in for 10 minutes on Sunday, all day on Monday,
for two hours on Tuesday and Wednesday, twenty hours on Friday, and all day
Saturday. Any value over 1440 [not inclusive] will prevent the process watcher
from killing the user's process.)

Assuming that the user names of the kids described in the Background are mary,
david, and chris, a complete configuration file would be:

mary:120:120:120:120:120:120:120
david:45:60:60:60:60:60:45
chris:30:30:30:30:30:30:30

If a username does not appear in the configuration file, it is assumed that the
user has no time limits.

It is a bad idea to put the root user or system accounts in this file.  You
have been warned.