The trustees project is an advanced linux permission system inspired by Netware.

Copyright (C) V.L. Zavadsky, 1999-2000
Copyright (C) Andrew Ruder,  2004 (aeruder@ksu.edu)

Current Maintainer:
	Andrew Ruder <aeruder@ksu.edu>

======
Table of Contents
======

I.   Introduction
II.  Installation
III. Configuration
IV.  Usage
V.   Known Issues/Bugs/"Features"

======
I. Introduction
======

Trustees is an advanced linux permission system inspired by Netware.  It
allows a system administrator to attach "trustees" to any directory or file.
All subdirectories and files in that directory will also inherit these 
trustees.  Trustee rights can be overridden or added to in subsequent
directories.

Why not use POSIX ACLs?  POSIX ACLs are useful, but require intricate scripts
to maintain some sort of recursive ACL scheme.  Furthermore, the tools to just
analyze which ACLs are set where are also equally intricate.  ACLs are designed
for fine-grained access control.  For example, on my system, giving a user
write access to all files and directories in usr would require over 140,000
acls to be set.  Furthermore, how do you check that all these ACLs are what
you intended them to be?  Quite frankly, you can't.  Enter trustees.  Specify 
your full system's rights in one small config file and know that your controls 
on access are what you intended them to be.

======
II. Installation
======

the kernel module

	-=THIS STEP IS UNNECESSARY IF YOU USED THE KERNEL PATCH=-
	If you would like to use a kernel patch, please see the patches/ directory.
	Go to your linux source code, apply the patch (patch -p1 < /path/to/diff)
	and configure your kernel with Security => Trustees enabled.  This will 
	even allow you to build trustees into your kernel! If your kernel version
	is not listed in the patches/ directory, feel free to go ahead and try 
	applying anyways; most of the time the patches apply just fine between
	kernel releases (esp. minor releases, the 2.6.11 patch should more than
	likely work on any 2.6.11.x release).

	The included module can be compiled for any 2.6.x kernel. CONFIG_SECURITY,
	however, must be compiled in.  Assuming this is so, simply enter the
	module/ directory and type

	make install

	For non-typical situations, the makefile may not be able to find your
	kernel source directory.  If you have problems, try compiling with

	make KDIR=/path/to/src/linux-2.6.x install

the settrustees tool

	Simple enter the src/ directory and type make.  This will build the
	settrustees tool.

======
III. Configuration
======

The default location for the config file should be /etc/trustees.conf
This is where the settrustees code will look at by default.  (You can use
the -f option to override).  The config file should have one input per line.
The syntax of the input is described below.

There are two classes of inputs.  There is a device flags input and trustees
input.  

device flags
	The first class, device flags, is specified like this:

*[/block/device]flags
*{/network/share}flags

	This is used to tell the trustees kernel module certain information about a
	device.  For example, this is used to specify a case-insensitive
	filesystem.  If the trustees kernel module doesn't know that a filesystem
	is case-insensitive, it may give different rights to //smb/share/DIR1 than
	it gives to //smb/share/dir1 even though they are the same directory.

	Available device flags:
	I
		Designate a filesystem as being case-insensitive.

trustees
	The second class of input, trustees, are specified like this:
	
