path: root/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc

---
title: Chapter 28. PPP
part: IV. Network Communication
prev: books/handbook/serialcomms
next: books/handbook/mail
description: FreeBSD supports the Point-to-Point (PPP) protocol which can be used to establish a network or Internet connection using a dial-up modem
tags: ["PPP", "PPPoE", "PPPoA", "modem"]
showBookMenu: true
weight: 33
path: "/books/handbook/"
aliases: ["/en/books/handbook/userppp/","/en/books/handbook/ppp-troubleshoot/","/en/books/handbook/pppoe/","/en/books/handbook/pppoa/"]
---

[[ppp-and-slip]]
= PPP
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 28
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/handbook/ppp-and-slip/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

[[ppp-and-slip-synopsis]]
== Synopsis

FreeBSD supports the Point-to-Point (PPP) protocol which can be used to establish a network or Internet connection using a dial-up modem.
This chapter describes how to configure modem-based communication services in FreeBSD.

After reading this chapter, you will know:

* How to configure, use, and troubleshoot a PPP connection.
* How to set up PPP over Ethernet (PPPoE).
* How to set up PPP over ATM (PPPoA).

Before reading this chapter, you should:

* Be familiar with basic network terminology.
* Understand the basics and purpose of a dial-up connection and PPP.

[[userppp]]
== Configuring PPP

FreeBSD provides built-in support for managing dial-up PPP connections using man:ppp[8].
The default FreeBSD kernel provides support for [.filename]#tun# which is used to interact with a modem hardware.
Configuration is performed by editing at least one configuration file, and configuration files containing examples are provided.
Finally, `ppp` is used to start and manage connections.

In order to use a PPP connection, the following items are needed:

* A dial-up account with an Internet Service Provider (ISP).
* A dial-up modem.
* The dial-up number for the ISP.
* The login name and password assigned by the ISP.
* The IP address of one or more DNS servers. Normally, the ISP provides these addresses. If it did not, FreeBSD can be configured to use DNS negotiation.

If any of the required information is missing, contact the ISP.

The following information may be supplied by the ISP, but is not necessary:

* The IP address of the default gateway. If this information is unknown, the ISP will automatically provide the correct value during connection setup. When configuring PPP on FreeBSD, this address is referred to as `HISADDR`.
* The subnet mask. If the ISP has not provided one, `255.255.255.255` will be used in the man:ppp[8] configuration file.
*
+
If the ISP has assigned a static IP address and hostname, it should be input into the configuration file. Otherwise, this information will be automatically provided during connection setup.

The rest of this section demonstrates how to configure FreeBSD for common PPP connection scenarios.
The required configuration file is [.filename]#/etc/ppp/ppp.conf# and additional files and examples are available in [.filename]#/usr/share/examples/ppp/#.

[NOTE]
====
Throughout this section, many of the file examples display line numbers.
These line numbers have been added to make it easier to follow the discussion and are not meant to be placed in the actual file.

When editing a configuration file, proper indentation is important.
Lines that end in a `:` start in the first column (beginning of the line) while all other lines should be indented as shown using spaces or tabs.
====

[[userppp-staticIP]]
=== Basic Configuration

In order to configure a PPP connection, first edit [.filename]#/etc/ppp/ppp.conf# with the dial-in information for the ISP.
This file is described as follows:

[.programlisting]
....
1     default:
2       set log Phase Chat LCP IPCP CCP tun command
3       ident user-ppp VERSION
4       set device /dev/cuau0
5       set speed 115200
6       set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \
7                 \"\" AT OK-AT-OK ATE1Q0 OK \\dATDT\\T TIMEOUT 40 CONNECT"
8       set timeout 180
9       enable dns
10
11    provider:
12      set phone "(123) 456 7890"
13      set authname foo
14      set authkey bar
15      set timeout 300
16      set ifaddr x.x.x.x/0 y.y.y.y/0 255.255.255.255 0.0.0.0
17      add default HISADDR
....

Line 1:::
Identifies the `default` entry.
Commands in this entry (lines 2 through 9) are executed automatically when `ppp` is run.

