3 ## 18.2 Using User PPP
\r
5 ***Updated and enhanced by Tom Rhodes. ' **Originally contributed by Brian Somers.** 'With input from Nik Clayton, Dirk Fr�mberg, and Peter Childs. ***
\r
9 #### 18.2.1.1 Assumptions
\r
11 This document assumes you have the following:
\r
14 * An account with an Internet Service Provider (ISP) which you connect to using PPP.
\r
16 * You have a modem or other device connected to your system and configured correctly which allows you to connect to your ISP.
\r
18 * The dial-up number(s) of your ISP.
\r
20 * Your login name and password. (Either a regular UNIX® style login and password pair, or a PAP or CHAP login and password pair.)
\r
22 * 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.
\r
24 The following information may be supplied by your ISP, but is not completely necessary:
\r
27 * 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.
\r
28 This IP number is referred to as `HISADDR` by **ppp** .
\r
30 * The netmask you should use. If your ISP has not provided you with one, you can safely use `255.255.255.255`.
\r
32 * 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.
\r
34 If you do not have any of the required information, contact your ISP.
\r
36 **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.
\r
38 #### 18.2.1.2 Creating PPP Device Nodes
\r
40 Under normal circumstances, most users will only need one `tun` device (`/dev/tun0`). References to `tun0` below may be changed to `tun`***N****** where `***N***` is any unit number corresponding to your system.
\r
42 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:
\r
49 If you need 16 tunnel devices in your kernel, you will need to create them. This can be done by executing the following commands:
\r
56 #### 18.2.1.3 Automatic **PPP** Configuration
\r
58 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/`.
\r
60 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).
\r
62 ##### 18.2.1.3.1 PPP and Static IP Addresses
\r
64 You will need to edit the `/etc/ppp/ppp.conf` configuration file. It should look similar to the example below.
\r
66 **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.
\r
70 2 set log Phase Chat LCP IPCP CCP tun command
\r
71 3 ident user-ppp VERSION (built COMPILATIONDATE)
\r
72 4 set device /dev/cuaa0
\r
74 6 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \
\r
75 7 \"\" AT OK-AT-OK ATE1Q0 OK \\dATDT\\T TIMEOUT 40 CONNECT"
\r
80 12 set phone "(123) 456 7890"
\r
83 15 set login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp"
\r
85 17 set ifaddr `***x.x.x.x***` `***y.y.y.y***` 255.255.255.255 0.0.0.0
\r
86 18 add default HISADDR
\r
89 Line 1::: Identifies the default entry. Commands in this entry are executed automatically when ppp is run.Line 2::: Enables logging parameters. When the configuration is working satisfactorily, this line should be reduced to saying
\r
93 in order to avoid excessive log file sizes.Line 3::: 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.Line 4::: Identifies the device to which the modem is connected. `COM1` is `/dev/cuaa0` and `COM2` is `/dev/cuaa1`.Line 5::: Sets the speed you want to connect at. If 115200 does not work (it should with any reasonably new modem), try 38400 instead.Line 6 & 7::: The dial string. User PPP uses an expect-send syntax similar to the [chat(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#chat§ion8) program. Refer to the manual page for information on the features of this language.
\r
94 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.Line 8::: Sets the idle timeout for the link. 180 seconds is the default, so this line is purely cosmetic.Line 9::: 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.Line 10::: A blank line for readability. Blank lines are ignored by PPP.Line 11::: 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.Line 12::: 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)](http://leaf.dragonflybsd.org/cgi/web-man?command#ppp§ion8). 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.
\r
95 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.Line 13 & 14::: 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.Line 15::: 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](userppp.html#USERPPP-PAPNCHAP) for further details.
\r
96 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:
\r
100 password: `***bar***`
\r
103 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.Line 16::: 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.Line 17::: 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](userppp.html#USERPPP-DYNAMICIP). If this line is omitted, `ppp` cannot run in `-auto` mode.Line 18::: Adds a default route to your ISP's gateway. The special word `HISADDR` is replaced with the gateway address specified on line 17. It is important that this line appears after line 17, otherwise `HISADDR` will not yet be initialized.
\r
104 If you do not wish to run ppp in `-auto`, this line should be moved to the `ppp.linkup` file.
\r
106 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.
\r
108 Example configuration files can be found in the `/usr/share/examples/ppp/` directory.
\r
110 ##### 18.2.1.3.2 PPP and Dynamic IP Addresses
\r
112 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](userppp.html#USERPPP-STATICIP), with the following change:
\r
115 17 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.255
\r
118 Again, do not include the line number, it is just for reference. Indentation of at least one space is required.
\r
120 Line 17::: 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.
\r
121 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.
\r
123 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:
\r
127 2 add default HISADDR
\r
130 Line 1::: 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.Line 2::: 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.
\r
132 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.
\r
134 ##### 18.2.1.3.3 Receiving Incoming Calls
\r
136 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:
\r
139 gateway_enable="YES"
\r
142 ##### 18.2.1.3.4 Which getty?
\r
144 [dialup.html Configuring DragonFly for Dial-up Services] provides a good description on enabling dial-up services using [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#getty§ion8).
\r
146 An alternative to `getty` is [mgetty](http://www.leo.org/~doering/mgetty/index.html), a smarter version of `getty` designed with dial-up lines in mind.
\r
148 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.
\r
150 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.
\r
152 Refer to [ Mgetty and AutoPPP](userppp.html#USERPPP-MGETTY) for more information on `mgetty`.
\r
154 ##### 18.2.1.3.5 **PPP** Permissions
\r
156 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`.
\r
158 You will also need to give them access to one or more sections of the configuration file using the `allow` command:
\r
161 allow users fred mary
\r
164 If this command is used in the `default` section, it gives the specified users access to everything.
\r
166 ##### 18.2.1.3.6 PPP Shells for Dynamic-IP Users
\r
168 Create a file called `/etc/ppp/ppp-shell` containing the following:
\r
172 IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'`
\r
176 if [ x$IDENT = xdialup ]; then
\r
177 IDENT=`basename $TTY`
\r
180 echo "PPP for $CALLEDAS on $TTY"
\r
181 echo "Starting PPP for $IDENT"
\r
183 exec /usr/sbin/ppp -direct $IDENT
\r
186 This script should be executable. Now make a symbolic link called `ppp-dialup` to this script using the following commands:
\r
189 # ln -s ppp-shell /etc/ppp/ppp-dialup
\r
192 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`).
\r
195 pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup
\r
198 Create a `/home/ppp` directory that is world readable containing the following 0 byte files:
\r
201 -r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin
\r
202 -r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts
\r
205 which prevents `/etc/motd` from being displayed.
\r
207 ##### 18.2.1.3.7 PPP Shells for Static-IP Users
\r
209 Create the `ppp-shell` file as above, and for each account with statically assigned IPs create a symbolic link to `ppp-shell`.
\r
211 For example, if you have three dialup customers, `fred`, `sam`, and `mary`, that you route class C networks for, you would type the following:
\r
214 # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred
\r
215 # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam
\r
216 # ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary
\r
219 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`).
\r
221 ##### 18.2.1.3.8 Setting Up `ppp.conf` for Dynamic-IP Users
\r
223 The `/etc/ppp/ppp.conf` file should contain something along the lines of:
\r
227 set debug phase lcp chat
\r
231 set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255
\r
235 set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255
\r
239 **Note:** The indenting is important.
\r
241 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.
\r
243 ##### 18.2.1.3.9 Setting Up `ppp.conf` for Static-IP Users
\r
245 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.
\r
249 set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255
\r
252 set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255
\r
255 set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255
\r
258 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.
\r
262 add 203.14.101.0 netmask 255.255.255.0 HISADDR
\r
265 add 203.14.102.0 netmask 255.255.255.0 HISADDR
\r
268 add 203.14.103.0 netmask 255.255.255.0 HISADDR
\r
271 ##### 18.2.1.3.10 `mgetty` and AutoPPP
\r
273 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.
\r
275 This section assumes the user has successfully configured, compiled, and installed a version of `mgetty` with the `AUTO_PPP` option (v0.99beta or later).
\r
277 Make sure your `/usr/local/etc/mgetty+sendfax/login.config` file has the following in it:
\r
280 /AutoPPP/ - - /etc/ppp/ppp-pap-dialup
\r
283 This will tell `mgetty` to run the `ppp-pap-dialup` script for detected PPP connections.
\r
285 Create a file called `/etc/ppp/ppp-pap-dialup` containing the following (the file should be executable):
\r
289 exec /usr/sbin/ppp -direct pap$IDENT
\r
292 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.
\r
297 set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40
\r
301 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.
\r
307 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.
\r
309 ##### 18.2.1.3.11 MS Extensions
\r
311 It is possible to configure PPP to supply DNS and NetBIOS nameserver addresses on demand.
\r
313 To enable these extensions with PPP version 1.x, the following lines might be added to the relevant section of `/etc/ppp/ppp.conf`.
\r
317 set ns 203.14.100.1 203.14.100.2
\r
318 set nbns 203.14.100.5
\r
321 And for PPP version 2 and above:
\r
325 set dns 203.14.100.1 203.14.100.2
\r
326 set nbns 203.14.100.5
\r
329 This will tell the clients the primary and secondary name server addresses, and a NetBIOS nameserver host.
\r
331 In version 2 and above, if the `set dns` line is omitted, PPP will use the values found in `/etc/resolv.conf`.
\r
333 ##### 18.2.1.3.12 PAP and CHAP Authentication
\r
335 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.
\r
337 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***.
\r
339 Referring back to the [ PPP and Static IP addresses](userppp.html#USERPPP-STATICIP) or [ PPP and Dynamic IP addresses](userppp.html#USERPPP-DYNAMICIP) sections, the following alterations must be made:
\r
342 13 set authname `***MyUserName***`
\r
343 14 set authkey `***MyPassword***`
\r
347 Line 13::: This line specifies your PAP/CHAP user name. You will need to insert the correct value for `***MyUserName***`.Line 14::: 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:
\r
355 to make it obvious that this is the intention, but PAP and CHAP are both accepted by default.Line 15::: 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.
\r
357 ##### 18.2.1.3.13 Changing Your `ppp` Configuration on the Fly
\r
359 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:
\r
362 set server /var/run/ppp-tun`***%d***` DiagnosticPassword 0177
\r
365 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.
\r
367 Once a socket has been set up, the [pppctl(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#pppctl§ion8) program may be used in scripts that wish to manipulate the running program.
\r
369 #### 18.2.1.4 Using PPP Network Address Translation Capability
\r
371 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`:
\r
377 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.
\r
379 If you use this feature, you may also find useful the following `/etc/ppp/ppp.conf` options to enable incoming connections forwarding:
\r
382 nat port tcp 10.0.0.2:ftp ftp
\r
383 nat port tcp 10.0.0.2:http http
\r
386 or do not trust the outside at all
\r
389 nat deny_incoming yes
\r
392 #### 18.2.1.5 Final System Configuration
\r
394 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.
\r
396 Working from the top down in this file, make sure the `hostname=` line is set, e.g.:
\r
399 hostname="foo.example.com"
\r
402 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.
\r
404 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.
\r
407 network_interfaces="lo0 tun0"
\r
411 **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:
\r
417 This 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.
\r
419 Make sure the router program set to `NO` with following line in your `/etc/rc.conf`:
\r
425 It is important that the `routed` daemon is not started (it is by default), as `routed` tends to delete the default routing table entries created by `ppp`.
\r
427 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:
\r
430 sendmail_flags="-bd"
\r
433 The downside of this is that you must force `sendmail` to re-examine the mail queue whenever the ppp link is up by typing:
\r
436 # /usr/sbin/sendmail -q
\r
439 You may wish to use the `!bg` command in `ppp.linkup` to do this automatically:
\r
445 4 !bg sendmail -bd -q30m
\r
448 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.
\r
450 All that is left is to reboot the machine. After rebooting, you can now either type:
\r
456 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:
\r
459 # ppp -auto provider
\r
462 #### 18.2.1.6 Summary
\r
464 To recap, the following steps are necessary when setting up ppp for the first time:
\r
468 1. Ensure that the `tun` device is built into your kernel.
\r
469 1. Ensure that the `tun`***N****** device file is available in the `/dev` directory.
\r
470 1. Create an entry in `/etc/ppp/ppp.conf`. The `pmdemand` example should suffice for most ISPs.
\r
471 1. If you have a dynamic IP address, create an entry in `/etc/ppp/ppp.linkup`.
\r
472 1. Update your `/etc/rc.conf` file.
\r
473 1. Create a `start_if.tun0` script if you require demand dialing.
\r
477 1. Ensure that the `tun` device is built into your kernel.
\r
478 1. Ensure that the `tun`***N****** device file is available in the `/dev` directory.
\r
479 1. Create an entry in `/etc/passwd` (using the [vipw(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#vipw§ion8) program).
\r
480 1. Create a profile in this users home directory that runs `ppp -direct direct-server` or similar.
\r
481 1. Create an entry in `/etc/ppp/ppp.conf`. The `direct-server` example should suffice.
\r
482 1. Create an entry in `/etc/ppp/ppp.linkup`.
\r
483 1. Update your `/etc/rc.conf` file.
\r
488 CategoryHandbook-pppandslip
\r
projects / ikiwiki.git / blob