<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
 <!ENTITY kppp "<application>kppp</application>">
]>
<book lang="en">
<bookinfo>
<title>The <emphasis>kppp</emphasis> Handbook</title>
<authorgroup>
<author>
<firstname>Bernd Johannes</firstname>
<surname>Wuebben</surname>
<affiliation>
<address><email><ulink url="mailto:wuebben@kde.org">wuebben@kde.org</ulink></email></address></affiliation>
</author>
</authorgroup>
<date>Version 1.6.2, February 5, 1999</date>
<releaseinfo><!-- information about this particular version --></releaseinfo>
<abstract>
<para>This Handbook describes <emphasis>kppp</emphasis> Version 1.6.2</para>
<para>KPPP Internet Dialer</para><!-- Merge this with the previous paragraph; it comes from <META NAME="description" CONTENT="..."> --></abstract>
<keywordset>
<keyword>KPPP</keyword>
<keyword>Dialer</keyword>
<keyword>Internet</keyword>
<keyword>PPP</keyword>
<keyword>IP</keyword>
<keyword>PAP</keyword>
<keyword>CHAP</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<sect1 id="aboutkppp">
<title>About <emphasis>kppp</emphasis></title>

<para> <literal remap="tt"> PLEASE DON'T FORGET TO READ THE FREQUENTLY ASKED QUESTIONS! THANK YOU! </literal></para>

<para><emphasis>kppp</emphasis> 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 <emphasis>kppp</emphasis> 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. <emphasis>kppp</emphasis> features elaborate
phone cost accounting, which enables you to easily track your online
costs.</para>

<para>We hope you will enjoy this dialer.</para>
</sect1>

<sect1 id="maintainers">
<title>Authors</title>

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

<para>The main authors are:
<itemizedlist>
<listitem>
<para><literal remap="tt">Bernd Johannes Wuebben</literal>
<ulink url="mailto:wuebben@kde.org">wuebben@kde.org</ulink></para>
</listitem>
<listitem>
<para><literal remap="tt">Mario Weilguni</literal>
<ulink url="mailto:mweilguni@sime.com">mweilguni@sime.com</ulink></para>
</listitem>
<listitem>
<para><literal remap="tt">Harri Porten</literal>
<ulink url="mailto:porten@kde.org">porten@kde.org</ulink></para>
</listitem>
</itemizedlist>
</para>

<para>Many thanks to the following people who have contributed code to <emphasis>kppp</emphasis></para>

<para><itemizedlist>
<listitem>
<para><ulink url="mailto:jesus.fuentes@etsi.tel.uva.es">Jesus Fuentes Saaverdra</ulink> for implementing several options and miscellaneous work.
</para>
</listitem>
<listitem>
<para><ulink url="mailto:wuebben@eure.de">Markus Wuebben</ulink> for the ATI query dialog.
</para>
</listitem>
<listitem>
<para><ulink url="mailto:peter.silva@videotron.ca">Peter Silva</ulink> for pop
up dialogs
and other contributions.</para>
</listitem>
<listitem>
<para><ulink url="mailto:MABrown@etcconnect.com">Martin A. Brown</ulink> for
proofreading some English text in the program</para>
</listitem>
<listitem>
<para><ulink url="mailto:mh@ap-dec717c.physik.uni-karlsruhe.de">Martin Häfner</ulink> for the section on <link linkend="cb">callback</link></para>
</listitem>
<listitem>
<para><ulink url="mailto:okir@caldera.de">Olaf Kirch</ulink> for the introduction
to the mysteries of file descriptor passing.</para>
</listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="licenseandwarranty">
<title>License and warranty</title>

<para><emphasis>kppp</emphasis> is published under the terms of the <link linkend="GPL">GNU  General Public License</link> (GPL). There is <link linkend="gpl">no warranty</link> that this program works or for whatever.</para>
</sect1>
</chapter>

<chapter id="installation">
<title>Installation</title>

<para> <literal remap="tt"> PLEASE DON'T FORGET TO READ THE FREQUENTLY ASKED QUESTIONS! THANK YOU! </literal></para>

<sect1 id="howtoobtainkppp">
<title>How to obtain <emphasis>kppp</emphasis></title>

<para><emphasis>kppp</emphasis> is an application for the KDE project <ulink url="http://www.kde.org">http://www.kde.org</ulink>.
Kppp can be found on <ulink url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>, the main ftp site
of the KDE project.</para>
</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>In order to successfully compile <emphasis>kppp</emphasis>, you need the latest versions of <literal remap="tt">libkdecore</literal>
and <literal remap="tt">libkdeui</literal>. All required libraries as well as <emphasis>kppp</emphasis> itself can be found
on <ulink url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>. </para>
</sect1>

<sect1 id="compilationandinstallation">
<title>Compilation and installation</title>

<para> <literal remap="tt"> PLEASE DON'T FORGET TO READ THE FREQUENTLY ASKED QUESTIONS! THANK YOU! </literal></para>

<para>I haven't been able to test <emphasis>kppp</emphasis> 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.</para>

<para>If wish to compile <emphasis>kppp</emphasis> 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.</para>

<para>In order to compile and install <emphasis>kppp</emphasis> on your system, type the following in the base 
directory of the <emphasis>kppp</emphasis> distribution:
<screen>% ./configure
% make
% make install
</screen>
</para>

<para>This will install <emphasis>kppp</emphasis> with the <xref linkend="setuid"> bit on.</para>

<para>Make sure that the pppd's option file which usually resides in <literal remap="tt">/etc/ppp/</literal>
exists, but is empty. pppd requires it to exist, but it must be empty otherwise
pppd will not take its options from <emphasis>kppp</emphasis>.</para>

<para><emphasis remap="bf">Again:</emphasis> Should you run into problems, please report them to me. </para>
</sect1>

<sect1 id="preparingyourlinuxsystemforapppconnection">
<title>Preparing Your Linux System for a PPP Connection</title>

<para>In order for <emphasis>kppp</emphasis>/pppd to work your kernel must have ppp support compiled in. If this is
not the case get yourself the latest version of 
<ulink url="ftp://sunsite.unc.edu/pub/Linux/system/Network/serial/ppp/">pppd</ulink>
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 <literal remap="tt">dmesg</literal> at the command prompt
and look for something like this:</para>