Line 2:::
Enables verbose logging parameters for testing the connection.
Once the configuration is working satisfactorily, this line should be reduced to:
+
[.programlisting]
....
set log phase tun
....

Line 3:::
Displays the version of man:ppp[8] to the PPP software running on the other side of the connection.

Line 4:::
Identifies the device to which the modem is connected, where [.filename]#COM1# is [.filename]#/dev/cuau0# and [.filename]#COM2# is [.filename]#/dev/cuau1#.

Line 5:::
Sets the connection speed.
If `115200` does not work on an older modem, try `38400` instead.

Lines 6 & 7:::
The dial string written as an expect-send syntax.
Refer to man:chat[8] for more information.
+
Note that this command continues onto the next line for readability.
Any command in [.filename]#ppp.conf# may do this if the last character on the line is `\`.

Line 8:::
Sets the idle timeout for the link in seconds.

Line 9:::
Instructs the peer to confirm the DNS settings.
If the local network is running its own DNS server, this line should be commented out, by adding a `#` at the beginning of the line, or removed.

Line 10:::
A blank line for readability. Blank lines are ignored by man:ppp[8].

Line 11:::
Identifies an entry called `provider`.
This could be changed to the name of the ISP so that `load _ISP_` can be used to start the connection.

Line 12:::
Use the phone number for the ISP.
Multiple phone numbers may be specified using the colon (`:`) or pipe character (`|`) as a separator.
To rotate through the numbers, use a colon.
To always attempt to dial the first number first and only use the other numbers if the first number fails, use the pipe character.
Always enclose the entire set of phone numbers between quotation marks (`"`) to prevent dialing failures.

Lines 13 & 14:::
Use the user name and password for the ISP.

Line 15:::
Sets the default idle timeout in seconds for the connection.
In this example, the connection will be closed automatically after 300 seconds of inactivity.
To prevent a timeout, set this value to zero.

Line 16:::
Sets the interface addresses.
The values used depend upon whether a static IP address has been obtained from the ISP or if it instead negotiates a dynamic IP address during connection.
+
If the ISP has allocated a static IP address and default gateway, replace _x.x.x.x_ with the static IP address and replace _y.y.y.y_ with the IP address of the default gateway.
If the ISP has only provided a static IP address without a gateway address, replace _y.y.y.y_ with `10.0.0.2/0`.
+
If the IP address changes whenever a connection is made, change this line to the following value.
This tells man:ppp[8] to use the IP Configuration Protocol (IPCP) to negotiate a dynamic IP address:
+
[.programlisting]
....
set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.255 0.0.0.0
....

Line 17:::
Keep this line as-is as it adds a default route to the gateway.
The `HISADDR` will automatically be replaced with the gateway address specified on line 16.
It is important that this line appears after line 16.

Depending upon whether man:ppp[8] is started manually or automatically, a [.filename]#/etc/ppp/ppp.linkup# may also need to be created which contains the following lines.
This file is required when running `ppp` in `-auto` mode.
This file is used after the connection has been established.
At this point, the IP address will have been assigned and it is now possible to add the routing table entries.
When creating this file, make sure that _provider_ matches the value demonstrated in line 11 of [.filename]#ppp.conf#.

[.programlisting]
....
provider:
      add default HISADDR
....

This file is also needed when the default gateway address is "guessed" in a static IP address configuration.
In this case, remove line 17 from [.filename]#ppp.conf# and create [.filename]#/etc/ppp/ppp.linkup# with the above two lines.
More examples for this file can be found in [.filename]#/usr/share/examples/ppp/#.

By default, `ppp` must be run as `root`.
To change this default, add the account of the user who should run `ppp` to the `network` group in [.filename]#/etc/group#.

Then, give the user access to one or more entries in [.filename]#/etc/ppp/ppp.conf# with `allow`.
For example, to give `fred` and `mary` permission to only the `provider:` entry, add this line to the `provider:` section:

[.programlisting]
....
allow users fred mary
....

To give the specified users access to all entries, put that line in the `default` section instead.

=== Advanced Configuration

It is possible to configure PPP to supply DNS and NetBIOS nameserver addresses on demand.

To enable these extensions with PPP version 1.x, the following lines might be added to the relevant section of [.filename]#/etc/ppp/ppp.conf#.

