Provided by: portslave_2010.04.19ubuntu1_i386 bug

NAME

       pslave.conf - configuration file for portslave(8)

FORMAT

       A  line  that  starts  with  '#'  is  a  comment.   Any other line is a
       configuration statement.  Configuration statements may be  extended  to
       cover multiple lines with a '\' character at the end of a line.

OVERVIEW

       In  previous  versions  of  Portslave  there  are  two  main  types  of
       configuration directives, global directives  that  start  with  'conf.'
       and  line directives starting with 'all.'  or 'sXX.'  The configuration
       directives were divided (somewhat arbitarily)  into  global  directives
       that  apply  to  all  lines and line directives that may have different
       values for each line.  This distinction makes no sense to me, so I have
       removed  it.   Now  all  directives  can have different values for each
       line!  This gives this version  of  Portslave  many  new  configuration
       options that were previously absent.

       If  a line starts with 'conf.'  or 'all.'  then it's value is a default
       value for all lines.  If a line starts with  'sXX.'   then  it's  value
       applies  to  the specified line (where 'XX' specifies the number of the
       'NAS port' - a non-negative number).  This number is  the  command-line
       parameter used on the portslave command line.

DATA TYPES

       Configuration  directives  are  all  comprised  of a name followed by a
       value.  The value may be of type int, dynamic int, bool, string,  enum,
       hostname,  hostname  service,  IP number, IP number service, dynamic IP
       number, and chat-script.

       int    A simple number.

       dynamic int
              Number which may end in a '+' character to specify that  the  it
              is to have the port number added to it.

       bool   A boolean value, 0/no/false or 1/yes/true.

       string A  string  may  comprise multiple lines, non-terminal lines must
              end with a '\' character.  Strings do  not  need  quotes  around
              them  (double  quotes  around  strings are accepted but ignored,
              useful if you want leading or  trailing  white-space  I  guess).
              The  null  string  representation  is  "".  All the usual string
              escape sequences are supported,  \n  for  a  new  line,  \r  for
              carriage   return,  ^D  or  ^d  means  the  controll-D  sequence
              (character ASCII 4 EOT).

       enum   One of several string values that are internally translated to a
              number.

       hostname
              Hostnames are resolved to IP addresses immediately upon startup!
              You must have your  name  server  running  before  Portslave  is
              started!

       hostname service
              hostname  and  IP  service  (either  a  number  or  a name to be
              resolved from /etc/services).  The IP service is optional, if it
              is  specified  then  the  IP address must be enclosed in "[" and
              "]".

       IP number
              Simple dotted-quad IP address.

       dynamic IP number
              Dotted-quad IP address which may  end  in  a  '+'  character  to
              specify  that the IP address is to have the port number added to
              it.

EXPANSION

       Lines may be expanded in the following fashion:

       s{32-63}.tty tts/C{0-31}

       This means the same as the following:

       s32.tty tts/C0 s33.tty tts/C1 ...  s63.tty tts/C31

ATTRIBUTES

       logpassword
              bool - whether to write users' passwords to syslog (default no).

       chat-script
              A chat script is at it's simplest a series of expect send pairs.
              The  system will expect a string and then send another string in
              response  if/when   it   receives   the   expect   string.    An
              expect-string  may  be  of  the  form A-B-C in which case if the
              sub-string A is not found due to timeout then the  sub-string  B
              will  be  sent  and  then the sub-string C will be expected.  NB
              There must be exactly three parts to an expect-string  that  has
              sub-strings  and  they  are  to  be delimited by "-" characters.
              Also note that to wait for a "-" you must escape it as "\-".

              The send string may have the following special escape sequences.
              "\d"  for  a  one  second delay, "\p" for a 100ms pause, "\l" to
              lower DTR for one second, "\c" to specify that the string is not
              to  end  with  a  "\r"  character,  and  "\K"  to  send  a break
              character.

              Also special strings may be inserted before the  expect  strings
              in  any  part  of  the  chat script.  The special strings are as
              follows:

              TIMEOUT XX to specify that the new timeout when waiting  for  an
              expect string is to be XX seconds.

              WAIT DCD to wait for the DCD line of the modem to be asserted.

              STATUS  USER-NAME HOST-NAME writes an entry to the /var/run/utmp
              file with the  user  name  field  set  to  the  first  parameter
              (portslave uses "Incoming" and "Connected" as the default values
              for  the  first  two  phases  of  connecting).   It  also   uses
              "%p:I.HANDSHAKE"   as   the   default  for  the  hostname.   See
              ctlportslave for the use of this.

              ABORT XX to abort the connection if the  string  XX  (which  may
              contain multiple words surrounded by quotes) is received.

              SETVAR  Z=XX to set the variable specified by the character Z to
              the text following the string XX (quote the entire Z=XX part  if
              the  string XX contains a space).  The variable Z may be 'C' for
              the connect string, 'S' for the source of the call (from  caller
              line  identification), or 'D' for the number dialled (from CLI).
              Here is an example to recognise the connect strings from  common
              configurations of Hayes compatible modems:

              SETVAR "C=CARRIER " SETVAR C+PROTOCOL: SETVAR C?CONNECT

              The  first line does an unconditional assignment when the string
              "CARRIER " is found, the second appends  data  to  the  variable
              when  the  string  "PROTOCOL" is found, and the third will do an
              assignment when the string "CONNECT" is found if the variable is
              empty.

              Note  that in the variable assignment white-space preceeding the
              value is removed.