<para><screen>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
</screen>
</para>

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

<para>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 <literal remap="tt">/usr/sbin</literal>. 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:</para>

<para><screen>% pppd --version
</screen>
</para>

<para>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. </para>
</sect1>

<sect1 id="moreaboutppppppd">
<title>More about ppp/pppd</title>

<para>The following sites may be of interest for further information about the 
ppp protocol, pppd and networking in general:
<itemizedlist>
<listitem>
<para> Linux PPP FAQ: <ulink url="http://metalab.unc.edu/mdw/FAQ/PPP-FAQ.html">http://metalab.unc.edu/mdw/FAQ/PPP-FAQ.html</ulink></para>
</listitem>
<listitem>
<para> Linux PPP HOWTO: <ulink url="http://metalab.unc.edu/mdw/HOWTO/PPP-HOWTO.html">http://metalab.unc.edu/mdw/HOWTO/PPP-HOWTO.html</ulink></para>
</listitem>
<listitem>
<para> <ulink url="http://www.thoughtport.com:8080/PPP/index.html">http://www.thoughtport.com:8080/PPP/index.html</ulink></para>
</listitem>
<listitem>
<para> The Network Administrators' Guide: <ulink url="http://metalab.unc.edu/mdw/LDP/nag/nag.html">http://metalab.unc.edu/mdw/LDP/nag/nag.html</ulink></para>
</listitem>
</itemizedlist>
</para>
</sect1>
</chapter>

<chapter id="settingupkppp">
<title>Setting up <emphasis>kppp</emphasis></title>

<para>In order to set up <emphasis>kppp</emphasis>, start <emphasis>kppp</emphasis> and push the <literal remap="tt">Setup</literal> button on <emphasis>kppp</emphasis>'s
main window. A new tab dialog will appear. </para>

<sect1 id="accounts">
<title>Accounts</title>

<para>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. </para>
</sect1>

<sect1 id="lockfiles">
<title>Device</title>

<para><variablelist>
<varlistentry>
<term>Modem Device</term>
<listitem>
<para>Select the device appropriate for your
hardware. Here are some examples:
<itemizedlist>
<listitem>
<para><emphasis remap="bf">/dev/ttyS0</emphasis> - DOS or Windows users will know this as COM1, COM2 is
/dev/ttyS1 and so on. These devices are mostly used on Linux systems.</para>
</listitem>
<listitem>
<para><emphasis remap="bf">/dev/cua0</emphasis> - 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.</para>
</listitem>
<listitem>
<para><emphasis remap="bf">/dev/ttyI0</emphasis> - 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</para>
</listitem>
<listitem>
<para><emphasis remap="bf">/dev/modem</emphasis> - many Linux distributions make a symbolic link from
the real modem device to /dev/modem. <emphasis remap="bf">You should avoid using this
one</emphasis>. Use /dev/ttySx (x is a digit) instead of.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Flow Control</term>
<listitem>
<para>Select from Hardware (CRTSCTS), Software (XON/XOFF) and
no flow control. The recommended setting is Hardware flow control.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Line Termination</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Connection Speed</term>
<listitem>
<para>Choose from the list of connections speeds supported by
your serial port. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Use Lock File</term>
<listitem>
<para>Activate this option if you want <emphasis>kppp</emphasis> to create a lockfile. Under Linux
the directory for such a file will be <literal remap="tt">/var/lock</literal>.
Programs such as mgetty depend on the existence of such lock files and
<emphasis>kppp</emphasis> 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 <emphasis>kppp</emphasis> to lock the modem,
since the pppd option "lock" will induce pppd to try to lock the
modemdevice. However since <emphasis>kppp</emphasis> already locked the device pppd
will fail and <emphasis>kppp</emphasis> will display "pppd died unexpectedly".</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Modem Timeout</term>
<listitem>
<para>This is the time in seconds that <emphasis>kppp</emphasis> 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.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>

<sect1 id="modem">
<title>Modem</title>

<para><variablelist>
<varlistentry>
<term>Modem Commands</term>
<listitem>
<para>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 <emphasis>kppp</emphasis>
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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Query Modem</term>
<listitem>
<para>Pushing the Query Modem Button will induce <emphasis>kppp</emphasis> 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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Terminal</term>
<listitem>
<para>Pushing the <literal remap="tt">Terminal</literal> 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.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>

<sect1 id="ppp">
<title>PPP</title>

<para><variablelist>
<varlistentry>
<term>pppd Timeout</term>
<listitem>
<para><emphasis>kppp</emphasis> 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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Automatic Redial on Disconnect</term>
<listitem>
<para>Selecting this will have <emphasis>kppp</emphasis> try to 
reconnect in case you inadvertently got disconnected while online.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Show Clock on Caption</term>
<listitem>
<para>This will have <emphasis>kppp</emphasis> display the time connected
on the caption of the <emphasis>kppp</emphasis> window displayed while being online.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Disconnect on X-server shutdown</term>
<listitem>
<para>Checking this option will cause <emphasis>kppp</emphasis>
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 <emphasis>kppp</emphasis> on X-server exit or simply
don't want to have to worry about disconnecting your connection.
If you don't want <emphasis>kppp</emphasis> 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 <emphasis>kppp</emphasis> to hang up on X-server exit,  you will 
have a nonterminated accounting entry in you accounting logs, when the
X-server exits and <emphasis>kppp</emphasis> terminates.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Minimize Window on Connect</term>
<listitem>
<para><emphasis>kppp</emphasis>'s window will be minimized after a connection has been established. The elapsed connection time will be shown in the taskbar.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Dock into Panel on Connect</term>
<listitem>
<para>If this option is chosen <emphasis>kppp</emphasis> 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 <emphasis>kppp</emphasis>'s window. The right mouse button will open up a popup-menu</para>
<para>that offers to restore the window, show further transfer statistics or close the connection.
This option overrides <emphasis>Minimise Window on Connect</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
</chapter>

<chapter id="configuringanaccount">
<title>Configuring an Account</title>

<sect1 id="pppdarguments">
<title>Dial</title>

