

    Cistron RADIUS portslave  1.16  miquels@cistron.nl  11-Nov-1997


0. IMPORTANT

  * Portslave 1.16 and up is ment to be used with ppp-2.2.0f with special
    patches. However since 2 command line options have been renamed in
    the upcoming 2.3.x pppd wrt the 2.2.0f shipped with portslave, I have
    decided to use the new names.

       -ipx-protocol => noipx
       -ccp-protocol => noccp.

    Adjust your "server.cfg" accordingly or pppd will not run.
  * The interface to pppd has changed. The radius library is now loaded
    dynamically. You need to make sure that "uselib /path/to/libpsr.so"
    is included in the options.
  * You need the extra argument "login" on the autoppp command line.
  * The formats of "autoppp" and "waitfor" have changed in "server.cfg"
  * There is a new variable called "porttype" in "server.cfg"

1. DISCLAIMER.

  This is BETA software. It happens to work for us, but it might not
  work for you. If it breaks you get to keep both pieces. There is no
  warranty of any kind. YOU ARE ON YOUR OWN WITH THIS.

2. INTRODUCTION.

  This is the Cistron RADIUS portslave. We run this on our terminal
  servers so that, from the outside, a Linux terminal server box looks
  similar to a Livingston Portmaster (which we also use), or any other
  terminal server that speaks RADIUS.

  The system has been designed for use on a standalone terminal server.
  We use the Comtrol Rocket ports (2x16 or 1x32) cards in our terminal
  servers. We run Linux 2.0.29 on them.

3. RADIUS

  You will need at least one RADIUS server on one of your systems. These
  are available from ftp.livingston.com (the original livingston radius-1.16)
  and from ftp.merit.edu (the MERIT version). There are also a lot of
  alternate servers and patches floating around.

  An alternate simple but powerful RADIUS server is being worked on.
  Actually it works fine but the documentation is not done yet. You can
  find it under the name "radiusd-cistron-1.5.4.tar.gz" in the same directory
  as where this software came from.

  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. 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.

  The software was built under Debian/Linux 1.3.1, with libc 5.4.33
  and gcc-elf 2.7.2.1.

  You need a modified pppd first. Read the file README.PPPD first.

  Now, go into the src/ subdirectory. Edit "conf.h" to suit your
  system. We have the software installed under /usr/local/portslave/.

  Now go back to the main directory (cd ..). Type "make" to build
  all pieces of the system.

5. INSTALLING THE SOFTWARE.

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

  src/server.cfg		/usr/local/portslave/etc/server.cfg
  src/portslave			/usr/local/portslave/bin/portslave
  src/ctlportslave		/usr/local/portslave/bin/ctlportslave
  src/radinit			/usr/local/portslave/bin/radinit
  ppp-2.2.0f-radius/pppd/pppd	/usr/local/portslave/bin/pppd
  rlogin-8.10/rlogin		/usr/local/portslave/bin/rlogin

  You can use the provided "install.sh" script to do this for you.
  ("make install" also works, it calls the "install.sh" script).

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 "local6      /var/log/local6.log" to /etc/syslog.conf
  o change any lines that look like "*.debug" or "*.info" to
    "*.debug;local6.none" to prevent sensitive info being logged to
    maybe publically readable files.
  o Create /var/log/local6.log and chmod 600 it so that it's safe.

  o If you have a new syslog daemon, you might have to do some special
    things to let it listen to requests from the net. syslogd-1.3 needs
    the "-r" flag at startup, for example.

  Now you'll have to edit /usr/local/portslave/etc/server.cfg". The
  comments in that file are the only documentation at the moment ;)


  The next thing is that you'll have to add a line in your /etc/inittab
  for every dialin line that you have configured. These lines have to
  look like this:

  T0:23:respawn:/usr/local/portslave/bin/portslave 0
  [...]
  T31: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.


  You'll have to add a call to "/usr/local/portslave/bin/radinit" in your
  system startup scripts. If you run Debian, you can put the following
  script in the file /etc/rc.boot/radinit :

  #! /bin/sh
  /usr/local/portslave/bin/radinit

  This program updates the file /var/log/radsession.id that generates
  unique session ID's. It has to be updated every boot according to the
  RADIUS specifications.


7. CTLPORTSLAVE, FINGERD

   Ctlportslave gets installed setuid root, group daemon in the bin/
   directory. It offers a very limited subset of the Portmaster interface.
   It is intended to be used by the "pmmon" utility from Brad Owens,
   <thrasher@squashduck.com>. If it is called with the string "finger"
   in its name (argv[0]) it will act as a fingerd daemon. To install this
   on a portslave server:

   7.1 CTLPORTSLAVE

   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/portslave/bin/ctlportslave

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

   7.2 FINGERD

   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/portslave/bin/in.fingerd

   (all on one line). Now send SIGHUP to the running inetd.
   NOTE that fingerd runs as user nobody, group daemon.

8. FILES IN /etc/ppp

  Make sure there is no /etc/ppp/pap-secrets file. If it is present, PAP
  authentication over RADIUS will not work: the PPP daemon will not look
  any further then the pap-secrets file.

  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).


9. 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 "server.cfg" config file to 1, and add the keyword "debug" to
  both lines of ppp options (all.pppopt and all.autoppp). All debugging
  output will still go to the "local6.log" file.

10. MORE INFO.

  I've set up a web page at http://miquels.www.cistron.nl/radius/. It doesn't
  contain much information but it always has the latest versions of everything.

  Furthermore you can try the the linux-isp mailing list, which on a lot of
  sites is 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.

  Tim Sailer has some info on http://www.buoy.com/isp/.

  If you want to do some special routing for single static IP numbers
  have a look at ripd, at the same place you found this software.

11. LICENSE.

Portslave is Copyright (C) 1997 Cistron Internet Services B.V.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; version 2 dated June, 1991.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program;  if not, write to the Free Software
   Foundation, Inc., 675 Mass Ave., Cambridge, MA 02139, USA.

On Debian GNU/Linux systems, the complete text of the GNU General
Public License can be found in `/usr/doc/copyright/GPL'.

