Provided by: portslave_2010.04.19ubuntu1_amd64 bug


       pslave.conf - configuration file for portslave(8)


       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.


       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.


       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.

              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.


       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


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

              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

              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:


              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.


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

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

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

              Defaults to the location where we install pppd-radius.

              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!

              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

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

              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

              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!

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

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

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

              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.

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

              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.

              string - file name for configuration file for radclient

              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.

              enum  -  'login',  'rlogin',  'telnet',  'ssh1',  'ssh',  'slip',  'cslip',  'ppp',
              'ppp_only', 'tcpclear', 'tcplogin', 'console', 'socket_client', 'socket_server', or
               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.

              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.

              IP  number  -  in  almost  all cases it should be, 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.

              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.

              dynamic int - port number used for telnet targets.

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

              int - number of stop bits.

              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.

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

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

              string - the times that are allowed for logins.

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


       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

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

       %%     %


       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.


       This man page was written by Russell Coker <>.  May be freely used and
       distributed without restriction.


       portslave(8), pppd(8), cltportslave(1)