<para><variablelist>
<varlistentry>
<term>Connection Name</term>
<listitem>
<para>You must give the account a name. You can use anything
here, but if you have multiple accounts it must be unique.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Phone Number</term>
<listitem>
<para>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) <emphasis>kppp</emphasis> will try these numbers in a cyclic order whenever it receives a busy signal.
Example: "1111111:2222222:3333333"</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Authentication</term>
<listitem>
<para>Choose the appropriate method of authentication
that <emphasis>kppp</emphasis> 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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Store password</term>
<listitem>
<para>Check this option if you want <emphasis>kppp</emphasis> to remember
your password at the next session. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Execute Program upon Connect</term>
<listitem>
<para><emphasis>kppp</emphasis> will attempt to execute the command specified here once a ppp link has been set up. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Execute Program before Disconnect</term>
<listitem>
<para><emphasis>kppp</emphasis> 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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Execute Program upon Disconnect</term>
<listitem>
<para>analogue with previous item.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Edit pppd arguments</term>
<listitem>
<para>This will bring up the pppd arguments dialog. You may use
this dialog to add any desired options that you want <emphasis>kppp</emphasis> 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.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>

<sect1 id="autoconfigurehostname">
<title>IP</title>

<para><variablelist>
<varlistentry>
<term>Dynamic IP Address</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Static IP Address</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Auto-configure Hostname from this IP</term>
<listitem>
<para>Select this option if you want 
<emphasis>kppp</emphasis> 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 ...</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>

<sect1 id="dns">
<title>DNS</title>

<para><variablelist>
<varlistentry>
<term>Domain Name</term>
<listitem>
<para>Specify the domain name for your machine.
As with DNS Addresses it is restored to the original specified in <literal remap="tt">/etc/resolv.conf</literal>
when the connection goes down.
If it is left blank no changes are made to the domain name specified
in <literal remap="tt">/etc/resolv.conf</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DNS Servers</term>
<listitem>
<para>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 <literal remap="tt">/etc/resolv.config</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Disable existing DNS Servers during Connection</term>
<listitem>
<para>Select this option if 
you want <emphasis>kppp</emphasis> to disable already existing nameserver entries
in <literal remap="tt">/etc/resolv.conf</literal> during connection.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>

<sect1 id="gateway">
<title>Gateway</title>

<para><variablelist>
<varlistentry>
<term>Default Gateway</term>
<listitem>
<para>Check this if you want pppd to use the default Gateway
for your machine. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Static Gateway</term>
<listitem>
<para>Check this if you want to specify the Gateway to be used.</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para><variablelist>
<varlistentry>
<term>Assign the Default Route to this Gateway</term>
<listitem>
<para>You almost certainly will need
this. Leave it on unless you really know what you are doing.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>

<sect1 id="loginscript">
<title>Login Script</title>

<para><variablelist>
<varlistentry>
<term>Edit Script</term>
<listitem>
<para>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.</para>
<para><itemizedlist>
<listitem>
<para>Expect: <emphasis>kppp</emphasis> will wait for the specified string to be received.</para>
</listitem>
<listitem>
<para>Send: <emphasis>kppp</emphasis> will send the specified string.</para>
</listitem>
<listitem>
<para>Scan: <emphasis>kppp</emphasis> 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.</para>
</listitem>
<listitem>
<para>Save: permanently store the previously scanned string in the specified register. So far, the only valid register is 'password'.  </para>
</listitem>
<listitem>
<para>Pause: pause for the specified number of seconds</para>
</listitem>
<listitem>
<para>Hangup: <emphasis>kppp</emphasis> will send the hangup command to the modem</para>
</listitem>
<listitem>
<para>Answer: <emphasis>kppp</emphasis> will set the modem into answer mode</para>
</listitem>
<listitem>
<para>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.
</para>
</listitem>
<listitem>
<para>Prompt: Prompt the <emphasis>kppp</emphasis> 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.
</para>
</listitem>
<listitem>
<para>PWPrompt: Prompt the <emphasis>kppp</emphasis> user to enter a string, given the specified
string as a hint.  An asterisk will be printed for each character typed.
</para>
</listitem>
<listitem>
<para>ID: If the ID field on <emphasis>kppp</emphasis>'s main dialog is filled in, send that ID.
If the ID field is not filled in, prompt the <emphasis>kppp</emphasis> 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.
</para>
</listitem>
<listitem>
<para>Password: If the password field on <emphasis>kppp</emphasis>'s main dialog is filled in, send that 
password. If the password  field is not filled in, prompt the <emphasis>kppp</emphasis> 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.
</para>
</listitem>
<listitem>
<para>LoopStart: <emphasis>kppp</emphasis> will wait for the specified string to be received.
It will save the string for use by LoopEnd
</para>
</listitem>
<listitem>
<para>LoopEnd: <emphasis>kppp</emphasis> 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.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<sect2 id="examplescripts">
<title>Example scripts</title>

<para>Here is a simple script I could use to connect to my ISP:</para>

<para><screen>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.
</screen>
</para>

<para>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 <emphasis>kppp</emphasis>'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, <emphasis>kppp</emphasis> will start the script again after the LoopStart keyword.</para>

<para><screen>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
</screen>
</para>

<para>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 <emphasis>kppp</emphasis>'s main dialog.</para>

<para><screen>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
</screen>
</para>

<para>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.</para>

<para><screen>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
</screen>
</para>

<para>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.</para>

<para><screen>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:
</screen>
</para>

<para><emphasis>kppp</emphasis> 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:     
<screen>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
</screen>
</para>
</sect2>
</sect1>

<sect1 id="accounting">
<title>Accounting</title>

<para><variablelist>
<varlistentry>
<term>Accounting Setup</term>
<listitem>
<para>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 <literal remap="tt">TEMPLATE</literal> in <filename>&dollar;&lcub;KDEDIR&rcub;/share/doc/HTML/en/kppp/</filename>. 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 <emphasis>kppp</emphasis> and
must be installed in <literal remap="tt">&dollar;&lcub;KDEDIR&rcub;/share/apps/kppp/Rules</literal> or in 
<literal remap="tt">&dollar;&lcub;HOME&rcub;/.kde/share/apps/kppp/Rules</literal> before you will be able to
select it in this
dialog.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>