[.programlisting]
....
enable msext
set ns 203.14.100.1 203.14.100.2
set nbns 203.14.100.5
....

And for PPP version 2 and above:

[.programlisting]
....
accept dns
set dns 203.14.100.1 203.14.100.2
set nbns 203.14.100.5
....

This will tell the clients the primary and secondary name server addresses, and a NetBIOS nameserver host.

In version 2 and above, if the `set dns` line is omitted, PPP will use the values found in [.filename]#/etc/resolv.conf#.

[[userppp-PAPnCHAP]]
==== PAP and CHAP Authentication

Some ISPs set their system up so that the authentication part of the connection is done using either of the PAP or CHAP authentication mechanisms.
If this is the case, the ISP will not give a `login:` prompt at connection, but will start talking PPP immediately.

PAP is less secure than CHAP, but security is not normally an issue here as passwords, although being sent as plain text with PAP, are being transmitted down a serial line only.
There is not much room for crackers to "eavesdrop".

The following alterations must be made:

[.programlisting]
....
13      set authname MyUserName
14      set authkey MyPassword
15      set login
....

Line 13:::
This line specifies the PAP/CHAP user name.Insert the correct value for _MyUserName_.

Line 14:::
This line specifies the PAP/CHAP password.
Insert the correct value for _MyPassword_.
You may want to add an additional line, such as:
+
[.programlisting]
....
16      accept PAP
....
+
or
+
[.programlisting]
....
16      accept CHAP
....
+
to make it obvious that this is the intention, but PAP and CHAP are both accepted by default.

Line 15:::
The ISP will not normally require a login to the server when using PAP or CHAP.
Therefore, disable the "set login" string.

[[userppp-nat]]
==== Using PPP Network Address Translation Capability

PPP has ability to use internal NAT without kernel diverting capabilities.
This functionality may be enabled by the following line in [.filename]#/etc/ppp/ppp.conf#:

[.programlisting]
....
nat enable yes
....

Alternatively, NAT may be enabled by command-line option `-nat`.
There is also [.filename]#/etc/rc.conf# knob named `ppp_nat`, which is enabled by default.

When using this feature, it may be useful to include the following [.filename]#/etc/ppp/ppp.conf# options to enable incoming connections forwarding:

[.programlisting]
....
nat port tcp 10.0.0.2:ftp ftp
nat port tcp 10.0.0.2:http http
....

or do not trust the outside at all

[.programlisting]
....
nat deny_incoming yes
....

[[userppp-final]]
=== Final System Configuration

While `ppp` is now configured, some edits still need to be made to [.filename]#/etc/rc.conf#.

Working from the top down in this file, make sure the `hostname=` line is set:

[.programlisting]
....
hostname="foo.example.com"
....

If the ISP has supplied a static IP address and name, use this name as the host name.

Look for the `network_interfaces` variable.
To configure the system to dial the ISP on demand, make sure the [.filename]#tun0# device is added to the list, otherwise remove it.

[.programlisting]
....
network_interfaces="lo0 tun0"
ifconfig_tun0=
....

[NOTE]
====
The `ifconfig_tun0` variable should be empty, and a file called [.filename]#/etc/start_if.tun0# should be created.
This file should contain the line:

[.programlisting]
....
ppp -auto mysystem
....

This script is executed at network configuration time, starting the ppp daemon in automatic mode.
If this machine acts as a gateway, consider including `-alias`. Refer to the manual page for further details.
====

Make sure that the router program is set to `NO` with the following line in [.filename]#/etc/rc.conf#:

[.programlisting]
....
router_enable="NO"
....

It is important that the `routed` daemon is not started, as `routed` tends to delete the default routing table entries created by `ppp`.

It is probably a good idea to ensure that the `sendmail_flags` line does not include the `-q` option, otherwise `sendmail` will attempt to do a network lookup every now and then, possibly causing your machine to dial out.
You may try:

[.programlisting]
....
sendmail_flags="-bd"
....

The downside is that `sendmail` is forced to re-examine the mail queue whenever the ppp link.
To automate this, include `!bg` in [.filename]#ppp.linkup#:

