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.6.4 October 2024 propppd(8)