<sect1 id="volaccounting">
<title>Volume accounting</title>

<sect2 id="whatisvolumeaccounting">
<title>What is volume accounting?</title>

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

<sect2 id="whyshouldiusevolumeaccounting">
<title>Why should I use volume accounting?</title>

<para>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. <emphasis>kppp</emphasis> 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...</para>
</sect2>

<sect2 id="whattypeofvolumeaccountingshouldiselect">
<title>What type of volume accounting should I select?</title>

<para>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.</para>
</sect2>

<sect2 id="drawbacks">
<title>Drawbacks</title>

<para>Unfortunately thereīs a drawback on volume accounting. <emphasis>kppp</emphasis> 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, <emphasis>kppp</emphasis> 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 <emphasis>kppp</emphasis> may be
higher.</para>
</sect2>
</sect1>
</chapter>

<chapter id="modemtrickshints">
<title>Modem Tricks & Hints</title>

<para>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.</para>

<sect1 id="modemsessions">
<title>Modem Sessions</title>

<para>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 <emphasis remap="bf">ATZ</emphasis> (which 
resets your modem)  Your should get an <emphasis remap="bf">OK</emphasis> response.  use File/Close to 
end the session.</para>
</sect1>

<sect1 id="modemprofiles">
<title>Modem Profiles</title>

<para>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,...  <emphasis remap="bf">AT&amp;V</emphasis>
can be used to view them all.  The default profile is usually 0 (this 
can be changed via <emphasis remap="bf">AT&amp;Y</emphasis>.) The profile currently in use is called the "active" 
profile.</para>

<para>When you change a setting, the active profile is modified.  The <emphasis remap="bf">ATZ</emphasis> 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 <emphasis remap="bf">ATZ</emphasis><emphasis>n</emphasis> (where <emphasis>n</emphasis> is the profile number).  Make the
changes you want, then save it with <emphasis remap="bf">AT&amp;W<emphasis>n</emphasis></emphasis>.  To have <emphasis>kppp</emphasis> use the profile
you want, change the modem initialization string
(Setup/Modem/Modem Commands/Initialization String.)  For example
<emphasis remap="bf">ATZ1</emphasis> will have the <emphasis>kppp</emphasis> reset the modem and use stored profile &num;1.</para>

<para>If you want reset you modem to get back to some known starting point, use
<emphasis remap="bf">AT&amp;F&amp;W</emphasis> to set the active profile to the factory defaults, and store those
settings as the default profile.  </para>

<para>Example of profile changes are in the next section.</para>
</sect1>

<sect1 id="gettingthemodemtohangup">
<title>Getting the modem to hang up</title>

<para>Sometimes, you may find <emphasis>kppp</emphasis> has difficulties hanging up the modem.  This
is likely the result of a mismatch between <emphasis>kppp</emphasis> 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).   </para>

<para>Outside of <emphasis>kppp</emphasis>, 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.</para>

<sect2 id="dtratdnmethod">
<title>DTR (AT&amp;Dn) method</title>

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

<para><screen>ATZ		# reset to default profile
AT&amp;D2		# Set to hang up on DTR drop.
AT&amp;W		# Write to default profile
</screen>
</para>

<sect3 id="howthedtrmethodworks">
<title>How The DTR Method Works</title>

<para>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 <emphasis>kppp</emphasis> 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 <emphasis>kppp</emphasis> has closed
the serial port, or something worse!), the modem will hangup.</para>
</sect3>
</sect2>

<sect2 id="commandmethod">
<title>Command Method</title>

