propppd(8)                      ProL2TP Manual                      propppd(8)



NAME
       propppd - Pro Point-to-Point Protocol Daemon

SYNOPSIS
       propppd [-f] [-o log-file] [-c config-file]

DESCRIPTION
       PPP  is  the protocol used for establishing internet links over dial-up
       modems, DSL connections, and many other types of point-to-point  links.
       The  propppd  daemon supports many PPP instances in a single daemon and
       is controlled by the propppctl(1) command line utility.

OPTIONS
       Most configuration options are specified in the propppd config file  at
       propppd.conf(5).  Only options which may not be modified at runtime are
       set using command line options when starting propppd.

       -f     Run propppd in the  foreground.  Log  messages  are  written  to
              stdout instead of syslog, unless the -o option is given.

       -o log-file
              Output  log  messages to the specified file instead of to syslog
              or stdout.

       -c config-file
              Use the specified config file instead of the default.

EVENTS
       The following event types are generated by propppd when  PPP  instances
       are created, destroyed or change state:

       CREATED   A  new PPP instance has been created. Event data includes the
                 instance name.

       DESTROYED A PPP instance has been  destroyed.  Event  data  includes  a
                 reason code and/or string and the instance name.

       UP        A  PPP  instance has successfully established a link with the
                 peer. Event data includes the instance  name,  PPP  interface
                 name, PPP user, IP addresses, link type and link device.

       DOWN      A  PPP  instance  has lost its connection with the peer. Data
                 can no longer pass. Event data includes  the  instance  name,
                 PPP  interface name, link type, reason code and/or string and
                 data transfer counters.

       The propppwatch(1) utility may be used to listen for and  print  events
       in real-time.