[.programlisting]
....
1     provider:
2       delete ALL
3       add 0 0 HISADDR
4       !bg sendmail -bd -q30m
....

An alternative is to set up a "dfilter" to block SMTP traffic.
Refer to the sample files for further details.

=== Using `ppp`

All that is left is to reboot the machine.
After rebooting, either type:

[source,shell]
....
# ppp
....

and then `dial provider` to start the PPP session, or, to configure `ppp` to establish sessions automatically when there is outbound traffic and [.filename]#start_if.tun0# does not exist, type:

[source,shell]
....
# ppp -auto provider
....

It is possible to talk to the `ppp` program while it is running in the background, but only if a suitable diagnostic port has been set up.
To do this, add the following line to the configuration:

[.programlisting]
....
set server /var/run/ppp-tun%d DiagnosticPassword 0177
....

This will tell PPP to listen to the specified UNIX(R) domain socket, asking clients for the specified password before allowing access.
The `%d` in the name is replaced with the [.filename]#tun# device number that is in use.

Once a socket has been set up, the man:pppctl[8] program may be used in scripts that wish to manipulate the running program.

[[userppp-mgetty]]
=== Configuring Dial-in Services

crossref:serialcomms[dialup,“Dial-in Service”] provides a good description on enabling dial-up services using man:getty[8].

An alternative to `getty` is package:comms/mgetty+sendfax[] port), a smarter version of `getty` designed with dial-up lines in mind.

The advantages of using `mgetty` is that it actively _talks_ to modems, meaning if port is turned off in [.filename]#/etc/ttys# then the modem will not answer the phone.

Later versions of `mgetty` (from 0.99beta onwards) also support the automatic detection of PPP streams, allowing clients scriptless access to the server.

Refer to http://mgetty.greenie.net/doc/mgetty_toc.html[http://mgetty.greenie.net/doc/mgetty_toc.html] for more information on `mgetty`.

By default the package:comms/mgetty+sendfax[] port comes with the `AUTO_PPP` option enabled allowing `mgetty` to detect the LCP phase of PPP connections and automatically spawn off a ppp shell.
However, since the default login/password sequence does not occur it is necessary to authenticate users using either PAP or CHAP.

This section assumes the user has successfully compiled, and installed the package:comms/mgetty+sendfax[] port on his system.

Ensure that [.filename]#/usr/local/etc/mgetty+sendfax/login.config# has the following:

[.programlisting]
....
/AutoPPP/ -     - /etc/ppp/ppp-pap-dialup
....

This tells `mgetty` to run [.filename]#ppp-pap-dialup# for detected PPP connections.

Create an executable file called [.filename]#/etc/ppp/ppp-pap-dialup# containing the following:

[.programlisting]
....
#!/bin/sh
exec /usr/sbin/ppp -direct pap$IDENT
....

For each dial-up line enabled in [.filename]#/etc/ttys#, create a corresponding entry in [.filename]#/etc/ppp/ppp.conf#.
This will happily co-exist with the definitions we created above.

[.programlisting]
....
pap:
  enable pap
  set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40
  enable proxy
....

Each user logging in with this method will need to have a username/password in [.filename]#/etc/ppp/ppp.secret#, or alternatively add the following option to authenticate users via PAP from [.filename]#/etc/passwd#.

[.programlisting]
....
enable passwdauth
....

To assign some users a static IP number, specify the number as the third argument in [.filename]#/etc/ppp/ppp.secret#.
See [.filename]#/usr/share/examples/ppp/ppp.secret.sample# for examples.

[[ppp-troubleshoot]]
== Troubleshooting PPP Connections

This section covers a few issues which may arise when using PPP over a modem connection.
Some ISPs present the `ssword` prompt while others present `password`.
If the `ppp` script is not written accordingly, the login attempt will fail.
The most common way to debug `ppp` connections is by connecting manually as described in this section.

=== Check the Device Nodes

When using a custom kernel, make sure to include the following line in the kernel configuration file:

[.programlisting]
....
device   uart
....

The [.filename]#uart# device is already included in the `GENERIC` kernel, so no additional steps are necessary in this case.
Just check the `dmesg` output for the modem device with:

