<!DOCTYPE book PUBLIC  "-//KDE//DTD DocBook V4.1-Based Variant V1.0//EN" [
  <!ENTITY kappname "&kppp;" -- replace kapp here. This only *seems* redundant -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" -- change language only here -->
  <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Documentation V2.0//EN">
  %ents;
  <!-- Do not define any other entities; instead, use the entities
       from kde-genent.entities and <lg>/user.entities. -->
]>

<book lang="&language;">

<bookinfo>
<title>The &kppp; Handbook</title>

<authorgroup>
<author>
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation>
<address><email>vampyr@atconnex.net</email></address>
</affiliation>
</author>
</authorgroup>

<copyright>
<year>2001</year>
<holder>Lauri Watts</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>17/01/2001</date>
<releaseinfo>1.01.00</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>&kppp; is a dialer and front end for <application>pppd</application>,
allowing for interactive script generation and network setup.</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kppp</keyword>
<keyword>kdenetwork</keyword>
<keyword>dialler</keyword>
<keyword>internet</keyword>
<keyword>ppp</keyword>
</keywordset>

</bookinfo>

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

<para>&kppp; is a dialer and front end for <application>pppd</application>. It
allows for interactive script generation and network setup. It will automate the
dialing in process to your <acronym>ISP</acronym> while letting you conveniently
monitor the entire process. </para>

<para>Once connected &kppp; will provide a rich set of statistics and keep track
of the time spent online for you.</para>

<para>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 <application>seyon</application> or <application>minicom</application>
to test and setup your connection.</para>

<para>&kppp; features elaborate phone cost accounting, which enables you to
easily track your online costs.</para>

<para>We hope you enjoy this dialler, and that it eases your way onto the
internet.</para>

</chapter>

<chapter id="getting-online">
<title>Getting online the easy way</title>

<sect1 id="things-to-prepare">
<title>A few things you should have ready before you start</title>

<para>If you have a fairly modern &Linux distribution, you might find the rest
of this document superfluous.  &kppp; comes with a clever little wizard that in
many cases can have you up and running with an internet connection in just a few
minutes.</para>

<para>Whether using the wizard or not, you should know the following information
before you begin:</para>

<itemizedlist>
<listitem><para>Your <acronym>ISP</acronym> modem pool phone
number.</para></listitem>
<listitem><para>Your username and password for your
<acronym>ISP</acronym>.</para></listitem>
<listitem><para>Your <acronym>ISP</acronym>'s <acronym>DNS</acronym> servers
(one is sufficient, but two is better).</para></listitem>
</itemizedlist>

<para>Other optional information you should find out to fully access your
<acronym>ISP</acronym>'s services are:</para>

<itemizedlist>
<listitem><para>The incoming mail server address (often <systemitem
class="systemname">pop.yourisp.com</systemitem> or <systemitem 
class="systemname">mail.yourisp.com</systemitem>)</para><para>Also find out if
your <acronym>ISP</acronym> uses the POP3 protocol or IMAP.</para></listitem>
<listitem><para>The outgoing (<acronym>SMTP</acronym>) mail server address (it
could be the same as the incoming mail server, or it is often called something
like <systemitem
class="systemname">smtp.yourisp.com</systemitem>).</para></listitem>
<listitem><para>The Usenet News (<acronym>NNTP</acronym>) server address (possibly
<systemitem class="systemname">news.yourisp.com</systemitem> or <systemitem
class="systemname">nntp.yourisp.com</systemitem>).</para></listitem>
<listitem><para>Any proxy servers your <acronym>ISP</acronym> has set
up.</para></listitem>
</itemizedlist>

<para>All this information is probably available on any paperwork you received
from your <acronym>ISP</acronym> when you signed up with them, or you can find
it out from your <acronym>ISP</acronym>'s support telephone line.</para>

<para>Armed with the above, and a fairly recent default installation of &Linux;,
you may well find that setting up an internet connection is as simple as running
the &kppp; wizard.</para>
</sect1>

</chapter>

<chapter id="wizard">
<title>The &kppp; wizard</title>

<sect1 id="starting-the-wizard">
<title>Starting the Wizard.</title>

<para>You can start the wizard from &kppp;'s initial screen.  Start &kppp; from
your <guimenu>K</guimenu> menu, where you will find it's entry in the
<guisubmenu>Internet</guisubmenu> as <guimenuitem>Internet
Dialer</guimenuitem>.</para>

<para>The following dialog will appear:</para>

<screenshot>
<screeninfo>The &kppp; dialer startup screen</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-dialler-tab.png" format="PNG">
</imageobject>
<textobject><phrase>The &kppp; dialer startup screen</phrase>
</textobject>
<caption><para>The &kppp; dialer startup screen</para></caption>
</mediaobject>
</screenshot>

<para>It will probably not have any entries to begin with, and that's what we're
about to do now.</para>

<para>Click the <guibutton>Setup</guibutton> button to begin setting up a new
Internet connection.</para>

<para>The wizard will offer you three choices, <guibutton>Wizard</guibutton>,
<guibutton>Dialog Setup</guibutton> and <guibutton>Cancel</guibutton></para>

<screenshot>
<screeninfo>The wizard asks you what you want to do...</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-wizard.png" format="PNG">
</imageobject>
<textobject><phrase>The wizard asks you what you want to
do...</phrase></textobject>
<caption><para>The wizard asks you what you want to do</para></caption>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guibutton>Cancel</guibutton></term>
<listitem><para>Choose this if you really don't want to be setting up a new
account right now. The message box will go away, and you will be left with the
dialler screen as before.</para></listitem>
</varlistentry>

<varlistentry>
<term><guibutton>Wizard</guibutton></term>
<listitem><para>If you have a fairly standard modem, and use one of the larger
ISP's for your country, the wizard will probably be able to set you up
immediately with a working Internet Connection. Try this first, before you try
to set up the connection manually.</para></listitem>
</varlistentry>

<varlistentry>
<term><guibutton>Dialog Setup</guibutton></term>
<listitem><para>If you don't succeed with the Wizard, or you just want to do
things yourself, choose this.  The wizard currently is only useful for a small
subset of countries and Internet Providers.</para>
</listitem>
</varlistentry>
</variablelist>

<para>For the purposes of this chapter, we'll assume you are choosing
<guibutton>Wizard</guibutton>, and the dialog based setup will be described in a
later chapter.</para>

</sect1>

<sect1 id="finishing-the-wizard">
<title>The Rest of the Wizard</title>

<para>The first screen you see contains just introductory text, explaining the
things you read about in the first section of this chapter.  Press
<guibutton>Next</guibutton> to move on.</para>

<para>The second screen asks you to choose the country you live in.  Not all
countries are represented here, and if the country you live in is not listed,
you will have to press <guibutton>Cancel</guibutton>, in which case the <link
linkend="dialog-setup">Dialog based setup</link> will start for you to continue
with.</para>

<para>On the next screen, you will be given a choice of Internet Providers that
&kppp; knows about, based on your choice of location in the previous screen.
Again, if your <acronym>ISP</acronym> is not listed here, you will have to press
<guibutton>Cancel</guibutton> and do your setup in the <link
linkend="dialog-setup">Dialog based setup</link></para>

<para>You will now be asked to enter your username and password for your
internet connection.  Please note, that for some <acronym>ISP</acronym>s this
differs from your mail account user name and password, so make sure you use the
right one. Choose <guibutton>Next</guibutton> to continue.</para>

<para>On the next screen, you have a chance to enter any special dial prefixes
you might have - for example, if you must dial <quote>0</quote> for an outside
line, or if have a prefix you can dial to turn off call waiting.  Choose
<guibutton>Next</guibutton> to continue.</para>

<para>And that's all!  If you want to revisit any of your choices, you can use
the <guibutton>Back</guibutton> and <guibutton>Next</guibutton> buttons to move
back and forth through the dialogs.  When you're happy, press the
<guibutton>Finish</guibutton> button, and you're all done.</para>

<para>Of course, any of this information can be edited at a later time, from the
&kppp; Configuration dialog.</para>

</sect1>

</chapter>

<chapter id="dialog-setup">
<title>Setting up a connection with the dialogs</title>

<para>Setting up a connection with the dialog based setup is not too much more
difficult than using the wizard.</para>

<para>You can reach the setup dialog the same way you did the wizard.  Start
&kppp; from your <guimenu>K</guimenu> menu, where you will find its entry in the
<guisubmenu>Internet</guisubmenu> as <guimenuitem>Internet
Dialler</guimenuitem>.</para>

<para>The following dialog will appear:</para>

<screenshot>
<screeninfo>The &kppp; dialer startup screen</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-dialler-tab.png" format="PNG">
</imageobject>
<textobject><phrase>The &kppp; dialer startup screen</phrase>
</textobject>
<caption><para>The &kppp; dialer startup screen</para></caption>
</mediaobject>
</screenshot>

<para>It will probably not have any entries to begin with, and that's what we're
about to do now.</para>

<para>Click the <guibutton>Setup</guibutton> button to begin setting up a new
Internet connection.</para>

<para>This time, choose <guilabel>Dialog setup</guilabel> and you'll see the
following Dialog appear:</para>

<screenshot>
<screeninfo>The <guilabel>New Account</guilabel> Dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-account-dial-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The <guilabel>New Account</guilabel> Dialog</phrase>
</textobject>
<caption>
<para>The <guilabel>New Account</guilabel> Dialog</para>
</caption>
</mediaobject>
</screenshot>

<!-- Make a screenshot of the actual new Account Dialog with no entries -->

<para>The <guilabel>New Account</guilabel> dialog contains the following
sections:</para>

<itemizedlist>
<listitem>
<para><link linkend="account-dial"><guilabel>Dial</guilabel></link></para>
</listitem>
<listitem>
<para><link linkend="account-ip"><guilabel>IP</guilabel></link></para>
</listitem>
<listitem>
<para><link linkend="account-gateway"><guilabel>Gateway</guilabel></link></para>
</listitem>
<listitem>
<para><link linkend="account-dns"><guilabel>DNS</guilabel></link></para>
</listitem>
<listitem>
<para><link linkend="account-login-script"><guilabel>Login
Script</guilabel></link></para>
</listitem>
<listitem>
<para><link linkend="account-execute"><guilabel>Execute</guilabel></link></para>
</listitem>
<listitem>
<para><link
linkend="account-accounting"><guilabel>Accounting</guilabel></link></para>
</listitem>
</itemizedlist>

<para>You normally won't need to fill in all these, although each of them is
described in the following sections.</para>

<sect1 id="account-dial">
<title>The <guilabel>Dial</guilabel> tab</title>

<screenshot>
<screeninfo>The Accounts <guilabel>Dial</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-account-dial-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The Accounts <guilabel>Dial</guilabel> tab</phrase>
</textobject>
<caption><para>The Accounts <guilabel>Dial</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<para>The <guilabel>Dial</guilabel> tab has the following options:</para>

