propppd

 

NAME

propppd - Pro Point-to-Point Protocol Daemon  

SYNOPSIS

propppd [-f] [-l 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 -l option is given.
-l 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 terminated 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           *

 

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 Protocol (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-licensed 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 reserved.
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 modification, 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 FITNESS, 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, 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.


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
EVENTS
AUTHENTICATION
Local Authentication
RADIUS
RADIUS Authentication
RADIUS Accounting
RADIUS Disconnect
FILES
EXAMPLES
SEE ALSO
COPYRIGHT

This document was created by man2html, using the manual pages.
Time: 13:51:04 GMT, May 25, 2018