The '<code>/etc/ppp/ppp.conf</code>' file

PPP - Pedantic PPP Primer : Configuring the PPP Dial-Out Connection : Create your own PPP configuration files : The '/etc/ppp/ppp.conf' file
Previous: Create your own PPP configuration files
Next: The '/etc/ppp/ppp.linkup' file

4.2.1. The '`/etc/ppp/ppp.conf`' file

The '/etc/ppp/ppp.conf' file contains the information and settings required to set up a dial-out PPP connection. More than one configuration may be contained in this file. The FreeBSD handbook (XXX URL? XXX) describes the contents and syntax of this file in detail.

This section will describe only the minimal configuration to get a dial-out connection working.

Below is the /etc/ppp/ppp.conf file that we'll be using to provide a dial-out Internet gateway for our example LAN: <hr>

################################################################
# PPP Configuration File ('/etc/ppp/ppp.conf')
#
# Default settings; These are always executed always when PPP
# is invoked and apply to all system configurations.
################################################################
default:
set device /dev/cuaa0
set speed 57600
disable pred1
deny pred1
disable lqr
deny lqr
set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT"
set redial 3 10
#
#
################################################################
#
# For interactive mode use this configuration:
#
# Invoke with `ppp -alias interactive`
#
################################################################
interactive:
set authname Your_User_ID_On_Remote_System
set authkey Your_Password_On_Remote_System
set phone 1-800-123-4567
set timeout 300
set openmode active
accept chap
#
################################################################
#
# For demand-dial (automatic) mode we'll use this configuration:
#
# Invoke with: 'ppp -auto -alias demand'
#
################################################################
demand:
set authname Your_User_ID_On_Remote_System
set authkey Your_Password_On_Remote_System
set phone 1-800-123-4567
set timeout 300
set openmode active
accept chap
set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0
add 0 0 127.2.2.2
################################################################
# End of /etc/ppp/ppp.conf

<hr> This file, taken verbatim from a working system, has three relevant configuration sections:

4.2.1.1. The "`default`" Section

The 'default:' section contains the values and settings used by every other section in the file. Essentially, this section is implicitly added to the configuration lines to each other section.

This is a good place to put "global defaults" applicable to all dial-up sessions; especially modem settings and dialing prefixes which typically don't change based on which destination system you're connecting to.

Following are the descriptions of each line in the "default" section of the sample '/etc/ppp/ppp.conf' file:


set device /dev/cuaa0

This statement informs the PPP program that it should use the first serial port. Under FreeBSD the '/dev/cuaa0' device is the same port that's known as "COM1:" under DOS, Windows, Windows 95, etc....

If your modem is on COM2: you should specify '/dev/cua01;, COM3: would be '/dev/cua02'.


set speed 57600

This line sets the transmit and receive speed for the connection between the serial port and the modem. While the modem used for this configuration is only a 28.8 device, setting this value to 57600 lets the serial link run at a higher rate to accommodate higher throughput as a result of the data compression built into late-model modems.

If you have trouble communicating with your modem, try setting this value to 38400 or even as low as 19200.


disable pred1
deny pred1

These two lines disable the "CCP/Predictor type 1" compression features of the PPP program. The current version of `ppp` supports data compression in accordance with draft Internet standards. Unfortunately many ISPs use equipment that does not support this capability. Since most modems try to perform on-the-fly compression anyway you're probably not losing much performance by disabling this feature on the FreeBSD side and denying the remote side from forcing it on you.


disable lqr
deny lqr

These two lines control the "Line Quality Reporting" functions which are part of the complete Point-to-Point (PPP) protocol specification. (See RFC-1989 for details.)

The first line, "disable lqr", instructs the PPP program to not attempt to report line quality status to the device on the remote end.

The second line, "deny lqr", instructs the PPP program to deny any attempts by the remote end to reports line quality.

As most modern dial-up modems have automatic error correction and detection and LQR reporting is not fully implemented in many vendor's products it's generally a safe bet to include these two lines in the default configuration.


set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT"

NOTE: (This statement should appear on a single line; ignore any line wrapping that may appear in this document.)

This line instructs the PPP program how to dial the modem and specifies some rudimentary guidelines for doing so:

