This document assumes you have the following:
An account with an Internet Service Provider (ISP) which you connect to using PPP.
You have a modem or other device connected to your system and configured correctly which allows you to connect to your ISP.
The dial-up number(s) of your ISP.
Your login name and password. (Either a regular Unix-style login and password pair, or a PAP or CHAP login and password pair.)
The IP address of one or more name servers. Normally, you will be given two IP addresses by your ISP to use for this. If they have not given you at least one, then you can use the enable dns command in ppp.conf and ppp will set the name servers for you. This feature depends on your ISPs PPP implementation supporting DNS negotiation.
The following information may be supplied by your ISP, but is not completely necessary:
The IP address of your ISP's gateway. The gateway is the machine to which you will connect and will be set up as your default route. If you do not have this information, we can make one up and your ISP's PPP server will tell us the correct value when we connect.
This IP number is referred to as HISADDR by ppp.
The netmask you should use. If your ISP has not provided you with one, you can safely use 255.255.255.255.
If your ISP provides you with a static IP address and hostname, you can enter it. Otherwise, we simply let the peer assign whatever IP address it sees fit.
If you do not have any of the required information, contact your ISP.
Note: Throughout this section, many of the examples showing the contents of configuration files are numbered by line. These numbers serve to aid in the presentation and discussion only and are not meant to be placed in the actual file. Proper indentation with tab and space characters is also important.
Under normal circumstances, most users will only use one tun device (/dev/tun0). References to tun0 below may be changed to tunN where N is any unit number corresponding to your system.
For FreeBSD installations that do not have devfs(5) enabled (FreeBSD 4.X and earlier), the existence of the tun0 device should be verified (this is not necessary if devfs(5) is enabled as device nodes will be created on demand).
The easiest way to make sure that the tun0 device is configured correctly is to remake the device. To remake the device, do the following:
# cd /dev
# sh MAKEDEV tun0
If you need 16 tunnel devices in your kernel, you will need to create them. This can be done by executing the following commands:
# cd /dev
# sh MAKEDEV tun15
If you reconfigured your kernel then you recall the sio device. If your modem acts like a standard serial port then you most likely only need to make the serial device. You can do this by changing your directory to /dev and running the MAKEDEV script like above. Now make the serial devices with
# sh MAKEDEV cuaa0 cuaa1 cuaa2 cuaa3
which will create the serial devices for your system.
If your modem is on sio1 or
COM2 if you are in DOS,
then your modem device would be /dev/cuaa1. 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 your ISP handles connections. Lets start PPP from the command line, note that, in all of our examples we will use localhost as the hostname of the machine running PPP. You start ppp by just typing ppp:
# ppp
We have now started ppp.
ppp ON example> set device /dev/cuaa1
We set our modem device, in this case it is cuaa1.
ppp ON example> set speed 115200
Set the connection speed, in this case we are using 115,200 kbps.
ppp ON example> enable dns
Tell ppp to configure our resolver and add the nameserver lines to /etc/resolv.conf. If ppp cannot determine our hostname, we can set one manually later.
ppp ON example> term
Switch to ``terminal'' mode so that we can manually control the modem.
deflink: Entering terminal mode on /dev/cuaa1
type '~h' for help
at
OK
atdt123456789
Use at to initialize the modem, then use atdt and the number for your ISP to begin the dial in process.
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.
ISP Login:myusername
Here you are prompted for a username, return the prompt with the username that was provided by the ISP.
ISP Pass:mypassword
This time we are prompted for a password, just reply with the password that was provided by the ISP. Just like when logging into FreeBSD, the password will not echo.
Shell or PPP:ppp
Depending on your ISP this prompt may never appear. Here we are being asked if we wish to use a shell on the provider, or to start ppp. In this example, we have chosen to use ppp as we want an internet connection.
Ppp ON example>
Notice that in this example the first p has been capitalized. This shows that we have successfully connected to the ISP.
PPp ON example>
We have successfully authenticated with our ISP and are waiting for the assigned IP address.
PPP ON example>
We have made an agreement on an IP address and successfully completed our connection.
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 you can put a bang character ! in front of the add. Alternatively, you can 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 CTRL+z If you notice the PPP return to ppp then we have lost our connection. This is good to know because it shows our connection status. Capital P's show that we have a connection to the ISP and lowercase p's show that the connection has been lost for whatever reason. ppp only has these 2 states.
Like everything else, once in awhile a problem or may occur. PPP is no exemption to this theory. If ppp would happen to stop responding there are some things we can try.
If you have a direct line and cannot seem to make a connection, then turn hardware flow CTS/RTS to off with the set ctsrts off. This is mainly the case if you are connected to some PPP capable terminal servers, where PPP hangs when it tries to write data to your communication link, so it would be waiting for a CTS, or Clear To Send signal which may never come. If you use this option however, you should also use the set accmap option, which may be required to defeat hardware dependent on passing certain characters from end to end, most of the time XON/XOFF. See the ppp(8) manual page for more information on this option, and how it is used.
If you have an older modem, you may need to use the 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 and some ISPs. You may need this option for the Compuserve ISP.
PPP may not return to the command mode, which is usually a negotiation error where the ISP is waiting for your side to start negotiating. At this point, using the ~p command will force ppp to start sending the configuration information.
If you never obtain a login prompt, then most likely you need to use PAP or CHAP authentication instead of the Unix-style in the example above. To use PAP or CHAP just add the following options to PPP before going into terminal mode:
ppp ON localhost> set authname myusername
Where myusername should be replaced with the username that was assigned by the ISP.
ppp ON localhost> set authkey mypassword
Where mypassword should be replaced with the password that was assigned by the ISP.
If you connect fine, but cannot seem to find any domain name, try to use ping(8) with an IP address and see if you can get any return information. If you experience 100 percent (100%) packet loss, then its most likely that you were not assigned a default route. Double check that the option add default HISADDR was set during the connection. If you can connect to a remote IP address then it is possible that a resolver address has not been added to the /etc/resolv.conf. This file should look like:
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 your ISP's DNS servers. This information may or may not have been provided when you signed up, but a quick call to your ISP should remedy that.
You could also have syslog(3) provide a logging function for your PPP connection. Just add:
!ppp
*.* /var/log/ppp.log
to /etc/syslog.conf. In most cases, this functionality already exists.
Both ppp and pppd (the kernel level implementation of PPP) use the configuration files located in the /etc/ppp directory. Examples for user ppp can be found in /usr/share/examples/ppp/.
Configuring ppp requires that you edit a number of files, depending on your requirements. What you put in them depends to some extent on whether your ISP allocates IP addresses statically (i.e., you get given one IP address, and always use that one) or dynamically (i.e., your IP address changes each time you connect to your ISP).
You will need to edit the /etc/ppp/ppp.conf configuration file. It should look similar to the example below.
Note: Lines that end in a : start in the first column (beginning of the line)-- all other lines should be indented as shown using spaces or tabs. Most of the information you need to provide here was shown to us by doing the manual dial above.
1 default:
2 set log Phase Chat LCP IPCP CCP tun command
3 ident user-ppp VERSION (built COMPILATIONDATE)
4 set device /dev/cuaa0
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 login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp"
16 set timeout 300
17 set ifaddr x.x.x.x y.y.y.y 255.255.255.255 0.0.0.0
18 add default HISADDR
Identifies the default entry. Commands in this entry are executed automatically when ppp is run.
Enables logging parameters. When the configuration is working satisfactorily, this line should be reduced to saying
set log phase tun
in order to avoid excessive log file sizes.Tells PPP how to identify itself to the peer. PPP identifies itself to the peer if it has any trouble negotiating and setting up the link, providing information that the peers administrator may find useful when investigating such problems.
Identifies the device to which the modem is connected. COM1 is /dev/cuaa0 and COM2 is /dev/cuaa1.
Sets the speed you want to connect at. If 115200 does not work (it should with any reasonably new modem), try 38400 instead.
The dial string. User PPP uses an expect-send syntax similar to the chat(8) program. Refer to the manual page for information on the features of this language.
Note that this command continues onto the next line for readability. Any command in ppp.conf may do this if the last character on the line is a ``\'' character.
Sets the idle timeout for the link. 180 seconds is the default, so this line is purely cosmetic.
Tells PPP to ask the peer to confirm the local resolver settings. If you run a local name server, this line should be commented out or removed.
A blank line for readability. Blank lines are ignored by PPP.
Identifies an entry for a provider called ``provider''. This could be changed to the name of your ISP so that later you can use the load ISP to start the connection.
Sets the phone number for this provider. Multiple phone numbers may be specified using the colon (:) or pipe character (|)as a separator. The difference between the two separators is described in ppp(8). To summarize, if you want to rotate through the numbers, use a colon. If you want 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 quote the entire set of phone numbers as shown.
You must enclose the phone number in quotation marks (") if there is any intention on using spaces in the phone number. This can cause a simple, yet subtle error.
Identifies the user name and password. When connecting using a Unix-style login prompt, these values are referred to by the set login command using the \U and \P variables. When connecting using PAP or CHAP, these values are used at authentication time.
If you are using PAP or CHAP, there will be no login at this point, and this line should be commented out or removed. See PAP and CHAP authentication for further details.
The login string is of the same chat-like syntax as the dial string. In this example, the string works for a service whose login session looks like this:
J. Random Provider
login: foo
password: bar
protocol: ppp
You will need to alter this script to suit your own needs. When you write this script for the first time, you should ensure that you have enabled ``chat'' logging so you can determine if the conversation is going as expected.
Sets the default idle timeout (in seconds) for the connection. Here, the connection will be closed automatically after 300 seconds of inactivity. If you never want to timeout, set this value to zero or use the -ddial command line switch.
Sets the interface addresses. The string x.x.x.x should be replaced by the IP address that your provider has allocated to you. The string y.y.y.y should be replaced by the IP address that your ISP indicated for their gateway (the machine to which you connect). If your ISP has not given you a gateway address, use 10.0.0.2/0. If you need to use a ``guessed'' address, make sure that you create an entry in /etc/ppp/ppp.linkup as per the instructions for PPP and Dynamic IP addresses. If this line is omitted, ppp cannot run in -auto mode.
Adds a default route to your ISP's gateway. The special word HISADDR is replaced with the gateway address specified on line 9. It is important that this line appears after line 9, otherwise HISADDR will not yet be initialized.
If you do not wish to run ppp in -auto, this line should be moved to the ppp.linkup file.
It is not necessary to add an entry to ppp.linkup when you have a static IP address and are running ppp in -auto mode as your routing table entries are already correct before you connect. You may however wish to create an entry to invoke programs after connection. This is explained later with the sendmail example.
Example configuration files can be found in the /usr/share/examples/ppp/ directory.
If your service provider does not assign static IP addresses, ppp can be configured to negotiate the local and remote addresses. This is done by ``guessing'' an IP address and allowing ppp to set it up correctly using the IP Configuration Protocol (IPCP) after connecting. The ppp.conf configuration is the same as PPP and Static IP Addresses, with the following change:
17 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.255
Again, do not include the line number, it is just for reference. Indentation of at least one space is required.
The number after the / character is the number of bits of the address that ppp will insist on. You may wish to use IP numbers more appropriate to your circumstances, but the above example will always work.
The last argument (0.0.0.0) tells PPP to start negotiations using address 0.0.0.0 rather than 10.0.0.1 and is necessary for some ISPs. Do not use 0.0.0.0 as the first argument to set ifaddr as it prevents PPP from setting up an initial route in -auto mode.
If you are not running in -auto mode, you will need to create an entry in /etc/ppp/ppp.linkup. ppp.linkup is used after a connection has been established. At this point, ppp will have assigned the interface addresses and it will now be possible to add the routing table entries:
1 provider:
2 add default HISADDR
On establishing a connection, ppp will look for an entry in ppp.linkup according to the following rules: First, try to match the same label as we used in ppp.conf. If that fails, look for an entry for the IP address of our gateway. This entry is a four-octet IP style label. If we still have not found an entry, look for the MYADDR entry.
This line tells ppp to add a default route that points to HISADDR. HISADDR will be replaced with the IP number of the gateway as negotiated by the IPCP.
See the pmdemand entry in the files /usr/share/examples/ppp/ppp.conf.sample and /usr/share/examples/ppp/ppp.linkup.sample for a detailed example.
When you configure ppp to receive incoming calls on a machine connected to a LAN, you must decide if you wish to forward packets to the LAN. If you do, you should allocate the peer an IP number from your LAN's subnet, and use the command enable proxy in your /etc/ppp/ppp.conf file. You should also confirm that the /etc/rc.conf file contains the following:
gateway_enable="YES"
Configuring FreeBSD for Dial-up Services provides a good description on enabling dial-up services using getty(8).
An alternative to getty is mgetty, 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 /etc/ttys then your modem will not answer the phone.
Later versions of mgetty (from 0.99beta onwards) also support the automatic detection of PPP streams, allowing your clients script-less access to your server.
Refer to Mgetty and AutoPPP for more information on mgetty.
The ppp command must normally be run as the root user. If however, you wish to allow ppp to run in server mode as a normal user by executing ppp as described below, that user must be given permission to run ppp by adding them to the network group in /etc/group.
You will also need to give them access to one or more sections of the configuration file using the allow command:
allow users fred mary
If this command is used in the default section, it gives the specified users access to everything.
Create a file called /etc/ppp/ppp-shell containing the following:
#!/bin/sh
IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'`
CALLEDAS="$IDENT"
TTY=`tty`
if [ x$IDENT = xdialup ]; then
IDENT=`basename $TTY`
fi
echo "PPP for $CALLEDAS on $TTY"
echo "Starting PPP for $IDENT"
exec /usr/sbin/ppp -direct $IDENT
This script should be executable. Now make a symbolic link called ppp-dialup to this script using the following commands:
# ln -s ppp-shell /etc/ppp/ppp-dialup
You should use this script as the shell for all of your dialup users. This is an example from /etc/password for a dialup PPP user with username pchilds (remember do not directly edit the password file, use vipw).
pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup
Create a /home/ppp directory that is world readable containing the following 0 byte files:
-r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin
-r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts
which prevents /etc/motd from being displayed.
Create the ppp-shell file as above, and for each account with statically assigned IPs create a symbolic link to ppp-shell.
For example, if you have three dialup customers, fred, sam, and mary, that you route class C networks for, you would type the following:
# ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred
# ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam
# ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary
Each of these users dialup accounts should have their shell set to the symbolic link created above (for example, mary's shell should be /etc/ppp/ppp-mary).
The /etc/ppp/ppp.conf file should contain something along the lines of:
default:
set debug phase lcp chat
set timeout 0
ttyd0:
set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255
enable proxy
ttyd1:
set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255
enable proxy
Note: The indenting is important.
The default: section is loaded for each session. For each dialup line enabled in /etc/ttys create an entry similar to the one for ttyd0: above. Each line should get a unique IP address from your pool of IP addresses for dynamic users.
Along with the contents of the sample /usr/share/examples/ppp/ppp.conf above you should add a section for each of the statically assigned dialup users. We will continue with our fred, sam, and mary example.
fred:
set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255
sam:
set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255
mary:
set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255
The file /etc/ppp/ppp.linkup should also contain routing information for each static IP user if required. The line below would add a route for the 203.14.101.0 class C via the client's ppp link.
fred:
add 203.14.101.0 netmask 255.255.255.0 HISADDR
sam:
add 203.14.102.0 netmask 255.255.255.0 HISADDR
mary:
add 203.14.103.0 netmask 255.255.255.0 HISADDR
Configuring and compiling mgetty with the AUTO_PPP option enabled allows 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 configured, compiled, and installed a version of mgetty with the AUTO_PPP option (v0.99beta or later).
Make sure your /usr/local/etc/mgetty+sendfax/login.config file has the following in it:
/AutoPPP/ - - /etc/ppp/ppp-pap-dialup
This will tell mgetty to run the ppp-pap-dialup script for detected PPP connections.
Create a file called /etc/ppp/ppp-pap-dialup containing the following (the file should be executable):
#!/bin/sh
exec /usr/sbin/ppp -direct pap$IDENT
For each dialup line enabled in /etc/ttys, create a corresponding entry in /etc/ppp/ppp.conf. This will happily co-exist with the definitions we created above.
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 /etc/ppp/ppp.secret file, or alternatively add the following option to authenticate users via PAP from /etc/password file.
enable passwdauth
If you wish to assign some users a static IP number, you can specify the number as the third argument in /etc/ppp/ppp.secret. See /usr/share/examples/ppp/ppp.secret.sample for examples.
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 /etc/ppp/ppp.conf.
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:
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 /etc/resolv.conf.
Some ISPs set their system up so that the authentication part of your connection is done using either of the PAP or CHAP authentication mechanisms. If this is the case, your ISP will not give a login: prompt when you connect, 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''.
Referring back to the PPP and Static IP addresses or PPP and Dynamic IP addresses sections, the following alterations must be made:
7 set login
...
12 set authname MyUserName
13 set authkey MyPassword
Your ISP will not normally require that you log into the server if you are using PAP or CHAP. You must therefore disable your ``set login'' string.
This line specifies your PAP/CHAP user name. You will need to insert the correct value for MyUserName.
This line specifies your PAP/CHAP password. You will need to insert the correct value for MyPassword. You may want to add an additional line, such as:
15 accept PAP
or
15 accept CHAP
to make it obvious that this is the intention, but PAP and CHAP are both accepted by default.
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 your configuration:
set server /var/run/ppp-tun%d DiagnosticPassword 0177
This will tell PPP to listen to the specified Unix-domain socket, asking clients for the specified password before allowing access. The %d in the name is replaced with the tun device number that is in use.
Once a socket has been set up, the pppctl(8) program may be used in scripts that wish to manipulate the running program.
PPP has ability to use internal NAT without kernel diverting capabilities. This functionality may be enabled by the following line in /etc/ppp/ppp.conf:
nat enable yes
Alternatively, PPP NAT may be enabled by command-line option -nat. There is also /etc/rc.conf knob named ppp_nat, which is enabled by default.
If you use this feature, you may also find useful the following /etc/ppp/ppp.conf options to enable incoming connections forwarding:
nat port tcp 10.0.0.2:ftp ftp
nat port tcp 10.0.0.2:http http
or don't trust the outside at all
nat deny_incoming yes
You now have ppp configured, but there are a few more things to do before it is ready to work. They all involve editing the /etc/rc.conf file.
Working from the top down in this file, make sure the hostname= line is set, e.g.:
hostname="foo.example.com"
If your ISP has supplied you with a static IP address and name, it is probably best that you use this name as your host name.
Look for the network_interfaces variable. If you want to configure your system to dial your ISP on demand, make sure the tun0 device is added to the list, otherwise remove it.
network_interfaces="lo0 tun0"
ifconfig_tun0=
Note: The ifconfig_tun0 variable should be empty, and a file called /etc/start_if.tun0 should be created. This file should contain the line:
ppp -auto mysystemThis script is executed at network configuration time, starting your ppp daemon in automatic mode. If you have a LAN for which this machine is a gateway, you may also wish to use the -alias switch. Refer to the manual page for further details.
Set the router program to NO with following line in your /etc/rc.conf:
router_enable="NO"
It is important that the routed daemon is not started (it is started by default), as routed tends to delete the default routing table entries created by ppp.
It is probably worth your while ensuring 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:
sendmail_flags="-bd"
The downside of this is that you must force sendmail to re-examine the mail queue whenever the ppp link is up by typing:
# /usr/sbin/sendmail -q
You may wish to use the !bg command in ppp.linkup to do this automatically:
1 provider:
2 delete ALL
3 add 0 0 HISADDR
4 !bg sendmail -bd -q30m
If you do not like this, it is possible to set up a ``dfilter'' to block SMTP traffic. Refer to the sample files for further details.
Now the only thing left to do is reboot the machine.
All that is left is to reboot the machine. After rebooting, you can now either type:
# ppp
and then dial provider to start the PPP session, or, if you want ppp to establish sessions automatically when there is outbound traffic (and you have not created the start_if.tun0 script), type:
# ppp -auto provider
To recap, the following steps are necessary when setting up ppp for the first time:
Client side:
Ensure that the tun device is built into your kernel.
Ensure that the tunX device file is available in the /dev directory.
Create an entry in /etc/ppp/ppp.conf. The pmdemand example should suffice for most ISPs.
If you have a dynamic IP address, create an entry in /etc/ppp/ppp.linkup.
Update your /etc/rc.conf file.
Create a start_if.tun0 script if you require demand dialing.
Server side:
Ensure that the tun device is built into your kernel.
Ensure that the tunX device file is available in the /dev directory.
Create an entry in /etc/passwd (using the vipw(8) program).
Create a profile in this users home directory that runs ppp -direct direct-server or similar.
Create an entry in /etc/ppp/ppp.conf. The direct-server example should suffice.
Create an entry in /etc/ppp/ppp.linkup.
Update your /etc/rc.conf file.
This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.
For questions about FreeBSD, read the
documentation
before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.