# The kppp Handbook

Bernd Johannes
Wuebben

    wuebben@kde.org

Version 1.6.2, February 5, 1999

This Handbook describes kppp Version 1.6.2

KPPP Internet Dialer

KPPP
Dialer
Internet
PPP
IP
PAP
CHAP

## Introduction

### About kppp

`PLEASE DON'T FORGET TO READ THE FREQUENTLY ASKED QUESTIONS! THANK YOU!`

kppp is a dialer and front end for pppd. It allows for interactive script generation and network setup. It will automate the dialing in process to your ISP while letting you conveniently monitor the entire process. Once connected kppp will provide a rich set of statistics and keep track of the time spent online for you. A built-in terminal and script generator will enable you to set up your connection with ease. You will no longer need an additional terminal program such as seyon or minicom to test and setup your connection. kppp features elaborate phone cost accounting, which enables you to easily track your online costs.

We hope you will enjoy this dialer.

### Authors

kppp is derived from ezppp 0.6 from Jay Painter. However, nearly everything in kppp was rewritten and so ezppp and kppp do not have very much in common.

The main authors are:

- `Bernd Johannes Wuebben` wuebben@kde.org

- `Mario Weilguni` mweilguni@sime.com

- `Harri Porten` porten@kde.org

Many thanks to the following people who have contributed code to kppp

- Jesus Fuentes Saaverdra for implementing several options and miscellaneous work.

- Markus Wuebben for the ATI query dialog.

- Peter Silva for pop up dialogs and other contributions.

- Martin A. Brown for proofreading some English text in the program

- Martin Häfner for the section on callback

- Olaf Kirch for the introduction to the mysteries of file descriptor passing.

### License and warranty

kppp is published under the terms of the GNU General Public License (GPL). There is no warranty that this program works or for whatever.

## Installation

`PLEASE DON'T FORGET TO READ THE FREQUENTLY ASKED QUESTIONS! THANK YOU!`

### How to obtain kppp

kppp is an application for the KDE project http://www.kde.org. Kppp can be found on ftp://ftp.kde.org/pub/kde/, the main ftp site of the KDE project.

### Requirements

In order to successfully compile kppp, you need the latest versions of `libkdecore` and `libkdeui`. All required libraries as well as kppp itself can be found on ftp://ftp.kde.org/pub/kde/.

### Compilation and installation

`PLEASE DON'T FORGET TO READ THE FREQUENTLY ASKED QUESTIONS! THANK YOU!`

I haven't been able to test kppp on anything else but Linux, but you should be able to get pppd to work on a variety of platforms including but not limited to SVR4, Solaris 2, Linux, FreeBSD, NetBSD, SunOS 4, AIX 4, OSF/1 as long as you have pppd installed on those systems.

If wish to compile kppp on a platform different from Linux, please check briefly the first couple of lines of pppstats.cpp and make sure the defines and includes are O.K. Most likely however they should be fine. Please inform me of any necessary changes.

In order to compile and install kppp on your system, type the following in the base directory of the kppp distribution:

    % ./configure
    % make
    % make install

This will install kppp with the bit on.

Make sure that the pppd's option file which usually resides in `/etc/ppp/` exists, but is empty. pppd requires it to exist, but it must be empty otherwise pppd will not take its options from kppp.

Again: Should you run into problems, please report them to me.

### Preparing Your Linux System for a PPP Connection

In order for kppp/pppd to work your kernel must have ppp support compiled in. If this is not the case get yourself the latest version of pppd from any of the popular Linux archives and recompile your kernel with ppp support enabled. Don't fret since this sounds scarier than it actually is. Don't forget to install pppd afterwards. If unsure whether you have a kernel with ppp support issue `dmesg` at the command prompt and look for something like this:

    PPP: version 2.3.0 (demand dialling)
    TCP compression code copyright 1989 Regents of the University of California
    PPP Dynamic channel allocation code copyright 1995 Caldera, Inc.
    PPP line discipline registered

Update: kppp since version 1.5.32 tries to find out itself if the kernel supports PPP. If not, you will be notified on start of kppp. This feature is not well tested, so you should not rely on it for now.

There were changes in the kernel PPP from Linux version 1.2.x to 2.0.x which forced the programming of a new pppd daemon. In most distributions, the pppd daemon can be found in `/usr/sbin`. For kernel versions 1.2.x, the correct version of the pppd daemon is 2.1; for kernel versions 2.0.x, the correct version is 2.2. or newer; for kernel versions 2.1.x and 2.2.x you need pppd version 2.3. If you don't know what version of the pppd daemon your system has, you can type:

    % pppd --version

None of the pppd daemons actually have a --version option, but putting the option in will cause the pppd daemon to error out from a unrecognised option and print out a list of options, which includes the version of the pppd daemon.

### More about ppp/pppd

The following sites may be of interest for further information about the ppp protocol, pppd and networking in general:

- Linux PPP FAQ: http://metalab.unc.edu/mdw/FAQ/PPP-FAQ.html

- Linux PPP HOWTO: http://metalab.unc.edu/mdw/HOWTO/PPP-HOWTO.html

- http://www.thoughtport.com:8080/PPP/index.html

- The Network Administrators' Guide: http://metalab.unc.edu/mdw/LDP/nag/nag.html

## Setting up kppp

In order to set up kppp, start kppp and push the `Setup` button on kppp's main window. A new tab dialog will appear.

### Accounts

This dialog will display the accounts you have created. You must create at least one account. The ``Reset Button'' will reset the accumulated cost for the selected account to zero. Typically you want to press this button once a month after having consolidated your telephone costs.

### Device

Modem Device

  Select the device appropriate for your hardware. Here are some examples:

  - /dev/ttyS0 - DOS or Windows users will know this as COM1, COM2 is /dev/ttyS1 and so on. These devices are mostly used on Linux systems.

  - /dev/cua0 - the first serial line (COM1). COM2 would be /dev/cua1 and so on. These devices are mostly used on BSD systems, namely FreeBSD, NetBSD and OpenBSD.

  - /dev/ttyI0 - under Linux, these belong to internal ISDN cards. These devices emulate a common Hayes compatible modem. /dev/ttyI0 is for the first, /dev/ttyI1 for the second ISDN card and so on. These devices are only available in the Linux version

  - /dev/modem - many Linux distributions make a symbolic link from the real modem device to /dev/modem. You should avoid using this one. Use /dev/ttySx (x is a digit) instead of.

Flow Control

  Select from Hardware (CRTSCTS), Software (XON/XOFF) and no flow control. The recommended setting is Hardware flow control.

Line Termination

  Choose the correct ``Enter'' character sequence for your modem. Most modems will use ``CR/LF''. However some modems need a different setting. If you experience trouble while running a script: Play with this parameter.

Connection Speed

  Choose from the list of connections speeds supported by your serial port.

Use Lock File

  Activate this option if you want kppp to create a lockfile. Under Linux the directory for such a file will be `/var/lock`. Programs such as mgetty depend on the existence of such lock files and kppp will not work with mgetty if the lock file is not set. Make sure that you don't use the option "lock" to pppd if you want kppp to lock the modem, since the pppd option "lock" will induce pppd to try to lock the modemdevice. However since kppp already locked the device pppd will fail and kppp will display "pppd died unexpectedly".