Attempts to dial should fail if the modem returns a "BUSY" result code,
Attempts to dial should also fail if the modem returns a "NO CARRIER" result code,
The PPP program should expect each of the following events to complete within a 5-second timeout period:
- The PPP program will initially expect nothing (specified above by the \"\" portion of the statement) from the modem
- The program will send the modem initialization string "ATE1Q0M0" to the modem and await a response of "OK". If a response is not received, the program should send an attention command to the modem ("AT") and look again for a response of "OK",
- The program should delay for one second (specified by the "\\d" part of the statement, and send the dialing string to the modem. The "ATDT" portion of the statement is the standard modem prefix to dial using tone-dialing; if you do not have touch-tone service on your local phone line, replace the "ATDT" with "ATDP". The "\\T" string is a placeholder for the actual phone number (which will be automatically inserted as specified by the "set dial 123-4567").
Finally, before a (maximum) timeout of 40 seconds, the PPP program should expect to see a "CONNECT" result code returned from the modem.

A failure at any point in this dialog will be interpreted as a dialing failure and the PPP program will fail to connect.

(For a detailed description of the mini-scripting language used by the PPP dialer, refer to the "chat" manpage.)


set redial 3 10

This line specifies that if a dial connection cannot immediately be made the PPP program should retry (up to 3 times if necessary) with a delay of 10 seconds between redialing attempts.

4.2.1.2. The "`interactive`" Section

The 'interactive:' section contains the values and settings used to set up an "interactive" PPP session with a specific remote system. Settings in this section will have the lines included in the "default" section included automatically.

The example cited in this section of the guide presumes that you'll be connecting to a remote system that understands how to authenticate a user without any fancy scripting language. That is, this sample uses the CHAP protocol to set up the connection.

A good rule of thumb is that if the Windows '95 dialer can set up a connection by just clicking the "Connect" button this sample configuration should work OK.

If, on the other hand, when you connect to your ISP using Microsoft Windows '95 Dial-Up Networking you need to resort to using the "Dial Up Scripting Tool" from the Microsoft Plus! pack or you have to select "Bring up a terminal windows after dialing" in the Windows '95 connection options then you'll need to look at the sample PPP configuration files and the ppp manpage for examples of "expect / response" scripting to make your ISP connection.

Or even better, find an ISP who knows how to provide PAP or CHAP authentication!

The configuration examples shown here have been successfully used to connect to:

Various Shiva LanRovers
AT&T WorldNet (http://att.com/worldnet)
Erol's (http://www.erols.com)
The IBM Network (http://www.ibm.net)
NetCom (http://www.netcom.com)

Following are descriptions for each line in the "interactive" section of the sample '/etc/ppp/ppp.conf' file:


set authname Your_User_ID_On_Remote_System

This line specifies the name you would use to log in to the remote system.


set authkey Your_Password_On_Remote_System

This is the password you'd use to log in to the remote system.


set phone 1-800-123-4567

This is the phone number of the remote system. If you're inside a PBX you can prepend '9, ' to the number here.


set timeout 300

This tells the PPP program that it should automatically hang up the phone if no data has be exchanged for 300 seconds (5 minutes). You may wish to tailor this number to your specific requirements.


set openmode active

This tells the PPP program that once the modems are connected it should immediately attempt to negotiate the connection. Some remote sites do this automatically, some don't. This instructs your side of the link to take the initiative and try to set up the connection.


accept chap

This tells the PPP program to use the "Challenge-Handshake Authentication Protocol" to authenticate you. The values exchanged between the local and remote side for UserID and password are taken from the 'authname' and 'authkey' entries above.

4.2.1.3. The "`demand`" Section

The "demand" section contains the values and settings used to set up a "Dial-on-demand" PPP session with a specific remote system. Settings in this section will also have the lines included in the "default" section included automatically.

Except for the last two lines in this section it is identical to the configuration section which defines the "interactive" configuration.

As noted in Paragraph ???, the examples cited in this section of the guide presume that you'll be connecting to a remote system that understands how to use the CHAP protocol to set up the connection.

Following are descriptions for each line in the "demand" section of the sample '/etc/ppp/ppp.conf' file:


set authname Your_User_ID_On_Remote_System

This line specifies the name you would use to log in to the remote system.


set authkey Your_Password_On_Remote_System

This is the password you'd use to log in to the remote system.


set phone 1-800-123-4567

This is the phone number of the remote system.


set timeout 300

This tells the PPP program that it should automatically hang up the phone if no data has be exchanged for 300 seconds (5 minutes). You may wish to tailor this number to your specific requirements.


set openmode active


accept chap


set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0

This command sets up a pair of "fake" IP addresses for the local and remote sides of the PPP link. It instructs the PPP program to create an IP address of 127.1.1.1 for the local side of the 'tun0' (tunnel) device (refer back to section ?? for a description of this device) and 127.2.2.2 for the remote side. Appending '/0' to each address tells the PPP program that zero of the bits that make up these addresses are significant and can (in fact, must!) be negotiated between the local and remote systems when the link is established. The 255.255.255.0 string tells the PPP program what Subnet mask to apply to these pseudo-interfaces.

Remember, we've assumed that your ISP provides the IP addresses for both ends of the link! If your ISP assigned you a specific IP address that you should use on your side when configuring your system, enter that IP address here instead of 127.1.1.1.

Conversly, if your ISP gave you a specific IP address that he uses on his end you should enter that IP address here instead of 127.2.2.2.

In both cases, it's probably a good idea to leave the '/0' on the end of each address. This gives the PPP program the opportunity to change the address(es) of the link if it has to.


add 0 0 127.2.2.2

This last line tells the PPP program that it should add a default route for IP traffic that points to the (fake) IP address of the ISP's system.

*** Note: If you used an ISP-specified address instead of 127.2.2.2 on the preceeding line, use the same number here instead of 127.2.2.2.

By adding this "fake" route for IP traffic, the PPP program can, while idle:

Accept packets that FreeBSD doesn't already know how to forward,
Establish a connection to the ISP "on-the-fly",
Reconfigure the IP addresses of the local and remote side of the link,
Forward packets between your workstation and the ISP.

automatically!

Once the number of seconds specified by the timeout value in the "default" section have elapsed without any TCP/IP traffic the PPP program will automatically close the dial-up connection and the process will begin again.

4.2.1. The '/etc/ppp/ppp.conf' file

4.2.1.1. The "default" Section

4.2.1.2. The "interactive" Section

4.2.1.3. The "demand" Section

4.2.1. The '`/etc/ppp/ppp.conf`' file

4.2.1.1. The "`default`" Section

4.2.1.2. The "`interactive`" Section

4.2.1.3. The "`demand`" Section