<variablelist>
<varlistentry>
<term><guilabel>Connection Name:</guilabel></term>
<listitem>
<para>You must give the account a name.  This can be anything you like, but if
you have more than one account, each name must be unique.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Phone Number:</guilabel></term>
<listitem>
<para>Specify the phone number to dial.  You can use characters such as
<quote>-</quote> to make the number more legible.  If you concatenate a series
of numbers separated by a colon (&eg;
<userinput>1111111:2222222:3333333</userinput>, &kppp; will try these numbers one
after the other whenever it receives a busy signal.  You can use the
<guibutton>Add</guibutton> button to add another number,
<guibutton>Remove</guibutton> to remove a number from the list, and the
<guiicon>up</guiicon> and <guiicon>down</guiicon> arrows to change the order of
the list.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Authentication</guilabel></term>
<listitem>
<para>Choose the appropriate method of authentication that &kppp; should use to
log into the server.  Check with your provider for more information.  Use of
<acronym>PAP</acronym> and <acronym>CHAP</acronym> are described in the chapter
<xref linkend="chap-and-pap">.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Store password</guilabel></term>
<listitem>
<para>Check this option if you want &kppp; to remember your password between
sessions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Customize pppd arguments...</guibutton></term>
<listitem>
<para>This will bring up the <application>pppd</application> arguments dialog.
You can use this dialog to add any desired options that you want &kppp; to hand
to <application>pppd</application>.  See the <application>pppd</application> man
page for a list of available options, but unless you know exactly what you are
doing, you should probably restrain yourself from tinkering with these.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="account-ip">
<title>The <guilabel>IP</guilabel> tab</title>

<screenshot>
<screeninfo>The Accounts <guilabel>IP</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-account-ip-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The Accounts <guilabel>IP</guilabel> tab</phrase>
</textobject>
<caption><para>The Accounts <guilabel>IP</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guilabel>Dynamic IP Address</guilabel></term>
<listitem>
<para>Check this if your <acronym>ISP</acronym> uses dynamic
<acronym>IP</acronym> address assignment.  In this case, your
<acronym>IP</acronym> address will change every time you establish a
connection.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Static IP Address</guilabel></term>
<listitem>
<para>Check this if your <acronym>ISP</acronym> has given you a static
<acronym>IP</acronym> address. In that case you will also need to fill in that
address in the <guilabel>IP Address</guilabel> box, and any <guilabel>Subnet
Mask</guilabel> if applicable. Ask your <acronym>ISP</acronym> if
unsure.  Dynamically assigned addresses are used in the huge majority if
<acronym>ISP</acronym>'s and leaving this checked will in most cases be the
right choice.</para>
</listitem>
</varlistentry>
<varlistentry id="auto-configure-hostname">
<term><guilabel>Auto-configure hostname from this IP</guilabel></term>
<listitem>
<para>Select this option if you want &kppp; to set the hostname and domain for
your machine after a successful <acronym>ppp</acronym> connection.</para>
<para>This is done by querying the defined Domain Name Server with the
<acronym>IP</acronym> assigned for the <acronym>ppp</acronym> link.</para>
<para>This option is useful for those stand-alone machines which want to use
protocols such as talk, which require the hostname to be the same as your
machine is known on the internet.  It overrides the <guilabel>Domain
Name</guilabel> option in the <guilabel>DNS</guilabel> section, and the machine
defaults are restored to their original values when you close the
<acronym>ppp</acronym> connection.</para>
<para>This option is <emphasis>not</emphasis> useful if you just want to connect
to the internet and surf, check mail, or chat.  It has the side-effect of
disallowing any new connections to your X server - in other words, you can't
open any more <acronym>GUI</acronym> programs.</para>
<para>Only turn this on if you are absolutely sure you need it.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="account-gateway">
<title>The <guilabel>Gateway</guilabel> tab</title>

<screenshot>
<screeninfo>The Accounts <guilabel>Gateway</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-account-gateway-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The Accounts <guilabel>Gateway</guilabel> tab</phrase>
</textobject>
<caption><para>The Accounts <guilabel>Gateway</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guilabel>Default Gateway</guilabel></term>
<listitem>
<para>Check this if you want <application>pppd</application> to use the default
Gateway for your machine.  This is the default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Static Gateway</guilabel></term>
<listitem>
<para>Check this if you want to specify the Gateway to be used in place of the
default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Assign the Default Route to this Gateway</guilabel></term>
<listitem>
<para>You almost certainly will need this to be checked (the default).</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="account-dns">
<title>The <guilabel>DNS</guilabel> tab</title>

<screenshot>
<screeninfo>The Accounts <guilabel>DNS</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-account-dns-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The Accounts <guilabel>DNS</guilabel> tab</phrase>
</textobject>
<caption><para>The Accounts <guilabel>DNS</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guilabel>Domain Name:</guilabel></term>
<listitem>
<para>Specify the domain name for your machine.  As with <acronym>DNS</acronym>
addresses, it is restored to the original specified in
<filename>/etc/resolv.conf</filename> when the connection goes down.  If it is
left blank, no changes are made to the domain name specified in
<filename>/etc/resolv.conf</filename></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Configuration:</guilabel></term>
<listitem>
<para>Choose between <guilabel>Automatic</guilabel> (the <acronym>ISP</acronym>
will automatically issue you <acronym>DNS</acronym> server addresses when you
connect) and <guilabel>Manual</guilabel>.  If you choose manual, the
<guilabel>DNS IP Address</guilabel> section is then enabled.</para> 
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>DNS IP Address</guilabel></term>
<listitem>
<para>This section is only enabled if you chose <guilabel>Manual</guilabel> in
the previous option.  Add the Domain Name Servers assigned to you by your
<acronym>ISP</acronym>.  You must specify at least one Domain Name Server for
your <acronym>OS</acronym> to be able to resolve human readable
<acronym>IP</acronym> addresses such as
<systemitem>ftp.kde.org</systemitem>. The <acronym>DNS</acronym> server
addresses supplied must be in numeric form, &eg;
<systemitem>128.231.231.233</systemitem>.  These addresses will be added at
runtime to <filename>/etc/resolv.conf</filename>.</para> 
<para>Choose the <guibutton>Add</guibutton> button to add each new
<acronym>DNS</acronym> server address to the list box below.  Choose
<guibutton>Remove</guibutton> to remove an entry from the list.</para> 
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Disable existing DNS Servers during Connection</guilabel></term>
<listitem>
<para>If you check this box, any <acronym>DNS</acronym> servers listed in
<filename>/etc/resolv.conf</filename> will be disabled while the connection
remains up.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="account-login-script">
<title>The <guilabel>Login Script</guilabel> tab</title>

<screenshot>
<screeninfo>The Accounts <guilabel>Login Script</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-account-login-script-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The Accounts <guilabel>Login Script</guilabel> tab</phrase>
</textobject>
<caption><para>The Accounts <guilabel>Login Script</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<para>Use this dialog to compose a dial in script for your
<acronym>ISP</acronym> dialup connection. You can use the mini-terminal and the
information supplied by your <acronym>ISP</acronym> to find out what sequence of
actions needs to be executed.</para>

<para>Choose an option from the drop down box on the left, and then add any
parameters for that action in the edit box on the right.  Use
<guibutton>Add</guibutton> to add each entry to the <emphasis>bottom</emphasis>
of the script, which is displayed in the lower part of the dialog.  Use
<guibutton>Insert</guibutton> to insert an entry anywhere in the script, and use
<guibutton>Remove</guibutton> to delete a line from the script.</para>

<para>The options available are:</para>

<variablelist>
<varlistentry>
<term><guilabel>Expect</guilabel></term>
<listitem>
<para>&kppp; will wait for the specified string to be received.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Send</guilabel></term>
<listitem>
<para>&kppp; will send the specified string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Scan</guilabel></term>
<listitem>
<para>&kppp; will scan the input stream for the specified string, and will
store any character from the end of the string up to the next newline, in an
internal buffer.  Trailing and leading whitespace will be stripped off.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Save</guilabel></term>
<listitem>
<para>Permanently store the previously scanned string in the specified register.
Currently the only valid register is <varname>password</varname>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Pause</guilabel></term>
<listitem>
<para>Pause for the specified number of seconds.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Hangup</guilabel></term>
<listitem>
<para>&kppp; will send the <command>hangup</command> to the modem.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Answer</guilabel></term>
<listitem>
<para>&kppp; will set the modem into answer mode.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Timeout</guilabel></term>
<listitem>
<para>Change the default timeout to the specified number of seconds dynamically
during the script.  You can change the timeout several times during script
execution if necessary.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Prompt</guilabel></term>
<listitem>
<para>Prompt the &kppp; user to enter a string, given the specified string as a
hint.  The user will see what is typed.  If the specified string includes the
mark <userinput>##</userinput>, the mark will be replaced with the current
content of the internal scan buffer, as previously stored with the
<guilabel>scan</guilabel> command.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>PWPrompt</guilabel></term>
<listitem>
<para>Prompt the &kppp; user to enter a string, given the specified string as a
hint.  An asterisk will be printed for each character the user types.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>ID</guilabel></term>
<listitem>
<para>If the <guilabel>Login ID</guilabel> field on &kppp;'s main dialog is filled in,
send that <acronym>ID</acronym>.  If the <guilabel>Login ID</guilabel> field is not
filled in, prompt the &kppp; user to enter an <acronym>ID</acronym>, given the
specified string as a hint.  The user will see what is typed.  On a second pass,
such as in a loop on a second iteration, or during callback authentication, the
prompt will be displayed regardless of whether the <guilabel>Login ID</guilabel> field
is filled in.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Password</guilabel></term>
<listitem>
<para>If the <guilabel>Password</guilabel> field on &kppp;'s main dialog is
filled in, send that password.  If the <guilabel>Password</guilabel> field is
not filled in, prompt the &kppp; user to enter a password, with 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 a second iteration, or during callback
authentication, the prompt will be displayed regardless of whether the
<guilabel>Password</guilabel> field is filled in.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>LoopStart</guilabel></term>
<listitem>
<para>&kppp; will wait for the specified string to be received.  It will save
the string for use by <varname>LoopEnd</varname>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>LoopEnd</guilabel></term>
<listitem>
<para>&kppp; will wait for the specified string to be received to exit the loop.
If the string given by the corresponding <varname>LoopStart</varname> is
received first, it will trigger a jump to the line after
<varname>LoopStart</varname>, enabling repetition of username/password style
paired dialogs.</para>
</listitem>
</varlistentry>
</variablelist>

<sect2>
<title>Example Scripts</title>

<example>
<title>A simple example login script</title>
<para>Here is a simple example script I could use to connect to my
<acronym>ISP</acronym></para>

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

</example>

<example>
<title>A login script that prompts for ID and password, and has loops.</title>

<para>Here is a script for the same account with an <acronym>ID</acronym> and
password prompt.  This script will prompt for <acronym>ID</acronym> and password
each time, no matter what is typed into the <guilabel>Login ID</guilabel> and
<guilabel>password</guilabel> fields on &kppp;'s main screen.</para>

<para>This script also illustrates the use of the LoopStart/LoopEnd structure.
If something goes wrong during the login procedure, for example, I mistype the
password, my <acronym>ISP</acronym> will print an error message and restart the
id/password loop by issuing the string <computeroutput>ID:</computeroutput>
again.  If the string <computeroutput>ID:</computeroutput> is caught before the
LoopEnd keyword was parsed, &kppp; will start the script again, from the line
after the LoopStart keyword.</para>

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

<example>
<title>Prompts for information not filled in on the main dialog.</title>

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

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

</example>

<example>
<title>A script for an <acronym>ISP</acronym> using challenge/response
authentication.</title>

<para>Here is a script that I use to connect to an <acronym>ISP</acronym> 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
<acronym>ISP</acronym>. You have to know a password to use the token. After
dialling in your <acronym>ISP</acronym> 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>

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

<example>
<title>Using Scan and Save in scripts</title>

<para>The following log shows the login procedure of a fictitious
<acronym>ISP</acronym> that provides a new password on each login. The new
password has to be verified and recorded for the next session. </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>&kppp; can be used to this 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 the combination of Scan/Save
keywords.</para>

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

</sect2>

</sect1>

<sect1 id="account-execute">
<title>The <guilabel>Execute</guilabel> tab</title>

<screenshot>
<screeninfo>The Accounts <guilabel>Execute</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-account-execute-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The Accounts <guilabel>Execute</guilabel> tab</phrase>
</textobject>
<caption><para>The Accounts <guilabel>Execute</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<para>Here you can select commands to run at certain stages of the connection.
These commands are run with your real user id, so you cannot run any commands
here requiring root permissions, unless you are of course dialled in as root (a
bad thing to do for many reasons!)</para>

<para>Make sure to supply the whole path to the program, otherwise &kppp; may
not be able to find it.</para>

<para>You can add commands to be run at four distinct times during the
connection process:</para>

<variablelist>
<varlistentry>
<term><guilabel>Before Connect</guilabel></term>
<listitem>
<para>Run this command before the dialling is initiated, so it is already
running when you connect to your <acronym>ISP</acronym>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Upon Connect</guilabel></term>
<listitem>
<para>Run this command only after a successful connection is
made.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Before disconnect</guilabel></term>
<listitem>
<para>Run this command while still connected, before hanging up the
modem.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Upon disconnect</guilabel></term>
<listitem>
<para>Run this command after the connection has been closed.</para>
</listitem>
</varlistentry>
</variablelist>

<para>You might for example want to run <application>leafnode</application> as
soon as you have connected, or check your mail.  You might want to make sure any
mail in your queue is sent, before you close your connection down.  You might
want a <quote>clean-up</quote> script to tidy up logs and clear your cache after
you have disconnected.</para>

</sect1>

<sect1 id="account-accounting">
<title>The <guilabel>Accounting</guilabel> tab</title>

<screenshot>
<screeninfo>The Accounts <guilabel>Accounting</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-account-accounting-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The Accounts <guilabel>Accounting</guilabel> tab</phrase>
</textobject>
<caption><para>The Accounts <guilabel>Accounting</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<para>Check the <guilabel>Enable Accounting</guilabel> box to enable or disable
telephone cost accounting for this account.</para>

<para>Select from the list the applicable rule for your telecoms
provider.</para>

<para>If you can't find one, you can write one yourself by copying the supplied
template, which you will find in an <link
linkend="appendix-accounting-template">appendix</link>.</para>

<para>The final option on this page is <guilabel>Volume Accounting</guilabel>,
described below.</para>

<sect2>
<title>Volume Accounting</title>

<sect3>
<title>What is volume accounting?</title>

<para>Basically, it means to count the number of bytes transmitted to and from
the Internet.  &kppp; can count incoming bytes, outgoing bytes, or both.  It's
up to you what you want (or must) use.</para>

</sect3>

<sect3>
<title>Why should I use volume acounting?</title>

<para>Many Internet Service Providers bill their customers based on the number
of bytes transferred.  Even more commonly, <acronym>ISP</acronym>'s offer a flat
rate up to some arbitrary transfer limit, and then charge more for every
megabyte above this limit.  &kppp; shows you your current volume and can help
you keep your bills to the minimum.  Of course, even if you're not billed based
on volume, you can turn on volume accounting just to satisfy your own
curiosity.</para>

</sect3>

<sect3>
<title>What type of volume accounting should I select?</title>

<para>That depends mainly on your provider.  Many of them only count how many
megabytes you download from the Internet,and ignore how much you send.  In that
case you should choose <guilabel>Bytes In</guilabel>.  If you have to pay for
both, you should choose <guilabel>Bytes In and Out</guilabel>.  <guilabel>Bytes
Out</guilabel> is really only here for completeness, as we're not aware of any
providers using it as a billing basis.  It might be useful to those of you
running a web or &FTP; server at home though.</para>

</sect3>

<sect3>
<title>Drawbacks</title>

<para>Unfortunately, there is a drawback on volume accounting.  &kppp; will only
count the number of bytes, regardless of their origin.  Many providers set their
limit only for Internet access, and not for data on their own network.  Some
providers set different limits for data that is on their own network, in the
same country, and coming from overseas.  So, if you're doing not much
websurfing, and getting most of your pages from your <acronym>ISP</acronym>'s
own proxy cache, then your provider is probably not charging you for that data.
&kppp; will not know these <acronym>IP</acronym> packets are coming from the
proxy, and so it will count them.  So if you this situation applies to you, or,
as another example, your provider uses a caching news server such as
<application>nntpcached</application>, then the volume reported by &kppp; may be
higher than the amount you are going to be billed for.  On the bright side, at
least &kppp; will never underestimate your bills.</para>

</sect3>

</sect2>

</sect1>

</chapter>

<chapter id="global-settings">
<title>Global &kppp; settings</title>

<para>The changes made here affect all accounts you have set up in &kppp;</para>

<sect1 id="global-accounts">
<title>The <guilabel>Accounts</guilabel> tab</title>

<screenshot>
<screeninfo>The <guilabel>Accounts</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-config.png" format="PNG">
</imageobject>
<textobject>
<phrase>The <guilabel>Accounts</guilabel> tab</phrase>
</textobject>
<caption><para>The <guilabel>Accounts</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<para>In this dialog, you can manage the accounts themselves.  The names of the
accounts appear in a list on the left of the dialog.</para>

<para>To delete an account, select the <guibutton>Delete</guibutton> button.
You will be asked to confirm before the account is finally deleted.</para>

<para>You can make a copy of an account with the <guibutton>Copy</guibutton>
button.  You could use this for example, to separate different users in the
family, although that would normally be better done by having them be different
users in the OS as well!  Or perhaps you just have more than one account with
the same <acronym>ISP</acronym> and wish to use both of them.</para>

<para>Choosing <guibutton>Edit...</guibutton> will take you to the dialog
described in <link linkend="dialog-setup">Dialog Setup</link>, but with the
selected accounts details.</para>

<para>Choosing <guibutton>New...</guibutton> will offer you the choice between
the <link linkend="wizard">Wizard</link> or the <link
linkend="dialog-setup">Dialog Setup</link> already described.</para>

<para>If you select an account, and you have turned on <link
linkend="account-accounting">accounting</link> then the accumulated information
for that account will appear in the two panels labelled <guilabel>Phone
Costs:</guilabel> and <guilabel>Volume:</guilabel> respectively.</para>

<para>To the left of the accounting display, are two buttons:
<guibutton>Reset...</guibutton> and <guibutton>View Logs</guibutton>.</para>

<para>Pressing <guibutton>Reset...</guibutton> will reset the <guilabel>Phone
Costs:</guilabel> and <guilabel>Volume:</guilabel> information to 0.  You would
typically want to do this once a month or quarter, when you have recieved your
phone bill and reconciled the telephone costs. You can reset either
independently, and are offered the choice of which item you want to reset, when
you press the <guibutton>Reset</guibutton> button.</para>

<para>Pressing <guibutton>View Logs</guibutton> will open another window, where
a log of all the calls made with &kppp; will be displayed.  If you have kept
logs, you can move forward and backward, in monthly steps.  This might be useful
if you have received an abnormally large phone bill and are investigating
why!</para>

</sect1>

<sect1 id="global-device">
<title>The <guilabel>Device</guilabel> tab</title>

<screenshot>
<screeninfo>The <guilabel>Device</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-device-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The <guilabel>Device</guilabel> tab</phrase>
</textobject>
<caption><para>The <guilabel>Device</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<para>Here you can select and configure your modem.</para>

<variablelist>
<varlistentry>
<term><guilabel>Modem Device</guilabel></term>
<listitem>
<para>Choose the device appropriate for your hardware.</para>
<variablelist>
<varlistentry>
<term><filename class="devicefile">/dev/ttys0</filename></term>
<listitem>
<para>DOS or &Windows; users will know this as COM1, while COM2 is
<filename class="devicefile">/dev/ttys1</filename> and so on.  These devices are
the ones normally used on &Linux; systems.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename class="devicefile">/dev/cua0</filename></term>
<listitem>
<para>The first serial line (COM1).  COM2 is usually
<filename>/dev/cua1</filename> and so on.  These devices are commonly used on
BSD systems, namely FreeBSD, NetBSD and OpenBSD.  Older &Linux; systems may also
have these, although on &Linux; they were renamed some time ago to <filename
class="devicefile">/dev/ttyS<replaceable>x</replaceable></filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename class="devicefile">/dev/ttyI0</filename></term>
<listitem>
<para>On &Linux; these belong to internal <acronym>ISDN</acronym> cards.  These
devices emulate a common Hayes compatible modem.
<filename class="devicefile">/dev/ttyI0</filename> is for the first,
<filename class="devicefile">/dev/ttyI1</filename> is for the second
<acronym>ISDN</acronym> card and so on. These devices are only available in the
&Linux; version.</para> 
</listitem>
</varlistentry>
<varlistentry>
<term><filename class="symlink">/dev/modem</filename></term>
<listitem>
<para>Many &Linux; distributions make a symbolic link from the real modem device
to <filename class="symlink">/dev/modem</filename>.  <emphasis>You should avoid
using this one.</emphasis>.  Use the real device that it is pointing to
instead.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Flow Control</guilabel></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><guilabel>Line Termination</guilabel></term>
<listitem>
<para>Choose the correct <quote>Enter</quote> character sequence for your
modem.  Most modems will use <quote>CR/LF</quote>, however some modems need a
different setting.  If you experience trouble while running a login script, play
with this parameter.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Connection Speed</guilabel></term>
<listitem><para>Choose from the list of connection speeds supported by your
serial port.  Note that the serial port supports much higher speeds than your
modem in most cases. You should probably start with the highest number
available, and only reduce it if you have connection problems.
</para></listitem> 
</varlistentry>
<varlistentry>
<term id="lock-files"><guilabel>Use Lock File</guilabel></term>
<listitem>
<para>Activate this option if you want &kppp; to create a lockfile. Under
&Linux; the directory for such a file will be <filename
class="directory">/var/lock</filename>.  Programs such as
<application>mgetty</application> depend on the existence of such lock files,
and &kppp; will not work with <application>mgetty</application> if the lock file
is not set.  Make sure that you don't use the option <option>lock</option> for
<application>pppd</application> if you want &kppp; to lock the modem, since the
<application>pppd</application> option <option>lock</option> will induce
<application>pppd</application> to try to lock the modem device.  Since &kppp;
will have already locked the device, <application>pppd</application> will fail,
and &kppp; will display the error <errorname>pppd died
unexpectedly</errorname>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Modem Timeout</guilabel></term>
<listitem>
<para>This is the time in seconds that &kppp; will wait for the
<returnvalue>CONNECT</returnvalue> response from your modem.  A setting of about
30 seconds should be sufficient for most purposes.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="global-modem">
<title>The <guilabel>Modem</guilabel> tab</title>

<screenshot>
<screeninfo>The <guilabel>Modem</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-modem-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The <guilabel>Modem</guilabel> tab</phrase>
</textobject>
<caption><para>The <guilabel>Modem</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guilabel>Busy Wait</guilabel></term>
<listitem>
<para>This is the length of time the modem should wait before redialling, after
it has received a busy signal.  Note there are requirements by telecom providers
in some countries, which ask you to not set this too low.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Modem volume</guilabel></term>
<listitem>
<para>Use the slider to set the modem volume.  Left is low volume, center is
medium volume, and right is high volume.  On some modems, low volume is the same
as turning the volume off, and on other modems, medium and high are effectively
the same thing.</para>
</listitem>
</varlistentry>
<varlistentry id="modem-commands">
<term><guibutton>Modem Commands</guibutton></term>
<listitem>
<para>In this dialog you can fill in any particular commands appropriate for
your modem.  If you own a Hayes compatible modem, you most likely won't need to
change any of the defaults, but you are encouraged to read the <link
linkend="appendix-hayes-commands">Hayes Commands</link> Appendix in this help file.  The
information supplied there can be very helpful in cases where you experience
trouble setting up a stable connection with your <acronym>ISP</acronym>'s
modems.  In particular the two settings for <guilabel>Pre-Init Delay</guilabel>
and for <guilabel>Post-Init Delay</guilabel> if you are experienceing modem
lockups.  These settings make &kppp; pause a little just before and just after
sending the initialization string to your modem.  The <guilabel>Pre-Init
Delay</guilabel> will by default also send a CR, unless you have set it the
delay interval to 0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Query Modem</guibutton></term>
<listitem>
<para>Pushing this button will make &kppp; 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><guibutton>Terminal</guibutton></term>
<listitem>
<para>Pushing the <guibutton>Terminal</guibutton> button will bring up a mini
terminal. You can use the mini terminal to test your modem and to experiment
with the negotiation protocol for initialising a ppp connection with your
<acronym>ISP</acronym>.  You no longer need a terminal program such as
<application>minicom</application> or <application>Seyon</application>.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="global-graph">
<title>The <guilabel>Graph</guilabel> tab</title>

<screenshot>
<screeninfo>The <guilabel>Graph</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-graph-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The <guilabel>Graph</guilabel> tab</phrase>
</textobject>
<caption><para>The <guilabel>graph</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<para>Here you can set the colours used by the &kppp; graph.  You can set
different colors for <guilabel>Background color</guilabel>, <guilabel>Text
color</guilabel>, <guilabel>Input bytes color</guilabel> and <guilabel>Output
bytes color</guilabel>.</para>

</sect1>

<sect1 id="global-misc">
<title>The <guilabel>Misc</guilabel> tab</title>

<screenshot>
<screeninfo>The <guilabel>Misc.</guilabel> tab</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kppp-misc-tab.png" format="PNG">
</imageobject>
<textobject>
<phrase>The <guilabel>Misc.</guilabel> tab</phrase>
</textobject>
<caption><para>The <guilabel>Misc.</guilabel> tab</para>
</caption>
</mediaobject>
</screenshot>

<para>Here are some options that don't really fit in with other sections, but
can be very useful nonetheless.</para>

<variablelist>
<varlistentry>
<term><guilabel>pppd Version</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>pppd Timeout</guilabel></term>
<listitem>
<para>&kppp; will wait this amount of time after running the script and starting
<application>pppd</application> for <application>pppd</application> to establish
a valid <acronym>ppp</acronym> link before giving up and killing
<application>pppd</application></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Dock into Panel on Connect</guilabel></term>
<listitem>

<para>If this option is chosen, &kppp; will dock into the panel where it will be
symbolized by a small animated icon.  Use the <mousebutton>left</mousebutton>
mouse button on this icon to restore &kppp;'s window.  The
<mousebutton>right</mousebutton> mouse button will open a popup menu that offers
to restore the window, show transfer statistics, or close the connection.  This
option overrides <guilabel>Minimize Window on Connect</guilabel>.</para>

</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Automatic Redial on Disconnect</guilabel></term>
<listitem>
<para>Selectintg this will have &kppp; try to reconnect if you are
disconnected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Show Clock on Caption</guilabel></term>
<listitem>
<para>This will have &kppp; display the time connected on the caption of the
&kppp; window, while you are online.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Disconnect on X-server shutdown</guilabel></term>
<listitem>
<para>Checking this will cause &kppp; to terminate the <acronym>ppp</acronym>
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 forgetting you are
online, when you shut down the X-server, or if you simply don't want to worry
about manually disconnecting your session.  If you don't want &kppp; to hang up
the modem on X-server exit, you should leave this checkbox empty.  Beware that
if you have accounting enabled, and you leave this option turned off, you will
have an unterminated accounting entry in your logs, from each time the X-server
exits and &kppp; terminates.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Quit on Disconnect</guilabel></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Minimize Window on Connect</guilabel></term>
<listitem>
<para>If this option is chosen, &kppp; will be minimized after a connection is
established.  The elapsed connection time will be shown in the taskbar.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="global-about">
<title>The <guilabel>About</guilabel> tab</title>

<para>The <guilabel>About</guilabel> tab shows version, license, and author
information about &kppp;.</para>

</sect1>

</chapter>

<chapter id="security">
<title>&kppp; and security issues</title>

<para>This section is mainly for superusers (<systemitem
class="username">root</systemitem>) 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, although you may learn a thing or two in any
case.</para>

<sect1 id="security-restricting-access">
<title>Restricting access to &kppp;</title>

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

<sect2 id="security-group-permissions">
<title>Restricting access with group permissions</title>

<para>Create a new group (you might want to name it <systemitem
class="groupname">dialout</systemitem> or similar), and put every user that
should be allowed to use &kppp; into that group.  Then type at the
prompt:</para>

<screen><prompt>#</prompt> <userinput><command>chown</command> <option>root.dialout</option> <filename>/opt/kde/bin/kppp</filename></userinput>
<prompt>#</prompt> <userinput><command>chmod</command> <option>4750</option> <filename>/opt/kde/bin/kppp</filename></userinput>
</screen>

<para>This assumes that &kde; was installed in <filename class="directory">
/opt/kde/</filename> and that your new group is named <systemitem
class="groupname">dialout</systemitem>.</para>

</sect2>

<sect2 id="security-kppps-way">
<title>Restricting access &kppp;'s way</title>

<para>Before doing anything, &kppp; checks if there is a file named
<filename>/etc/kppp.allow</filename>. If such a file exists, only users named in
this file are allowed to dial out.  This file must be readable by everyone (but
of course <emphasis>NOT</emphasis> writable.)  Only login names are recognized,
so you cannot use <acronym>UID</acronym>'s in this file.  Here is a short
example:</para>

<screen>
# /etc/kppp.allow
# comment lines like this are ignored
# as well as empty lines

fred
karl
daisy
</screen>

<para>In the example above, only the users <systemitem
class="username">fred</systemitem>, <systemitem
class="username">karl</systemitem> and <systemitem
class="username">daisy</systemitem> are allowed to dial out, as well as every
user with a <acronym>UID</acronym> of 0 (so you don't have to explicitly list
root in the file).</para>

</sect2>

</sect1>

<sect1 id="security-why-suid">
<title>&kppp; has the <acronym>SUID</acronym> bit on? What about
security?</title>

<para>It's virtually impossible to write a dialler without the
<acronym>SUID</acronym> bit that is both safe and easy to use for inexperienced
users.  &kppp; addresses the security issues with the following strategy.</para>

<itemizedlist>
<listitem>
<para>Immediately after the program starts, &kppp; forks.</para>
</listitem>
<listitem>
<para>The master process, which handles all the <acronym>GUI</acronym> stuff
such as user interaction) drops the <acronym>SUID</acronym> state after the
fork, and runs with normal user privileges.</para>
</listitem>
<listitem>
<para>The slave process keeps its  privileges, and is responsible for all
actions that need <systemitem class="username">root</systemitem> privileges.  To
keep this part safe, no &kde; or &Qt; library calls are used here, just simple
library calls.  The source code for this process is short (around 500 lines) and
well documented, so it's easy for you to check it for security holes.</para>
</listitem>
<listitem>
<para>Master and slave processes communicate with standard &UNIX;
<acronym>IPC</acronym>.</para>
</listitem>
</itemizedlist>