[source,shell]
....
# dmesg | grep uart
....

This should display some pertinent output about the [.filename]#uart# devices.
These are the COM ports we need.
If the modem acts like a standard serial port, it should be listed on [.filename]#uart1#, or [.filename]#COM2#.
If so, a kernel rebuild is not required.
When matching up, if the modem is on [.filename]#uart1#, the modem device would be [.filename]#/dev/cuau1#.

=== Connecting Manually

Connecting to the Internet by manually controlling `ppp` is quick, easy, and a great way to debug a connection or just get information on how the ISP treats `ppp` client connections.
Lets start PPP from the command line.
Note that in all of our examples we will use _example_ as the hostname of the machine running PPP.
To start `ppp`:

[source,shell]
....
# ppp
....

[source,shell]
....
ppp ON example> set device /dev/cuau1
....

This second command sets the modem device to [.filename]#cuau1#.

[source,shell]
....
ppp ON example> set speed 115200
....

This sets the connection speed to 115,200 kbps.

[source,shell]
....
ppp ON example> enable dns
....

This tells `ppp` to configure the resolver and add the nameserver lines to [.filename]#/etc/resolv.conf#.
If `ppp` cannot determine the hostname, it can manually be set later.

[source,shell]
....
ppp ON example> term
....

This switches to "terminal" mode in order to manually control the modem.

[.programlisting]
....
deflink: Entering terminal mode on /dev/cuau1
type '~h' for help
....

[source,shell]
....
at
OK
atdt123456789
....

Use `at` to initialize the modem, then use `atdt` and the number for the ISP to begin the dial in process.

[source,shell]
....
CONNECT
....

Confirmation of the connection, if we are going to have any connection problems, unrelated to hardware, here is where we will attempt to resolve them.

[source,shell]
....
ISP Login:myusername
....

At this prompt, return the prompt with the username that was provided by the ISP.

[source,shell]
....
ISP Pass:mypassword
....

At this prompt, reply with the password that was provided by the ISP.
Just like logging into FreeBSD, the password will not echo.

[source,shell]
....
Shell or PPP:ppp
....

Depending on the ISP, this prompt might not appear.
If it does, it is asking whether to use a shell on the provider or to start `ppp`.
In this example, `ppp` was selected in order to establish an Internet connection.

[source,shell]
....
Ppp ON example>
....

Notice that in this example the first `p` has been capitalized.
This shows that we have successfully connected to the ISP.

[source,shell]
....
Ppp ON example>
....

We have successfully authenticated with our ISP and are waiting for the assigned IP address.

[source,shell]
....
PPP ON example>
....

We have made an agreement on an IP address and successfully completed our connection.

[source,shell]
....
PPP ON example>add default HISADDR
....

Here we add our default route, we need to do this before we can talk to the outside world as currently the only established connection is with the peer.
If this fails due to existing routes, put a bang character `!` in front of the `add`.
Alternatively, set this before making the actual connection and it will negotiate a new route accordingly.

If everything went good we should now have an active connection to the Internet, which could be thrown into the background using kbd:[CTRL+z].
If `PPP` returns to `ppp` the connection has been lost.
This is good to know because it shows the connection status.
Capital P's represent a connection to the ISP and lowercase p's show that the connection has been lost.

=== Debugging

If a connection cannot be established, turn hardware flow CTS/RTS to off using `set ctsrts off`.
This is mainly the case when connected to some PPP-capable terminal servers, where PPP hangs when it tries to write data to the communication link, and waits for a Clear To Send (CTS) signal which may never come.
When using this option, include `set accmap` as it may be required to defeat hardware dependent on passing certain characters from end to end, most of the time XON/XOFF.
Refer to man:ppp[8] for more information on this option and how it is used.

An older modem may need `set parity even`.
Parity is set at none be default, but is used for error checking with a large increase in traffic, on older modems.

PPP may not return to the command mode, which is usually a negotiation error where the ISP is waiting for negotiating to begin.
At this point, using `~p` will force ppp to start sending the configuration information.

If a login prompt never appears, PAP or CHAP authentication is most likely required.
To use PAP or CHAP, add the following options to PPP before going into terminal mode:

