If your connection to the Internet is through a modem, or you wish to provide other people with dialup connections to the Internet using FreeBSD, you have the option of using PPP or SLIP. Furthermore, two varieties of PPP are provided: user (sometimes referred to as iijppp) and kernel. The procedures for configuring both types of PPP, and for setting up SLIP are described in this chapter.
User PPP was introduced to FreeBSD in release 2.0.5 as an addition to the existing kernel implementation of PPP. So, what is different about this new PPP that warrants its addition? To quote from the manual page:
This is a user process PPP software package. Normally, PPP is implemented as a part of the kernel (e.g. as managed by pppd) and it is thus somewhat hard to debug and/or modify its behavior. However, in this implementation PPP is done as a user process with the help of the tunnel device driver (tun).
In essence, this means that rather than running a PPP daemon, the ppp program can be run as and when desired. No PPP interface needs to be compiled into the kernel, as the program can use the generic tunnel device to get data into and out of the kernel.
From here on out, user ppp will be referred to simply as ppp unless a distinction needs to be made between it and any other PPP client/server software such as pppd. Unless otherwise stated, all commands in this section should be executed as root.
There are a large number of enhancements in version 2 of ppp. You can discover what version you have by running ppp with no arguments and typing show version at the prompt. It is a simple matter to upgrade to the latest version of ppp (under any version of FreeBSD) by downloading the latest archive via www.Awfulhak.org.
This document assumes you are in roughly this position:
You have an account with an Internet Service Provider (ISP) which lets you use PPP. Further, you have a modem (or other device) connected and configured correctly which allows you to connect to your ISP.
You are going to need the following information to hand:
Your ISPs phone number(s).
Your login name and password. This can be either a regular unix style login/password pair, or a PPP PAP or CHAP login/password pair.
The IP addresses of one or more nameservers. Normally, you will be given two IP numbers. You must have this information for PPP version 1.x unless you run your own nameserver. From version 2 onwards, PPP supports nameserver address negotiation. If your ISP supports this, then using the command enable dns in your config file will tell PPP to set the nameservers for you.
The following information may have been supplied by your ISP, but is not strictly 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 your ISP hasn't given you this number, 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.
Your ISP's netmask. If your ISP hasn't given you this information, you can safely use a netmask of 255.255.255.0.
If your ISP allocates you a static IP address and hostname then you can enter this information. Otherwise, we simply let the peer assign whatever IP number it sees fit.
If you do not have any of the required information, contact your ISP and make sure they provide it to you.
As the description states, ppp uses the kernel tun device. It is necessary to make sure that your kernel has support for this device compiled in.
To check this, go to your kernel compile directory (/sys/i386/conf or /sys/pc98/conf) and examine your kernel configuration file. It needs to have the line
pseudo-device tun 1
in it somewhere. The stock
GENERIC kernel has this as standard, so if you have
not installed a custom kernel or you do not have a /sys directory, you do not have to
change anything.
If your kernel configuration file does not have this line in it, or you need to configure more than one tun device (for example, if you are setting up a server and could have 16 dialup ppp connections at any one time then you will need to use 16 instead of 1), then you should add the line, re-compile, re-install and boot the new kernel. Please refer to the Configuring the FreeBSD Kernel section for more information on kernel configuration.
You can check how many tunnel devices your current kernel has by typing the following:
# ifconfig -a
tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
inet 200.10.100.1 --> 203.10.100.24 netmask 0xffffffff
tun1: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 576
tun2: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
inet 203.10.100.1 --> 203.10.100.20 netmask 0xffffffff
tun3: flags=8010<POINTOPOINT,MULTICAST> mtu 1500
This case shows four tunnel devices, two of which are currently configured and being used. It should be noted that the RUNNING flag above indicates that the interface has been used at some point---it is not an error if your interface does not show up as RUNNING.
If you have a kernel without the tun device, and you can not rebuild it for some reason, all is not lost. You should be able to dynamically load the code. Refer to the appropriate modload(8) and lkm(4) pages for further details.
You may also wish to take this opportunity to configure a firewall. Details can be found in the Firewalls section.
Most users will only require one tun device (/dev/tun0). If you have used more (i.e., a number other than 1 in the pseudo-device line in the kernel configuration file) then alter all references to tun0 below to reflect whichever device number you are using.
The easiest way to make sure that the tun0 device is configured correctly is to re-make it. To do this, execute the following commands:
# cd /dev
# ./MAKEDEV tun0
If you require 16 tunnel devices in your kernel, you will need to create more than just tun0:
# cd /dev
# ./MAKEDEV tun15
Also, to confirm that the kernel is configured correctly, the following command should give the indicated output:
# ifconfig tun0
tun0: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 1500
The RUNNING flag may not yet be set, in which case you will see:
# ifconfig tun0
tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500
The resolver is the part of the system that turns IP addresses into hostnames and vice versa. It can be configured to look for maps that describe IP to hostname mappings in one of two places. The first is a file called /etc/hosts (man 5 hosts). The second is the Internet Domain Name Service (DNS), a distributed data base, the discussion of which is beyond the scope of this document.
This section describes briefly how to configure your resolver.
The resolver is a set of system calls that do the name mappings, but you have to tell them where to find their information. You do this by first editing the file /etc/host.conf. Do not call this file /etc/hosts.conf (note the extra s) as the results can be confusing.
This file should contain the following two lines (in this order):
hosts
bind
These instructs the resolver to first look in the file /etc/hosts, and then to consult the DNS if the name was not found.
This file should contain the IP addresses and names of machines on your network. At a bare minimum it should contain entries for the machine which will be running ppp. Assuming that your machine is called foo.bar.com with the IP address 10.0.0.1, /etc/hosts should contain:
127.0.0.1 localhost
10.0.0.1 foo.bar.com foo
The first line defines the alias localhost as a synonym for the current machine. Regardless of your own IP address, the IP address for this line should always be 127.0.0.1. The second line maps the name foo.bar.com (and the shorthand foo) to the IP address 10.0.0.1.
If your provider allocates you a static IP address and name, then use these in place of the 10.0.0.1 entry.
/etc/resolv.conf tells the resolver how to behave. If you are running your own DNS, you may leave this file empty. Normally, you will need to enter the following line(s):
nameserver x.x.x.x
nameserver y.y.y.y
domain bar.com
The x.x.x.x and y.y.y.y addresses are those given to you by your ISP. Add as many nameserver lines as your ISP provides. The domain line defaults to your hostname's domain, and is probably unnecessary. Refer to the resolv.conf manual page for details of other possible entries in this file.
If you are running PPP version 2 or greater, the enable dns command will tell PPP to request that your ISP confirms the nameserver values. If your ISP supplies different addresses (or if there are no nameserver lines in /etc/resolv.conf), PPP will rewrite the file with the ISP-supplied values.
Both user ppp and pppd (the kernel level implementation of PPP) use configuration files located in the /etc/ppp directory. The sample configuration files provided are a good reference for user ppp, so don't delete them.
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 can be different for each PPP session).
You will need to create a configuration file called /etc/ppp/ppp.conf. It should look similar to the example below.
Note: Lines that end in a : start in the first column, all other lines should be indented as shown using spaces or tabs.
1 default:
2 set device /dev/cuaa0
3 set speed 115200
4 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0 OK-AT-OK \\dATDT\\TTIMEOUT 40 CONNECT"
5 provider:
6 set phone "(0123) 456 7890"
7 set login "TIMEOUT 10 \"\" \"\" gin:--gin: foo word: bar col: ppp"
8 set timeout 300
9 set ifaddr x.x.x.x y.y.y.y 255.255.255.0 0.0.0.0
10 add default HISADDR
11 enable dns
Do not include the line numbers, they are just for reference in this discussion.
Identifies the default entry. Commands in this entry are executed automatically when ppp is run.
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 doesn't 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.
Identifies an entry for a provider called ``provider''.
Sets the phone number for this provider. Multiple phone numbers may be specified using the : or | character as a separator. The difference between these separators is described in ppp(8). To summarize, if you want to rotate through the numbers, use the :. 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 |. Always quote the entire set of phone numbers as shown.
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 enable ``chat'' logging to ensure that the conversation is going as expected.
If you're using PAP or CHAP, there will be no login at this point, so your login string can be left blank. See PAP and CHAP authentication for further details.
Sets the default 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.
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 hasn't 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 or -dynamic mode.
Adds a default route to your ISPs 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.
This line tells PPP to ask your ISP to confirm that your nameserver addresses are correct. If your ISP supports this facility, PPP can then update /etc/resolv.conf with the correct nameserver entries.
It is not necessary to add an entry to ppp.linkup when you have a static IP address 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 /etc/ppp directory.
If your service provider does not assign static IP numbers, ppp can be configured to negotiate the local and remote addresses. This is done by ``guessing'' an IP number 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:
9 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0
Again, do not include the line numbers, they are just for reference in this discussion. 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 negotiate using address 0.0.0.0 rather than 10.0.0.1. 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 running version 1.x of PPP, you will also 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 know what IP addresses should really be used. The following entry will delete the existing bogus routes, and create correct ones:
1 provider:
2 delete ALL
3 add 0 0 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 number of our gateway. This entry is a four-octet IP style label. If we still haven't found an entry, look for the MYADDR entry.
This line tells ppp to delete all existing routes for the acquired tun interface (except the direct route 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 in the IPCP.
See the pmdemand entry in the files /etc/ppp/ppp.conf.sample and /etc/ppp/ppp.linkup.sample for a detailed example.
Version 2 of PPP introduces ``sticky routes''. Any add or delete lines that contain MYADDR or HISADDR will be remembered, and any time the actual values of MYADDR or HISADDR change, the routes will be re-applied. This removes the necessity of repeating these lines in ppp.linkup.
This section describes setting up ppp in a server role.
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 ppp.conf file. You
should also confirm that the
/etc/rc.conf file (this file used to be called /etc/sysconfig) contains the
following:
gateway=YES
Configuring FreeBSD for Dialup Services provides a good description on enabling dialup services using getty.
An alternative to getty is mgetty, a smarter version of getty designed with dialup 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 won't 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.
ppp must normally be run as user id 0. 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 your dialup ppp users. This is an example from /etc/password for a dialup PPP user with username pchilds. (remember don't 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. (ie. 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 /etc/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
enable passwdauth
option to authenticate users via pap from the /etc/password file.
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 /etc/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's 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
As always, do not include the line numbers, they are just for reference in this discussion. Indentation of at least one space is required.
Your ISP will not normally require that you log into the server if you're 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
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.
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 (was /etc/sysconfig).
Working from the top down in this file, make sure the hostname= line is set, e.g.:
hostname=foo.bar.com
If your ISP has supplied you with a static IP address and name, it's 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 the line
router_enable=NO (/etc/rc.conf)
router=NO (/etc/sysconfig)
It is important that the routed daemon is not started (it's 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 upshot 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 don't like this, it is possible to set up a ``dfilter'' to block SMTP traffic. Refer to the sample files for further details.
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 haven't 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 (or sysconfig) 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 (or sysconfig) file.
This section of the handbook was last updated on Monday Aug 10, 1998 by Brian Somers <brian@FreeBSD.org>
Thanks to the following for their input, comments & suggestions:
Nik Clayton <nik@FreeBSD.org>
Dirk-Willem van Gulik <Dirk.vanGulik@jrc.it>
Peter Childs <pjchilds@imforei.apana.org.au>