<para>Special thanks to Harri Porten for writing this excellent piece of code.
It was thought to be impossible, but he managed it within a week.</para>

</sect1>

</chapter>

<chapter id="chap-and-pap">
<title><acronym>PAP</acronym> and <acronym>CHAP</acronym></title>

<para>Starting with version 0.9.1, &kppp; has supported directly the most
commonly used form of <acronym>PAP</acronym> authentication. </para>

<sect1 id="pap-with-kppp">
<title><acronym>PAP</acronym> with &kppp;</title>

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

<sect2 id="client-side-authentication">
<title>Client side authentication</title>

<para>This variant is used by many commercial <acronym>ISP</acronym>'s.  It
basically means that you (or rather, your computer) must authenticate yourself
to the <acronym>ISP</acronym>'s <acronym>PPP</acronym> server.  The
<acronym>PPP</acronym> server does not need to authenticate itself to your
computer.  This is no security issue, as you should know which computer you just
tried to dial to.</para>

<para>If your <acronym>ISP</acronym> gives you a username and password, and
tells you to use <acronym>PAP</acronym> authentication, this is the variant you
should choose.</para>

</sect2>

<sect2 id="two-way-authentication">
<title>Two way authentication</title>

<para>As above, but in this case your computer requires the
<acronym>ISP</acronym> <acronym>PPP</acronym> server to authenticate itself.  In
order to establish a connection, you must chose the authentication method
<guilabel>Script based</guilabel>, not <guilabel>PAP</guilabel>, and you will
have to manually edit <filename>/etc/ppp/pap-secrets</filename>.  While &kppp;
doesn't provide built in support for this variant, it is nevertheless easy to
establish a connection.</para>

</sect2>

<sect2 id="preparing-kppp-for-pap">
<title>Preparing &kppp; for <acronym>PAP</acronym></title>

<procedure>
<step>
<para>Make sure that the file <filename>/etc/ppp/options</filename> (and
<filename>&tilde;/.ppprc</filename> if it exists) do <emphasis>not</emphasis>
contain one of the following arguments:</para>

<itemizedlist>
<listitem>
<para><option>+pap</option></para>
</listitem>
<listitem>
<para><option>-pap</option></para>
</listitem>
<listitem>
<para><option>papcrypt</option></para>
</listitem>
<listitem>
<para><option>+chap</option></para>
</listitem>
<listitem>
<para><option>+chap</option></para>
</listitem>
<listitem>
<para><option>+ua</option></para>
</listitem>
<listitem>
<para><option>remotename</option></para>
</listitem>
</itemizedlist>

