ip_restrict Plugin
==================

Version: 0.1
Author: Jonathan Angliss <jon@squirrelmail.org>

Installing
----------
Please see INSTALL for basic installation instructions.

Information
-----------
This plugin is fairly easy to use.  The format is very simple, and it
takes but a few minutes to read the documentation and understand the examples.
Please take time to read through the documentation thoroughly before asking
questions.

Please also remember this plugin is a basic protection, and is nothing
compared to using strong passwords, firewall policies, and good security
practices.

License
-------
This package is covered by the GNU General Public License unless explicitly 
stated otherwise.

Configuring
-----------
ip_restrict supports a vast range of options to restrict user logins to a set
ip address, or network.  All these restrictions should be placed in
restrict.php.  The file must start with:

<?php
/*

And the file must end with

*/
?>

If you define more than one restriction for a user or group of users, the
LAST ONE found in restrict.php is the one that will be used.  However,
if a user account is covered by both a restriction defined for that
user AND a restriction for a group that the user falls within, the
most restrictive of the two will be used.  See the section on "Multiple Users"
for an example.


Restricting a user to a certain IP
----------------------------------
To restrict a user to a certain IP address, you use the format:

  username=ip
  
For a simple example, we want to restrict the user "admin" to a dedicated
computer with the IP 192.168.0.2.  The example follows like this:

  admin=192.168.0.2

  
Restricting a user to multiple IP addresses
-------------------------------------------
In a larger example, you might want to restrict your "admin" user to be limited
to logins from multiple computers, for example 192.168.0.2 and the additional
computer 192.168.0.3.  This can be accomplished by using the following format:

  username=ip1|ip2
  
For our example, the format would be:

  admin=192.168.0.2|192.168.0.3
  
This can be extending to contain multiple IP addresses by using the | (pipe)
symbol.


Restricting a user to a specific network
----------------------------------------
Sometimes it's not feasible to type in all the possible IP addresses you wish
to restrict a user to.  For example, in a corporate network, we might want to
restrict the "admin" login to only allow logins from within the corporate
network which uses the address 192.168.0.0 with a network mask of 255.255.255.0
This is cam also be denoted as 192.168.0.0/24 (CIDR Notation).  You can get more
details on subnets, and CIDR notations on http://en.wikipedia.org/wiki/Subnetwork.

To continue our example, we want to restrict the "admin" user login access to
the corporate network 192.168.0.0/24.  The format for this is:

  username=network/cidr
  
Or it can also be denoted as:

  username=network/mask
  
Using our admin and corporate network as an example, the configuration would be:

  admin=192.168.0.0/24
  
Or using the mask format:

  admin=192.168.0.0/255.255.255.0
  


Restricting a user to multiple networks
---------------------------------------
As with hosts, networks can be combined using the | symbol.  Keeping with our
admin example, we might have decided to allow a dedicated "noc" network also
have access to the "admin" account.  They are using a different subnet of
10.10.10.0/24.  The format for this would be:

  username=network/cidr|network/cidr
  
As with a specific network, this can be mixed with the network mask, so you can
also use the format:

  username=network/mask|network/cidr|network/mask

Using our "admin" user, and the corporate network, we can see this can be used
like so:

  admin=192.168.0.0/24|10.10.10.0/24
  

Restrict a user to a single network, and additional host
--------------------------------------------------------
There might be a time you want to restrict a user to the internal network, and
their home address to allow them access from home without special equipment.
This is a case of mixing hosts and networks, and works the same as multiple
networks by using the | symbol.  For exmaple, our "admin" user has a static
IP address for their home connection of 24.24.24.2, and needs access from the
corporate network.  The format would be:

  username=ip|network/cidr
  
For example:

  username=24.24.24.2|192.168.0.0/24
  
  
Unrestricting a user completely
-------------------------------
There may be a time where you want to allow a user access from anywhere in the world.
This can occur if you have an important executive that likes to travel and read his
email from Hawaii (lucky exec).  This can be achieved using the wildcard "0".  For 
example, our executive uses the login "salesmaster", the format would be:

  username=0
  
Using our "salesmaster" as an example:

  salesmaster=0


Restricting a user completely
-----------------------------
There may also be times you want to completely disallow a user access.  This can be
achieved by not specifying an IP address at all.  For example:

  username=
  
This will block access entirely.  Using out admin as an example:

  admin=
  
  
Multiple Users
--------------
The above examples are all fine for restricting a single user, but on a standard
IMAP server, there could be hundreds of users.  This makes managing the restrictions
difficult.  It's also quite possible that you really don't need to restrict all the
users to specific networks, or you only need to restrict special accounts (admin,
root, master, etc) to certain networks.  This is where the * username comes into play.
The format is like all the above examples, you just replace username with a *.  For
example:

  *=0
  
This unrestricts all users to all networks.  Combined with the example above of
restricting our admin user to the corporate network, our restrict.php file may look
like this:

  admin=192.168.0.0/24
  *=0
  
You can also restrict all users to a certain network by using any of the above formats,
for example:

  *=192.168.0.0/24
  
The above would restrict all users to the corporate network in our example.


Email as usernames
------------------
This plugin can handle full email addresses as the username if that is what is required.
If you rely on the vlogin plugin to handle the transformation of a simple username to a
complete username based on the login domain, you must ensure the vlogin plugin is loaded
BEFORE the ip_restrict plugin.


Mixed case usernames
--------------------
Some IMAP servers support the use of mixed case usernames to mean different users.  This
is highly unusual and prone to some errors somewhere along the lines, however the 
ip_restrict plugin is case sensitive, and respects your SquirrelMail settings.  If you
enable the force_username_lowercase option, the ip_restrict plugin will work in lowercase
so the configuration file can be configured to use all lowercase.


Other possible plugin issues
----------------------------
Due to the vast number of plugins, it is quite difficult to test the possible issues that
might be available if other plugins are enabled.  The vlogin plugin may causes issues in
regards to changing the username (see the section "Email as usernames"), however, work
has been done with the vlogin author to try and work around this issue. The adjustments
for the vlogin plugin require you to be using vlogin 3.8.1 or higher. Earlier versions
of the vlogin plugin will need to be included before the ip_restrict plugin. With 
that in mind, there may be other plugins that might cause issues, such as the login_auto 
plugin.  If you are having issues with a specific plugin enabled, please notify me so 
I am able to test and devise a workaround or fix for the issue.


Other Questions, Bugs, Security Issues
--------------------------------------
If you have any other questions, you can address them to jon@squirrelmail.org, or see
me on irc://irc.freenode.net/#squirrelmail as Valcor or jangliss.
