README #1

			README FOR 'P4U'
			---------------

Introduction
------------

P4U is a Perforce command line client designed to facilitate the management
of Unix machines using Perforce. There are some files on Unix machines
(like /etc/shadow!) which must always have the correct access permissions.
The standard Perforce Command Line Client (P4) simply uses the unix user's
umask to decide what permissions the files it writes should have. This can
make it difficult to manage permission-sensitive files in Perforce.

Perforce 2004.2 allows you to define per-revision attributes on files and
P4U makes use of this functionality. When P4U writes a file into your
workspace, it checks to see if there's a 'unixMask' attribute on the
revision and uses that to exclude the unwanted permissions.

Status
------

P4U should be considered experimental software. The basic Perforce
functionality is taken from the Perforce C++ API so that is well proven. The
experimental part is the management of the file permissions using the 
unixMask file attribute. Since this requires individual handling for specific
Perforce commands, support may not yet be complete. As the license says, you
use it at your own risk.

Building P4U
------------

To build P4U you'll need:

a) The Perforce C++ API (2004.2 or later preferred) for your platform
	
	gcc3.x users please take care to choose an API build compiled with
	a gcc3 compiler. For Linux users, this means you should use the
	api tarballs from the bin.linux26x86 or bin.linux80x86 directories,
	NOT the bin.linux24x86.

b) A C++ compiler 

c) Jam

	http://public.perforce.com/public/jam/index.html


Step 1

    Build and install Jam.

Step 2

    Unpack the Perforce API

Step 3

    Build P4U:

    	jam -sP4=<path to the Perforce API>

    Should work for most people. If not, you may need to set the OSVER
    Jam variable if you're building for a specific version of an OS. i.e.

    	jam -sP4=<path to the Perforce API> -sOSVER=26

    would be correct for Solaris 2.6. The operating systems and their
    versions are all in the Jamrules file supplied with the Perforce API.

Using P4U
---------

Just add the unixMask attribute to the files you want protected and after
you've submitted the files will have the correct permission.

For example:

	p4u add /etc/shadow
	p4u attribute -n unixMask -v 077 /etc/shadow
	p4u submit

Note, to prevent you from forgetting to type 'p4u' instead of 'p4', it's a
good idea to alias p4=p4u for the relevant user (root?).

A word or two on security
-------------------------

1. Perforce is not secure. Perforce Software Inc. make no claim that it is.
   So if you're doing this, you should take reasonable steps to secure access
   to both the Perforce depot files and the Perforce service itself. Using
   the little documented rsh: value for P4PORT in your environment may be
   what you want. i.e.

   	P4PORT="rsh:ssh p4host p4d -r /var/p4root -i"

   This will remove the need to have your Perforce server listening on a PORT
   at the cost of performance: a new SSH session is started for each command
   so there might be a significant cost.


2. There's little point in using this tool to lock down the permissions on 
   sensitive files if you then take no steps to prevent anyone from looking
   at the Perforce repository files where they are stored. Please consider
   your whole environment when you plan to use P4U.


3. Use a P4CONFIG file in /, but make sure its own file permissions are
   strictly controlled.

4. 'p4 login' allows you to avoid the need to put your password in the 
   P4CONFIG file. Use it, but protect the ticket file (.p4tickets). It should
   be protected by default, but check it.

5. You may want to put your root user in a group with a short ticket timeout
   to prevent overly long-lived tickets being created.


License
-------

Copyright (c) 2004, Perforce Software, Inc.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1.  Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

2.  Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL PERFORCE SOFTWARE, INC. BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.