[source,shell]
....
ppp ON example> set authname myusername
....

Where _myusername_ should be replaced with the username that was assigned by the ISP.

[source,shell]
....
ppp ON example> set authkey mypassword
....

Where _mypassword_ should be replaced with the password that was assigned by the ISP.

If a connection is established, but cannot seem to find any domain name, try to man:ping[8] an IP address.
If there is 100 percent (100%) packet loss, it is likely that a default route was not assigned.
Double check that `add default HISADDR` was set during the connection.
If a connection can be made to a remote IP address, it is possible that a resolver address has not been added to [.filename]#/etc/resolv.conf#.
This file should look like:

[.programlisting]
....
domain example.com
nameserver x.x.x.x
nameserver y.y.y.y
....

Where _x.x.x.x_ and _y.y.y.y_ should be replaced with the IP address of the ISP's DNS servers.

To configure man:syslog[3] to provide logging for the PPP connection, make sure this line exists in [.filename]#/etc/syslog.conf#:

[.programlisting]
....
!ppp
*.*     /var/log/ppp.log
....

[[pppoe]]
== Using PPP over Ethernet (PPPoE)

This section describes how to set up PPP over Ethernet (PPPoE).

Here is an example of a working [.filename]#ppp.conf#:

[.programlisting]
....
default:
  set log Phase tun command # you can add more detailed logging if you wish
  set ifaddr 10.0.0.1/0 10.0.0.2/0

name_of_service_provider:
  set device PPPoE:xl1 # replace xl1 with your Ethernet device
  set authname YOURLOGINNAME
  set authkey YOURPASSWORD
  set dial
  set login
  add default HISADDR
....

As `root`, run:

[source,shell]
....
# ppp -ddial name_of_service_provider
....

Add the following to [.filename]#/etc/rc.conf#:

[.programlisting]
....
ppp_enable="YES"
ppp_mode="ddial"
ppp_nat="YES"	# if you want to enable nat for your local network, otherwise NO
ppp_profile="name_of_service_provider"
....

=== Using a PPPoE Service Tag

Sometimes it will be necessary to use a service tag to establish the connection.
Service tags are used to distinguish between different PPPoE servers attached to a given network.

Any required service tag information should be in the documentation provided by the ISP.

As a last resort, one could try installing the package:net/rr-pppoe[] package or port.
Bear in mind however, this may de-program your modem and render it useless, so think twice before doing it.
Simply install the program shipped with the modem.
Then, access the menu:System[] menu from the program.
The name of the profile should be listed there.
It is usually _ISP_.

The profile name (service tag) will be used in the PPPoE configuration entry in [.filename]#ppp.conf# as the provider part for `set device`.
Refer to man:ppp[8] for full details. It should look like this:

[.programlisting]
....
set device PPPoE:xl1:ISP
....

Do not forget to change _xl1_ to the proper device for the Ethernet card.

Do not forget to change _ISP_ to the profile.

For additional information, refer to http://renaud.waldura.com/doc/freebsd/pppoe/[Cheaper Broadband with FreeBSD on DSL] by Renaud Waldura.

[[ppp-3com]]
=== PPPoE with a 3Com(R) HomeConnect(TM) ADSL Modem Dual Link

This modem does not follow the PPPoE specification defined in http://www.faqs.org/rfcs/rfc2516.html[RFC 2516].

In order to make FreeBSD capable of communicating with this device, a sysctl must be set.
This can be done automatically at boot time by updating [.filename]#/etc/sysctl.conf#:

[.programlisting]
....
net.graph.nonstandard_pppoe=1
....

or can be done immediately with the command:

[source,shell]
....
# sysctl net.graph.nonstandard_pppoe=1
....

Unfortunately, because this is a system-wide setting, it is not possible to talk to a normal PPPoE client or server and a 3Com(R) HomeConnect(TM) ADSL Modem at the same time.

[[pppoa]]
== Using PPP over ATM (PPPoA)

The following describes how to set up PPP over ATM (PPPoA).
PPPoA is a popular choice among European DSL providers.

=== Using mpd