GLOBAL DIRECTIVES

       hostname
              String - Hostname  of  the  current  system.   Defaults  to  the
              hostname returned by gethostname().

       loc_host
              IP  number  - address for local end of SLIP and PPP connections,
              defaults to a DNS lookup of the value from hostname.

       lockdir
              String - Lock directory, defaults  to  /var/lock  which  is  the
              directory  for  FSSTD  compliant  systems.   If  set to an empty
              string then it will turn off locking.

       rlogin String - Where to find the rlogin binary  that  accepts  the  -i
              flag for specifying the local user-name.

              Defaults to the location where we install rlogin-radius.

       telnet String  -  Where  to  find  telnet.  This can just be the system
              telnet.

              Defaults to where telnet is detected on the local system.

       ssh    String - Where to find ssh.  This can just be the system SSH.

              Defaults to where ssh is detected on the local system.

       pppd   String - Where to  find  our  patched  pppd  that  supports  the
              libpsr.so library.

              Defaults to the location where we install pppd-radius.

       locallogins
              bool - If you set this to true, you can login locally by putting
              a '!' before your loginname.  Useful for  emergencies  when  the
              RADIUS  server  is  down.   Setting this is a potential security
              risk!

       allow_chap
              bool - Set to true if you want CHAP authentication.  Turned  off
              by  default  at the moment because the chap code in pppd doesn't
              allow setting the IP address.

       syslog hostname - The host to send remote syslog data to.  Leave  empty
              for only local logging.

       facility
              int - The local facility number.  A number from 0 to 7 inclusive
              means syslog facility local0 to local7.

       filterdir
              string - Directory where your scripts that set up  IP  filtering
              (typically  using  ipchains  or iptables) are stored.  To invoke
              them, just add the RADIUS-attribute Framed-Filter-Id = "foo"  to
              your  profile, where foo is the name of script.  Then the script
              will be run as:  script  <start:stop>  <remote  ip>  <local  ip>
              <remote netmask>

       stripnames
              bool - whether to remove a preceeding 'P', 'C', 'S', '!', or 'L'
              or a trailing '.slip', '.cslip', or '.ppp'  before  storing  the
              user-name in the utmp.

       tty    string  -  this is the only line directive that can't be used as
              an 'all.' or path or relative to /dev)  that  is  used  for  the
              device.  If you want devices /dev/tts/0 and /dev/ttr/5 to be NAS
              ports 1 and 2 respectively and have them use  the  default  line
              settings  (from the 'all' values) then you can use the following
              lines:

              s1.tty    tts/0 s2.tty    ttr/5

       debug  int - 0 means no debug output, 1 means some,  2  means  all.   2
              means lots of data!

       sysutmp
              bool  - if true then log to utmp like a regular getty/login.  Do
              not set this to false unless you really know what you are doing,
              it breaks ctlportslave (amoung other things).

       syswtmp
              bool  -  if true then log to wtmp like a regular getty/login (NB
              we will never log to wtmp if utmp logging is off).

       utmpfrom
              string - format of the utmp/wtmp FROM field.  See the  expansion
              directives  section.   The  default  value is "%p:%P.%3.%4", for
              ctlportslave to work properly the start of the  string  must  be
              "%p:".

       emumodem
              bool  - emulate a modem.  This is for when Portslave is directly
              connected to a machine that thinks it is connected to  a  modem.
              Portslave will emulate a Hayes compatible modem.

       porttype
              enum - 'async', 'sync', 'isdn', 'isdn-v120', or 'isdn-v110'.  If
              you don't understand this then you probably want 'async'.

       authtype
              enum  -   'none',   'radius',   'tacacs',   'remote',   'local',
              'radius/local',      'tacacs/local',      'local/radius',     or
              'local/tacacs' for which type of authentication to use.   'none'
              means  that  we  just  use  the  supplied  user-name for logging
              purposes and don't talk to the RADIUS server on login.

       radclient_config_file
              string - file name for configuration file for radclient

       radnullpass
              bool - true means to accept RADIUS logins with a null  password,
              false means to reject them.  Default true.

       tacauthhost1 tacauthhost2
              hostname  -  host  names  for  the TACACS Authentication host if
              Portslave is compiled with TACACS support.

       protocol
              enum -  'login',  'rlogin',  'telnet',  'ssh1',  'ssh',  'slip',
              'cslip',  'ppp',  'ppp_only', 'tcpclear', 'tcplogin', 'console',
              'socket_client', 'socket_server', or 'socket_ssh'.
               Login is to exec /bin/login.  Rlogin, telnet, and ssh  are  for
              executing  those  programs  to  login  to other machines.  Slip,
              cslip, and PPP are for running those IP connectivity  protocols,
              ppp_only is for leased line configuration.  Tcplogin and console
              are apparently not implemented, with tcpclear I  have  not  been
              able  to work out what it does.  Contributions welcome!  Default
              ppp.

       host   hostname - default host for rlogin/telnet/ssh sessions.

       rem_host
              dynamic IP number - used as the client IP address if the  RADIUS
              server  doesn't send an IP address, or when it tells us to use a
              dynamic address.

       netmask
              IP number - in almost all cases it  should  be  255.255.255.255,
              leave it at that unless you really know what you are doing.

       mtu    int  -  MTU  for connection, 1500 is a good value as that's what
              Ethernet uses and most packets get routed over Ethernet in  some
              way  so  1500  avoids  fragmentation  and  reduces the number of
              packets needed to transfer data.

       mru    int - MRU for connection, generally should be the  same  as  the
              MTU.

       autoppp
              string  - PPP command-line options to be used when we autodetect
              a PPP session.  Note that the expansion directives apply.

       pppopt string - PPP command-line  options  to  be  used  when  we  have
              already  authenticated the user and the service type is known to
              be PPP.  Same format as autoppp.

       issue  string  -  message  that  is  issued  on   connect.    Expansion
              directives are applied.

       prompt string  -  login  prompt,  default  is  "%h login: ".  Expansion
              directives are applied.

       term   string - terminal type for rlogin/telnet/ssh sessions.  Defaults
              to vt100.

       speed  int - port speed in bps.

       socket_port
              dynamic int - port number used for telnet targets.

       parity enum - 'none', 'odd', or 'even'.

       stopbits
              int - number of stop bits.

       datasize
              int - size of a character 5, 6, 7, or 8 bits.

       dcd    bool  -  use the DCD line or not (this sets CLOCAL if off). This
              means that the session will get hung up if the modem hangs up.

       flow   enum - 'none', 'hard', or 'soft'.  Hardware (RTS/CTS),  software
              (XON/XOFF AKA ^S/^Q), or no flow control.

       initchat
              chat-script  -  the  chat  script for initialising the modem and
              answering.  Needs much more documentation on this.

       radclient_config_file
              string   -   configuration   file   for    radclient    (default
              /etc/portslave/radclient.conf).

       login_time
              string - the times that are allowed for logins.

       login_time_limited
              bool  -  if  true  then  the  maximum length of the call will be
              determined by the value of the login_time setting.