<para>It is very unlikely that any of these options are already there, but just
to be sure, please check.</para>
</step>
<step>
<para>Start &kppp;</para>
</step>
<step>
<para>Click <guibutton>Setup</guibutton></para>
</step>
<step>
<para>Choose the account you want to use <acronym>PAP</acronym> with and click
<guibutton>Edit</guibutton></para>
</step>
<step>
<para>Choose the <guilabel>Dial</guilabel> tab</para>
</step>
<step>
<para>Select <acronym>PAP</acronym> in the <guilabel>Authentication</guilabel>
drop down box.</para>
</step>
<step>
<para>If you do not want to retype the password each time you dial in, select
<guilabel>Store password</guilabel>.  This will save the password to a file, so
make sure that nobody else has access to your account.</para>
</step>
<step>
<para>That's it.  Close the dialogs, type in the username and password your
<acronym>ISP</acronym> supplied, and click
<guibutton>Connect</guibutton>.</para>
</step>
</procedure>


</sect2>

</sect1>

<sect1 id="pap-and-chap-alternate-method">
<title>An alternative method of using <acronym>PAP</acronym> and
<acronym>CHAP</acronym> with &kppp;</title>

<para>This section is based on an email from Keith Brown
<email>kbrown@pdq.net</email> and explains how to make &kppp; work with a
generic <acronym>PAP</acronym> or <acronym>CHAP</acronym> account.  If your
<acronym>ISP</acronym> just gave you a user id and a password for an account,
you probably can skip this section, and the instructions in the previous one
will be all you need.</para>

<para><acronym>PAP</acronym> 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 <acronym>PAP</acronym>.  The
client (<application>pppd</application>) looks in a specific file for an entry
that contains a matching server name, and a client name for this connection, and
then sends the password it finds there.  That's about it!</para>

<para>Now here's how to make that happen.  I am assuming a
<acronym>pppd</acronym> version of 2.2.x or better and a standard installation
of configuration files under <filename
class="directory">/etc/ppp</filename>.</para>

<para>For the purposes of illustration, imagine that you have an internet
account with <systemitem>glob.net</systemitem> with the username <systemitem
class="username">userbaz</systemitem> and the password
<literal>foobar</literal></para>

<para>First, you need to add all this to a  file called
<filename>/etc/ppp/pap-secrets</filename>.  The format of an entry for our
purposes is:</para>

<screen><userinput>USERNAME    SERVERNAME     PASSWORD</userinput></screen>

<para>So you would add the following line to
<filename>/etc/ppp/pap-secrets</filename> and then save it :</para>

<screen><userinput>userbaz     glob           foobar</userinput></screen>

<note>
<para>You can use any name for the server you wish, so long as you use the
same name in the <application>pppd</application> arguments, as you'll see
shortly.  Here it's been shortened to <userinput>glob</userinput>, but this name
is only used to locate the correct password.</para>
</note>

<para>Next you need to set up the connection in &kppp;.  The basics are the same
as any other connection, so we won't go into details here, except to say that
you probably want to make sure that <filename>/etc/ppp/options</filename> is
empty, and you don't want to create a login script either.</para>

<para>In the &kppp; settings dialog, at the bottom of the
<guilabel>Dial</guilabel> tab, is a <guibutton>pppd arguments</guibutton>
button.  This brings up an editing dialog.  Here you can enter values that will
be sent to <application>pppd</application> as command line arguments, and in the
case of multiple value arguments, you need to enter each value as a separate
entry in the listbox, in the correct order.</para>

<para>You can put in any other arguments you want first.  Then add the arguments
that <application>pppd</application> uses to handle <acronym>PAP</acronym>
authentication.  In this example, we are going to add
<userinput>user</userinput>, <userinput>userbaz</userinput>,
<userinput>remotename</userinput> and <userinput>glob</userinput> in that
order.</para>

<para>The <option>user</option> tells the <application>pppd</application> what
user name to look for in the <filename>pap-secrets</filename> file and then to
send to the server.  The remotename is used by <application>pppd</application>
to match the entry in the <filename>pap-secrets</filename> file, so again, it
can be anything you want so long as it is consistent with the entry in the
<filename>pap-secrets</filename> file.</para>

<para>That's all there is to it, and you should now be able to set up your own
connection to a server with <acronym>PAP</acronym> authentication.
<acronym>CHAP</acronym> is not much different.  You can see the &Linux; Network
Administrators Guide for a <filename>chap-secrets</filename> file format, and
the <application>pppd</application> arguments used, and the rest should be
simple.</para>

</sect1>
</chapter>

<chapter id="modem-tricks">
<title>Modem Tricks and 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="modem-sessions">
<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 <guibutton>Setup</guibutton>, then <guilabel>Modem</guilabel>
<guibutton>Terminal</guibutton> dialog. This will open a window for interactive
configuration of the modem. Try typing
<userinput><command>ATZ</command></userinput> (which resets your modem) Your
should get an OK response. Use
<menuchoice><guimenu>File</guimenu><guimenuitem>Close</guimenuitem></menuchoice>
to end the session.</para>

</sect1>

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

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

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

<para>Examples of profile changes are in the next section</para>

</sect1>

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

<para>Sometimes you may find that &kppp; has difficulties hanging up the modem.
This is likely the result of a mismatch between &kppp; settings and those of the
modem.  A standard modem uses two methods to decide to hangup: <link
linkend="hangup-command-method">Command</link>, and <link
linkend="hangup-dtr-method"><acronym>DTR</acronym></link>.  The Command method involves
sending an escape sequence to the modem, which puts it in command mode, then
issuing the hangup command (<command>ATH</command>).</para>

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

<sect2 id="hangup-dtr-method">
<title><acronym>DTR</acronym> (<command>AT&amp;Dn</command>) method</title>

<para>The <acronym>DTR</acronym> method will have the modem hangup whenever
&kppp; stops using the modem.  If you obtain a modem session, and query the
state via <command>AT&amp;V</command>, and you can see among the displayed
settings for the active profile a <command>&amp;D0</command>, then the
<acronym>DTR</acronym> hangup method is disabled.  To enable the
<acronym>DTR</acronym> method, use the <guibutton>Terminal</guibutton> button to
get a modem session, then:</para>

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

<sect3>
<title>How the <acronym>DTR</acronym> method works</title>

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

</sect2>

<sect2 id="hangup-command-method">
<title>Command method</title>

<para>The other way to have a modem hang up when connected (used when
<command>AT&amp;D<replaceable>n</replaceable></command> where
<replaceable>n</replaceable> is not <returnvalue>2</returnvalue>) is to have the
modem accept the command when a session is in progress.  To have it hang up
properly, get a modem session, and set the guard time to a short interval like
so:</para>

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