The mpd application can be used to connect to a variety of services, in particular PPTP services.
It can be installed using the package:net/mpd5[] package or port.
Many ADSL modems require that a PPTP tunnel is created between the modem and computer.

Once installed, configure mpd to suit the provider's settings.
The port places a set of sample configuration files which are well documented in [.filename]#/usr/local/etc/mpd/#.
A complete guide to configure mpd is available in HTML format in [.filename]#/usr/ports/shared/doc/mpd/#.
Here is a sample configuration for connecting to an ADSL service with mpd.
The configuration is spread over two files, first the [.filename]#mpd.conf#:

[NOTE]
====
This example [.filename]#mpd.conf# only works with mpd 4.x.
====

[.programlisting]
....
default:
    load adsl

adsl:
    new -i ng0 adsl adsl
    set bundle authname username <.>
    set bundle password password <.>
    set bundle disable multilink

    set link no pap acfcomp protocomp
    set link disable chap
    set link accept chap
    set link keep-alive 30 10

    set ipcp no vjcomp
    set ipcp ranges 0.0.0.0/0 0.0.0.0/0

    set iface route default
    set iface disable on-demand
    set iface enable proxy-arp
    set iface idle 0

    open
....

<.> The username used to authenticate with your ISP.
<.> The password used to authenticate with your ISP.

Information about the link, or links, to establish is found in [.filename]#mpd.links#.
An example [.filename]#mpd.links# to accompany the above example is given beneath:

[.programlisting]
....
adsl:
    set link type pptp
    set pptp mode active
    set pptp enable originate outcall
    set pptp self 10.0.0.1 <.>
    set pptp peer 10.0.0.138 <.>
....

<.> The IP address of FreeBSD computer running mpd.
<.> The IP address of the ADSL modem. The Alcatel SpeedTouch(TM) Home defaults to `10.0.0.138`.

It is possible to initialize the connection easily by issuing the following command as `root`:

[source,shell]
....
# mpd -b adsl
....

To view the status of the connection:

[source,shell]
....
% ifconfig ng0
ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500
     inet 216.136.204.117 --> 204.152.186.171 netmask 0xffffffff
....

Using mpd is the recommended way to connect to an ADSL service with FreeBSD.

=== Using pptpclient

It is also possible to use FreeBSD to connect to other PPPoA services using package:net/pptpclient[].

To use package:net/pptpclient[] to connect to a DSL service, install the port or package, then edit [.filename]#/etc/ppp/ppp.conf#.
An example section of [.filename]#ppp.conf# is given below.
For further information on [.filename]#ppp.conf# options consult man:ppp[8].

[.programlisting]
....
adsl:
 set log phase chat lcp ipcp ccp tun command
 set timeout 0
 enable dns
 set authname username <.>
 set authkey password <.>
 set ifaddr 0 0
 add default HISADDR
....

<.> The username for the DSL provider.
<.> The password for your account.

[WARNING]
====

Since the account's password is added to [.filename]#ppp.conf# in plain text form, make sure nobody can read the contents of this file:

[source,shell]
....
# chown root:wheel /etc/ppp/ppp.conf
# chmod 600 /etc/ppp/ppp.conf
....

====

This will open a tunnel for a PPP session to the DSL router.
Ethernet DSL modems have a preconfigured LAN IP address to connect to.
In the case of the Alcatel SpeedTouch(TM) Home, this address is `10.0.0.138`.
The router's documentation should list the address the device uses.
To open the tunnel and start a PPP session:

[source,shell]
....
# pptp address adsl
....

[TIP]
====

If an ampersand ("&") is added to the end of this command, pptp will return the prompt.
====

A [.filename]#tun# virtual tunnel device will be created for interaction between the pptp and ppp processes.
Once the prompt is returned, or the pptp process has confirmed a connection, examine the tunnel:

[source,shell]
....
% ifconfig tun0
tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
        inet 216.136.204.21 --> 204.152.186.171 netmask 0xffffff00
	Opened by PID 918
....

If the connection fails, check the configuration of the router, which is usually accessible using a web browser.
Also, examine the output of `pptp` and the contents of the log file, [.filename]#/var/log/ppp.log# for clues.