<para>The other way to have a modem hang up when connected (used when AT&amp;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:</para>

<para><screen>ATZ
ATS12=5
AT&amp;W
</screen>
</para>

<para>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.</para>

<sect3 id="howthecommandmethodworks">
<title>How The Command Method Works</title>

<para>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.</para>

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

<para><itemizedlist>
<listitem>
<para>Quiet (must last more than S12/50 seconds)</para>
</listitem>
<listitem>
<para>Escape character (defined by register S2, default is "+") 
repeated three times (less than S12/50 seconds between each)</para>
</listitem>
<listitem>
<para>Quiet (must last more than S12/50 seconds)
</para>
</listitem>
</itemizedlist>
</para>

<para>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 <emphasis>kppp</emphasis>
are shown in the Setup/More/Modem Commands dialogs.  These should match
your modem.</para>
</sect3>
</sect2>
</sect1>

<sect1 id="maketonediallingfaster">
<title>Make Tone Dialling Faster</title>

<para>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. </para>

<para><screen>ATZ		# reset to default profile
ATS11=50	# fastest possible dialling, use a higher number if it doesn't work.
AT&amp;W		# Write to default profile
</screen>
</para>
</sect1>
</chapter>

<chapter id="papandchap">
<title>PAP and CHAP</title>

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

<sect1 id="papwithkppp">
<title>PAP with <emphasis>kppp</emphasis></title>

<para>There are two different ways to use PAP:</para>

<sect2 id="clientsideauthentication">
<title>Client side authentication</title>

<para> 
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. <emphasis>kppp</emphasis> supports
this variant directly. See below for instruction how use this one.</para>

<para>If your ISP just gives you a username and a password and tells you to use
PAP authentication you must use this variant.</para>
</sect2>

<sect2 id="twowayauthentication">
<title>Two way authentication</title>

<para> 
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 <emphasis remap="it">Script based</emphasis>,
not <emphasis remap="it">PAP</emphasis>, and you will have to manually edit
<literal remap="tt">/etc/ppp/pap-secrets</literal>. While <emphasis>kppp</emphasis> doesn't provide build in support
for this variant -- it is nevertheless easy to establish a connection
using this variant of PAP with <emphasis>kppp</emphasis>. The details are described in the
previous section 'Using PAP and CHAP with <emphasis>kppp</emphasis>'.</para>
</sect2>

<sect2 id="preparingkpppforpap">
<title>Preparing <emphasis>kppp</emphasis> for PAP</title>

<para><orderedlist><listitem>
<para> Make sure that the <literal remap="tt">/etc/ppp/options</literal> (and <literal remap="tt">&tilde;/.ppprc</literal> if
you do have such a file) does <emphasis remap="bf">not</emphasis> contain one of the arguments:
<itemizedlist>
<listitem>
<para>+pap</para>
</listitem>
<listitem>
<para>-pap</para>
</listitem>
<listitem>
<para>papcrypt</para>
</listitem>
<listitem>
<para>+chap</para>
</listitem>
<listitem>
<para>+ua</para>
</listitem>
<listitem>
<para>remotename</para>
</listitem>
</itemizedlist>
</para>

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

</listitem>
<listitem>
<para>Start <emphasis>kppp</emphasis></para>
</listitem>
<listitem>
<para>Click on <emphasis remap="it">Setup</emphasis></para>
</listitem>
<listitem>
<para>Choose the account you want to use PAP with and click on <emphasis remap="it">Edit</emphasis></para>
</listitem>
<listitem>
<para>Click on the <emphasis remap="it">Dial</emphasis> tab.</para>
</listitem>
<listitem>
<para>Select <emphasis remap="it">PAP</emphasis> in the checkbox <emphasis remap="it">Authentication</emphasis></para>
</listitem>
<listitem>
<para>If you do not want to retype the password each time you dial in, select
<emphasis remap="it">Store password</emphasis>. 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.</para>
</listitem>
<listitem>
<para>That's it. Close the dialogs, type in your the username and password
your ISP supplied to you and dial.</para>
</listitem>
</orderedlist>
</para>
</sect2>
</sect1>

<sect1 id="pap">
<title>PAP and CHAP with <emphasis>kppp</emphasis> (alternate method)</title>

<para>The following is based on an email by <ulink url="kbrown@pdq.net">Keith Brown</ulink>
and explains how to make <emphasis>kppp</emphasis> 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 <emphasis>kppp</emphasis>'.</para>

<para>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 <literal remap="tt">/etc/ppp</literal>.</para>

<para>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 <literal remap="tt">/etc/ppp/pap-secrets </literal>. 
The format of an entry for our purposes, is:</para>

<para><screen>USERNAME  SERVERNAME   PASSWORD
</screen>
</para>

<para>so I add the line:</para>

<para><screen>booger  glob  foobar
</screen>
</para>

<para>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.</para>

<para>Now, I need to set up my connection in <emphasis>kppp</emphasis>. 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 <literal remap="tt">/etc/ppp/options,</literal> 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.</para>

<para>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.</para>

<para>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.</para>
</sect1>
</chapter>

<chapter id="questionsandanswers">
<title>Questions and answers</title>

<sect1 id="ltemkpppfaq">
<title>Frequently Asked Questions</title>

<sect2 id="icantgetkppptoworkkppptellsmethatpppdhasdied">
<title>I can't get <emphasis>kppp</emphasis> to work. <emphasis>kppp</emphasis> tells me that pppd has died or that a timeout has expired! </title>

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

<para><itemizedlist>
<listitem>
<para> Click on the "Details" button. <emphasis>kppp</emphasis> 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.
</para>
</listitem>
<listitem>
<para> Make sure that pppd is the actual pppd binary not a script
</para>
</listitem>
<listitem>
<para> Make sure that pppd is setuid root. You may set this mode by issuing <emphasis remap="it">chmod u+s pppd</emphasis> as root.
</para>
</listitem>
<listitem>
<para> Make sure that your <literal remap="tt">/etc/ppp/options</literal> file exists and that it doesnīt contain any conflicting entries. If in doubt: Leave this file empty. 
</para>
</listitem>
<listitem>
<para> Make sure that you DON'T use the option "lock" as an argument
for pppd (<emphasis>kppp</emphasis> is already taking care of device locking )
</para>
</listitem>
<listitem>
<para> Remove the "lock" option from your <literal remap="tt">/etc/ppp/options</literal>
and <literal remap="tt">&tilde;/.ppprc</literal> files!
</para>
</listitem>
<listitem>
<para> Using the symbolic link <literal remap="tt">/dev/modem</literal> may cause some conflicts.
Eliminate this source of trouble by using the real device, i.e. <literal remap="tt">/dev/cuaX</literal>
or <literal remap="tt">/dev/ttySX</literal>.
NOTE: COM1 equals ttyS0, COM2 is ttyS1 and so on. </para>
</listitem>
<listitem>
<para> 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 <emphasis>kppp</emphasis> setuid root. The proper way to proceed would probably
be creating a "modem" group.
</para>
</listitem>
<listitem>
<para> 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.
</para>
</listitem>
</itemizedlist>
</para>

<para>If nothing helps, you might obtain some debugging info from your systems log by issuing:
<screen># tail /var/log/messages
</screen>
</para>
</sect2>

<sect2 id="kppptellsmesorrycantopenthemodem">
<title><emphasis>kppp</emphasis> tells me ``Sorry, can't open the modem''.</title>

<para>This means that <emphasis>kppp</emphasis> 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 <emphasis>kppp</emphasis> the right permission to access the modem 
device and to be able to modify <literal remap="tt">/etc/resolv.conf</literal> in case you want <emphasis>kppp</emphasis> to 
configure DNS correctly for you. If you can afford to run <emphasis>kppp</emphasis> 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
<emphasis>kppp</emphasis> setuid root permissions do the following:</para>

<para><screen>% su root
# chown root:root &dollar;{KDEDIR}/bin/kppp
# chmod +s &dollar;{KDEDIR}/bin/kppp
# exit
</screen>
</para>
</sect2>

<sect2 id="setuid">
<title><emphasis>kppp</emphasis> tells me it can't create a modem lock file.</title>

<para>This in most instances means that you have installed <emphasis>kppp</emphasis>
without SETUID bit on while you, the person executing <emphasis>kppp</emphasis>, 
doesn't have write access to the lock file directory which
by default is <literal remap="tt">/var/lock</literal>. 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 <emphasis>kppp</emphasis> SETUID if you can afford to, or give regular
users write access to <literal remap="tt">/var/lock</literal> or create a modem group
that will have access to the <literal remap="tt">/var/lock</literal> file.</para>
</sect2>

<sect2 id="whyiskpppinstalledwiththesetuidbiton">
<title>Why is <emphasis>kppp</emphasis> installed with the SETUID bit on?</title>

<para>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 <emphasis>kppp</emphasis>, then <literal remap="tt">/etc/resolv.conf</literal> must be read/writable by the
members of that group. The same counts for
<literal remap="tt">/etc/ppp/pap-secrets</literal> and <literal remap="tt">/etc/ppp/chap-secrets</literal> if
you want to use the built-in PAP or CHAP support, respectively.</para>

<para>Please do not criticise me for installing <emphasis>kppp</emphasis> 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 <emphasis>kppp</emphasis> to work because they 
didn't understand enough about Unix and device permissions.</para>

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

<para>You might also want to read the <link linkend="security">Security</link> section.</para>
</sect2>

<sect2 id="kpppjustsitsthereandwaitsexpectingok">
<title><emphasis>kppp</emphasis> just sits there and waits: Expecting OK</title>

<para><itemizedlist>
<listitem>
<para> Have you played with the CR/LF setting? Try CR, LF or CR/LF.
</para>
</listitem>
<listitem>
<para> 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.
</para>
</listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="autohostname">
<title>The connection works fine but I canīt start any applications.</title>

<para>You probably have activated the <xref linkend="Autoconfigurehostname"> 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 <emphasis remap="it">xhost +</emphasis> before starting the connection would do the job, but be <emphasis remap="bf">warned</emphasis> of any security risks that involves since everyone else is granted access to your X Server.</para>
</sect2>

<sect2 id="kpppreportsasuccessfulconnectionbutnetscapej">
<title><emphasis>kppp</emphasis> reports a successful connection, but Netscape just says "The server does not have a DNS entry"</title>

<para>Try pinging another server by its IP number, e.g. <literal remap="tt">ping 195.0.254.76</literal>. If that
works you should</para>

<para><itemizedlist>
<listitem>
<para> check if you provided <emphasis>kppp</emphasis> with at least one DNS address</para>
</listitem>
<listitem>
<para> check the contents of <literal remap="tt">/etc/host.conf</literal>. There should be a line
saying something similar to <literal remap="tt">order hosts, bind</literal>. The <literal remap="tt">bind</literal>
keyword advises the resolver library to include a name server query when
performing an address lookup.
</para>
</listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="howdoimakekpppsendanorar">
<title>How do I make <emphasis>kppp</emphasis> send a \n or a \r?</title>

<para>Just send an empty string such as in the following script:
<screen>Send                                   # send an empty string
Expect      ID:                        
Send        itsme                     
Expect      word:                      
Send        forgot                    
Expect      granted                    
Send        ppp                        
                                       
</screen>
</para>
</sect2>

<sect2 id="kpppcomplainscantcreatelockfile">
<title><emphasis>kppp</emphasis> complains: "Can't create lock file"</title>

<para>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 <emphasis>kppp</emphasis> setuid permissions. Please read the section on <xref linkend="lockfiles">.</para>
</sect2>

<sect2 id="mymodemmakesmuchnoisewhendialling">
<title>My modem makes much noise when dialling!</title>

<para>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"!</para>
</sect2>

<sect2 id="iturnedthemodemvolumeoffandverifiedthemodemc">
<title>I turned the modem volume "off" and verified the modem commands,
but I still hear that noise when dialling!</title>

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

<para>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"!</para>
</sect2>

<sect2 id="kpppreportsanunusualmodemspeedlike1152005760">
<title><emphasis>kppp</emphasis> reports an unusual modem speed like 115200, 57600 or similar </title>

<para>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".</para>
</sect2>

<sect2 id="kpppreportsunknownspeed">
<title><emphasis>kppp</emphasis> reports "Unknown speed"</title>

<para>New modems often have very complex connection messages like "CONNECT
LAP.M/V42.bis/115000:RX/31200:TX", and <emphasis>kppp</emphasis> 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.</para>
</sect2>

<sect2 id="slowconnectionspeed">
<title>Slow connection speed</title>

<para>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.</para>

<para>Additionally, consult your modem manual to look for init strings that enable a
high speed mode.</para>
</sect2>

<sect2 id="reallyslowconnectionspeed">
<title>REALLY slow connection speed</title>

<para>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.</para>

<para>Obtain some information about your serial port with
<literal remap="tt">setserial -a /dev/ttySx</literal> and check for interrupt conflicts with other
components of your system.</para>
</sect2>

<sect2 id="myphonelineneedspulsediallinginsteadoftonedi">
<title>My phone line needs pulse dialling instead of tone dialling (or vice-versa)</title>

<para>You must modify you modem dial string. Nearly all modems support the 
following AT-commands:
<itemizedlist>
<listitem>
<para>ATDT - selects tone dial</para>
</listitem>
<listitem>
<para>ATDP - selects pulse dial</para>
</listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="kpppmakesreallystrangethingswhatever">
<title><emphasis>kppp</emphasis> makes really strange things (whatever)</title>

<para>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.</para>
</sect2>

<sect2 id="howdoiwriteatelephonecostrulesfile">
<title>How do I write a telephone cost rules file?</title>

<para>Just follow the TEMPLATE rules files supplied with <emphasis>kppp</emphasis>. You should be
able to find a copy in the <literal remap="tt">&dollar;&lcub;KDEDIR&rcub;/doc/HTML/kppp</literal>. 
Use the <literal remap="tt">-r</literal> <emphasis>kppp</emphasis> command line options to check the syntax of your proposed
rules file.</para>
</sect2>

<sect2 id="ihavewrittenatelephonecostrulesfileformyregi">
<title>I have written a telephone cost rules file for my region. Where can I submit it so that others can make use of it?</title>

<para>I would love to receive any rule files written. I will make them available
on my <emphasis>kppp</emphasis> <ulink url="http://math.cornell.edu/~wuebben/kppp/kppp.html">web page</ulink>.
Before you send me a new rules file make sure it is not already available on 
the <emphasis>kppp</emphasis> web page. Then email the new rules file  to 
<ulink url="mailto:wuebben@math.cornell.edu">me</ulink>.</para>
</sect2>

<sect2 id="canmyphonecostrulefilecontainfractionaltimeu">
<title>Can my phone cost rulefile contain fractional time units, e.g. "(0.17,
45.5)"?</title>