<para>Then use the <guilabel>Guard Time</guilabel> slider in the Modem commands
section to match the register (<varname>S12</varname> to this value
<returnvalue>5</returnvalue>.  The modem should then hangup properly.</para>

<sect3>
<title>How the Command Method Works</title>

<para>When the local modem is connected to a remote modem, it is in the
<quote>connect</quote> state, where it passes all 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 being three intervals of time whose length
is defined by <varname>S12</varname> in fiftieths of a second.</para>

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

<para>Once the modem is in the command state, you can send it commands.  To have
it hang up, send the command <command>ATH</command>.  The escape codes and the
hangup string used by &kppp; are shown in the <link
linkend="modem-commands"><guilabel>Modem Commands</guilabel></link> dialog.
These should match your modem.</para>

</sect3>
</sect2>
</sect1>

<sect1 id="tone-dialling-speedup">
<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 <varname>S11</varname> 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>

<screen>
<userinput><command>ATZ</command></userinput>        <lineannotation># reset to default profile</lineannotation>
<userinput><command>ATS11=50</command></userinput>   <lineannotation># fastest possible dialling, use a higher number if it doesn't work</lineannotation>
<userinput><command>AT&amp;W</command></userinput>   <lineannotation># write to default profile</lineannotation>
</screen>

</sect1>
</chapter>

<chapter id="callback">
<title>Configuring &kppp; for callback</title>

<para>This chapter is based on material provided by Martin H&auml;fner,
<email>mh@ap-dec717c.physik.uni-karlsruhe.de</email></para>

<sect1 id="unix-callback-server">
<title>&UNIX; or &Linux; callback server</title>

<para>This section introduces &UNIX; (&Linux;) callback, and how &kppp; can be
configured to connect to a &UNIX; callback server, especially to a script based
&Linux; <link linkend="callback-resources">callback server</link></para>

<sect2>
<title>An Introduction to callback</title>

<para>There are several reasons to consider using callback.  Some of these are:</para>

<itemizedlist>
<listitem>
<para>To increase the security of your local network</para>
</listitem>
<listitem>
<para>To reduce expenses of external co-workers</para>
</listitem>
<listitem>
<para>To control telephone costs where calls are claimed as business
expenses</para>
</listitem>
</itemizedlist>

<para>Think about someone calling the number of your dial in server, and then
cracking a password.  Why bother to maintain a firewall for your internet
connection, if access to your network is that easy?.</para>

<para>Callback software generally asks for your name, and then hangs up the
line.  It then calls you back, usually at a number that is stored
<emphasis>on the server</emphasis> in a database.  The client then picks up the
phone line and continues with the dial-in as if nothing had happened.  The
server now requests your username and password, knowing that you are who you
said you were when you first dialled in, or at the least, you are where you said
you were.  The connection is established normally, and the
<application>pppd</application> is started.</para>

<para>Now the big question is, how to tell the client to pick up the phone, when
the server calls you back.  Do you need a special program, such as
<application>mgetty</application>?  The answer is, <emphasis>no</emphasis>, you
don't need a special client program.  In general, any client can be used for
callback connections, you could even use an ordinary terminal program such as
<application>minicom</application> to connect.</para>

<para>The only thing you have to do is tell your modem to
<command>AutoAnswer</command> the phone when a
<computeroutput>RING</computeroutput> is detected by the modem.  This is done
with the following modem command:</para>

<screen>
<userinput><command>AT&amp;SO=1</command></userinput>
</screen>

<para>This tells the modem to pick the phone up after one
<computeroutput>RING</computeroutput>.</para>

<para>Like a lot of other client programs, &kppp; checks to see if the
connection is closed by the server, and then stops the current session if a
<computeroutput>NO CARRIER</computeroutput> is detected.  This, then, is the
real problem when setting up callback.  <computeroutput>NO
CARRIER</computeroutput> will of course be detected the moment the callback
server hangs up the line.  Some servers therefore use a special login program.
So how do you solve this problem?  You tell your modem to show
<computeroutput>CARRIER UP</computeroutput> at all times (which causes no
problems if you tell the client to hang up the line.)  You can do this with the
following modem command:</para>

<screen>
<userinput><command>AT&amp;C0</command></userinput>
</screen>

<para>If you want to test this, you can first use an ordinary terminal program
such as <application>minicom</application>, and call your callback server, to
see what hapens.</para>

</sect2>

<sect2>
<title>The &kppp; setup</title>

<para>So, now that you've seen the theory in action, how do you go about setting
up &kppp; to handle the connection? </para>

<para>The procedure is quite straightforward, as follows.</para>

<procedure>
<step>
<para>First tell the modem to accept connections, and to not stop the
negotiation when the callback server hangs up the line for the first time.  You
can add both these options in the <guilabel>Modem</guilabel> tab of the &kppp;
configuration, by adding to the option <guilabel>Dial String</guilabel> the
string <command>AT&amp;C0S0=1DT</command></para>
<para>There are no other changes with configuration for &kppp;.  If you meet
trouble with modem init and reset, check the <link
linkend="callback-troubleshooting">Troubleshooting</link> section for more
information.</para>
</step>
<step>
<para>Think about your server for a moment.  Remember that &UNIX;, &Windows; and
Macintosh operating systems have differing opinions about how to end a line in a
text file, and therefore, in login procedures too.  If you are connecting to a
&Windows; server, use <userinput>CR/LF</userinput>, if you are connecting to a
&UNIX; server, use <userinput>CR</userinput>, and if you are connecting to a
Macintosh server, use <userinput>LF</userinput>

</para>
</step>
<step>
<para>We are assuming for these instructions that you are calling a &Linux;
callback package which uses ordinary login (not <acronym>PAP</acronym> or
such).</para>
<para>Set the <guilabel>Authentication</guilabel> style in the
<guilabel>Dial</guilabel> tab of the account configuration to
<guilabel>Script-based</guilabel></para>
</step>
<step>
<para>Now you have to build the login script.  Editing of login scripts is one
of the very cool features of &kppp; You can find it in the <guilabel>Login
Script</guilabel> tab of the <guilabel>Edit Account</guilabel> dialog.</para>

<para>In this example, the user <systemitem>userxyz</systemitem> needs the
following script to be called.  The callback server already knows the table of
names and their applicable phone numbers, so you select the phone number to be
used with an alias, for security purposes.</para>

<para>For each line, choose the criteria from the drop down list on the left of
the diaog, and type in the action in the text box on it's right.  Choose the
<guibutton>Add</guibutton> to add each line to the script.  You can use
<guibutton>Insert</guibutton> to add a line into the middle of the script, and
<guibutton>Remove</guibutton> to delete a line if you made a mistake.</para>

<para>The entire script should look something like this (without the comments,
shown here starting with a #)</para>

<screen> 
Expect       ogin:           <lineannotation># remember, we do ordinary terminal login</lineannotation>
ID           ""              <lineannotation># kppp sends the id you configured in
the main dialog</lineannotation>
Expect       for userxyz:    <lineannotation># a list of available numbers is
shown, the user should choose one</lineannotation> 
Send         userxyz-home    <lineannotation># the user wants to be called back
on their home number</lineannotation>
Expect       ogin:           <lineannotation># The callback process is now
running, a new connection, and so a new login.</lineannotation>
ID
Expect       assword:        <lineannotation># Now send your password</lineannotation>
Expect       &gt;            <lineannotation># Wait for the command prompt (the
prompt may vary)</lineannotation>
Send         start_ppp       <lineannotation># this command starts the pppd</lineannotation>
</screen>

<para>After waiting for the login request, the user sends his ID and waits for a
list of available phone numbers for that username.  Then he tells the server
which of the numbers offered he would like to be called back on.  &kppp; can
open a dialog for this, if your location changes often, &eg; you are a sales
representative and move from hotel to hotel.  Now the server is expecting login
and password for authentication, but in the meantime, the server hangs up and
calls the user back.  The authentication information is sent, and &kppp; waits
for a command prompt, and then starts a small script (here called
<filename>start_ppp</filename> which fires up <application>pppd</application> on
the server.</para>
					      
<para>The <filename>start_ppp</filename> script might look something like the
following:</para>
					      
<programlisting>
#!/bin/sh
stty -echo
exec /usr/sbin/pppd -detach silent modem
</programlisting>
					      
<para>Of course, setting up a <acronym>PPP</acronym> server is not within the
scope of this document.  For detailed information, see the
<application>pppd</application> man pages.  An excellent description of a
callback server can be found at <ulink
url="http://ap-dec717c.physik.uni-karlsruhe.de/~mh/callback">
http://ap-dec717c.physik.uni-karlsruhe.de/~mh/callback</ulink></para>
</step>
</procedure>

<para>All other configuration issues, such as <application>pppd</application>
configuration or <acronym>IP</acronym> settings work as normal, and no special
software is required to pick up the line.</para>

<note>
<para>&kppp; callback and other programs such as
<application>mgetty</application> or any other faxgetty can be run on the same
serial port.  There are no problems with the dial in, as &kppp; creates a lock
file which will tell the getty program that another application (in this case,
&kppp; of course,) is using the line at that time.</para>
</note>

</sect2>

<sect2 id="callback-troubleshooting">
<title>Troubleshooting</title>

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

<itemizedlist>
<listitem>
<para>As you initialize the modem to auto answer, you need to reset the modem
after your connection is closed.  Otherwise, your modem will continue to pick up
the line for you, which is not a good idea if the line in question is your main
phone line.</para>
</listitem>
<listitem>
<para>&kppp; has some small problems when sharing a line with another program,
such as <application>mgetty</application>.  If <application>mgetty</application>
is running on the same modem line, &kppp; is not able to initialize the modem
correctly. <!-- This happens on the second try (does this mean it can initialize -->
<!-- on the second try, or it fails on the second time? --> </para>
</listitem>
<listitem>
<para>&kppp; is unable to prompt for certain user input during a scripting based
login.  Unfortunately, when using the example script above, &kppp; also asks for
the user name the second time the callback server requests it.  You can get rid
of this by hardcoding your userid into the login script (not very portable or
nice, but it works.</para>
</listitem>
</itemizedlist>

</sect2>

<sect2 id="callback-resources">
<title>Internet Resources for server software</title>

<para>&Linux; callback server software bundles are available in many
places.</para>

<para>The well known <application>mgetty</application> is a very powerful
program, and is also able to handle callback connections.  A description of how
to set up <application>mgetty</application> for this purpose is maintained at 
<ulink url="http://www.dyer.demon.co.uk/slug/tipscrip.htm">
http://www.dyer.demon.co.uk/slug/tipscrip.htm</ulink>, by Colin McKinnon,
<email>colin@wew.co.uk</email>.</para>

<para>There is also a ready to use package for &Linux; at <ulink
url="http://www.icce.rug.nl/docs/programs/callback/callback.html">
http://www.icce.rug.nl/docs/programs/callback/callback.html</ulink>.  This
package is maintained by Frank B. Brokken, <email>frank@icce.rug.nl</email>.  As
the setup, although straightforward, is not very easy, I have written a short
introduction for it at <ulink
url="http://ap-dec717c.physik.uni-karlsruhe.de/~mh/callback">http://ap-dec717c.physik.uni-karlsruhe.de/~mh/callback/</ulink>,
which also contains a more general introduction to callback.</para>

</sect2>
</sect1>

<sect1 id="nt-callback">
<title>&Windows; NT <acronym>RAS</acronym> callback</title>

<para>&Windows; NT uses a completely different approach than the one described
above.  NT requires an extension to the <acronym>PPP</acronym> protocol itself,
called <acronym>CBCP</acronym> (Call Back Control Protocol).
<application>pppd</application> has support for this protocol, but you must
recompile <application>pppd</application>.  If anybody has experience with
successfully connecting to an NT callback server, please let us know.</para>

</sect1>
</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs;

<qandaset id="faqlist">

<qandadiv id="faq-dialling">
<title>Questions about Dialling</title>
<qandaentry>
<question><para>I can't get &kppp; to work.  &kppp; tells me
<application>pppd</application> has died or that a timeout has expired.  What's
going on?</para></question>

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

<itemizedlist>

<listitem><para> Click on the <guibutton>Details</guibutton> button. &kppp; will
you give an excerpt from the <acronym>PPP</acronym> 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 <application>pppd</application> is the actual
<application>pppd</application> binary not a script</para></listitem>

<listitem><para> Make sure that <application>pppd</application> is setuid
<systemitem class="username">root</systemitem>. You may set this mode by issuing
<userinput><command>chmod</command> <option>u+s pppd</option></userinput> as
<systemitem class="username">root</systemitem>. </para></listitem>

<listitem><para> Make sure that your <filename>/etc/ppp/options</filename> 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 <emphasis>don't</emphasis> use the option
<option>lock</option> as an argument for <application>pppd</application> (&kppp;
is already taking care of device locking).</para></listitem>

<listitem><para> Remove the <option>lock</option> option from
<emphasis>both</emphasis> your <filename>/etc/ppp/options</filename>
<emphasis>and</emphasis> <filename>&tilde;/.ppprc</filename>
files!</para></listitem>
<listitem><para> Using the symbolic link <filename
class="symlink">/dev/modem</filename> may cause some conflicts. Eliminate this
source of trouble by using the real device, &ie; <filename>/dev/cuaX</filename>
or <filename>/dev/ttySX</filename>. </para>
<note><para><hardware>COM1</hardware> equals <filename>ttyS0</filename>,
<hardware>COM2</hardware> is <filename>ttyS1</filename> and so
on. </para></note></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
fine give it less harmful permission if you can not afford to run &kppp; setuid
<systemitem class="username">root</systemitem>. The proper way to proceed would
probably be creating a <systemitem class="groupname">modem</systemitem>
group.</para></listitem>

<listitem><para>You might be launching <application>pppd</application> too
early, &ie; before the remote server is ready to negotiate a
<acronym>PPP</acronym> 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 <command>Send</command> or <command>Send
ppp</command> to launch <acronym>PPP</acronym>. Some users even reported, that
they had to append <command>Pause 1</command> or <command>Pause 2</command> to
their script to solve timing conflicts.</para></listitem>

</itemizedlist>

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

<screen><prompt>#</prompt> <userinput><command>tail</command> <filename>/var/log/messages</filename></userinput></screen>

</answer>
</qandaentry>

<qandaentry>
<question><para>Why does &kppp; tell me <errorname>Sorry, can't open the
modem</errorname>?</para></question>

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

<screen><prompt>%</prompt> <userinput><command>su</command> <option>root</option></userinput>
<prompt>#</prompt> <userinput><command>chown</command> <option>root:root &dollar;KDEDIR/bin/kppp</option></userinput>
<prompt>#</prompt> <userinput><command>chmod</command> <option>+s &dollar;KDEDIR/bin/kppp</option></userinput>
<prompt>#</prompt> <userinput><command>exit</command></userinput>
</screen>
</answer>
</qandaentry>

<qandaentry>
<question><para>Why does &kppp; tell me it can't create a modem lock
file?</para></question>

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

<qandaentry>
<question><para>Why is &kppp; installed with the SETUID bit
on?</para></question>

<answer><para>para>There is no need for the SETUID bit, if you know a bit of
&UNIX; systems administration. Simply create a <systemitem
class="groupname">modem</systemitem> 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 <acronym>DNS</acronym> configuration to work with
&kppp;, then <filename>/etc/resolv.conf</filename> must be read/writable by the
members of that group. The same counts for
<filename>/etc/ppp/pap-secrets</filename> and
<filename>/etc/ppp/chap-secrets</filename> if you want to use the built-in
<acronym>PAP</acronym> or <acronym>CHAP</acronym> support, respectively.</para>

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

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

<qandaentry>
<question><para>What do I do when &kppp; just sits there and waits with the
message: <computeroutput>Expecting OK</computeroutput></para></question>

<answer><para>Have you played with the CR/LF setting? Try CR, LF or
CR/LF.</para>

<para>Alternatively, your modem might need some time to respond to its
intialization.  Open the <guilabel>Modem Commands</guilabel> dialog on the
<guilabel>Modem</guilabel> tab and adjust the <guilabel>Pre-Init</guilabel> and
<guilabel>Post-Init</guilabel> delays.  See if you are successful when
drastically increasing their values, and then do some fine-tuning
later.</para></answer>
</qandaentry>

<qandaentry>
<question><para>The connection works fine, but I can't start any
applications!</para></question>

<answer><para>You have probably selected the <link
linkend="auto-configure-hostname">Auto Configure Host Name</link> option, and
the X Server has problems connecting to your newly named host.  If you really
need this option (and chances are you really don't), you are unfortunately on
your own to set up the appropriate authorisations.  Issuing
<userinput><command>xhost</command> <option>+</option></userinput> before
starting the connection would do the job, but be warned of the security risks
involved, since this effectively gives everyone else access to your X
Server.</para></answer>
</qandaentry>

<qandaentry>
<question><para>&kppp; reports a successful connection, but &konqueror; just says
<errorname>Unknown host <replaceable>hostname</replaceable></errorname>, and
&Netscape; reports <errorname>The server does not have a DNS
entry</errorname>.</para></question>

<answer><para>Try pinging another server by its <acronym>IP</acronym> number,
&eg; <userinput><command>ping</command>
<option>195.0.254.76</option></userinput>.  If that works, you could try the
following:</para>

<itemizedlist>
<listitem><para>Check if you have provided &kppp; with at least one
<acronym>DNS</acronym> address.</para></listitem>

<listitem><para>Check the contents of <filename>/etc/host.conf</filename>.  There
should be a line saying something similar to <literal>order hosts,
bind</literal>.  The <option>bind</option> keyword advises the resolver library
to include a name server query when performing an address lookup.  If such a
line is not there, try adding it.</para></listitem>
</itemizedlist></answer>
</qandaentry>

<qandaentry>
<question><para>How do I make &kppp; send a <keysym>\n</keysym> or a
<keysym>\r</keysym></para></question>

<answer><para>Just send an empty string such as in the following script:</para>

<informalexample>
<screen>
Send                            # send an empty string
Expect           ID:            
Send             itsme
Expect           word:
Send             forgot
Expect           granted
Send             ppp
</screen>
</informalexample>
</answer>
</qandaentry>

<qandaentry>
<question><para>How can I stop &kppp; complaining: <errorname>Can't create lock
file</errorname>?</para></question>
<answer><para>This happens because you don't have permissions to create a lock
file.  If you chose to use a lock file, you must have write permision to the
directory (typically <filename class="directory">/var/lock</filename>).  This is
of course no problem if you have given &kppp; setuid permissions.  Please read
the section on <link linkend="lock-files">Lock files</link>.</para></answer>
</qandaentry>

<qandaentry>
<question><para>Why is my modem making so much noise when
dialling?</para></question>

<answer><para>Click on <guibutton>Setup</guibutton>, then
<guilabel>Modem</guilabel>.  You can control the modem volume here in three
steps: Off, medium and high.  For most modems, medium or high result in the same
volume.  If changing this setting doesn't work, make sure the correct settings
for your modem are specified in <guibutton>Setup</guibutton>,
<guilabel>Modem</guilabel>, <guibutton>Modem
Commands</guibutton>.</para></answer>
</qandaentry>

<qandaentry>
<question><para>I turned the modem volume to <quote>Off</quote> and verified the
modem commands, but I still hear that awful noise during dialling.
Why?</para></question>

<answer><para>The volume initialisation string can get lost if your modem can't
cope with the speed it is receiving commands from &kppp;.  Increase the value of
<guilabel>Post-Init Delay</guilabel> in <guibutton>Setup</guibutton>,
<guilabel>Modem</guilabel>, <guibutton>Modem
Commands</guibutton>.</para></answer>
</qandaentry>

<qandaentry>
<question><para>&kppp; keeps reporting unusual modem speeds like
<quote>115200</quote> or <quote>57600</quote></para></question>

<answer><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 by adding some commands to the modem init or dial
strings.  For many modems this command is <command>ATW2</command>.  If you want
to add it to the dial string (which normally starts with
<command>ATD</command>), the new dial string would be
<command>ATW2D</command>.</para></answer>
</qandaentry>

<qandaentry>
<question><para>Why does &kppp; report <quote>Unknown
speed</quote></para></question>

<answer><para>New modems often have very complex connection messages like
<computeroutput>CONNECT LAP.M/V42.bis/115000:RX/31200:TX</computeroutput>, and
&kppp; cannot parse this message correctly. Turn on <guibutton>Show
Log</guibutton> and you'll see the connection speed.</para></answer>
</qandaentry>

<qandaentry>
<question><para>I get a slow connection speed</para></question>

<answer><para>If you are not satisfied with the modem speed, make sure you've
set the connection speed (you can reach it by clicking on
<guibutton>Setup</guibutton>, <guilabel>Device</guilabel>, <guibutton>Connection
Speed</guibutton>) to 57600 or higher.  Make sure your serial ports support
higher speeds.  Many older systems based on i486 do not work correctly if you
set the speed to 115200.  If you have an old <hardware>8250 UART</hardware>
chip, it won't work.  If you have a <hardware>16550</hardware> or
<hardware>16550A</hardware> it should work flawlessly.</para>

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

<qandaentry>
<question><para>I get a <emphasis>REALLY</emphasis> slow connection
speed!</para></question>

<answer><para>If data drips on 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>You can obtain some information about your serial port with
<userinput><command>setserial</command> <option>-a
<replaceable>/dev/ttySx</replaceable></option></userinput> and check for interrupt
conflicts with other components of your system.  The &kcontrol; module
<guilabel>Information</guilabel> might also be of help here.</para></answer>
</qandaentry>

<qandaentry>
<question><para>My phone line needs pulse dialling instead of tone dialling (or
vice-versa).  How do I change that?</para></question>
<answer><para>You must modify your modem dial string.  Nearly all modems support
the following AT commands:</para>

<variablelist>
<varlistentry>
<term><command>ATDT</command></term>
<listitem><para><action>Selects tone dialling</action></para></listitem>
</varlistentry>
<varlistentry>
<term><command>ATDP</command></term>
<listitem><para><action>Selects pulse dialling</action></para></listitem>
</varlistentry>
</variablelist>
</answer>
</qandaentry>

</qandadiv>

<qandadiv id="faq-telephone-cost-rules">
<title>Questions about Telephone Cost Rules</title>
<qandaentry>
<question><para>How do I write a telephones cost rules file?</para></question>
<answer><para>Just follow the <filename>TEMPLATE</filename> rules file supplied
with &kppp;.  You should be able to find a copy in <filename
class="directory">$KDEDIR/doc/HTML/<replaceable>yourlang</replaceable>/kppp/</filename>.
Use the <option>-r</option> &kppp; command line option to check the syntax of
your proposed rules file.</para></answer>
</qandaentry>

<qandaentry>
<question><para>I have written a telephone cost rules for my region.  Where can
I submit it so that others can make use of it?</para></question>
<answer><!-- LW: Find out -->
<!-- lukas: the answer is: send it to the kppp maintainer, Harri Porten --></answer>
</qandaentry>

<qandaentry>
<question><para>Can my phone cost rulefile contain fractional time units like
"(0.17, 45.5)"?</para></question>
<answer><para>Yes this is possible.  But you shouldn't use unusually small time
units below a tenth of a second, because this would result in higher
<acronym>CPU</acronym> load, although you probably won't notice on a modern
<acronym>CPU</acronym>.</para></answer>
</qandaentry>

<qandaentry>
<question><para>My country observes other <quote>moving</quote> holidays than
Easter.</para></question>
<answer><para>In that case, you need to write new code that allows for the
computation of that holiday.  Please have a look at
<filename>ruleset.cpp</filename> and emulate the <quote>easter</quote> example.
Then send in the patches!.</para></answer>
</qandaentry>
</qandadiv>

<qandadiv id="faq-system-logs">
<title>Questions about the System Logs</title>
<qandaentry>
<question><para>I see a message saying <errorname>Serial line is looped
back</errorname>.  What does this mean?</para></question>

<answer><para>Short answer: You didn't start the <acronym>PPP</acronym> software
on the peer system.</para>

<!-- this doc doesn't exist.. help -->
<!-- http://www.dejanews.com/getdoc.xp?AN=184945314 -->

</answer>
</qandaentry>

<qandaentry>
<question><para>The logs show <errorname>Signal 15</errorname></para></question>
<answer><para>If you see the following lines, you've probably just received a
timeout error from &kppp;.  &kppp; has been waiting for the
<acronym>PPP</acronym> interface to come up and gave up after the specified
timeout. <application>pppd</application> was signalled to shut down, with signal
number 15, &ie; <errorcode>SIGTERM</errorcode>.</para>

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

<qandaentry>
<question><para>What about <errorname>Receive serial link is not 8-bit
clean</errorname></para></question>
<answer><para>The <acronym>PPP</acronym> daemon is alarmed by the fact that all the
data it receives has bit 8 set to zero.  In most cases this simply indicates
that the remote <acronym>PPP</acronym> server isn't running yet.  You might
still be confronted by a login prompt that echoes back all the data sent by your
<application>pppd</application>.</para></answer>
</qandaentry>

<qandaentry>
<question><para>and <errorname>can't locate module ppp-compress</errorname>?
What's this?</para></question>
<answer><para>Do you see the following messages?</para>

<informalexample>
<screen><computeroutput>
modprobe: can't locate module ppp-compress-21 
modprobe: can't locate module ppp-compress-26 
modprobe: can't locate module ppp-compress-24
</computeroutput></screen>
</informalexample>

<para>Just add the lines:</para>

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

<para> to your <filename>/etc/conf.modules</filename> file.</para>
</answer>
</qandaentry>

</qandadiv>

</qandaset>

</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>&kppp;</para>

<para>&kppp; is derived from <application>ezppp</application> 0.6, by Jay
Painter.  However, nearly everything in &kppp; was rewritten so
<application>ezppp</application> and &kppp; do not have much in common any
longer.</para>

<para>Primary Developers:</para>

<itemizedlist>
<listitem><para>Bernd Johannes Wuebben <email>wuebben@kde.org</email></para>
</listitem>
<listitem><para>Mario Weilguni <email>mweilguni@sime.com</email></para>
</listitem>
<listitem><para>Harri Porten <email>porten@kde.org</email> (Current
maintainer)</para>
</listitem>
</itemizedlist>

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

<itemizedlist>
<listitem><para>Jesus Fuentes Saaverdra
<email>jesus.fuentes@etsi.tel.uva.esfor</email> implementing several options and
miscellaneous work.</para>
</listitem>
<listitem><para>Markus Wuebben <email>wuebben@eure.de</email> for the ATI query
dialog</para>
</listitem>
<listitem><para>Peter Silva <email>peter.silva@videotron.ca</email> for pop up
dialogs and other contributions</para>
</listitem>
<listitem><para>Martin A. Brown <email>MABrown@etcconnect.org</email></para>
</listitem>
<listitem><para>Martin H&auml;fner
<email>mh@ap-dec717c.physik.uni-karlsruhe.de</email> for the section on callback.</para>
</listitem>
<listitem><para>Olaf Kirch <email>okir@caldera.de</email> for the introduction
to the mysteries of file descriptor passing.</para>
</listitem>
</itemizedlist>


<para>Documentation copyright 2001 Lauri Watts
<email>vampyr@atconnex.net</email>, although largely based on the original by
Bernd Johannes Wuebben <email>wuebben@kde.org</email></para>

&underFDL;               <!-- FDL: do not remove -->

&underGPL;        	 <!-- GPL License -->

</chapter>

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

<sect1 id="getting-kppp">
<title>How to obtain &kppp;</title>

<para>&kppp; is part of the &kde; project <ulink
url="http://www.kde.org">http://www.kde.org</ulink>.  &kppp; can be found in the
kdenetwork package 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="compilation">
<title>Compilation and installation</title>

<para>In order to compile and install &kppp; on your system, type the following
in the base directory of the &kppp; distribution:</para>

<screen width="40">
<prompt>%</prompt> <userinput><command>./configure</command></userinput>
<prompt>%</prompt> <userinput><command>make</command></userinput>
<prompt>%</prompt> <userinput><command>make</command> <option>install</option></userinput>
</screen>

<para>Since &kppp; uses <application>autoconf</application> and
<application>automake</application> you should have not trouble compiling
it. Should you run into problems please report them to the &kde; mailing
lists.</para>

</sect1>

<sect1 id="preparing-your-computer">
<title>Preparing your Computer for a <acronym>PPP</acronym> Connection</title>

<para>The following sections contain some fairly generic information for several
common operating systems which might run &kppp;.  The following sites may be of
interest for further information about the <acronym>ppp</acronym> protocol,
<application>pppd</application> and networking in general:</para>

<itemizedlist>
<listitem><para>The &Linux; <acronym>PPP</acronym> &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>The &Linux; <acronym>PPP</acronym> 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>

<sect2 id="preparing-linux-for-ppp">
<title>Preparing a &Linux; system for <acronym>PPP</acronym></title>

<para>In order for &kppp; (or indeed, <application>pppd</application>) to work,
your kernel must have ppp support compiled in.  If this is not the case, get
yourself the latest version of <application>pppd</application> from any of the
popular &Linux; archives (such as <ulink
url="ftp://sunsite.unc.edu/pub/Linux/system/Network/serial/ppp/">ftp://sunsite.unc.edu/pub/Linux/system/Network/serial/ppp/</ulink>,
and recompile your kernel with <acronym>ppp</acronym> support enabled.</para>

<para>Don't fret, since this sounds a lot scarier than it actually is.  Don't
forget to install <application>pppd</application> afterwards.</para>

<para>If you're not sure if you have a kernel with ppp support, issue the
<command>dmesg</command> at the command prompt and look for something like
this:</para>

<informalexample>
<screen><computeroutput>
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
</computeroutput></screen>
</informalexample>

<para>&kppp; tries to find out for itself if your kernel supports
<acronym>PPP</acronym>.  If not, you will be notified as soon as &kppp; starts
up.</para>

<para>For &Linux; 2.x kernels, the <application>pppd</application> daemon should
be version 2.3 or greater.  You can find out what version your system has, by
issuing the command <userinput><command>pppd</command>
<option>--version</option></userinput> on the comamnd line.  None of the
<application>pppd</application> daemons actually have a
<option>--version</option>, but putting the option in will cause the
<application>pppd</application> daemon to issue an error message, and then to
print out a list of options and other information, which includes the version of
the <application>ppd</application> daemon.</para>

</sect2>

<sect2 id="preparing-bsd-for-ppp">
<title>Preparing your FreeBSD computer for ppp connections</title>

<para></para>
</sect2>

</sect1>

</appendix>

<appendix id="appendix-hayes-commands">
<title>The Hayes Modem Command Set</title>

<para>Here is a description of the Hayes Command Set. Most modems follow this
command set to large extent. If you lost your modem manual or never had one in
the first place, this reference might come in handy. I for instance finally found
out how to turn my modems speaker off: <command>ATM0</command> -- Finally:
Silence!</para>

<para>The modem initialization string consists of a series of commands. It
prepares the modem for communications, setting such features as dialing mode,
waits, detection of the busy signal and many other settings. Newer modem
communications programs reset the initializations string for you according to
which menu options you select, which features you enable, &etc;.</para>

<para>For many years Hayes modems have been the standard. As the field of modem
manufactures has grown, most have adhered at least loosely to the Hayes
standard. The following is a partial list of the Hayes command set. (called the
<quote>AT</quote> commands). The Hayes Command Set can be divided into four
groups:</para>

<variablelist>
<varlistentry>
<term>Basic Command Set</term>
<listitem><para>A capital character followed by a digit. For example,
<command>M1</command>.</para></listitem>
</varlistentry>
<varlistentry>
<term>Extended Command Set</term>
<listitem><para>An <quote>&amp;</quote> (ampersand) and a capital character
followed by a digit. This is an extension of the basic command set. For example,
<command>&amp;M1</command>. Note that <command>M1</command> is different from
<command>&amp;M1</command>.</para></listitem>
</varlistentry>
<varlistentry>
<term>Proprietary Command Set</term>
<listitem><para>Usually started by either a backslash (<quote>\</quote>), or a
percent sign (<quote>&percnt;</quote>), these commands vary widely among modem
manufacturers. For that reason, only a few of these commands are listed
below.</para></listitem>
</varlistentry>
<varlistentry>
<term>Register Commands</term>
<listitem><para><command>S<replaceable>r</replaceable>=<replaceable>n</replaceable></command>
where <replaceable>r</replaceable> is the number of the register to be changed,
and <replaceable>n</replaceable> is the new value that is
assigned.</para>

<para>A <quote>register</quote> is computerese for a specific physical location
in memory. Modems have small amounts of memory onboard. This fourth set of
commands is used to enter values in a particular register (memory location). The
register will be storing a particular <quote>variable</quote> (alpha-numeric
information) which is utilized by the modem and communication software. For
example, <command>S7=60</command> instructs your computer to <quote>Set register
#7 to the value 60</quote>.</para></listitem>
</varlistentry>
</variablelist>

<note><para>Although most commands are defined by a letter-number combination
(<command>L0</command>, <command>L1</command> &etc;), the user of a zero is
optional.  In this example, <command>L0</command> is the same as a plain
<command>L</command>.  Keep this in mind when reading the table
below!</para></note>

<para>Here are some of the most important characters that may appear in the
modem initialization string.  These characers normally should not be
changed.</para>

<variablelist>
<varlistentry>
<term><command>AT</command></term>
<listitem><para>Tells the modem that modem commands follow.  This must begin
each line of commands.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>Z</command></term>
<listitem><para>Resets the modem to it's default state</para></listitem>
</varlistentry>
<varlistentry>
<term><command>,</command> (a comma)</term>
<listitem><para>makes your software pause for a second. You can use more than
one <command>,</command> in a row. For example, <command>,,,,</command> tells
the software to pause four seconds. (The duration of the pause is governed by
the setting of register <varname>S8</varname>.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>^M</command></term>
<listitem><para>Sends the terminating Carriage Return character to the modem.
This is a control code that most communication software translates as
<quote>Carriage Return</quote></para></listitem></varlistentry>
</variablelist>

<sect1 id="hayes-basic-commands">
<title>The Basic Hayes Command Set</title>

<para>In alphabetical order:</para>

   <table>
    <title>Basic Hayes Command Set</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Command</entry>
       <entry>Description</entry>
       <entry>Comments</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><command>A0</command> or <command>A</command></entry>
       <entry>Answer incoming call</entry>
       <entry></entry>
      </row>
      <row>
       <entry><command>A/</command></entry>
       <entry>Repeat last command</entry>
       <entry>Don't preface with <command>AT</command>.  Enter usually
       aborts.</entry>
      </row>
      <row>
       <entry><command>B0</command> or <command>B</command></entry>
       <entry>Call negotiation</entry>
       <entry>V32 Mode/CCITT Answer Seq.</entry>
      </row>
      <row>
       <entry><command>B1</command></entry>
       <entry>Call negotiation</entry>
       <entry>Bell 212A Answer Seq.</entry>
      </row>
      <row>
       <entry><command>B2</command></entry>
       <entry>Call negotiation</entry>
       <entry>Verbose/Quiet On Answer</entry>
      </row>
      <row>
       <entry><command>D</command></entry>
       <entry>Dial</entry>
       <entry><para>Dial the following number and then handshake in orginate
       mode.</para><variablelist>
	 <varlistentry>
	  <term><command>P</command></term>
	  <listitem><para>Pulse Dial</para></listitem>
	 </varlistentry>
	 <varlistentry>
	  <term><command>T</command></term>
	  <listitem><para>Touch Tone Dial</para></listitem>
	 </varlistentry>
	 <varlistentry>
	  <term><command>W</command></term>
	  <listitem><para>Wait for the second dial tone</para></listitem>
	 </varlistentry>
	 <varlistentry>
	  <term><command>,</command></term>
	  <listitem><para>Pause for the time specified in register
	  <varname>S8</varname> (usually 2 seconds</para></listitem>
	 </varlistentry>
	 <varlistentry>
	  <term><command>;</command></term>
	  <listitem><para>Remain in command mode after dialing.</para></listitem>
	 </varlistentry>
	 <varlistentry>
	  <term><command>!</command></term>
	  <listitem><para>Flash switch-hook (Hang up for a half second, as in
	  transferring a call.</para></listitem>
	 </varlistentry>
	 <varlistentry>
	  <term><command>L</command></term>
	  <listitem><para>Dial last number</para></listitem>
	 </varlistentry>
	</variablelist></entry>
      </row>
      <row>
       <entry><command>E0</command> or <command>E</command></entry>
       <entry>No Echo</entry>
       <entry>Will not echo commands to the computer</entry>
      </row>
      <row>
       <entry><command>E1</command></entry>
       <entry>Echo</entry>
       <entry>Will echo commands to the computer (so one can see what one
       types)</entry>
      </row>
      <row>
       <entry><command>H0</command></entry>
       <entry>Hook Status</entry>
       <entry>On hook - Hang up</entry>
      </row>
      <row>
       <entry><command>H1</command></entry>
       <entry>Hook status</entry>
       <entry>Off hook - phone picked up</entry>
      </row>
      <row>
       <entry><command>I0</command> or <command>I</command></entry>
       <entry>Inquiry, Information, or Interrogation</entry>
       <entry>This command is very model specific.  <command>I0</command>
       usually returns a number or code, while higher numbers often provide much
       more useful information.</entry>
      </row>
      <row>
       <entry><command>L0</command> or <command>L</command></entry>
       <entry>Speaker Loudness.  Modems with volume control knobs will not have
       these options.</entry>
       <entry>Off or low volume</entry>
      </row>
      <row>
       <entry><command>L1</command></entry>
       <entry></entry>
       <entry>Low Volume</entry>
      </row>
      <row>
       <entry><command>L2</command></entry>
       <entry></entry>
       <entry>Medium Volume</entry>
      </row>
      <row>
       <entry><command>L3</command></entry>
       <entry></entry>
       <entry>Loud or High Volume</entry>
      </row>
      <row>
       <entry><command>M0</command> or <command>M</command></entry>
       <entry>Speaker off</entry>
       <entry><command>M3</command> is also common, but different on many
       brands</entry>
      </row>
      <row>
       <entry><command>M1</command></entry>
       <entry></entry>
       <entry>Speaker on until remote carrier detected (&ie; until the other
       modem is heard)</entry>
      </row>
      <row>
       <entry><command>M2</command></entry>
       <entry></entry>
       <entry>Speaker is always on (data sounds are heard after CONNECT)</entry>
      </row>
      <row>
       <entry><command>N0</command> or <command>N</command></entry>
       <entry>Handshake Speed</entry>
       <entry>Handshake only at speed in <link linkend="hayes-s37"><varname>S37</varname></link></entry>
      </row>
      <row>
       <entry><command>N1</command></entry>
       <entry></entry>
       <entry>Handshake at highest speed larger than <link linkend="hayes-s37"><varname>S37</varname></link></entry>
      </row>
      <row>
       <entry><command>O0</command> or <command>O</command></entry>
       <entry>Return Online</entry>
       <entry>See also <link linkend="hayes-basic-x1"><command>X1</command></link> as dial tone
       detection may be active.</entry>
      </row>
      <row>
       <entry><command>O1</command></entry>
       <entry></entry>
       <entry>Return Online after an equalizer retrain sequence</entry>
      </row>
      <row>
       <entry><command>Q0</command> or <command>Q1</command></entry>
       <entry>Quiet Mode</entry>
       <entry>Off - Displays result codes, user sees command responses (&eg;
       <computeroutput>OK</computeroutput>)</entry>
      </row>
      <row>
       <entry><command>Q1</command></entry>
       <entry>Quiet Mode</entry>
       <entry>On - Result codes are suppressed, user does not see
       responses.</entry>
      </row>
      <row>
       <entry><command>S<replaceable>n</replaceable>?</command></entry>
       <entry></entry>
       <entry>Query the contents of S-register
       <replaceable>n</replaceable></entry>
      </row>
      <row>
       <entry><command>S<replaceable>n</replaceable>=<replaceable>r</replaceable></command></entry>
       <entry>Store</entry>
       <entry>Store the value of <replaceable>r</replaceable> in S-register
       <replaceable>n</replaceable></entry>
      </row>
      <row>
       <entry><command>V0</command> or <command>V</command></entry>
       <entry>Verbose</entry>
       <entry>Numeric result codes</entry>
      </row>
      <row>
       <entry><command>V1</command></entry>
       <entry></entry>
       <entry>English result codes (&eg;
       <computeroutput>CONNECT</computeroutput>,
       <computeroutput>BUSY</computeroutput>, <computeroutput>NO
       CARRIER</computeroutput> &etc;)</entry>
      </row>
      <row>
       <entry><command>X0</command> or <command>X</command></entry>
       <entry>Smartmodem</entry>
       <entry>Hayes Smartmodem 300 compatible result codes</entry>
      </row>
      <row>
       <entry><anchor id="hayes-basic-x1"><command>X1</command></entry>
       <entry></entry>
       <entry>Usually adds connection speed to basic result codes (&eg;
       <computeroutput>CONNECT 1200</computeroutput></entry>
      </row>
      <row>
       <entry><command>X2</command></entry>
       <entry></entry>
       <entry>Usually adds dial tone detection (preventing blind dial, and
       sometimes preventing <command>AT0</command>)</entry>
      </row>
      <row>
       <entry><command>X3</command></entry>
       <entry></entry>
       <entry>Usually adds busy signal detection</entry>
      </row>
      <row>
       <entry><command>X4</command></entry>
       <entry></entry>
       <entry>Usually adds both busy signal and dial tone detection</entry>
      </row>
      <row>
       <entry><command>Z0</command> or <command>Z</command></entry>
       <entry>Reset</entry>
       <entry>Reset modem to stored configuration. Use <command>Z0</command>,
	<command>Z1</command> &etc; for multiple profiles.  This is the same as
	<command>&amp;F</command> for factory default on modems without
       <acronym>NVRAM</acronym> (non voltaile memory)</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </sect1>

  <sect1 id="hayes-extended-commands">
   <title>The Extended Hayes Command Set</title><subtitle>Ampersand Commands</subtitle>

   <table>
    <title>The Extended Hayes Command Set</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Command</entry>
       <entry>Description</entry>
       <entry>Comments</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><command>&amp;B0</command> or <command>&amp;B</command></entry>
       <entry>Retrain Parameters</entry>
       <entry>Disable auto retrain function</entry>
      </row>
      <row>
       <entry><command>&amp;B1</command></entry>
       <entry>Retrain Parameters</entry>
       <entry>Enable auto retrain function</entry>
      </row>
      <row>
       <entry><command>&amp;B2</command></entry>
       <entry>Retrain Parameters</entry>
       <entry>Enable auto retrain, but disconnect if no line improvement over
       the period dictated by <link
       linkend="hayes-s7"><varname>S7</varname></link></entry>
</row>
      <row>
       <entry><command>&amp;C0</command> or <command>&amp;C1</command></entry>
       <entry>Carrier detect</entry>
       <entry>Signal always on</entry>
      </row>
      <row>
       <entry><command>&amp;C1</command></entry>
       <entry>Carrier detect</entry>
       <entry>Indicates remote carrier (usual preferred default)</entry>
      </row>
      <row>
       <entry><command>&amp;D0</command> or <command>&amp;D</command></entry>
       <entry>Data Terminal Ready (<acronym>DTR</acronym></entry>
       <entry>Signal ignored (This is modem specific, you must see your manual
       for information on this one!)</entry>
      </row>
      <row>
       <entry><command>&amp;D1</command></entry>
       <entry>Data Terminal Ready (<acronym>DTR</acronym></entry>
       <entry>If <acronym>DTR</acronym> goes from On to Off the modem goes into
       command mode (Some modems only)</entry>
      </row>
      <row>
       <entry><command>&amp;D2</command></entry>
       <entry>Data Terminal Ready (<acronym>DTR</acronym></entry>
       <entry>Some modems hang up on <acronym>DTR</acronym> On to Off transition
       (This is the usual preferred default)</entry>
      </row>
      <row>
       <entry><command>&amp;D3</command></entry>
       <entry>Data Terminal Ready (<acronym>DTR</acronym></entry>
       <entry>Hang up, reset the modem, and return to command mode upon
       <acronym>DTR</acronym></entry>
      </row>
      <row>
       <entry><command>&amp;F0</command> or <command>&amp;F</command></entry>
       <entry>Factory defaults</entry>
       <entry><para>Generic Hayes-compatible defaults. </para><para>This is
       usually a good thing to use in your init string, since the
       <command>&amp;F1</command>-<command>&amp;F3</command> settings can vary
       among modems, and they may actually be the cause of connection
       problems. (Since you never know exactly what Brand X's
       <command>&amp;F2</command> really changes.</para><para>On the other hand,
       it pays to try out the other options below; many people's problems can be
       solved by replacing a complicated init string with a simple
       <command>&amp;F2</command> or the like. However, if you're building an
       init string, it's best to start with a simple <command>&amp;F</command>,
       and not use the <quote>customized</quote> form of
       defaults.</para></entry>
      </row>
      <row>
       <entry><command>&amp;F1</command></entry>
       <entry>Factory Defaults</entry>
       <entry>Factory Defaults tailored to an IBM <acronym>PC</acronym>
       compatible user</entry>
      </row>
      <row>
       <entry><command>&amp;F2</command></entry>
       <entry>Factory Defaults</entry>
       <entry>Factory defaults for a Mac w/software handshaking</entry>
      </row>
      <row>
       <entry><command>&amp;F3</command></entry>
       <entry>Factory Defaults</entry>
       <entry>Factory defaults for a Mac w/hardware handshaking</entry>
      </row>
      <row>
       <entry><command>&amp;G0</command> or <command>&amp;G</command></entry>
       <entry>Guard tones</entry>
       <entry>Disable guard tones</entry>
      </row>
      <row>
       <entry><command>&amp;K0</command> or <command>&amp;K</command></entry>
       <entry>Local flow control</entry>
       <entry>Disable local flow control</entry>
      </row>
      <row>
       <entry><command>&amp;K1</command></entry>
       <entry>Local flow control</entry>
       <entry>Enable RTS/CTS hardware local flow control</entry>
      </row>
      <row>
       <entry><command>&amp;K2</command></entry>
       <entry>Local flow control</entry>
       <entry>Enable XON/XOFF software local flow control</entry>
      </row>
      <row>
       <entry><command>&amp;K3</command></entry>
       <entry>Local flow control</entry>
       <entry>Enable RTS/CTS hardware local flow control</entry>
      </row>
      <row>
       <entry><command>&amp;K4</command></entry>
       <entry>Local flow control</entry>
       <entry>Enable XON/XOFF software local flow control</entry>
      </row>
      <row>
       <entry><command>&amp;L0</command> or <command>&amp;L</command></entry>
       <entry>Dial mode</entry>
       <entry>Select dial-up mode</entry>
      </row>
      <row>
       <entry><command>&amp;M0</command> or <command>&amp;M</command></entry>
       <entry>Error control mode</entry>
       <entry>Select asynchronous non-<acronym>EC</acronym> mode (the same as
       <command>&amp;Q0</command>)</entry>
      </row>
      <row>
       <entry><command>&amp;P0</command> or <command>&amp;P</command></entry>
       <entry>Pulse dialing ratio</entry>
       <entry>U.S./Canada pulse dialing 39% make / 61% break ratio</entry>
      </row>
      <row>
       <entry><command>&amp;P1</command></entry>
       <entry>Pulse dialing ratio</entry>
       <entry>U.K./Hong Kong pulse dialing 33% make / 67% break ratio</entry>
      </row>
      <row>
       <entry><command>&amp;Q0</command> or <command>&amp;Q</command></entry>
       <entry>Error control mode</entry>
       <entry>Asynchronous non-<acronym>EC</acronym> more. No data
       buffering. <acronym>ASB</acronym> disabled.</entry>
      </row>
      <row>
       <entry><command>&amp;Q5</command></entry>
       <entry>Error control mode</entry>
       <entry>Select V.42 <acronym>EC</acronym> operation (requires flow
       control)</entry>
      </row>
      <row>
       <entry><command>&amp;Q6</command></entry>
       <entry>Error control mode</entry>
       <entry>Asynchronous mode with <acronym>ASB</acronym> (requires flow
       control)</entry>
      </row>
      <row>
       <entry><command>&amp;Q8</command></entry>
       <entry>Error control mode</entry>
       <entry>Select alternate <acronym>EC</acronym> protocol
       (<acronym>MNP</acronym>)</entry>
      </row>
      <row>
       <entry><command>&amp;Q9</command></entry>
       <entry>Error control mode</entry>
       <entry>Conditional data compression: V.42bis = yes, MNP5 = no.</entry>
      </row>
      <row>
       <entry><command>&amp;S0</command> or <command>&amp;S</command></entry>
       <entry><acronym>DSR</acronym> action select</entry>
       <entry>Always on (default)</entry>
      </row>
      <row>
       <entry><command>&amp;S1</command></entry>
       <entry><acronym>DSR</acronym> action select</entry>
       <entry>Follows <acronym>EIA</acronym> specification (Active following
       carrier tone, and until carrier is lost.)</entry>
      </row>
      <row>
       <entry><command>&amp;T0</command> or <command>&amp;T</command></entry>
       <entry>Self test</entry>
       <entry>Model specific self test on some modems</entry>
      </row>
      <row>
       <entry><command>&amp;U0</command> or <command>&amp;U</command></entry>
       <entry>Trellis code modulation</entry>
       <entry>Enable V.32 <acronym>TCM</acronym></entry>
      </row>
      <row>
       <entry><command>&amp;U1</command></entry>
       <entry>Trellis code modulation</entry>
       <entry>Disable V.32 <acronym>TCM</acronym></entry>
      </row>
      <row>
       <entry><command>&amp;V0</command> or <command>&amp;V1</command></entry>
       <entry>View active</entry>
       <entry>(and often stored) configuration profile settings (or
       <command>ATI4</command></entry>
      </row>
      <row>
       <entry><command>&amp;W0</command> or <command>&amp;W</command></entry>
       <entry>Store profile</entry>
       <entry>In <acronym>NVRAM</acronym> (<command>&amp;W0</command>,
       <command>&amp;W1</command> etc. for multiple profiles) Some settings
       cannot be stored. These often don't show on <command>&amp;V</command> or
       <command>ATI4</command></entry>
      </row>
      <row>
       <entry><command>&amp;Y0</command> or <command>&amp;Y</command></entry>
       <entry>Select configuration loaded at power-up</entry>
       <entry>Load profile 0 (default)</entry>
      </row>
      <row>
       <entry><command>&amp;Y1</command></entry>
       <entry>Select configuration loaded at power-up</entry>
       <entry>Load profile 1</entry>
      </row>
      <row>
       <entry><command>&amp;Z<replaceable>n</replaceable>=<replaceable>x</replaceable></command></entry>
       <entry>Soft reset and load stored profile number
       <replaceable>n</replaceable></entry>
       <entry>Note that all items after the <command>&amp;Z</command> on the
       command line are ignored</entry>
      </row>
     </tbody>
    </tgroup>
   </table>

  </sect1>

  <sect1 id="hayes-backslash-commands">
   <title>Backslash and Percent Commands</title>

   <table>
    <title>Backslash and Percent Commands</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Command</entry>
       <entry>Description</entry>
       <entry>Comments</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><command>\A0</command> or <command>\A</command></entry>
       <entry>Character maximum <acronym>MNP</acronym> block size</entry>
       <entry>64 character maximum</entry>
      </row>
      <row>
       <entry><command>\A1</command></entry>
       <entry>Character maximum <acronym>MNP</acronym> block size</entry>
       <entry>128 character maximum</entry>
      </row>
      <row>
       <entry><command>\A2</command></entry>
       <entry>Character maximum <acronym>MNP</acronym> block size</entry>
       <entry>192 character maximum</entry>
      </row>
      <row>
       <entry><command>\A3</command></entry>
       <entry>Character maximum <acronym>MNP</acronym> block size</entry>
       <entry>256 character maximum</entry>
      </row>
      <row>
       <entry><command>&percnt;C0</command> or
       <command>&percnt;C</command></entry>
       <entry>Data Compression Enable/Disable</entry>
       <entry>Disabled</entry>
      </row>
      <row>
       <entry><command>&percnt;C1</command></entry>
       <entry>Data Compression Enable/Disable</entry>
       <entry>MNP5 enabled</entry>
      </row>
      <row>
       <entry><command>&percnt;C2</command></entry>
       <entry>Data Compression Enable/Disable</entry>
       <entry>V.42bis (<acronym>BTLZ</acronym>) Enabled</entry>
      </row>
      <row>
       <entry><command>&percnt;C3</command></entry>
       <entry>Data Compression Enable/Disable</entry>
       <entry>MNP5 & V.42bis (<acronym>BTLZ</acronym>) Enabled</entry>
      </row>
      <row>
       <entry><command>&percnt;D0</command> or
       <command>&percnt;D</command></entry>
       <entry>Data compression</entry>
       <entry>512 BLTZ dictionary size</entry>
      </row>
      <row>
       <entry><command>&percnt;D1</command></entry>
       <entry>Data compression</entry>
       <entry>1024 BLTZ dictionary size</entry>
      </row>
     <row>
       <entry><command>&percnt;D2</command></entry>
       <entry>Data compression</entry>
       <entry>2048 BLTZ dictionary size</entry>
      </row>
     <row>
       <entry><command>&percnt;D3</command></entry>
       <entry>Data compression</entry>
       <entry>4096 BLTZ dictionary size</entry>
      </row>
      <row>
       <entry><command>&percnt;E0</command> or
       <command>&percnt;E1</command></entry>
       <entry>Escape method</entry>
       <entry>ESCAPE DISABLED</entry>
      </row>
      <row>
       <entry><command>&percnt;E1</command></entry>
       <entry>Escape method</entry>
       <entry><command>+++AT</command> method (default)</entry>
      </row>
      <row>
       <entry><command>&percnt;E2</command></entry>
       <entry>Escape method</entry>
       <entry><computeroutput>Break</computeroutput> <command>AT</command>
       method</entry>
      </row>
      <row>
       <entry><command>&percnt;E3</command></entry>
       <entry>Escape method</entry>
       <entry>BOTH methods enabled</entry>
      </row>
      <row>
       <entry><command>&percnt;E4</command></entry>
       <entry>Escape method</entry>
       <entry>Disable <computeroutput>OK</computeroutput> to
       <command>+++</command></entry>
      </row>
      <row>
       <entry><command>&percnt;E5</command></entry>
       <entry>Escape method</entry>
       <entry>Enable <computeroutput>OK</computeroutput> to
       <command>+++</command></entry>
      </row>
      <row>
       <entry><command>\J0</command> or <command>\J</command></entry>
       <entry><acronym>DTE</acronym> Auto Rate Adjustment</entry>
       <entry>Disabled</entry>
      </row>
      <row>
       <entry><command>\J1</command></entry>
       <entry><acronym>DTE</acronym> Auto Rate Adjustment</entry>
       <entry><acronym>DTE</acronym> rate is adjusted to match carrier rate.</entry>
      </row>
      <row>
       <entry><command>\N0</command> or <command>\N</command></entry>
       <entry>Connection type</entry>
       <entry>Normal connection (see below for definitions)</entry>
      </row>
      <row>
       <entry><command>\N1</command></entry>
       <entry>Connection type</entry>
       <entry>Direction connection</entry>
      </row>
      <row>
       <entry><command>\N2</command></entry>
       <entry>Connection type</entry>
       <entry><acronym>MNP</acronym> Auto-reliable connection</entry>
      </row>
      <row>
       <entry><command>\N3</command></entry>
       <entry>Connection type</entry>
       <entry>Auto-reliable connection</entry>
      </row>
      <row>
       <entry><command>\N4</command></entry>
       <entry>Connection type</entry>
       <entry>V.42bis reliable link with phase detection</entry>
      </row>
      <row>
       <entry><command>\N5</command></entry>
       <entry>Connection type</entry>
       <entry>V.42bis auto-reliable link with phase detection</entry>
      </row>     
      <row>
       <entry><command>\N6</command></entry>
       <entry>Connection type</entry>
       <entry>V.42 reliable link with phase detection</entry>
      </row>
        <row>
       <entry><command>\N7</command></entry>
       <entry>Connection type</entry>
       <entry>V.42 auto-reliable link with phase detection</entry>
      </row>
     </tbody>
    </tgroup>
   </table>

<para>A direct connection is a simple straight-through connection without any
error connection or data compression.  In this case, the computer-to-modem and
modem-to-modem speeds must be identical.</para>

<para>A normal connection uses flow control (either software or hardware) to
buffer the data being sent or received, so that the modem can transmit data at a
different rate than the computer is actually sending or receiving it. For
example, a computer may send actual data at 57kbps, but using compression, the
modem only actually sends 28.8kbps. This is the mode use by most modems.</para>

<para>A reliable connection is a type of normal connection; if, for some reason,
data compression or error correction cannot be established or maintained, the
connection will hang up. (In essence, such a modem ensures that all connections
are reliable, for it will hang up if the connection isn't.)</para>

<para>Likewise, an auto-reliable connection is virtually the same, except that
the modem will try to renegotiate the connection in order to establish a
reliable connection. Again, this is the mode that most modems use.</para>

</sect1>

<sect1 id="hayes-sregisters">
<title>S-Registers</title>

   <table>
    <title>S Registers</title>
    <tgroup cols="4">
     <thead>
      <row>
       <entry>Register</entry>
       <entry>Range</entry>
       <entry>Default</entry>
       <entry>Function</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><varname>S0</varname></entry>
       <entry>0-255 rings</entry>
       <entry>1-2</entry>
       <entry>Answer on ring number. Don't answer if 0</entry>
      </row>
      <row>
       <entry><varname>S1</varname></entry>
       <entry>0-255 rings</entry>
       <entry>0</entry>
       <entry>if <varname>S0</varname> is greater than
       <returnvalue>0</returnvalue> this register counts the incoming
       rings.</entry>
      </row>
     <row>
       <entry><varname>S2</varname></entry>
       <entry>0-127 <acronym>ASCII</acronym></entry>
       <entry>43 +</entry>
       <entry>Escape to command mode character</entry>
      </row>
     <row>
       <entry><varname>S2</varname></entry>
       <entry>&gt;127</entry>
       <entry></entry>
       <entry>no ESC</entry>
      </row>
     <row>
       <entry><varname>S3</varname></entry>
       <entry>0-127 <acronym>ASCII</acronym></entry>
       <entry>13 CR</entry>
       <entry>Carriage return character</entry>
      </row>
     <row>
       <entry><varname>S4</varname></entry>
       <entry>0-127 <acronym>ASCII</acronym></entry>
       <entry>10 LF</entry>
       <entry>Line feed character</entry>
      </row>
     <row>
       <entry><varname>S5</varname></entry>
       <entry>0-32, 127 <acronym>ASCII</acronym></entry>
       <entry>8 BS</entry>
       <entry>Backspace character</entry>
      </row>
     <row>
       <entry><varname>S6</varname></entry>
       <entry>2-255 seconds</entry>
       <entry>2</entry>
       <entry>Dial tone wait time (blind dialling, see <link
       linkend="hayes-basic-x1">X<replaceable>n</replaceable></link></entry>
      </row>
     <row>
       <entry><anchor id="hayes-s7"><varname>S7</varname></entry>
       <entry>1-255 seconds</entry>
       <entry>30-60</entry>
       <entry>Wait time for remote carrier</entry>
      </row>
     <row>
       <entry><varname>S8</varname></entry>
       <entry>0-255 seconds</entry>
       <entry>2</entry>
       <entry>Comma pause time used in dialing</entry>
      </row>
     <row>
       <entry><varname>S9</varname></entry>
       <entry>1-255 1/10ths second</entry>
       <entry>6</entry>
       <entry>Carrier detect time required for recognition</entry>
      </row>
     <row>
       <entry><varname>S10</varname></entry>
       <entry>1-255 1/10ths second</entry>
       <entry>7-14</entry>
       <entry>Time between loss of carrier and hangup</entry>
      </row>
     <row>
       <entry><varname>S11</varname></entry>
       <entry>50-255 milliseconds</entry>
       <entry>70-95</entry>
       <entry>Duration and spacing of tones when tone dialing</entry>
      </row>
     <row>
       <entry><varname>S12</varname></entry>
       <entry>0-255 1/50th seconds</entry>
       <entry>50</entry>
       <entry>Guard time for pause around <command>+++</command> command
       sequence</entry>
      </row>
     <row>
       <entry><varname>S36</varname></entry>
       <entry><para>Fallback options when error correction link
       fails:</para><itemizedlist>
	 <listitem><para>0 - Disconnect</para>
	 </listitem>
	 <listitem><para>1 - Establish Direct Connection</para>
	 </listitem>
	 <listitem><para>3 - Establish Normal Connection</para>
	 </listitem>
	 <listitem><para>4 - Establish an <acronym>MNP</acronym> connection if
	 possible, else disconnect</para>
	 </listitem>
	 <listitem><para>5 - Establish an <acronym>MNP</acronym> connection if
	 possible, else Direct Connection.</para>
	 </listitem>
	 <listitem><para>7 - Establish an <acronym>MNP</acronym> connection if
	 possible, else Normal connection</para>
	 </listitem>
	</itemizedlist></entry>       
       <entry>7</entry>
       <entry>Negotiation Failure Treatment</entry>
      </row>
      <row>
       <entry><anchor id="hayes-s37"><varname>S37</varname></entry>
       <entry><itemizedlist>
	 <listitem><para><returnvalue>1</returnvalue> = 300 bps</para>
	 </listitem>
	 <listitem><para><returnvalue>5</returnvalue> = 1200 bps</para>
	 </listitem>
	 <listitem><para><returnvalue>6</returnvalue> = 2400 bps</para>
	 </listitem>
	 <listitem><para><returnvalue>7</returnvalue> = 1200/75 bps (v.23
	 mode)</para>
	 </listitem>
	 <listitem><para><returnvalue>8</returnvalue> = 4800 bps</para>
	 </listitem>
	 <listitem><para><returnvalue>9</returnvalue> = 9600 bps</para>
	 </listitem>
	 <listitem><para><returnvalue>10</returnvalue> = 12000 bps</para>
	 </listitem>
	 <listitem><para><returnvalue>11</returnvalue> = 14400 bps</para>
	 </listitem>
	 <listitem><para><returnvalue>12</returnvalue> = 7200 bps</para>
	 </listitem>
	</itemizedlist></entry>
       <entry>0</entry>
       <entry>Negotiation Speed (Intial handshake)</entry>
      </row>
     </tbody>
    </tgroup>
   </table>

<para>Many modems have dozens, even hundreds, of S registers, but only the first
dozen or so are fairly standard. They are changed with a command like
<command>ATS<replaceable>n</replaceable>=<replaceable>N</replaceable></command>,
and examined with <command>ATS<replaceable>n</replaceable>?</command> (&eg;
<userinput><command>AT</command> <command>S10</command><option>=70</option>
<command>S1?</command></userinput> would tell the modem not to hang up for seven
seconds should it not hear the answering modem, and return the number of times
the phone last rang.)</para>

</sect1>
</appendix>

<appendix id="appendix-accounting-template">
<title>An example template for Telephone cost accounting.</title>

<para>If you can't find a rule for your region you will have to write one by
following the following template. Don't be afraid though it is really
easy.</para>

<para>Don't forget to submit your newly created rules file to &kppp;'s
maintainer. The newly created rules file can be checked for valid syntax with
the <userinput><option>-r</option>
<replaceable>rule_file</replaceable></userinput> command line option to 6kppp;
and must be installed in <filename
class="directory">${KDEDIR}/share/apps/kppp/Rules</filename> or in <filename
class="directory">${HOME}/.kde/share/apps/kppp/Rules</filename> before you will
be able to select it in this dialog.</para>

<programlisting>
################################################################
#
# Disclaimer/License
# This Template ist (c) by Mario Weilguni &lt;mweilguni@kde.org&gt;
# It ist licenced under the same terms as the kppp package, 
# which it is part of
#
################################################################
#
# This is a sample rule set for kppp. You can use it as a 
# template when you have to create your own ruleset. If you do
# so, remove all comments and add your own. This will allow
# other users to check your ruleset more easily.
# 
# Please sign the the tarif file with your name an email address
# so that I can contact you if necessary.
#
# NOTE: the rules in this rule set do not make much sense and
#       are only for demonstration purposes
#
# NOTE ON FILENAMES:
#	when you create your own ruleset, use "_" in filename
#	instead of spaces and use ".rst  as extension
#	   i.e. "Austria city calls"
#          --> file should be saved as "Austria_city_calls.rst"
#
# Thanks, Bernd Wuebben
# wuebben@math.cornell.edu / wuebben@kde.org
################################################################


################################################################
#
# NAME OF THE RULESET. This is NEEDED for accounting purposes.
#
################################################################
name=default

################################################################
# currency settings
################################################################

# defines ATS (Austrian Schilling) to be used as currency
# symbol (not absolutely needed, default = "$")
currency_symbol=ATS

# Define the position of the currency symbol.
# (not absolutely needed, default is "right")
currency_position=right 

# Define the number of significant digits.
# (not absolutely needed, default is "2"
currency_digits=2



################################################################
# connection settings
################################################################

# NOTE: rules are applied from top to bottom - the
#       LAST matching rule is the one used for the
#       cost computations.

# This is charged whenever you connect. If you don't have to
# pay per-connection, use "0" here or comment it out.
per_connection=0.0


# minimum costs per per connection. If the costs of a phone
# call are less than this value, this value is used instead
minimum_costs=0.0


# You pay .74 for the first 180 seconds ( 3 minutes) no matter
# whether you are connected for 1 second or 180 seconds.
# This rule will take priority during the first 180 seconds
# over any other rule, in particular the 'default' rule.
# have a look at costgraphs.gif in the docs directory
# of the kppp distribution for a graphic illustration.
flat_init_costs=(0.74,180)

# This is the default rule which is used when no other rule
# applies. The first component "0.1" is the price of one
# "unit", while "72" is the duration in seconds.
# Therefore the following rule means: "Every 72 seconds 0.1 
# ATS are added to the bill"
default=(0.1, 72)

#
# more complicated rules:
#

# "on monday until sunday from 12:00 am until 11:59 pm the costs
# are 0.2 each 72 seconds"
on () between () use (0.2, 2)

# same as above
on (monday..sunday) between () use (0.2, 2)

# same as above. You must use 24 hour notation, or the accounting
# will not work correctly. (Example: write 15:00 for 3 pm)
on (monday..sunday) between (0:00..23:59) use (0.2, 2)

# applies on friday, saturday, sunday and monday 8am until 1pm
on (friday..monday) between (8:00..13:00) use(0.3,72)

# ATTENTION:
on(monday..friday) between (21:00..5:00) use (0.4,2)
# does NOT include saturday 0:00-5:00, just monday..friday, as it says.

# applies on a given date (christmas)
on (12/25) between () use (0.3,72)

# a range of dates and one weekday
on (12/25..12/27, 12/31, 07/04, monday) between () use (0.4, 72)

# use this for easter
on (easter) between () use (0.3,72)

# easter + 50 days (Pfingstmontag/ Pentecost Monday )
on (easter+50) between () use (0.3,72)

on (thursday) between (20:00..21:52) use (8.2, 1)


# The "on()" rules above all relates to current time only. You can also
# make a rule depend on the number of seconds you have been connected
# by specifying this time as a third argument to "use()".
# For instance, let's say normal rate in the evening is 0.20 per minute,
# and it drops by 20% after one hour of connect time. This can be modelled
# like:

on () between (19:30..08:00) use (0.20, 60)
on () between (19:30..08:00) use (0.16, 60, 3600)

# Note that these rules, just like other rules, are sensitive to the 
# order in which they appear.
</programlisting>

</appendix>


&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
End:
-->
