Ubuntu Manpage: pslave.conf - configuration file for portslave(8)

Provided by: portslave_2010.04.19.1ubuntu1_amd64

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.