
   Portslave 2000+   Russell Coker <russell@coker.com.au>

1. DISCLAIMER.

  There is no warranty of any kind. Please see the LICENSE file for
  additional information.

2. INTRODUCTION.

  This is the Portslave RADIUS client. RADIUS (Remote Authentication
  Dial-In User Service), simply put allows you to authenticate logins from
  a central RADIUS server without having to keep user account information
  on multiple machines. As the name states RADIUS is primarily used in
  terminal servers (aka RAS: Remote Auth Servers) for logging in dial in modem
  users. Portslave can 'answer the line' and act as the RADIUS client for this
  as well as other Unix services such as telnet and secure shell (ssh).
  

3. RADIUS
 
  You will need at least one RADIUS server on one of your systems. The
  best RADIUS server is FreeRadius.
 
  You *need* a working RADIUS server first, and you have to understand
  how it works before you can continue.
 
  Note that if you want to offer shell-logins you need an updated dictionary
  file with the "Shell-User" entry (such as the default for FreeRadius). Use
  "Login-Service = Shell-User" to let a user use an account on the local
  machine. BTW, the official new name for this is actually
  "Administrative-User".


4. BUILDING THE SOFTWARE.

How to compile pppd and rlogin.

This version supports pppd versions 2.4.0 and 2.4.1.

The ./configure script by default will look in the parent directory for the
most recent (according to an alpha-numeric sort) file matching "../ppp*gz".

Alternatively you can run "./configure --enable-pppdir=ppp-2.4.0" to specify
the old version.

The ./configure script will create makefiles that take the name of the archive
without the ".tar.gz" or ".tgz" extension as the name of the directory that it
will be extracted to.

Then it will extract the archive as part of the build process and compile the
files it contains.  Then it will apply patches from the patches/ppp-version
directory.

The reason for this is to support multiple versions of pppd without the need
to include the source to any version of the pppd in the archive.  Also
eventually I hope to do away with the need for a hacked pppd.


5. INSTALLING THE SOFTWARE.

  If you use the default paths, you need to install the next files:

  pslave.conf			/etc/portslave/pslave.conf
  pslave.conf.5			/usr/local/man/man5/pslave.conf.5
  src/portslave			/usr/local/sbin/portslave
  portslave.8			/usr/local/man/man8/portslave.8
  src/ctlportslave		/usr/local/sbin/ctlportslave
  ctlportslave.1		/usr/local/man/man1/ctlportslave.1
  libpsr/libpsr.so		/usr/local/lib/libpsr.so
  ppp-2.4.1/pppd/pppd		/usr/local/sbin/pppd-radius

  You can use the provided "install.sh" script to do this for you.
  ("make install" also works, it calls the "install.sh" script).
  It's usually safer to just move all files by hand.
  
  Notice that the Portslave RADIUS specific pppd and binary appends a
  '-radius' suffix so it can peacefully co-exist with the non-RADIUS version.

6. CONFIGURATION

  First you'll have to choose where to let the portslaves log their
  messages. The portslaves can use both a local or a remote syslog
  daemon. On that machine, do the following:

  o add "local2      -/var/log/local2.log" to /etc/syslog.conf
  o change any lines that look like "*.debug" or "*.info" to
    "*.debug;local2.none" to prevent sensitive info being logged to
    maybe publically readable files.
  o Create /var/log/local2.log and chmod 600 it so that it's safe.
    Although we won't write passwords there by default so making it more
    widely read shouldn't be such a problem.

  Now you'll have to edit /etc/portslave/pslave.conf". The comments in this
  file are intentionally minimal as it is fully documented in the man page.

7. EXECUTION

  Portslave is designed to be spawned by init. This is done by adding a line
  in your /etc/inittab for every port that you have configured. These lines
  have to look like this:

  S0:23:respawn:/usr/local/portslave/bin/portslave 0
  [...]
  S31:23:respawn:/usr/local/portslave/bin/portslave 31

  Note that the first field (the "id" field) can only have more than 2
  characters if you have a recent sysvinit (>= 2.60) compiled with a
  recent libc (>= 5.2.18). This doesn't matter; 2 characters is also fine
  as long as the id fields are unique.


8. CTLPORTSLAVE, FINGERD

   Ctlportslave gets installed setuid root, group daemon.
   -rwsr-x---   1 root      daemon        12428 Jun 21 04:00 ctlportslave 

   It offers a very limited subset of the Portmaster interface, and as of
   1.2.0 some of it's own unique features.
   
   It offers two modes of operation, as a client for the "pmmon" utility from
   Brad Owens, <thrasher@squashduck.com>, or when invoked with '-f' as a quasi
   emulation of the finger daemon. 

   7.1 CTLPORTSLAVE AS PMMON CLIENT (depreciated)

   Add the following to /etc/passwd and set the password for `!root'
   using the "passwd \!root" command:

   !root:x:999:1:Portslave Admin:/tmp:/usr/local/sbin/ctlportslave

   999 is a free UID, 1 is the GID of the daemon group on your machine.

   ctlportslave can also be invoked ont he local machine for 'pmmon' style
   access without the above set up.

   Unless you already have a desire to use pmmon, it it recommended you
   only complete the 'finger' set up.

   7.2 CTLPORTSLAVE AS FINGERD (prefered)

   Add this to /etc/inetd.conf. Comment out the existing fingerd entry
   if needed:

   finger stream tcp nowait nobody.daemon /usr/sbin/tcpd 
   			/usr/local/sbin/ctlportslave -f
			  
			  ctlportslave -f -p psfinger -r psreset

ps-finger		7979/tcp
			  

   (all on one line). Now send SIGHUP to the running inetd.
   NOTE that fingerd runs as user nobody, group daemon.
   
   ctlportslave can also be renamed (or smylinked) with 'finger' in it's name
   and it will be run as finger without the '-f'. This is provided for 
   backwards compatability and this method has depreciated.
   

9. FILES IN /etc/ppp

  Make sure the /etc/ppp/pap-secrets file is empty.

  Also there must be 2 files "ip-up" and "ip-down" there, that are
  executable. A file with a single first line "#! /bin/sh" will do.
  Chmod those files to 755.

  You also need an options file there. That file must preferably also
  be empty (0 bytes).


10. AND NOW...

  Give an "init q" and the portslaves should start. You can see in the
  logfile (/var/log/local6.log) what exactly is happening.

  If you want to see much more debug output, set the "debug" entry in
  the "pslave.conf" config file to 1 or 2, and add the keyword "debug" to
  both lines of ppp options (all.pppopt and all.autoppp). All debugging
  output will still go to the "local2.log" file.

11. MORE INFO.

  You can try the the linux-isp mailing list, which on a lot of sites
  used to be accessible as the newsgroup linux.admin.isp (not anymore).
  For the mailing list, send a message with "help" in the body to
  linuxisp-request@friendly.jeffnet.org. Several people on that list are
  successfully using this software.

  Home of portslave at http://portslave.linuxrouter.org/

  If you want to do some special routing for single static IP numbers
  have a look at ripd, @ http://www.miquels.cistron.nl/radius/portslave.html

  Read the MAINTAINER file to find out who is maintaining portslave.