AUTHENTICATION
       Authentication  is  the process whereby one peer convinces the other of
       its identity.  This involves the first peer sending  its  name  to  the
       other,  together  with some kind of secret information which could only
       come from the genuine  authorized  user  of  that  name.   In  such  an
       exchange,  we  will  call the first peer the "client" and the other the
       "server".  The client has a name by which it identifies itself  to  the
       server, and the server also has a name by which it identifies itself to
       the client.  Generally  the  genuine  client  shares  some  secret  (or
       password)  with the server, and authenticates itself by proving that it
       knows that secret.  Very  often,  the  names  used  for  authentication
       correspond  to  the  internet  hostnames  of the peers, but this is not
       essential.

       propppd supports authentication using information in local  data  files
       or  using  RADIUS.  The  authentication  options  are specified per PPP
       instance when the instance is created. If local data  files  are  used,
       propppd uses the same file formats as pppd(8).  If migrating to propppd
       from pppd, the /etc/ppp/*-secrets files may be copied to /etc/proppp.

       At  present,  propppd  supports  three  authentication  protocols:  the
       Password    Authentication    Protocol   (PAP),   Challenge   Handshake
       Authentication Protocol (CHAP), and Extensible Authentication  Protocol
       (EAP).   PAP  involves  the  client  sending  its  name and a cleartext
       password to the server to authenticate itself.  In contrast, the server
       initiates  the  CHAP  authentication exchange by sending a challenge to
       the client (the challenge packet  includes  the  server's  name).   The
       client must respond with a response which includes its name plus a hash
       value derived from the shared secret and the  challenge,  in  order  to
       prove   that   it   knows   the   secret.    EAP   supports  CHAP-style
       authentication.

       The PPP protocol, being symmetrical, allows both peers to  require  the
       other   to  authenticate  itself.   In  that  case,  two  separate  and
       independent authentication exchanges will  occur.   The  two  exchanges
       could   use  different  authentication  protocols,  and  in  principle,
       different names could be used in the two exchanges.

       The default behaviour  of  propppd  is  to  agree  to  authenticate  if
       requested,  and  to not require authentication from the peer.  However,
       propppd will  not  agree  to  authenticate  itself  with  a  particular
       protocol if it has no secrets which could be used to do so.

   Local Authentication
       Propppd  stores  secrets  for  use  in  authentication in secrets files
       (/etc/proppp/pap-secrets for PAP,  /etc/proppp/chap-secrets  for  CHAP,
       and  EAP  MD5-Challenge.   All secrets files have the same format.  The
       secrets files can contain secrets for propppd to use in  authenticating
       itself  to  other  systems,  as well as secrets for propppd to use when
       authenticating other systems to itself.

       Each line in a secrets file contains one secret.   A  given  secret  is
       specific to a particular combination of client and server - it can only
       be used by that client to authenticate itself  to  that  server.   Thus
       each  line  in  a  secrets  file has at least 3 fields: the name of the
       client, the name of the server, and the secret.  These  fields  may  be
       followed  by  a  list of the IP addresses that the specified client may
       use when connecting to the specified server.

       A secrets file is parsed into words as  for  a  options  file,  so  the
       client name, server name and secrets fields must each be one word, with
       any embedded spaces or other  special  characters  quoted  or  escaped.
       Note that case is significant in the client and server names and in the
       secret.

       If the secret starts with an `@', what follows is  assumed  to  be  the
       name  of  a file from which to read the secret.  A "*" as the client or
       server name matches any name.  When selecting a secret,  propppd  takes
       the best match, i.e.  the match with the fewest wildcards.

       Any  following  words  on  the  same  line  are  taken  to be a list of
       acceptable IP addresses for that client.  If there are only 3 words  on
       the  line,  or  if  the  first  word  is "-", then all IP addresses are
       disallowed.  To allow any address, use "*".  A word starting  with  "!"
       indicates that the specified address is not acceptable.  An address may
       be followed by "/" and a number n, to indicate a whole subnet, i.e. all
       addresses which have the same value in the most significant n bits.  In
       this form, the address may be followed by a plus sign ("+") to indicate
       that  one  address  from  the  subnet  is  authorized, based on the ppp
       network interface unit number in use.  In this case, the host  part  of
       the address will be set to the unit number plus one.

       Thus  a  secrets  file  contains both secrets for use in authenticating
       other hosts, plus secrets which we use for authenticating ourselves  to
       others.   When  propppd is authenticating the peer (checking the peer's
       identity), it chooses a secret with the peer's name in the first  field
       and  the name of the local system in the second field.  The name of the
       local system defaults to the hostname, with the domain name appended if
       the  domain  option  is  used.  This default can be overridden with the
       name option, except when the usehostname option is used.

       When propppd is choosing a secret to use in  authenticating  itself  to
       the  peer, it first determines what name it is going to use to identify
       itself to the peer.  This name can be specified by the  user  with  the
       user option.  If this option is not used, the name defaults to the name
       of the local system, determined as described in the previous paragraph.
       Then  propppd  looks for a secret with this name in the first field and
       the peer's name in the second field.  Propppd will know the name of the
       peer if CHAP or EAP authentication is being used, because the peer will
       have sent it in the challenge packet.  However, if PAP is  being  used,
       propppd  will  have  to  determine  the  peer's  name  from the options
       specified by the user.  The user can specify the peer's  name  directly
       with  the  remotename  option.  Otherwise, if the remote IP address was
       specified by a name (rather than in numeric form), that  name  will  be
       used  as  the  peer's  name.   Failing  that, propppd will use the null
       string as the peer's name.

       When authenticating the peer with PAP, the supplied password  is  first
       compared  with  the  secret  from  the  secrets  file.  If the password
       doesn't match the secret, the password is encrypted using  crypt()  and
       checked  against the secret again.  Thus secrets for authenticating the
       peer can be stored in encrypted  form  if  desired.   If  the  papcrypt
       option  is  given,  the  first (unencrypted) comparison is omitted, for
       better security.

       Furthermore, if the  login  option  was  specified,  the  username  and
       password  are also checked against the system password database.  Thus,
       the system administrator can set up the pap-secrets file to  allow  PPP
       access  only  to certain users, and to restrict the set of IP addresses
       that each user can use.  Typically, when using the  login  option,  the
       secret  in  /etc/proppp/pap-secrets  would  be "", which will match any
       password supplied by the peer.  This avoids the need to have  the  same
       secret in two places.

       Authentication  must  be  satisfactorily  completed before IPCP (or any
       other Network Control  Protocol)  can  be  started.   If  the  peer  is
       required  to  authenticate  itself,  and  fails  to do so, propppd will
       terminate  the  link  (by  closing  LCP).   If   IPCP   negotiates   an
       unacceptable  IP  address for the remote host, IPCP will be closed.  IP
       packets can only be sent or received when IPCP is open.

       In some  cases  it  is  desirable  to  allow  some  hosts  which  can't
       authenticate  themselves  to connect and use one of a restricted set of
       IP  addresses,  even   when   the   local   host   generally   requires
       authentication.   If  the  peer  refuses  to  authenticate  itself when
       requested, propppd takes that as equivalent to authenticating with  PAP
       using  the empty string for the username and password.  Thus, by adding
       a line to the pap-secrets file which specifies the empty string for the
       client and password, it is possible to allow restricted access to hosts
       which refuse to authenticate themselves.

RADIUS
       ProPPP supports the following RADIUS features:

       RADIUS authentication (PAP and CHAP)

       RADIUS accounting (Start, Stop and InterimUpdate)

       RADIUS Disconnect (RFC3576)

   RADIUS Authentication
       If enabled by the radius config option, propppd will authenticate using
       RADIUS. RADIUS messages contain a number of attributes.
       Access Request

       User-Name
              The PPP username to be authenticated.

       Service-Type
              Always set to the value Framed-User.

       Framed-Protocol
              Always set to the value PPP.

       Password
              If  authenticating  with PAP, this attribute contains the user's
              password.

       CHAP-Password
              If authenticating with CHAP, this attribute is the  user's  CHAP
              password.

       CHAP-Challenge
              If   authenticating  with  CHAP,  this  attribute  is  the  CHAP
              challenge data.

       NAS-IP-Address
              This attribute is included only if the  ppp  option  rad-nas-ip-
              addr  is  set.  It  indicates  the  IP  address of the initating
              system.TP , perhaps an L2TP LNS.

       NAS-Identifier
              This attribute is included only if the ppp option rad-nas-id  is
              set.

       Calling-Station-Id
              This  attribute  is included only if the ppp option rad-calling-
              station-id is set.

       NAS-Port-Type
              This attribute is included only if the ppp option  rad-nas-port-
              type is set.

       NAS-Port
              This  attribute  is included only if the ppp option rad-nas-port
              is set.

       The attributes NAS-IP-Address, NAS-Identifier, Calling-Station-Id, NAS-
       Port-Type  and  NAS-Port  may  be used by the RADIUS server to identify
       parameters to be used for  all  sessions  initiating  by  this  propppd
       instance.  If  specific values are required by the RADIUS server, these
       can be set using PPP profiles in propppd.conf.

       Access Accept

       Service-Type
              Matches the value sent in the Access Request.  Must  be  Framed-
              User.

       Framed-Protocol
              Matches the value sent in the Access Request. Must be PPP.

       Framed-IP-Address
              If  the  RADIUS  server  assigns an IPv4 address, this attribute
              will contain the address. propppd will assign  this  address  to
              the interface of the PPP instance.

       Framed-IP-Netmask
              If  the  RADIUS  server wants the PPP instance to use a specific
              IPv4 netmask, this attribute will indicate the netmask.  propppd
              will configure the PPP interface of the PPP instance.

       Framed-Compression
              This  attribute  tells  propppd  whether  to  negotiate IPv4 Van
              Jacobsen compression with the peer.

       Reply-Message
              This attribute may contain a human-readable message.  Its  value
              is  logged by propppd but is otherwise not used in Access Accept
              messages.

       Framed-MTU
              If present, this attribute indicates the MTU to be used for  the
              PPP connection. Since the MTU has already been negotiated by PPP
              before the Auth Request is sent, propppd would need to force  an
              LCP  renegotiation  to  honour  this  attribute. This is not yet
              implemented.

       All other attributes in Access Request messages are ignored.

       Auth Access Reject (input)

       When received, propppd terminates the corresponding PPP instance.

   RADIUS Accounting
       Accounting Request (output)

       There are three types of Accounting Request: Start, Stop and Update. If
       enabled by the rad-acct option, Start and Stop messages are sent when a
       new PPP connection is successfully established  or  torn  down.  Update
       messages  are  transmitted periodically if the propppd option rad-acct-
       interim-interval is non-zero (disabled by default).

       Accounting messages carry the following options:

       User-Name
              Identifies the user.

       Service-Type
              Always Framed-User. Always matches the value sent previously  in
              the Access Request message.

       Framed-Protocol
              Always  PPP.  Always  matches  the  value sent previously in the
              Access Request message.

       Acct-Status-Type
              Indicates    the    type    of    the     Accounting     message
              (Start/Stop/Update).

       Acct-Session-Id
              A  locally  significant  unique  identifier of the PPP instance.
              This is a string assigned by propppd using the propppd  pid  and
              the  internal  PPP  connection  handle. It is used by the RADIUS
              server as a key for tracking PPP instances.

       Acct-Delay-Time
              Always 0. This is not used by propppd.

       NAS-IP-Address
              Always matches the value sent previously in the  Access  Request
              message, if present.

       NAS-Identifier
              Always  matches  the value sent previously in the Access Request
              message, if present.

       Calling-Station-Id
              Always matches the value sent previously in the  Access  Request
              message, if present.

       NAS-Port-Type
              Always  matches  the value sent previously in the Access Request
              message, if present.

       NAS-Port
              Always matches the value sent previously in the  Access  Request
              message, if present.

       Several  additional attributes are included if Acct-Status-Type is Stop
       or Update: Acct-Input-Octets, Acct-Input-Gigawords, Acct-Input-Packets,
       Acct-Output-Octets,  Acct-Output-Gigawords,  Acct-Output-Packets, Acct-
       Session-Time.

   RADIUS Disconnect
       RADIUS Disconnect messages are used by a  RADIUS  Server  or  a  RADIUS
       client  application to request that a PPP instance is disconnected. The
       support for Disconnect must be enabled in propppd.conf, e.g.

       radius {
           disconnect {
               local_disc_address 192.168.1.12
               local_disc_port 5000
               radius_disc_client "radserverd1" {
                   peer_address 10.1.1.42
                peer_port 5042
                   secret "mysecret1"
               }
           }
       }


       This tells propppd to listen for RADIUS Disconnect messages from client
       10.1.1.42  port  5042.  propppd  listens  on 192.168.1.12 port 5000 for
       Disconnect  messages.  Messages  are  authenticated  using  the  secret
       "mysecret1". Thus, Disconnect messages are allowed only from well known
       requestors.

       Disconnect Request (input)

       The following attributes may  be  present  in  the  Disconnect  Request
       message:

       User-Name
              Identifies the user. Must be present.

       Service-Type
              If  present,  this  value must match the Service-Type of the PPP
              instance to be disconnected.

       Framed-IP-Address
              If present, this value must match the Framed-IP-Address  of  the
              PPP instance to be disconnected.

       Framed-IP-Netmask
              If  present,  this value must match the Framed-IP-Netmask of the
              PPP instance to be disconnected.

       NAS-IP-Address
              If present, this value must match the NAS-IP-Address of the  PPP
              instance to be disconnected.

       NAS-Identifier
              If  present, this value must match the NAS-Identifier of the PPP
              instance to be disconnected.

       Calling-Station-Id
              If present, this value must match the Calling-Station-Id of  the
              PPP instance to be disconnected.

       NAS-Port-Type
              If  present,  this value must match the NAS-Port-Type of the PPP
              instance to be disconnected.

       NAS-Port
              If present, this value  must  match  the  NAS-Port  of  the  PPP
              instance to be disconnected.

       Thus, PPP instances can be identified with only the User-Name. However,
       if there is more than one PPP instance with the same username, it  will
       be  necessary  for  other attributes to be present to uniquely identify
       the instance to be disconnected. In most cases,  the  request  will  be
       sent   by  the  RADIUS  server  which  should  include  all  attributes
       associated with the instance to be disconnected in its request.

       Disconnect Ack (output)
       Disconnect Nack (output)

       If a Disconnect Request is accepted, a Disconnect Ack response is  sent
       to  the requestor and propppd destroys the PPP instance. If the request
       is rejected, either because a matching PPP instance cannot be found  or
       the  attributes  match  more  than  one PPP instance, a Disconnect Nack
       message is sent to the requestor. Disconnect-Nack messages  contain  an
       Error-Cause  attribute which indicates the reason for the request being
       rejected. This is a code defined in RFC3576.  The  most  common  Error-
       Cause values are:

       402 (Missing Attribute)
              More than one PPP instance matched the supplied attributes

       503 (Session Context Not Found)
              No matching PPP instances was found.

       If  the  Disconnect  Request  cannot  be  authenticated, it is silently
       discarded.

FILES
       /etc/proppp/propppd.conf
              The configuration file of propppd. See propppd.conf(5).

       /etc/proppp/pap-secrets
              Usernames, passwords and IP addresses  for  PAP  authentication.
              This  file  should be owned by root and not readable or writable
              by any other user.  propppd will log a warning if  this  is  not
              the case.

       /etc/proppp/chap-secrets
              Names,  secrets  and  IP  addresses  for  CHAP/MS-CHAP/MS-CHAPv2
              authentication.   As  for  /etc/proppp/pap-secrets,  this   file
              should  be  owned  by  root  and not readable or writable by any
              other user.  propppd will log a warning if this is not the case.

EXAMPLES
       Basic examples of pap-secrets and chap-seecrets files.

       pap-secrets

       # Every regular user can use PPP and has to use passwords from
       # /etc/passwd
       *    hostname  ""   *
       # UserIDs that cannot use PPP at all. Check your /etc/passwd
       # and add any other accounts that should not be able to use ppp!
       guest     hostname  "*"  -
       # Virtual user names
       test1     *         "test1password"     *
       test2     *         "test2password"     *


       chap-secrets

       # Secrets for authentication using CHAP
       # client  server    secret              IP addresses
       test1          *    test1password       *


SYSTEMD
       ProPPP is packaged to use the Linux distribution's default system  init
       subsystem.  For most Linux distros, this is systemd(1). propppd is con-
       trolled as the proppp systemd service.

       Where systemd is not used, propppd may be managed by upstart or rc init
       scripts.


SEE ALSO
       propppctl(1), propppwatch(1)

       RFC1144
              Jacobson,  V.   Compressing  TCP/IP headers for low-speed serial
              links.  February 1990.

       RFC1321
              Rivest, R.  The MD5 Message-Digest Algorithm.  April 1992.

       RFC1332
              McGregor, G.  PPP Internet  Protocol  Control  Protocol  (IPCP).
              May 1992.

       RFC1334
              Lloyd, B.; Simpson, W.A.  PPP authentication protocols.  October
              1992.

       RFC1661
              Simpson, W.A.  The Point-to-Point Protocol (PPP).  July 1994.

       RFC1662
              Simpson, W.A.  PPP in HDLC-like Framing.  July 1994.

       RFC2284
              Blunk, L.; Vollbrecht, J., PPP Extensible Authentication  Proto-
              col (EAP).  March 1998.

       RFC2472
              Haskin, D.  IP Version 6 over PPP December 1998.


COPYRIGHT
       propppd  is  proprietary  software  developed and maintained by Katalix
       Systems Limted. The implementation uses some code of  pppd,  a  BSD-li-
       censed ppp implementation.

       Pppd  is  copyrighted and made available under conditions which provide
       that it may be copied and used in source or binary forms provided  that
       the  conditions  listed below are met.  Portions of pppd are covered by
       the following copyright notices:

       Copyright (c) 1984-2000 Carnegie  Mellon  University.  All  rights  re-
       served.
       Copyright (c) 1993-2004 Paul Mackerras. All rights reserved.
       Copyright (c) 1995 Pedro Roque Marques.  All rights reserved.
       Copyright (c) 1995 Eric Rosenquist.  All rights reserved.
       Copyright (c) 1999 Tommi Komulainen.  All rights reserved.
       Copyright (C) Andrew Tridgell 1999
       Copyright (c) 2000 by Sun Microsystems, Inc.  All rights reserved.
       Copyright (c) 2001 by Sun Microsystems, Inc.  All rights reserved.
       Copyright (c) 2002 Google, Inc.  All rights reserved.

       The copyright notices contain the following statements.

       Redistribution and use in source and binary forms, with or without mod-
       ification, are permitted provided that  the  following  conditions  are
       met:

       1. Redistributions of source code must retain the above copyright
          notice, this list of conditions and the following disclaimer.

       2. Redistributions in binary form must reproduce the above copyright
          notice, this list of conditions and the following disclaimer in
          the documentation and/or other materials provided with the
          distribution.

       3. The name "Carnegie Mellon University" must not be used to
          endorse or promote products derived from this software without
          prior written permission. For permission or any legal
          details, please contact
            Office of Technology Transfer
            Carnegie Mellon University
            5000 Forbes Avenue
            Pittsburgh, PA  15213-3890
            (412) 268-4387, fax: (412) 268-7395
            tech-transfer@andrew.cmu.edu

       3b. The name(s) of the authors of this software must not be used to
          endorse or promote products derived from this software without
          prior written permission.

       4. Redistributions of any form whatsoever must retain the following
          acknowledgements:
          "This product includes software developed by Computing Services
           at Carnegie Mellon University (http://www.cmu.edu/computing/)."
          "This product includes software developed by Paul Mackerras
           <paulus@samba.org>".
          "This product includes software developed by Pedro Roque Marques
           <pedro_m@yahoo.com>".
          "This product includes software developed by Tommi Komulainen
           <Tommi.Komulainen@iki.fi>".

       CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
       SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND  FIT-
       NESS,  IN  NO  EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE FOR ANY
       SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR  ANY  DAMAGES  WHATSOEVER
       RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
       CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING  OUT  OF  OR  IN
       CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

       THE  AUTHORS  OF  THIS  SOFTWARE DISCLAIM ALL WARRANTIES WITH REGARD TO
       THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY  AND
       FITNESS, IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY SPECIAL, INDI-
       RECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING  FROM
       LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLI-
       GENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR  IN  CONNECTION  WITH
       THE USE OR PERFORMANCE OF THIS SOFTWARE.



ProL2TP 2.5.4                    January 2024                       propppd(8)