EXPANSION DIRECTIVES

       These directives can be used for the format of the utmp/wtmp field, for
       the autoppp, pppopt, issue, prompt fields, and others.

       %l     login name

       %L     stripped login name

       %p     NAS port number

       %P     protocol

       %b     port speed

       %H     host for telnet/ssh connections

       %i     local IP

       %j     remote IP

       %1     first byte (MSB) of remote IP

       %2     second byte of remote IP

       %3     third byte of remote IP

       %4     fourth byte (LSB) of remote IP

       %c     connect-info

       %m     netmask

       %M     multilink if the RADIUS server has PW_NAS_PORT_LIMIT set to > 1,
              otherwise empty string

       %t     MTU

       %r     MRU

       %I     idle timeout

       %T     session timeout

       %h     hostname

       %d     dcd setting, expands to "modem" if DCD line is to be used or  to
              "local"  if  it isn't.  Put this on the ppp command line to give
              it the right setting to match the value of the "dcd" attribute.

       %%     %

BUGS

       The documentation section for protocol in the line  directives  section
       needs to be improved.  I intend to do so as soon as I work out what the
       code does.

       The initchat option needs heaps  more  documentation.   As  soon  as  I
       figure it out...

       The realm section needs to be improved, to do this I have to go through
       the code and comment what it does so I can understand it.

AUTHOR

       This man page was written by Russell Coker <russell@coker.com.au>.  May
       be freely used and distributed without restriction.

SEE ALSO

       portslave(8),                  pppd(8),                 cltportslave(1)
       http://doc.coker.com.au/projects/portslave/

Russell Coker <russell@coker.com.a2>010.03.30                    pslave.conf(5)