[/block/device]/any/path:usr1:flags:+grp1:flags...
{/network/share}/any/path:+grp2:flags:*:flags...
	
	The path should be the real path, no symlinks.  usr1/grp2/usr2/grp1 should
	be any user/group names.  The preceding '+' distinguishes a group from a 
	user.  A * designates that it should apply to all users.  The flags 
	describe the access that the preceding user/group should receive. 
	Any number of user:flag or group:flag can be specified on a line.

	Also, this path should be relative to the device.  If /home is on its
	own device, and you want a rule to apply to /home/andy, you would use
	
		[/block/device]/andy:...

	and NOT
	
		[/block/device]/home/andy:...
	
	Flag modifiers are also available which can be used to clear a flag
	on a certain directory or to deny access instead of allowing access.

	This is how the permissions are calculated on a file called:
	   /path/file1
	First, two sets of flags are initialized: the allow flags and the
	deny flags.  The allow flags are initialized to [U] (use normal unix
	access) and the deny flags are initialized to [].  
	
	Then the allow/deny flags are gathered for /.  The flags here are or'd with
	the appropriate default flags.  So if / gave everybody RWEBX the allow
	flags would be [URWEBX] and the deny flags would still be [].  If
	everybody's flags were instead DRWBX the allow flags would be [U] and the
	deny flags would be [RWBX].  And lastly, if everybody was set to CU the
	allow flags would be [] and the deny flags would be [].
	
	Then the rights are looked up for /path.  The flags here are once again
	or'd/cleared into the appropriate allow/deny flags as shown above.

	When it has calculated the full allow/deny masks the algorithm is as
	such:  
	
	1. If superuser, permission granted.
	2. If any mode requested is in the deny flag, the request is denied.
	3. If the allow mode specifies [U], the unix permissions are calculated
	   and if they grant access, access is granted.
	4. If all modes are in the allow flag, access is granted.
	5. Permission denied.
	
	The following flags are available:
	R 
		Read any files
	W
		Write files and directories
	B   
		Browse (like UNIX execute for directories)
	E
		rEad directories
	X
		eXecute files
	U
		use UNIX permissions - set by default

	The following flag modifiers can also be specified along with the flags:
	C
		Clear the permissions (instead of set them)
	D
		Deny access (instead of grant)
	! 
		The trustee object applies to all except user or group
	O 
		One level. The trustee object applies to the given directory and files
		therein, but not to subdirectories.

Blank lines in the configuration file will be ignored as well as those that
begin with the character '#'

======
IV. Usage 
======

First, you should load the kernel module.  modprobe trustees.ko should do the
trick.

For the settrustees program to communicate with the kernel module a virtual
filesystem must be mounted.

mount -t trusteesfs none /some/place/to/mount

This filesystem will have a file called 'trustees' which is the file actually
used to communicate directly with the kernel module.  This is referred to as
the 'trustees device'.  Other files available in the filesystem may be
available to check status of the trustees module, statistics, or to turn
debugging messages on.

Now we use settrustees to load the config file into the kernel module.  
	/path/to/settrustees -f /path/to/config
It should automatically parse /etc/mtab and find where the trusteesfs is
mounted.  If not, use the -t option to specify the 'trustees device'.

Please note that in order to unload the kernel module, the virtual filesystem
must first be unmounted.

======
V. Known Issues/Bugs/"Features"
======

* No ACLs

  POSIX ACLs are not in any way supported by trustees.  If you use them,
  they will be ignored while trustees is loaded.  Sorry, folks,
  you either use trustees or you don't use trustees.

* Hard links

  The trustees module has to take some precautions against a file existing
  with more than one name.  The problem is that if full RWEXB access is 
  given to /tmp, some user joe could make a hardlink of /etc/passwd into
  /tmp and have full access to it!  That is bad!

  The trustees module can do nothing against cross-directory hard links that
  exist prior it to it loading, but while it is loading it attempts to stop
  their creation.

  Basically, if a hard link is requested of a file to another place in the
  same directory, it is allowed.  If an application tries to make a 
  inter-directory hard link, it will receive an error code indicating that
  the two locations are not on the same device. 

  Similarly, a file that has a hard link count of 2 or more cannot be moved
  out of a directory.  If a file is requested to be moved out of a directory,
  a return code is given that indicates that the two locations are on different
  devices.  Programs such as mv and others should compensate and perform a copy
  instead.

* Case insensitivity
  
  Due to lack of intelligence or effort or something, case insensitivity is
  implemented as referring to all files internally as being lowercase.  The
  lowercasing function does not take into account locale.  But assuming you
  aren't specifing trustees to directories with strange non-C-locale
  capital/lowercase characters, it shouldn't affect anything.  For example,
  don't specify a trustee to a directory with a capital umlauted 'O' and expect
  the trustees module to work nicely with it.

  This only applies to directories you are actually specifying in your
  trustees.conf.  If you have strange characters in your file/directory names
  that is fine, but you won't be able to specifically mention them in your
  trustees.conf file.  (They will still inherit trustee permissions correctly.)