Modem Timeout

  This is the time in seconds that kppp waits for the ``CONNECT'' response from your modem after dialing into another modem (typically a modem of your IPS's modem pool). I recommend a setting of about 30 seconds.

### Modem

Modem Commands

  This will bring up a dialog which you will need to fill with modem commands appropriate for you particular modem. If you own a Hayes compatible modem you most likely won't need to change any of the defaults. I encourage you however to read about the Hayes command in the Appendix of this documentation. The information supplied there should also be of help in case you experience trouble setting up a stable connection with your ISP's modems. The two settings "Pre-Init Delay" and "Post-Init Delay" might be of special interest to if you experience any modem lock-ups. These will make kppp pause a bit before and after sending the initialization string. The "Pre-Init Delay" will be accompanied by sending a CR unless given a delay interval of 0.

Query Modem

  Pushing the Query Modem Button will induce kppp to ask your modem to identify itself. On success your modems response will be displayed in a dialog. This may or may not prove to be informative depending on your modem.

Terminal

  Pushing the `Terminal` button will bring up a mini terminal. You can use the mini terminal to test your modem and experiment with the negotiation protocol for initiating a ppp connection with you ISP. You no longer need a terminal program such as minicom or seyon.

### PPP

pppd Timeout

  kppp will wait this amount of time after running the script and starting pppd for pppd to establish a valid ppp link before giving up and killing pppd.

Automatic Redial on Disconnect

  Selecting this will have kppp try to reconnect in case you inadvertently got disconnected while online.

Show Clock on Caption

  This will have kppp display the time connected on the caption of the kppp window displayed while being online.

Disconnect on X-server shutdown

  Checking this option will cause kppp to terminate the ppp link, disconnect the modem and terminate accounting in an orderly fashion when the X-server shuts down. This is useful if you are prone to forget to shut down kppp on X-server exit or simply don't want to have to worry about disconnecting your connection. If you don't want kppp to hang up the modem on X-server exit, you should leave this checkbox unchecked. Be aware however, that if you have accounting enabled, and you don't want kppp to hang up on X-server exit, you will have a nonterminated accounting entry in you accounting logs, when the X-server exits and kppp terminates.

Minimize Window on Connect

  kppp's window will be minimized after a connection has been established. The elapsed connection time will be shown in the taskbar.

Dock into Panel on Connect

  If this option is chosen kppp will dock into the panel where it will be symbolized by a small animated icon. Use the left mouse button on this icon to restore kppp's window. The right mouse button will open up a popup-menu

  that offers to restore the window, show further transfer statistics or close the connection. This option overrides Minimise Window on Connect.

## Configuring an Account

### Dial

Connection Name

  You must give the account a name. You can use anything here, but if you have multiple accounts it must be unique.

Phone Number

  Specify the phone number to dial. You may use characters such as ``-'' to make the number more legible. If you concatenate a series of numbers (separated by a colon) kppp will try these numbers in a cyclic order whenever it receives a busy signal. Example: "1111111:2222222:3333333"

Authentication

  Choose the appropriate method of authentication that kppp should use to log into the server. Check with your provider whether he offers PAP or CHAP support or if you have to use a script or terminal-based login method.

Store password

  Check this option if you want kppp to remember your password at the next session.

Execute Program upon Connect

  kppp will attempt to execute the command specified here once a ppp link has been set up.

Execute Program before Disconnect

  kppp will run the command before closing the connection. This will be useful if you have to change any route or address before you leave the net.

Execute Program upon Disconnect

  analogue with previous item.

Edit pppd arguments

  This will bring up the pppd arguments dialog. You may use this dialog to add any desired options that you want kppp to hand to pppd. See the pppd man page for a list of available options. Unless you know exactly what you are doing you should restrain from tinkering with the pppd options.

### IP

Dynamic IP Address

  Check this if your ISP uses dynamic IP address assignment. That is your IP address will most likely change every time you establish a connection.

Static IP Address

  Check this is your ISP has given you a static IP address. In that case you will also need to fill in that address and any Subnet Mask if applicable. Ask your ISP if unsure.

Auto-configure Hostname from this IP

  Select this option if you want kppp to set the hostname and domain for your machine after successful setup of a ppp link on connect. This is done by querying the defined Domain Name Server with the ip assigned for the ppp link. This option is useful for those stand-alone machines which want to use protocols like talk which require the hostname to be the same as your machine is known in the Internet. It overrides the Domain Name Option in the DNS Section. The machine defaults are restored to the original values when you close the ppp link Be careful when choosing this option: It may prove useful to you, but it may also cause lots of undesired side effect. Just play with it ...

### DNS

Domain Name

  Specify the domain name for your machine. As with DNS Addresses it is restored to the original specified in `/etc/resolv.conf` when the connection goes down. If it is left blank no changes are made to the domain name specified in `/etc/resolv.conf`

DNS Servers

  Add the Domain Name servers assigned to you by your ISP. You must specify at least a Domain Name server for your OS to be able to resolve human readable IP addresses such as ftp.kde.org. The DNS server addresses supplied must be in numeric form, e.g 128.231.231.233. The addresses will be added at runtime to `/etc/resolv.config`.

Disable existing DNS Servers during Connection

  Select this option if you want kppp to disable already existing nameserver entries in `/etc/resolv.conf` during connection.

### Gateway

Default Gateway

  Check this if you want pppd to use the default Gateway for your machine.

Static Gateway

  Check this if you want to specify the Gateway to be used.

Assign the Default Route to this Gateway

  You almost certainly will need this. Leave it on unless you really know what you are doing.

### Login Script

Edit Script

  Use this dialog to compose a dial in script for your ISP dialup connection. Use the mini-terminal and the information supplied by your ISP to understand which sequence of actions needs to be executed.

  - Expect: kppp will wait for the specified string to be received.

  - Send: kppp will send the specified string.

  - Scan: kppp will scan the the input stream for the specified string and store any character after the string up to the first newline in an internal buffer. Trailing and leading whitespace will be stripped off.

  - Save: permanently store the previously scanned string in the specified register. So far, the only valid register is 'password'.

  - Pause: pause for the specified number of seconds

  - Hangup: kppp will send the hangup command to the modem

  - Answer: kppp will set the modem into answer mode

  - Timeout: change the default timeout to the specified number of seconds dynamically during script execution. You can change the timeout several times during script execution if necessary.

  - Prompt: Prompt the kppp user to enter a string, given the specified string as a hint. The user will see what is typed. If the specified string includes the mark &num;&num; the mark will be replaced with the current content of the internal scan buffer.

  - PWPrompt: Prompt the kppp user to enter a string, given the specified string as a hint. An asterisk will be printed for each character typed.

  - ID: If the ID field on kppp's main dialog is filled in, send that ID. If the ID field is not filled in, prompt the kppp user to enter an ID, given the specified string as a hint. The user will see what is typed. On a second pass, such as in a loop on the second iteration, a prompt will be displayed, given the specified string as a hint.

  - Password: If the password field on kppp's main dialog is filled in, send that password. If the password field is not filled in, prompt the kppp user to enter a password given the specified string as a hint. An asterisk will be printed for each character typed. On a second pass, such as in a loop on the second iteration, a prompt will be displayed, given the specified string as a hint.

  - LoopStart: kppp will wait for the specified string to be received. It will save the string for use by LoopEnd

  - LoopEnd: kppp will wait for the specified string to be received to exit the loop. If the string given by the corresponding LoopStart is received first, it will trigger a jump to the line after the LoopStart, enabling repetition of username/password style paired dialogs.

#### Example scripts

Here is a simple script I could use to connect to my ISP:

    Expect      ID:                        # wait for ID:
    Send        myid                       # you have to substitute myid with your id
    Expect      word:                      # wait for 'password'
    Send        4u3fjkl                    # send my password '4u3fjkl'
    Expect      granted                    # My ISP send 'Permission granted' on login success.
    Send        ppp                        # This starts a ppp connection for
                                           # me on the ISP side.

Here a script for the same account with ID and password prompt: This script will prompt for ID and password each time, no matter what is typed into the ID and password field on kppp's main dialog. This script also illustrated the use of the LoopStart/LoopEnd structure. If something goes wrong during the login procedure, for example if I mistype the password, my ISP will print an error message and restart the id/password loop by issuing the string "ID:" again. If the string "ID" is caught before the LoopEnd keyword was parsed, kppp will start the script again after the LoopStart keyword.

    LoopStart   ID:                        # wait for ID:
    Prompt      Enter ID:                  # Prompt me for my ID and send it off.
    Expect      word:                      # wait for 'password'
    PWPrompt    Enter Password:            # Prompt me for my password and send it off.
    LoopEnd     granted                    # My ISP send 'Permission granted' on login success.
    Send        ppp                        # This starts a ppp connection for me

Here is the script that I actually use to connect to my ISP: This script will prompt for ID and password only if I haven't filled in the respective fields on kppp's main dialog.

    LoopStart   ID:                        # wait for ID:
    ID          Enter ID:                  # Prompt me for my ID and send it off.
    Expect      word:                      # wait for 'password'
    Password    Enter Password             # Prompt me for my password and send it off.
    LoopEnd     granted                    # My ISP send 'Permission granted' on login success.
    Send        ppp                        # This starts a ppp connection for me
                                           # on the ISP side

Here is a script that I use to connect to an ISP which is using some sort of challenge/response authentication. Usually you got a hardware token (a smart card with a display and calculator like keypad) from the ISP. You have to know a password to use the token. After dialling in your ISP displays your challenge. You have to type in the challenge to your token and get a dynamic password as a response. Then you have to enter that password.

    LoopStart   ID:                        # wait for ID:
    ID          Enter ID:                  # Prompt me for my ID and send it off.
    Scan        Challenge:                 # Scan for 'Challenge' and store everything behind up to the next newline.
    Expect      Password:                  # wait for 'password'
    Prompt      Your token is ## - Enter Password  # Prompt me for my password and send it off.
    LoopEnd     granted                    # My ISP sends 'Permission granted' on login success.
    Send        ppp                        # This starts a ppp connection for me
                                           # on the ISP side

The following log shows the login procedure of a fictitious ISP that provides a new password on each login. The new password has to be verified and recorded for the next session.

    University of Lummerland

    Login:mylogin
    Password:
    The password for your next session is: YLeLfkZb
    Please record and enter it for verification.
    Verification:YLeLfkZb

    1 = telnet
    2 = SLIP
    3 = PPP

    Your choice:

kppp can be used to do that cumbersome task for you (eliminating the risk of losing that little sheet of paper that holds your current password at the same time). The key part of the following script is a combination of the Scan/Save keywords:

    Expect      Login:                     # wait for login prompt
    ID                                     # send ID
    Expect      Password:                  # wait for password prompt
    Password                               # send password
    Scan        is:                        # wait for '... next session is:' and
                                           # scan the preceding password
    Save        password                   # save the new password for next login
    Expect      Verification:              # wait for 'Verification:'
    Password                               # send new password
    Expect      choice:                    # wait for a prompt that let's you choose
                                           # between different options (telnet, SLIP, PPP)
    Send        3                          # choose option 3, i.e. PPP

### Accounting

Accounting Setup

  Use the ``Enable accounting'' button to enable/disable phone cost accounting. Select a rule appropriate for your region. If you can't find a rule for your region you will have to write one by following the supplied `TEMPLATE` in `&dollar;&lcub;KDEDIR&rcub;/share/doc/HTML/en/kppp/`. Don't be afraid though it is really easy. Don't forget to submit your newly created rules file to me. The newly created rules file can be checked for valid syntax with the -r rule&lowbar;file command line option to kppp and must be installed in `&dollar;&lcub;KDEDIR&rcub;/share/apps/kppp/Rules` or in `&dollar;&lcub;HOME&rcub;/.kde/share/apps/kppp/Rules` before you will be able to select it in this dialog.

### Volume accounting

#### What is volume accounting?

It basically means to count the number of bytes transmitted from or to the Internet. kppp can count incoming bytes, outgoing bytes or both. Itīs up to you what you want (or must) use.

#### Why should I use volume accounting?

Because nowadays, many Internet Service Providers begin to bill their customers depending on the number of bytes transferred. Or very often those ISP give you an arbitrary transfer limit, and charge you for every megabyte above this limit. kppp shows you your current volume and can help you keeping your bills to the minimum. Of course, if you do not have volume limits and you are curious, you can use it too...

#### What type of volume accounting should I select?

That depends on your provider. Many of them only count how many megabytes you get from Internet and ignore how much you send. In that case you should choose "Bytes in". If you have to pay for both you should select "Bytes in and out". "Bytes out" is not of much use and is only here for completeness.

#### Drawbacks

Unfortunately thereīs a drawback on volume accounting. kppp will just count the number of bytes regardless their origin. Many providers set their limit only for internet access, not for their own network. So, if you do a little web surfing and you use a proxy-cache, the proxy will reside inside the network of your provider and he will not charge you for bytes transferred from his proxy cache. However, kppp will not know that these IP packets are coming from the proxy and thus count them. So, if you use a proxy, or your provider uses a caching news server (like nntpcached), the volume reported by kppp may be higher.

## Modem Tricks & Hints

This section should get the fearful started on the (not so) arcane art of modem tweaking. The commands here are all Hayes AT standard, but all modems are not equal, so your mileage may vary.

### Modem Sessions

A Modem session allows you to interact with the modem directly. You type commands, and it will respond. To obtain a modem session, when no connection is active, go into Setup/Modem/Terminal dialog. This will open a window for interactive configuration of the modem. Try typing ATZ (which resets your modem) Your should get an OK response. use File/Close to end the session.

### Modem Profiles

One reason you might want to send the modem commands directly is if you have a set of modem configurations you want to keep, and not have to specify for every connection. A good way to do that is via modem profiles. Modems can have several stored profiles numbered 0,1,... AT&V can be used to view them all. The default profile is usually 0 (this can be changed via AT&Y.) The profile currently in use is called the "active" profile.

When you change a setting, the active profile is modified. The ATZ command will have the modem load the default profile, erasing any changes you have made. To save changes, Load the profile you want to change via ATZ n (where n is the profile number). Make the changes you want, then save it with AT&Wn. To have kppp use the profile you want, change the modem initialization string (Setup/Modem/Modem Commands/Initialization String.) For example ATZ1 will have the kppp reset the modem and use stored profile &num;1.

If you want reset you modem to get back to some known starting point, use AT&F&W to set the active profile to the factory defaults, and store those settings as the default profile.

Example of profile changes are in the next section.

### Getting the modem to hang up

Sometimes, you may find kppp has difficulties hanging up the modem. This is likely the result of a mismatch between kppp settings and those of the modem. A standard modem uses two methods to decide to hangup: Command, and DTR. The Command method involves sending an escape sequence to the modem, which puts it in command mode, then issuing the hangup command (ATH).

Outside of kppp, when configuring the pppd package manually, it's often helpful to use the command method, so that one can exit a terminal session, and then start pppd without having the modem hangup. In most other situations, the DTR method is preferred, as it is simpler.

#### DTR (AT&Dn) method

The DTR method will have the modem hangup whenever kppp stops using the modem. If you obtain a modem session, and query the state via AT&V, and the among the settings displayed for the active profile are &D0, then the DTR hangup method is disabled. To enable the DTR method Use the Setup/More/Terminal to get a modem session. Then:

    ATZ		# reset to default profile
    AT&D2		# Set to hang up on DTR drop.
    AT&W		# Write to default profile

##### How The DTR Method Works

Whenever the Data Terminal Ready (DTR) line on the serial line between the host computer and the modem goes high, the modem hangs up. When kppp opens the serial port, the DTR line is pulled low, on an external modem, you can see the DTR (or TR) light come on when this happens. When the TR light goes out (because kppp has closed the serial port, or something worse!), the modem will hangup.

#### Command Method

The other way to have a modem hang up when connected (used when AT&Dn where n is not 2) is to have the modem accept the command when a session is in progress. To have it hangup properly, Get a modem session, and set the guard time to a short interval like so:

    ATZ
    ATS12=5
    AT&W

Then use the Settings/More/Modem Commands/Guard Time slider to match the register (S12) value to match (5) The modem should then hangup properly.

##### How The Command Method Works

When the local modem is connected to a remote modem, it is in the "connect" state, where it passes all the characters it receives to the remote modem without interpretation. To have the modem accept the characters as commands for itself, one must put the modem into the command state. The escape code does this.

The escape code is defined as a being three intervals of time whose length is defined by S12 (in fiftieth of a second.)

- Quiet (must last more than S12/50 seconds)

- Escape character (defined by register S2, default is "+") repeated three times (less than S12/50 seconds between each)

- Quiet (must last more than S12/50 seconds)

Once the modem is in the command state, you can send it commands. To have it hang up. Sent ATH. The escape codes and hangup string used by kppp are shown in the Setup/More/Modem Commands dialogs. These should match your modem.

### Make Tone Dialling Faster

If you can use tone dialling, the amount of time it takes to dial can be changed using the S11 register. It gives the duration (in 100hundreds of a second) to send each tone while dialling. The default is usually 95 (almost a second.) How fast you can dial depends on the phone company's switching equipment which handles your line. The minimum duration is 50, almost twice as fast, and that speed often works.

    ATZ		# reset to default profile
    ATS11=50	# fastest possible dialling, use a higher number if it doesn't work.
    AT&W		# Write to default profile

## PAP and CHAP

Starting with version 0.9.1 kppp supports directly the most commonly used form of PAP authentification. The section 'PAP and CHAP with kppp' will descripe how to make PAP and CHAP work with kppp in general, while the section 'PAP with kppp' will describe in detail how to take advantage of kppp's build in support for the most commonly encountered version of PAP wich is widely used by commercial Internet Service Providers (ISP).

### PAP with kppp

There are two different ways to use PAP:

#### Client side authentication

This variant is used by many commercial ISPīs. It basically means that you (or your computer) must authenticate yourself to the ISPīs PPP server. The PPP server must not authenticate himself to your computer, but typically this is not necessary since you know which computer you are connected to (because the connection was established by yourself). So this is no major security issue. kppp supports this variant directly. See below for instruction how use this one.

If your ISP just gives you a username and a password and tells you to use PAP authentication you must use this variant.

#### Two way authentication

Same as above, but your computer requires the ISP PPP server to authenticate himself. In order to establish a connection, you must choose the authentication method Script based, not PAP, and you will have to manually edit `/etc/ppp/pap-secrets`. While kppp doesn't provide build in support for this variant -- it is nevertheless easy to establish a connection using this variant of PAP with kppp. The details are described in the previous section 'Using PAP and CHAP with kppp'.

#### Preparing kppp for PAP

1. Make sure that the `/etc/ppp/options` (and `˜/.ppprc` if you do have such a file) does not contain one of the arguments:

   - +pap

   - -pap

   - papcrypt

   - +chap

   - +ua

   - remotename

   It is very unlikely that one of those arguments is already in there, but just to be sure.

2. Start kppp

3. Click on Setup

4. Choose the account you want to use PAP with and click on Edit

5. Click on the Dial tab.

6. Select PAP in the checkbox Authentication

7. If you do not want to retype the password each time you dial in, select Store password. This will save the password. Make sure that nobody other than you has access to your account, otherwise this person will have access to your password.

8. That's it. Close the dialogs, type in your the username and password your ISP supplied to you and dial.

### PAP and CHAP with kppp (alternate method)

The following is based on an email by Keith Brown and explains how to make kppp work for a generic PAP or CHAP account. If your ISP just gave you a user id and a password for a PAP account the odds are that you can skip this section and that you will get by just reading the next one entitled 'PAP with kppp'.

PAP seems a lot more complicated at first glance than it really is. The server (the machine you are connecting to) basically tells the client (your machine) to authenticate using PAP. The client (pppd) looks in a specific file for an entry that contains a matching server name and client's name for this connection, and then sends the password it finds there. That's about it! Now, here's how to make that happen. I am assuming a pppd version of 2.2.0 and a standard installation of configuration files under `/etc/ppp`.

For the purposes of illustration, pretend that I have an Internet account with 'glob.net', under the user name 'booger', and a password of 'foobar'. First, I need to add all this to the file `/etc/ppp/pap-secrets` . The format of an entry for our purposes, is:

    USERNAME  SERVERNAME   PASSWORD

so I add the line:

    booger  glob  foobar

to the file and save it. Note: I can use any name for the server I wish as long as I use the same name in the pppd arguments, as we'll see shortly. I have shortened it to 'glob'. This name is just used to locate the correct password.

Now, I need to set up my connection in kppp. The basics are the same as any other connection, and I won't go into details here, except to say that you probably want to make sure that the `/etc/ppp/options,` is empty, and you probably don't want any login script either. Now, in the settings dialog, at the bottom, is the pppd arguments button. This brings up a dialog similar to the one used for editing the login script. Here we enter values that will be sent to pppd as command line arguments, and in the case of multiple-value arguments, we need to enter each value as a separate entry in the listbox, in the correct order.

We can put any other arguments in here we want first. Now we need to add arguments that pppd needs to handle PAP authentication. In this example I am going to add 'user', 'booger', 'remotename', 'glob', in that order. The user argument tells pppd what user name to look for in pap-secrets, and send to the server. The remotename is only used by pppd to match the entry in the pap-secrets file, and is not sent to the server, so once again, it can be anything I want as long as it is consistent with the entry in the pap-secrets file.

That's all there is to it. You should now be able to set up your own connection to a server with PAP authentication. CHAP should not be much different. See the Linux Network Administrators' Guide for chap-secrets file format and pppd arguments used. The rest should be gravy, but...your mileage, ah you know the rest.

## Questions and answers

### Frequently Asked Questions

#### I can't get kppp to work. kppp tells me that pppd has died or that a timeout has expired!

Did you read the this manual carefully? Here are once more the most common pitfalls.

- Click on the "Details" button. kppp will you give an excerpt from the PPP log messages (may not work on non-Linux systems, or even on some Linux distributions). The log will help you to track down the bug.

- Make sure that pppd is the actual pppd binary not a script

- Make sure that pppd is setuid root. You may set this mode by issuing chmod u+s pppd as root.

- Make sure that your `/etc/ppp/options` file exists and that it doesnīt contain any conflicting entries. If in doubt: Leave this file empty.

- Make sure that you DON'T use the option "lock" as an argument for pppd (kppp is already taking care of device locking )

- Remove the "lock" option from your `/etc/ppp/options` and `˜/.ppprc` files!

- Using the symbolic link `/dev/modem` may cause some conflicts. Eliminate this source of trouble by using the real device, i.e. `/dev/cuaX` or `/dev/ttySX`. NOTE: COM1 equals ttyS0, COM2 is ttyS1 and so on.

- Make sure you set the right permission. In case of trouble you might want to run it as root first and then later, when everything is working o.k give it less harmful permission if you can not afford to run kppp setuid root. The proper way to proceed would probably be creating a "modem" group.

- You might be launching pppd too early, i.e. before the remote server is ready to negotiate a PPP connection. If you are using a login script, you should use the built-in terminal to verify your login procedure. Some providers will require you to issue a simple "Send" or "Send ppp" to launch PPP. Some users even reported, that they had to append "Pause 1" or "Pause 2" to their script to solve timing conflicts.

If nothing helps, you might obtain some debugging info from your systems log by issuing:

    # tail /var/log/messages

#### kppp tells me ``Sorry, can't open the modem''.

This means that kppp doesn't have permissions to open the modem device or that you selected a modem device on the Modem Tab Dialog that is not valid. First make sure you selected the right modem device. Once you are sure you have selected the right modem device, you must give kppp the right permission to access the modem device and to be able to modify `/etc/resolv.conf` in case you want kppp to configure DNS correctly for you. If you can afford to run kppp setuid root this would solve all access problems for you, if not you will have to figure out what the right permissions are for your purposes. In order to give kppp setuid root permissions do the following:

    % su root
    # chown root:root &dollar;{KDEDIR}/bin/kppp
    # chmod +s &dollar;{KDEDIR}/bin/kppp
    # exit

#### kppp tells me it can't create a modem lock file.

This in most instances means that you have installed kppp without SETUID bit on while you, the person executing kppp, doesn't have write access to the lock file directory which by default is `/var/lock`. This for example is the case on Red Hat systems. Check the modem dialog for the precise location you have chosen. The solution is easy -- either run kppp SETUID if you can afford to, or give regular users write access to `/var/lock` or create a modem group that will have access to the `/var/lock` file.

#### Why is kppp installed with the SETUID bit on?

There is no need for the SETUID bit, if you know a bit of Unix systems administration. Simply create a modem group, add all users that you want to give access to the modem to that group and make the modem device read/writable for that group. Also if you want DNS configuration to work with kppp, then `/etc/resolv.conf` must be read/writable by the members of that group. The same counts for `/etc/ppp/pap-secrets` and `/etc/ppp/chap-secrets` if you want to use the built-in PAP or CHAP support, respectively.

Please do not criticise me for installing kppp with setuid bit on, I simply can no longer handle the amount of mail I used to get from desperate users who had problems getting kppp to work because they didn't understand enough about Unix and device permissions.

The kppp team has lately done a lot of work to make kppp setuid-safe. But it's up to you to decide if you install and how you install it.

You might also want to read the Security section.

#### kppp just sits there and waits: Expecting OK

- Have you played with the CR/LF setting? Try CR, LF or CR/LF.

- Your modem might need some time to respond to its initialisation. Open the "Modem Commands" dialog on the "Modem" tab and adjust the "Pre-Init" and "Post-Init" delays. See if you are successful when drastically increasing their values and do some fine tuning later.

#### The connection works fine but I canīt start any applications.

You probably have activated the option and the X Server has problems connecting to your newly named host. If you really need this option (chances are that you donīt) you are on your own to setup the appropriate authorisations. Issuing xhost + before starting the connection would do the job, but be warned of any security risks that involves since everyone else is granted access to your X Server.

#### kppp reports a successful connection, but Netscape just says "The server does not have a DNS entry"

Try pinging another server by its IP number, e.g. `ping 195.0.254.76`. If that works you should

- check if you provided kppp with at least one DNS address

- check the contents of `/etc/host.conf`. There should be a line saying something similar to `order hosts, bind`. The `bind` keyword advises the resolver library to include a name server query when performing an address lookup.

#### How do I make kppp send a \n or a \r?

Just send an empty string such as in the following script:

    Send                                   # send an empty string
    Expect      ID:
    Send        itsme
    Expect      word:
    Send        forgot
    Expect      granted
    Send        ppp

#### kppp complains: "Can't create lock file"

This means that you don't have permissions to create a lock file. If you chose to use a lock file you must have write permissions to the directory (typically /var/lock). This is of course no problem if you have given kppp setuid permissions. Please read the section on .

#### My modem makes much noise when dialling!

Click on "Setup", "Modem". You can control the modem volume here in three steps: off, medium and high. For most modems "medium" and "high" result in the same volume. If that doesn't work, make sure that the correct settings for your modem are specified in "Setup"/"Modem"/"Modem commands"!

#### I turned the modem volume "off" and verified the modem commands, but I still hear that noise when dialling!

The volume initialisation string can get lost if your modem can't cope with the speed it revives its command from kppp. Increase the value of "Post-Init Delay" in "Setup"/"Modem"/"Modem commands"!

Click on "Setup", "Modem". You can control the modem volume here in three steps: off, medium and high. For most modems "medium" and "high" result in the same volume. If that doesn't work, make sure that the correct settings for your modem are specified in "Setup"/"Modem"/"Modem commands"!

#### kppp reports an unusual modem speed like 115200, 57600 or similar

Many modems only report the speed of the serial line and not the speed over the telephone line as default. You must configure these modems to report the true line speed (add to modem init or dial string). For many modems this command is "ATW2". If you want to add it to the dial-string (typical "ATD"), the new dial string would be "ATW2D".

#### kppp reports "Unknown speed"

New modems often have very complex connection messages like "CONNECT LAP.M/V42.bis/115000:RX/31200:TX", and kppp cannot parse this message correctly. Turn on "Show Log" and you'll see the connection speed. I'm currently working on a solution for this, and the parser is now much better, but still not perfect.

#### Slow connection speed

If you are not satisfied with the modem speed, make sure you've set the connection speed ("Setup" / "Device" / "Speed") to 57600 or higher. Make sure that your serial ports support higher speeds. Many systems based on i486 do not work correctly when you set the speed to 115200. If you have a 8250 UART chip, it won't work. If you have a 16550 or 16550A it should work flawlessly.

Additionally, consult your modem manual to look for init strings that enable a high speed mode.

#### REALLY slow connection speed

If data drips in at a rate of just a few bytes per second you should check your hardware setup. If moving your mouse speeds up the transmission this is definitely a hardware issue.

Obtain some information about your serial port with `setserial -a /dev/ttySx` and check for interrupt conflicts with other components of your system.

#### My phone line needs pulse dialling instead of tone dialling (or vice-versa)

You must modify you modem dial string. Nearly all modems support the following AT-commands:

- ATDT - selects tone dial

- ATDP - selects pulse dial

#### kppp makes really strange things (whatever)

Did you compile it or the libraries with gcc-2.8? This version of gcc is somewhat broken, and it will not work as expected.

#### How do I write a telephone cost rules file?

Just follow the TEMPLATE rules files supplied with kppp. You should be able to find a copy in the `&dollar;&lcub;KDEDIR&rcub;/doc/HTML/kppp`. Use the `-r` kppp command line options to check the syntax of your proposed rules file.

#### I have written a telephone cost rules file for my region. Where can I submit it so that others can make use of it?

I would love to receive any rule files written. I will make them available on my kppp web page. Before you send me a new rules file make sure it is not already available on the kppp web page. Then email the new rules file to me.

#### Can my phone cost rulefile contain fractional time units, e.g. "(0.17, 45.5)"?

Yes this is possible. But you should not use unusual small time units (below tenth of a second), because this would result in higher CPU load (though I doubt you'll notice with a modern CPU :-)

#### My country observes a moving holiday different from easter.

In that case you need to write new code that allows for the computation of that holiday. Please have a look at ruleset.cpp and emulate the ``easter'' example. Then send me the patches.

### How to interpret the system's log

#### Serial line is looped back

Short answer: You haven't started the PPP software on the peer system.

See a posting from Al Longyear on http://www.dejanews.com/getdoc.xp?AN=184945314 for a more detailed explanation.

#### Signal 15

If you see the following lines you've probably just received a timeout error from kppp, too. kppp has been waiting for the PPP interface to come up and gave up after the specified timeout. pppd was signaled to shut down with signal number 15, i.e. SIGTERM.

    pppd[26921]: pppd 2.3.5 started by me, uid 500
    pppd[26921]: Using interface ppp0
    pppd[26921]: Connect: ppp0 <--> /dev/ttyS0
    pppd[26921]: Terminating on signal 15.
    pppd[26921]: Connection terminated.
    pppd[26921]: Exit.

#### Receive serial link is not 8-bit clean

The PPP daemon is alarmed by the fact that all data it receives has bit 8 set to zero. In most cases this simply indicates that the remote PPP server isn't running yet. You might be still confronted with a login prompt that echoes back all data sent by your pppd.

#### can't locate module ppp-compress

Do you get the following messages ?

    modprobe: can't locate module ppp-compress-21
    modprobe: can't locate module ppp-compress-26
    modprobe: can't locate module ppp-compress-24

Just add the lines

    alias ppp-compress-21 bsd_comp
    alias ppp-compress-24 ppp_deflate
    alias ppp-compress-26 ppp_deflate

to your /etc/conf.modules file.

## kppp and Security Issues

This section is mainly for superusers (root), people with high security demands or simply technically interested people. It is not necessary to read this if you only use Linux at home for yourself (though you might learn something new when you read this)

### Restricting access to kppp

A system administrator might want to restrict access to who is allowed to use kppp. There are two ways to accomplish this:

#### With group permissions

Create a new group (you might want to name it "dialout" or similar), put every user that should be allowed to use kppp into that group and type:

    chown root.dialout /usr/local/kde/bin/kppp
    chmod 4750 /usr/local/kde/bin/kppp

This assumes that KDE was installed in `/usr/local/kde` and your new group is named "dialout".

#### kpppīs way

Before doing anything, kppp checks if there is a file named `/etc/kppp.allow`. If such a file exists, ONLY users named in this file are allowed to dial out. This file must be readable by every user (of course NOT writable). Only login names are recognised, thus you cannot use UIDīs in this file. Hereīs a short example:

    # /etc/kppp.allow
    # comment lines like this are ignored,
    # as well as empty lines
    fred
    karl

    # I put myself in here :-)
    mweilguni

In the example above only the users fred, karl and mweilguni can use kppp to dial out, as well as every user with a UID of 0. So you donīt need to put root in this file.

### kppp has the SUID bit on. What about security?

Itīs virtually impossible to write a dialer without the SUID bit, that is both safe and easy to use for unexperienced users. kppp addresses the security issues with the following strategy:

- Immidiatly after program start, kppp forks.

- The master process (which does all GUI stuff, user interaction and such) drops the SUID state afterwards, and runs with normal user privileges.

- The slave process keeps itīs privileges, and is responsible for all actions that need root privileges. To keep this part safe, no KDE/Qt library calls are used here, just simple C library calls. The source code for this process is short (around 500 lines) and well documented, so itīs easy for to check it for security holes.

- Master and slave process communicate with standard UNIX IPC.

Many thanks to Harri Porten for writing this excellent piece of code. I thought it was impossible - he made it within a week.

## Configuring kppp for callback

The following section was provided by Martin Häfner.

This chapter descibes the configuration of kppp for callback. The following servers are supported:

### Unix (Linux) callback server

This section introduces in Unix (Linux) callback proceeding and how kppp can be configured to connect to a Unix callback server, especially to a scripting based Linux callback server.

If you have any questions or problems please feel free to contact the author of this section.

#### Introduction in callback

To increase the security of your local network or to reduce the expenses of your external co-workers, setting up a callback server could be your first choice. Think about someone calling the number of your dial-in server and cracking a password? Why do you maintain a firewall for your internet connection then? Callback software generally asks you for your name and looks up the number to call back from a database. Therefore, the number should be stored on the server. After authentication the server will hang up the line and call you back immediately on the number chosen. The client picks up the phone line and continues the dial-in as if nothing happened. The server will ask for username and password, then the connection is established and the pppd could be started. Now, how can I tell the client to pick up the phone? Do I need a program like mgetty? Well, the answer is "NO"! You do not need a special client program. Generally spoken, all clients can be used for callback connections. You can even use an ordinary terminal program like minicom to connect to a callback server. The only thing you have to do is to tell your modem to `AutoAnswer` the phone when a `RING` is detected by the modem. This is done by using a certain modem command:

    AT&S0=1

This means that the modem will pick up the phone after one `RING`. Remember, this is done without any client software interaction. Like a lot of other client programs kppp checks if the connection is closed by the server and stops the current session if a `NO CARRIER` is detected. And this it the next problem: `NO CARRIER` is detected when the callback server hangs up the line after he knows on which number to call the client back. Some servers use a special login program therefore. How can you solve that problem? Tell your modem to show carrier up all the time (which makes no problems if the client hangs up the line) by using the modem command:

    AT&C0

If you want to test this you can first use an ordinary terminal program like minicom and call your callback server.

#### The kppp setup

Setting up kppp to connect to a Linux callback server is quite straight forward.

1. You only have to tell the modem to accept connections (see above) and not to stop the dialing when the callback server hangs up the line for the first time to initialize for the callback attempt. Both are modem settings which have to be configured in the "Modem" tab of the configuration. Make sure your setup looks like the following:

       Dial String:   AT&C0S0=1DT

   All the other configuration issues will remain as-is. kppp has some problems with modem init and reset. See the troubleshooting section if you are confronted with trouble.

2. Think about your server a moment. Remember that Unix and Windows operating systems have a different opinion about how to make line termination in text files (and in login procedures): simple CR or CR/LF or LF if you want to connect to a Macintosh server. Use CR as your line termination.

3. The next sections describes the callback setup of kppp on base of the Linux callback package (see below) which uses an ordinary user login (no PAP or whatever). Therefore you have to set up the following authentication style within the "Dial" tab of the account configuration:

       Authentication:   Script-based

   Of course, you can first choose "Terminal based" and test your connection. Have a look on what the server asks you so you can write your login script afterwards.

4. Now you have to build the login script. This is a quite cool feature of kppp. Just click around a little in the "Login Script" tab of your Account setup. For my server, the user "xyz" needs the following script to be called back at home (the callback server knows a table of names and numbers, so that you will select your phonenumber by an alias (security!)):

       Expect      ogin:       # remember, we do ordinary terminal login
       ID          ""          # kppp sends the id you have configured in the main dialog
       Expect      for xyz:    # a list of avaiable numbers is shown. The user must select one
       Send        xyz-home    # the user wants to be called back at home
       Expect      ogin:       # the callback process is running, a new connect, a new login
       ID
       Expect      assword:
       Password                # now your password authentication
       Expect      >           # wait for the command prompt (this may vary)
       Send        start_ppp   # start_ppp starts the pppd

   Just ignore the comments beginning with "&num;". After waiting for the login request he sends his user ID and waits for the list of available connections for his user ID. Then he tells the server on which number he wants to be called back. kppp can open a dialog for that (very nice feature) if your domicile changes rapidely (e.g. you are a representative and you are travelling from hotel to hotel). Now the server expects the login and Password authentication. In the meanwhile the server hangs up the line and calls the user back. kppp expects the commandline prompt and starts a small script which fires up the pppd on the server. The script may look like the following:

         #!/bin/sh

         stty -echo

         exec /usr/sbin/pppd -detach silent modem

   Of course, setting up a PPP-server is not within the scope of this document. For detailed information see the pppd man pages. An example callback server is described here.

All the other configuration issues (e.g. pppd config or IP settings) work as usual. Remember, no special software is needed to pick up the line.

Notice: kppp callback and other programs like mgetty or any other faxgetty can be run on the same serial port. There are no problems with the dial-in as kppp creates a Lock-file which will indicate the getty program that another program (kppp) is using the line at the moment. See problems with mgetty in the general troubleshooting below.

#### Troubleshooting

There are some known problems with kppp in callback mode:

- As you initialize the modem with AutoAnswer you would need to reset the modem after your connection closed. Otherwise your modem will continue to pick up the line for you.

- As already described in the setup section you will have to initialize the modem with the dial string. The normal kppp "initialization string" does not take more complex init strings needed for a callback setup.

- The next topic is more general and not related with callback: kppp has some slight problems when sharing the modem line with another program like mgetty. If mgetty is running on the same modem line, kppp is not able to initialize the modem correctly. This only happens on the second attempt.

- kppp is able to prompt for certain user input during a scripting based connetion. Unfortunately kppp also asks me for my user ID the second time the user ID will be asked for by the server (see the login script section above). If you want to get rid of that you will have to hardcode your user ID within your login script (not very nice, but it helps).

#### Internet Resources for server software

Linux callback server software bundles are available throughout the internet. Of course, the all known mgetty is a very powerful program which is also able to handle callback connections. There is a description for how to set up mgetty for that purpose here. The site is maintained by Colin Mc Kinnon, so please don't ask me if you have any problems. But there is also a ready-to-use package for a Linux callback server available here. The package is maintained by Frank B. Brokken. As the package is not very easy to set up (although the setup is straight forward), I have written a short introduction for it. Also have a look in it if you need further general introduction to callback.

### Windows NT RAS callback

Windows NT uses a completly different approach than the one described here (as usual). NT requires an extension to the PPP protocol itself called CBCP (Call Back Control Protocol). `pppd` has support for this protocol, but you have to recompile `pppd`.

If anybody has experience how to do this with kppp, please drop me a line.

## Appendix

### The Hayes Modem Command Set

The Hayes Command Set might come handy if you need to fine-tune your modem commands.

### kppp related files

By default kppp makes use of the following files and directories. The location of some of those can be changed at compile time.

    &dollar;{KDEDIR}/bin/kppp
    &dollar;{KDEDIR}/share/doc/HTML/.../kppp/*
    &dollar;{KDEDIR}/share/apps/kppp
    &dollar;{KDEDIR}/share/apps/kppp/Rules/*/*.rst
    &dollar;{KDEDIR}/share/apps/kppp/pics/*
    &dollar;{HOMEDIR}/.kde/share/apps/kppp
    &dollar;{HOMEDIR}/.kde/share/apps/kppp/kppp.pid
    &dollar;{HOMEDIR}/.kde/share/apps/kppp/Log/*
    &dollar;{HOMEDIR}/.kde/share/config/kppprc

### Reporting problems with kppp

Before reporting a problem or potential bug to the of kppp, please make sure that you have read the section Frequently asked Questions carefully.

If you still have problems, you need to include the following informations with your report:

- The version of kppp you are using. kppp -v will show the version number.

- The version of pppd you are using. /usr/sbin/pppd -h will show the number.

- What operating system and version you use. uname -a will tell you this information on most UNIX systems.

- If kppp reports "pppd died unexpectedly", add the debug option to the pppd arguments. Dial again to reproduce the error.

  Now the file `/var/log/messages` (this depends on your system and configuration, but a typically installed Linux system will have this. Of course you must have root permissions to read this file) will have a lot of debugging output at the end. Don't send us the whole file. It typically has several thousands of lines and we neither have time nor are we willing to process such a file. Just send us the last lines that contain pppd, instead. Make sure that this file does not contain security compromising information such as passwords or usernames. Replace such entries with something like "myusername" and "mypassword"

## The GNU General Public License

    		    GNU GENERAL PUBLIC LICENSE
    		       Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                              675 Mass Ave, Cambridge, MA 02139, USA
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

    			    Preamble

      The licenses for most software are designed to take away your
    freedom to share and change it.  By contrast, the GNU General Public
    License is intended to guarantee your freedom to share and change free
    software--to make sure the software is free for all its users.  This
    General Public License applies to most of the Free Software
    Foundation's software and to any other program whose authors commit to
    using it.  (Some other Free Software Foundation software is covered by
    the GNU Library General Public License instead.)  You can apply it to
    your programs, too.

      When we speak of free software, we are referring to freedom, not
    price.  Our General Public Licenses are designed to make sure that you
    have the freedom to distribute copies of free software (and charge for
    this service if you wish), that you receive source code or can get it
    if you want it, that you can change the software or use pieces of it
    in new free programs; and that you know you can do these things.

      To protect your rights, we need to make restrictions that forbid
    anyone to deny you these rights or to ask you to surrender the rights.
    These restrictions translate to certain responsibilities for you if you
    distribute copies of the software, or if you modify it.

      For example, if you distribute copies of such a program, whether
    gratis or for a fee, you must give the recipients all the rights that
    you have.  You must make sure that they, too, receive or can get the
    source code.  And you must show them these terms so they know their
    rights.

      We protect your rights with two steps: (1) copyright the software, and
    (2) offer you this license which gives you legal permission to copy,
    distribute and/or modify the software.

      Also, for each author's protection and ours, we want to make certain
    that everyone understands that there is no warranty for this free
    software.  If the software is modified by someone else and passed on, we
    want its recipients to know that what they have is not the original, so
    that any problems introduced by others will not reflect on the original
    authors' reputations.

      Finally, any free program is threatened constantly by software
    patents.  We wish to avoid the danger that redistributors of a free
    program will individually obtain patent licenses, in effect making the
    program proprietary.  To prevent this, we have made it clear that any
    patent must be licensed for everyone's free use or not licensed at all.

      The precise terms and conditions for copying, distribution and
    modification follow.

    		    GNU GENERAL PUBLIC LICENSE
       TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

      0. This License applies to any program or other work which contains
    a notice placed by the copyright holder saying it may be distributed
    under the terms of this General Public License.  The "Program", below,
    refers to any such program or work, and a "work based on the Program"
    means either the Program or any derivative work under copyright law:
    that is to say, a work containing the Program or a portion of it,
    either verbatim or with modifications and/or translated into another
    language.  (Hereinafter, translation is included without limitation in
    the term "modification".)  Each licensee is addressed as "you".

    Activities other than copying, distribution and modification are not
    covered by this License; they are outside its scope.  The act of
    running the Program is not restricted, and the output from the Program
    is covered only if its contents constitute a work based on the
    Program (independent of having been made by running the Program).
    Whether that is true depends on what the Program does.

      1. You may copy and distribute verbatim copies of the Program's
    source code as you receive it, in any medium, provided that you
    conspicuously and appropriately publish on each copy an appropriate
    copyright notice and disclaimer of warranty; keep intact all the
    notices that refer to this License and to the absence of any warranty;
    and give any other recipients of the Program a copy of this License
    along with the Program.

    You may charge a fee for the physical act of transferring a copy, and
    you may at your option offer warranty protection in exchange for a fee.

      2. You may modify your copy or copies of the Program or any portion
    of it, thus forming a work based on the Program, and copy and
    distribute such modifications or work under the terms of Section 1
    above, provided that you also meet all of these conditions:

        a) You must cause the modified files to carry prominent notices
        stating that you changed the files and the date of any change.

        b) You must cause any work that you distribute or publish, that in
        whole or in part contains or is derived from the Program or any
        part thereof, to be licensed as a whole at no charge to all third
        parties under the terms of this License.

        c) If the modified program normally reads commands interactively
        when run, you must cause it, when started running for such
        interactive use in the most ordinary way, to print or display an
        announcement including an appropriate copyright notice and a
        notice that there is no warranty (or else, saying that you provide
        a warranty) and that users may redistribute the program under
        these conditions, and telling the user how to view a copy of this
        License.  (Exception: if the Program itself is interactive but
        does not normally print such an announcement, your work based on
        the Program is not required to print an announcement.)

    These requirements apply to the modified work as a whole.  If
    identifiable sections of that work are not derived from the Program,
    and can be reasonably considered independent and separate works in
    themselves, then this License, and its terms, do not apply to those
    sections when you distribute them as separate works.  But when you
    distribute the same sections as part of a whole which is a work based
    on the Program, the distribution of the whole must be on the terms of
    this License, whose permissions for other licensees extend to the
    entire whole, and thus to each and every part regardless of who wrote it.

    Thus, it is not the intent of this section to claim rights or contest
    your rights to work written entirely by you; rather, the intent is to
    exercise the right to control the distribution of derivative or
    collective works based on the Program.

    In addition, mere aggregation of another work not based on the Program
    with the Program (or with a work based on the Program) on a volume of
    a storage or distribution medium does not bring the other work under
    the scope of this License.

      3. You may copy and distribute the Program (or a work based on it,
    under Section 2) in object code or executable form under the terms of
    Sections 1 and 2 above provided that you also do one of the following:

        a) Accompany it with the complete corresponding machine-readable
        source code, which must be distributed under the terms of Sections
        1 and 2 above on a medium customarily used for software interchange; or,

        b) Accompany it with a written offer, valid for at least three
        years, to give any third party, for a charge no more than your
        cost of physically performing source distribution, a complete
        machine-readable copy of the corresponding source code, to be
        distributed under the terms of Sections 1 and 2 above on a medium
        customarily used for software interchange; or,

        c) Accompany it with the information you received as to the offer
        to distribute corresponding source code.  (This alternative is
        allowed only for noncommercial distribution and only if you
        received the program in object code or executable form with such
        an offer, in accord with Subsection b above.)

    The source code for a work means the preferred form of the work for
    making modifications to it.  For an executable work, complete source
    code means all the source code for all modules it contains, plus any
    associated interface definition files, plus the scripts used to
    control compilation and installation of the executable.  However, as a
    special exception, the source code distributed need not include
    anything that is normally distributed (in either source or binary
    form) with the major components (compiler, kernel, and so on) of the
    operating system on which the executable runs, unless that component
    itself accompanies the executable.

    If distribution of executable or object code is made by offering
    access to copy from a designated place, then offering equivalent
    access to copy the source code from the same place counts as
    distribution of the source code, even though third parties are not
    compelled to copy the source along with the object code.

      4. You may not copy, modify, sublicense, or distribute the Program
    except as expressly provided under this License.  Any attempt
    otherwise to copy, modify, sublicense or distribute the Program is
    void, and will automatically terminate your rights under this License.
    However, parties who have received copies, or rights, from you under
    this License will not have their licenses terminated so long as such
    parties remain in full compliance.

      5. You are not required to accept this License, since you have not
    signed it.  However, nothing else grants you permission to modify or
    distribute the Program or its derivative works.  These actions are
    prohibited by law if you do not accept this License.  Therefore, by
    modifying or distributing the Program (or any work based on the
    Program), you indicate your acceptance of this License to do so, and
    all its terms and conditions for copying, distributing or modifying
    the Program or works based on it.

      6. Each time you redistribute the Program (or any work based on the
    Program), the recipient automatically receives a license from the
    original licensor to copy, distribute or modify the Program subject to
    these terms and conditions.  You may not impose any further
    restrictions on the recipients' exercise of the rights granted herein.
    You are not responsible for enforcing compliance by third parties to
    this License.

      7. If, as a consequence of a court judgment or allegation of patent
    infringement or for any other reason (not limited to patent issues),
    conditions are imposed on you (whether by court order, agreement or
    otherwise) that contradict the conditions of this License, they do not
    excuse you from the conditions of this License.  If you cannot
    distribute so as to satisfy simultaneously your obligations under this
    License and any other pertinent obligations, then as a consequence you
    may not distribute the Program at all.  For example, if a patent
    license would not permit royalty-free redistribution of the Program by
    all those who receive copies directly or indirectly through you, then
    the only way you could satisfy both it and this License would be to
    refrain entirely from distribution of the Program.

    If any portion of this section is held invalid or unenforceable under
    any particular circumstance, the balance of the section is intended to
    apply and the section as a whole is intended to apply in other
    circumstances.

    It is not the purpose of this section to induce you to infringe any
    patents or other property right claims or to contest validity of any
    such claims; this section has the sole purpose of protecting the
    integrity of the free software distribution system, which is
    implemented by public license practices.  Many people have made
    generous contributions to the wide range of software distributed
    through that system in reliance on consistent application of that
    system; it is up to the author/donor to decide if he or she is willing
    to distribute software through any other system and a licensee cannot
    impose that choice.

    This section is intended to make thoroughly clear what is believed to
    be a consequence of the rest of this License.

      8. If the distribution and/or use of the Program is restricted in
    certain countries either by patents or by copyrighted interfaces, the
    original copyright holder who places the Program under this License
    may add an explicit geographical distribution limitation excluding
    those countries, so that distribution is permitted only in or among
    countries not thus excluded.  In such case, this License incorporates
    the limitation as if written in the body of this License.

      9. The Free Software Foundation may publish revised and/or new versions
    of the General Public License from time to time.  Such new versions will
    be similar in spirit to the present version, but may differ in detail to
    address new problems or concerns.

    Each version is given a distinguishing version number.  If the Program
    specifies a version number of this License which applies to it and "any
    later version", you have the option of following the terms and conditions
    either of that version or of any later version published by the Free
    Software Foundation.  If the Program does not specify a version number of
    this License, you may choose any version ever published by the Free Software
    Foundation.

      10. If you wish to incorporate parts of the Program into other free
    programs whose distribution conditions are different, write to the author
    to ask for permission.  For software which is copyrighted by the Free
    Software Foundation, write to the Free Software Foundation; we sometimes
    make exceptions for this.  Our decision will be guided by the two goals
    of preserving the free status of all derivatives of our free software and
    of promoting the sharing and reuse of software generally.

    			    NO WARRANTY

      11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
    FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
    OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
    PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
    OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
    TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
    PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
    REPAIR OR CORRECTION.

      12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
    WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
    REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
    INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
    OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
    TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
    YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
    PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGES.

    		     END OF TERMS AND CONDITIONS