<para>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 :-)</para>
</sect2>

<sect2 id="mycountryobservesamovingholidaydifferentfrom">
<title>My country observes a moving holiday different from easter.</title>

<para>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 <ulink url="mailto:wuebben@math.cornell.edu">me</ulink> the patches.</para>
</sect2>
</sect1>

<sect1 id="howtointerpretthesystemslog">
<title>How to interpret the system's log</title>

<sect2 id="seriallineisloopedback">
<title>Serial line is looped back</title>

<para>Short answer: You haven't started the PPP software on the peer system.</para>

<para>See a posting from Al Longyear on <ulink url="http://www.dejanews.com/getdoc.xp?AN=184945314">http://www.dejanews.com/getdoc.xp?AN=184945314</ulink> for a more detailed explanation.</para>
</sect2>

<sect2 id="signal15">
<title>Signal 15</title>

<para>If you see the following lines you've probably just received a timeout error
from <emphasis>kppp</emphasis>, too. <emphasis>kppp</emphasis> 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.
<screen>pppd[26921]: pppd 2.3.5 started by me, uid 500
pppd[26921]: Using interface ppp0
pppd[26921]: Connect: ppp0 &lt;--&gt; /dev/ttyS0
pppd[26921]: Terminating on signal 15.
pppd[26921]: Connection terminated.
pppd[26921]: Exit.
</screen>
</para>
</sect2>

<sect2 id="receiveseriallinkisnot8-bitclean">
<title>Receive serial link is not 8-bit clean</title>

<para>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.</para>
</sect2>

<sect2 id="cantlocatemoduleppp-compress">
<title>can't locate module ppp-compress</title>

<para>Do you get the following messages ?
<screen>modprobe: can't locate module ppp-compress-21 
modprobe: can't locate module ppp-compress-26 
modprobe: can't locate module ppp-compress-24
</screen>
</para>

<para>Just add the lines </para>

<para><screen>alias ppp-compress-21 bsd_comp 
alias ppp-compress-24 ppp_deflate 
alias ppp-compress-26 ppp_deflate 
</screen>

to your /etc/conf.modules file. </para>
</sect2>
</sect1>
</chapter>

<chapter id="security">
<title><emphasis>kppp</emphasis> and Security Issues</title>

<para>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)</para>

<sect1 id="restrictingaccesstokppp">
<title>Restricting access to kppp</title>

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

<sect2 id="withgrouppermissions">
<title>With group permissions</title>

<para>Create a new group (you might want to name it "dialout" or
similar), put every user that should be allowed to use <emphasis>kppp</emphasis>
into that group and type:
<screen>chown root.dialout /usr/local/kde/bin/kppp
chmod 4750 /usr/local/kde/bin/kppp
</screen>

This assumes that KDE was installed in <literal remap="tt">/usr/local/kde</literal>
and your new group is named "dialout".</para>
</sect2>

<sect2 id="kpppsway">
<title><emphasis>kpppīs</emphasis> way</title>

<para>Before doing anything, <emphasis>kppp</emphasis> checks if there is a file named
<literal remap="tt">/etc/kppp.allow</literal>. 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:
<screen># /etc/kppp.allow
# comment lines like this are ignored, 
# as well as empty lines
fred
karl

# I put myself in here :-)
mweilguni
</screen>

In the example above only the users <emphasis remap="it">fred</emphasis>, <emphasis remap="it">karl</emphasis> and
<emphasis remap="it">mweilguni</emphasis> can use <emphasis>kppp</emphasis> to dial out, as well as every
user with a UID of 0. So you donīt need to put <emphasis remap="it">root</emphasis> in this
file.</para>
</sect2>
</sect1>

<sect1 id="kppphasthesuidbitonwhataboutsecurity">
<title><emphasis>kppp</emphasis> has the SUID bit on. What about security?</title>

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

<para><itemizedlist>
<listitem>
<para>Immidiatly after program start, <emphasis>kppp</emphasis> forks.</para>
</listitem>
<listitem>
<para>The master process (which does all GUI stuff, user interaction
and such) drops the SUID state afterwards, and runs with normal
user privileges.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>Master and slave process communicate with standard UNIX IPC.</para>
</listitem>
</itemizedlist>
</para>

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

<chapter id="cb">
<title>Configuring <emphasis>kppp</emphasis> for callback</title>

<para>The following section was provided by <ulink url="mailto:mh@ap-dec717c.physik.uni-karlsruhe.de">Martin Häfner</ulink>.</para>

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

<sect1 id="cb-intro">
<title>Unix (Linux) callback server</title>

<para>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 <link linkend="cb-ressources">callback server</link>.</para>

<para>If you have any questions or problems please feel free  to contact the <ulink url="mailto:mh@ap-dec717c.physik.uni-karlsruhe.de">author</ulink> of this section.</para>

<sect2 id="cb-kppp">
<title>Introduction in callback</title>

<para>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 <literal remap="tt">AutoAnswer</literal> the phone when a <literal remap="tt">RING</literal> is 
detected by the modem. This is done by using a certain modem command:</para>

<para><screen>AT&amp;S0=1
</screen>
</para>

<para>This means that the modem will pick up the phone after one <literal remap="tt">RING</literal>.
Remember, this is done without any client software interaction. 
Like a lot of other client programs 
<emphasis>kppp</emphasis> checks if the connection is closed by the server and stops the current 
session if a <literal remap="tt">NO CARRIER</literal> is detected. And this it the next 
problem:
<literal remap="tt">NO CARRIER</literal> 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 <emphasis>carrier up</emphasis> all the time
(which makes no problems if <emphasis>the client</emphasis> hangs up the line) by using the 
modem command:
<screen>AT&amp;C0
</screen>
</para>

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

<sect2 id="cb-scripting">
<title>The <emphasis>kppp</emphasis> setup</title>

<para>Setting up <emphasis>kppp</emphasis> to connect to a Linux callback server is quite straight 
forward. </para>

<para><orderedlist><listitem>
<para>You only have to tell the modem to accept connections 
(<link linkend="cb-intro">see above</link>) 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:
<screen>Dial String:   AT&amp;C0S0=1DT
</screen>


All the other configuration issues will remain as-is.
<emphasis>kppp</emphasis> has some problems with modem init and reset. See the 
<link linkend="cb-scripting">troubleshooting section</link> if you are confronted with trouble.
</para>
</listitem>
<listitem>
<para>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 <emphasis>CR</emphasis> as your line termination.
</para>
</listitem>
<listitem>
<para>The next sections describes the callback setup of <emphasis>kppp</emphasis> on base of the Linux
callback package (<link linkend="cb-ressources">see below</link>) 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:
<screen>Authentication:   Script-based
</screen>


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.
</para>
</listitem>
<listitem>
<para>Now you have to build the login script. This is a quite cool feature
of <emphasis>kppp</emphasis>. 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!)):

<screen>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      &gt;           # wait for the command prompt (this may vary)
Send        start_ppp   # start_ppp starts the pppd

</screen>


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. <emphasis>kppp</emphasis> 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. <emphasis>kppp</emphasis> expects the commandline prompt and 
starts a small script which fires up the pppd on the server. The script may
look like the following:

<screen>  #!/bin/sh

  stty -echo

  exec /usr/sbin/pppd -detach silent modem
</screen>


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 
<ulink url="http://ap-dec717c.physik.uni-karlsruhe.de/~mh/callback">here</ulink>.</para>
</listitem>
</orderedlist>
</para>

<para>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.</para>

<para><emphasis>Notice:</emphasis> <emphasis>kppp</emphasis> 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 <emphasis>kppp</emphasis> creates a Lock-file which will indicate the getty program that another
program (<emphasis>kppp</emphasis>) is using the line at the moment. See problems with mgetty in 
the general <link linkend="cb-scripting">troubleshooting</link> below.
</para>
</sect2>

<sect2 id="cb-ressources">
<title>Troubleshooting</title>

<para>There are some known problems with <emphasis>kppp</emphasis> in callback mode:</para>

<para><itemizedlist>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>As already described in the <link linkend="cb-kppp">setup section</link> you will
have to initialize the modem with the dial string. The normal 
<emphasis>kppp</emphasis> "initialization string" does not take more complex init strings 
needed for a callback setup.</para>
</listitem>
<listitem>
<para>The next topic is more general and not related with callback: <emphasis>kppp</emphasis> has 
some slight problems when sharing the modem line with another program
like mgetty. If mgetty is running on the same modem line, <emphasis>kppp</emphasis> is not 
able to initialize the modem correctly. This only happens on the second 
attempt.</para>
</listitem>
<listitem>
<para><emphasis>kppp</emphasis> is able to prompt for certain user input during a scripting based
connetion. Unfortunately <emphasis>kppp</emphasis> 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 <link linkend="cb-scripting">above</link>). 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).</para>
</listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="internetresourcesforserversoftware">
<title>Internet Resources for server software</title>

<para>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 <ulink url="http://www.dyer.demon.co.uk/slug/tipscrip.htm">here</ulink>.
The site is maintained by <ulink url="mailto:colin@wew.co.uk">Colin Mc Kinnon</ulink>, 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 <ulink url="http://www.icce.rug.nl/docs/programs/callback/callback.html">here</ulink>. The package is maintained by <ulink url="mailto:frank@icce.rug.nl">Frank B. Brokken</ulink>. As the package is not very easy to set up (although the setup is straight forward), I have written a <ulink url="http://ap-dec717c.physik.uni-karlsruhe.de/~mh/callback/">short introduction</ulink> for it. 
Also have a look in it if you need further general introduction to callback.</para>
</sect2>
</sect1>

<sect1 id="windowsntrascallback">
<title>Windows NT RAS callback</title>

<para>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). <literal remap="tt">pppd</literal> has support for this protocol, but you have to recompile <literal remap="tt">pppd</literal>.</para>

<para>If anybody has experience how to do this with <emphasis>kppp</emphasis>, please drop <ulink url="mailto:mweilguni@kde.org">me</ulink> a line.</para>
</sect1>
</chapter>

<chapter id="appendix">
<title>Appendix</title>

<sect1 id="thehayesmodemcommandset">
<title>The Hayes Modem Command Set</title>

<para><ulink url="hayes.html">The Hayes Command Set</ulink> might come handy if you 
need to fine-tune your modem commands.</para>
</sect1>

<sect1 id="kppprelatedfiles">
<title><emphasis>kppp</emphasis> related files</title>

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

<para><screen>&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
</screen>
</para>
</sect1>

<sect1 id="reportingproblemswithkppp">
<title>Reporting problems with <emphasis>kppp</emphasis></title>

<para>Before reporting a problem or potential bug to the 
<xref linkend="maintainers"> of <emphasis>kppp</emphasis>, 
please make sure that you have read the section <link linkend="ltemkpppFAQ">Frequently asked Questions</link> carefully.</para>

<para>If you still have problems, you need to include the following informations
with your report:
<itemizedlist>
<listitem>
<para>The version of <emphasis>kppp</emphasis> you are using. <emphasis remap="it">kppp -v</emphasis> will show the
version number.</para>
</listitem>
<listitem>
<para>The version of pppd you are using. <emphasis remap="it">/usr/sbin/pppd -h</emphasis> will show
the number.</para>
</listitem>
<listitem>
<para>What operating system and version you use. <emphasis remap="it">uname -a</emphasis> will tell you this
information on most UNIX systems.</para>
</listitem>
<listitem>
<para>If <emphasis>kppp</emphasis> reports "pppd died unexpectedly", add the <emphasis remap="it">debug</emphasis> option
to the <link linkend="pppdarguments">pppd arguments</link>. Dial again to
reproduce the error.</para>
<para>Now the file <literal remap="tt">/var/log/messages</literal> (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. <emphasis remap="bf">Don't send us the whole file</emphasis>. 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 <emphasis remap="it">pppd</emphasis>, instead. Make sure that this file does <emphasis remap="bf">not</emphasis> contain security compromising information such as passwords or usernames. Replace such entries with something like "myusername" and "mypassword"</para>

</listitem>
</itemizedlist>
</para>
</sect1>
</chapter>

<chapter id="gpl">
<title>The GNU General Public License</title>

<para>
<programlisting>		    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.
</programlisting>


<programlisting>			    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</programlisting>
</para>
</chapter>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
