diff options
| author | toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da> | 2009-11-25 17:56:58 +0000 |
|---|---|---|
| committer | toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da> | 2009-11-25 17:56:58 +0000 |
| commit | bcb704366cb5e333a626c18c308c7e0448a8e69f (patch) | |
| tree | f0d6ab7d78ecdd9207cf46536376b44b91a1ca71 /doc/kppp | |
| download | tdenetwork-bcb704366cb5e333a626c18c308c7e0448a8e69f.tar.gz tdenetwork-bcb704366cb5e333a626c18c308c7e0448a8e69f.zip | |
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923
git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdenetwork@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'doc/kppp')
31 files changed, 4038 insertions, 0 deletions
diff --git a/doc/kppp/Makefile.am b/doc/kppp/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/kppp/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kppp/accounting.docbook b/doc/kppp/accounting.docbook new file mode 100644 index 00000000..ec6db43c --- /dev/null +++ b/doc/kppp/accounting.docbook @@ -0,0 +1,158 @@ +<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 &kppp; +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 <mweilguni@kde.org> +# It ist licensed 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> diff --git a/doc/kppp/callback.docbook b/doc/kppp/callback.docbook new file mode 100644 index 00000000..93f79238 --- /dev/null +++ b/doc/kppp/callback.docbook @@ -0,0 +1,268 @@ +<chapter id="callback"> +<title>Configuring &kppp; for callback</title> + +<para>This chapter is based on material provided by Martin Hä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&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&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&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 dialog, 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 > <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, ⪚ 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> diff --git a/doc/kppp/chap.docbook b/doc/kppp/chap.docbook new file mode 100644 index 00000000..ebbdd3b9 --- /dev/null +++ b/doc/kppp/chap.docbook @@ -0,0 +1,191 @@ +<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>˜/.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>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> diff --git a/doc/kppp/costsgraphs.fig b/doc/kppp/costsgraphs.fig new file mode 100644 index 00000000..0c1f5d66 --- /dev/null +++ b/doc/kppp/costsgraphs.fig @@ -0,0 +1,55 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +0 +1200 2 +2 2 0 1 0 7 0 0 -1 0.000 0 0 -1 0 0 2 + 900 900 900 900 +2 2 0 1 0 7 0 0 -1 4.000 0 0 -1 0 0 5 + 900 900 6000 900 6000 3900 900 3900 900 900 +2 1 0 1 0 7 0 0 -1 4.000 0 0 -1 0 0 2 + 900 2700 2400 2700 +2 1 1 1 0 7 0 0 -1 4.000 0 0 -1 0 0 2 + 900 3900 2400 2700 +2 1 0 1 0 7 0 0 -1 4.000 0 0 -1 0 0 2 + 2400 2700 4800 900 +2 2 0 1 0 7 0 0 -1 4.000 0 0 -1 0 0 5 + 900 4500 6000 4500 6000 7500 900 7500 900 4500 +2 1 0 1 0 7 0 0 -1 4.000 0 0 -1 0 0 2 + 900 6300 2700 4500 +2 2 0 1 0 7 0 0 -1 4.000 0 0 -1 0 0 5 + 6900 900 12000 900 12000 3900 6900 3900 6900 900 +2 1 0 1 0 7 0 0 -1 4.000 0 0 -1 0 0 3 + 6900 3000 9600 3000 10800 900 +2 1 1 1 0 7 0 0 -1 4.000 0 0 -1 0 0 2 + 9600 3000 9075 3900 +2 1 0 1 0 7 0 0 -1 0.000 0 0 -1 0 1 2 + 2 1 1.00 60.00 120.00 + 9150 4050 9675 4275 +4 0 0 0 0 0 12 0.0000 4 180 4740 7125 5475 These graphs illustrate, why the new keyword 'flat_init_costs'\001 +4 0 0 0 0 0 12 0.0000 4 180 4830 7125 6150 minimum_cost and pre_connection alone. The situation depicted\001 +4 0 0 0 0 0 12 0.0000 4 180 165 750 525 a)\001 +4 0 0 0 0 0 12 0.0000 4 180 165 6975 600 c)\001 +4 0 0 0 0 0 12 0.0000 4 180 165 600 4350 b)\001 +4 0 0 0 0 0 12 0.0000 4 180 2055 8625 4500 Note: This is not the origin!\001 +4 0 0 0 0 0 12 0.0000 4 135 330 11400 4200 time\001 +4 0 0 0 0 0 12 0.0000 4 135 330 5325 4125 time\001 +4 0 0 0 0 0 12 0.0000 4 135 330 5475 7725 time\001 +4 0 0 0 0 0 12 0.0000 4 105 330 6300 975 cost\001 +4 0 0 0 0 0 12 0.0000 4 105 330 300 975 cost\001 +4 0 0 0 0 0 12 0.0000 4 105 330 300 4650 cost\001 +4 0 0 0 0 0 12 0.0000 4 135 1215 10650 7500 Bernd Wuebben\001 +4 0 0 0 0 0 12 0.0000 4 180 1395 10650 7725 wuebben@kde.org\001 +4 0 0 0 0 0 12 0.0000 4 180 4875 7125 6675 c) could also not be generated with 'rules' since rules depend on\001 +4 0 0 0 0 0 12 0.0000 4 180 4860 7125 6900 'absolut times 'such as '3:00pm', not on 'relative times' such as\001 +4 0 0 0 0 0 12 0.0000 4 180 2925 7125 7125 'the first 3 minutes' during connection.\001 +4 0 0 0 0 0 12 0.0000 4 180 1560 2550 675 minimum_cost graph\001 +4 0 0 0 0 0 12 0.0000 4 180 1620 2775 4275 per_connection graph\001 +4 0 0 0 0 0 12 0.0000 4 180 1560 8850 675 flat_init_costs graph\001 +4 0 0 0 0 0 12 0.0000 4 180 4920 7125 5700 was necessry. A cost graph such as the one show above, labeled\001 +4 0 0 0 0 0 12 0.0000 4 180 4425 7125 5925 'flat_init_cost graph' could not be generated with the rules\001 +4 0 0 0 0 0 12 0.0000 4 180 4455 7125 6375 in the graph c) above is the one encounted in France today.\001 diff --git a/doc/kppp/costsgraphs.png b/doc/kppp/costsgraphs.png Binary files differnew file mode 100644 index 00000000..2e5d88fd --- /dev/null +++ b/doc/kppp/costsgraphs.png diff --git a/doc/kppp/dialog-setup.docbook b/doc/kppp/dialog-setup.docbook new file mode 100644 index 00000000..ce76ac49 --- /dev/null +++ b/doc/kppp/dialog-setup.docbook @@ -0,0 +1,765 @@ +<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 +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>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 (⪚ +<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, ⪚ +<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 +dialing 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 dialing 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 accounting?</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> diff --git a/doc/kppp/getting-online.docbook b/doc/kppp/getting-online.docbook new file mode 100644 index 00000000..97d2ba66 --- /dev/null +++ b/doc/kppp/getting-online.docbook @@ -0,0 +1,52 @@ +<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> diff --git a/doc/kppp/global-settings.docbook b/doc/kppp/global-settings.docbook new file mode 100644 index 00000000..a11cc8d4 --- /dev/null +++ b/doc/kppp/global-settings.docbook @@ -0,0 +1,385 @@ +<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 received 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>/dev/ttys0</filename></term> +<listitem> +<para>DOS or &Windows; users will know this as COM1, while COM2 is +<filename>/dev/ttys1</filename> and so on. These devices are +the ones normally used on &Linux; systems.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><filename>/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>/dev/ttyS<replaceable>x</replaceable></filename>.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><filename>/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>/dev/ttyI0</filename> is for the first, +<filename>/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 folder 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 redialing, 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 experiencing 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 initializing 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 colors 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>The version number of the pppd daemon on your system.</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>If enabled, &kppp; will exit when you disconnect from the internet. If disabled, &kppp; will stay open after disconnection.</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> diff --git a/doc/kppp/hayes.docbook b/doc/kppp/hayes.docbook new file mode 100644 index 00000000..a8f6db7f --- /dev/null +++ b/doc/kppp/hayes.docbook @@ -0,0 +1,927 @@ +<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>&</quote> (ampersand) and a capital character +followed by a digit. This is an extension of the basic command set. For example, +<command>&M1</command>. Note that <command>M1</command> is different from +<command>&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>%</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 characters 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 originate + 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 (⪚ + <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 (⪚ + <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 (⪚ + <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>&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>&B0</command> or <command>&B</command></entry> + <entry>Retrain Parameters</entry> + <entry>Disable auto retrain function</entry> + </row> + <row> + <entry><command>&B1</command></entry> + <entry>Retrain Parameters</entry> + <entry>Enable auto retrain function</entry> + </row> + <row> + <entry><command>&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>&C0</command> or <command>&C1</command></entry> + <entry>Carrier detect</entry> + <entry>Signal always on</entry> + </row> + <row> + <entry><command>&C1</command></entry> + <entry>Carrier detect</entry> + <entry>Indicates remote carrier (usual preferred default)</entry> + </row> + <row> + <entry><command>&D0</command> or <command>&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>&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>&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>&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>&F0</command> or <command>&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>&F1</command>-<command>&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>&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>&F2</command> or the like. However, if you're building an + init string, it's best to start with a simple <command>&F</command>, + and not use the <quote>customized</quote> form of + defaults.</para></entry> + </row> + <row> + <entry><command>&F1</command></entry> + <entry>Factory Defaults</entry> + <entry>Factory Defaults tailored to an IBM <acronym>PC</acronym> + compatible user</entry> + </row> + <row> + <entry><command>&F2</command></entry> + <entry>Factory Defaults</entry> + <entry>Factory defaults for a Mac w/software handshaking</entry> + </row> + <row> + <entry><command>&F3</command></entry> + <entry>Factory Defaults</entry> + <entry>Factory defaults for a Mac w/hardware handshaking</entry> + </row> + <row> + <entry><command>&G0</command> or <command>&G</command></entry> + <entry>Guard tones</entry> + <entry>Disable guard tones</entry> + </row> + <row> + <entry><command>&K0</command> or <command>&K</command></entry> + <entry>Local flow control</entry> + <entry>Disable local flow control</entry> + </row> + <row> + <entry><command>&K1</command></entry> + <entry>Local flow control</entry> + <entry>Enable RTS/CTS hardware local flow control</entry> + </row> + <row> + <entry><command>&K2</command></entry> + <entry>Local flow control</entry> + <entry>Enable XON/XOFF software local flow control</entry> + </row> + <row> + <entry><command>&K3</command></entry> + <entry>Local flow control</entry> + <entry>Enable RTS/CTS hardware local flow control</entry> + </row> + <row> + <entry><command>&K4</command></entry> + <entry>Local flow control</entry> + <entry>Enable XON/XOFF software local flow control</entry> + </row> + <row> + <entry><command>&L0</command> or <command>&L</command></entry> + <entry>Dial mode</entry> + <entry>Select dial-up mode</entry> + </row> + <row> + <entry><command>&M0</command> or <command>&M</command></entry> + <entry>Error control mode</entry> + <entry>Select asynchronous non-<acronym>EC</acronym> mode (the same as + <command>&Q0</command>)</entry> + </row> + <row> + <entry><command>&P0</command> or <command>&P</command></entry> + <entry>Pulse dialing ratio</entry> + <entry>U.S./Canada pulse dialing 39% make / 61% break ratio</entry> + </row> + <row> + <entry><command>&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>&Q0</command> or <command>&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>&Q5</command></entry> + <entry>Error control mode</entry> + <entry>Select V.42 <acronym>EC</acronym> operation (requires flow + control)</entry> + </row> + <row> + <entry><command>&Q6</command></entry> + <entry>Error control mode</entry> + <entry>Asynchronous mode with <acronym>ASB</acronym> (requires flow + control)</entry> + </row> + <row> + <entry><command>&Q8</command></entry> + <entry>Error control mode</entry> + <entry>Select alternate <acronym>EC</acronym> protocol + (<acronym>MNP</acronym>)</entry> + </row> + <row> + <entry><command>&Q9</command></entry> + <entry>Error control mode</entry> + <entry>Conditional data compression: V.42bis = yes, MNP5 = no.</entry> + </row> + <row> + <entry><command>&S0</command> or <command>&S</command></entry> + <entry><acronym>DSR</acronym> action select</entry> + <entry>Always on (default)</entry> + </row> + <row> + <entry><command>&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>&T0</command> or <command>&T</command></entry> + <entry>Self test</entry> + <entry>Model specific self test on some modems</entry> + </row> + <row> + <entry><command>&U0</command> or <command>&U</command></entry> + <entry>Trellis code modulation</entry> + <entry>Enable V.32 <acronym>TCM</acronym></entry> + </row> + <row> + <entry><command>&U1</command></entry> + <entry>Trellis code modulation</entry> + <entry>Disable V.32 <acronym>TCM</acronym></entry> + </row> + <row> + <entry><command>&V0</command> or <command>&V1</command></entry> + <entry>View active</entry> + <entry>(and often stored) configuration profile settings (or + <command>ATI4</command></entry> + </row> + <row> + <entry><command>&W0</command> or <command>&W</command></entry> + <entry>Store profile</entry> + <entry>In <acronym>NVRAM</acronym> (<command>&W0</command>, + <command>&W1</command> etc. for multiple profiles) Some settings + cannot be stored. These often don't show on <command>&V</command> or + <command>ATI4</command></entry> + </row> + <row> + <entry><command>&Y0</command> or <command>&Y</command></entry> + <entry>Select configuration loaded at power-up</entry> + <entry>Load profile 0 (default)</entry> + </row> + <row> + <entry><command>&Y1</command></entry> + <entry>Select configuration loaded at power-up</entry> + <entry>Load profile 1</entry> + </row> + <row> + <entry><command>&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>&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>%C0</command> or + <command>%C</command></entry> + <entry>Data Compression Enable/Disable</entry> + <entry>Disabled</entry> + </row> + <row> + <entry><command>%C1</command></entry> + <entry>Data Compression Enable/Disable</entry> + <entry>MNP5 enabled</entry> + </row> + <row> + <entry><command>%C2</command></entry> + <entry>Data Compression Enable/Disable</entry> + <entry>V.42bis (<acronym>BTLZ</acronym>) Enabled</entry> + </row> + <row> + <entry><command>%C3</command></entry> + <entry>Data Compression Enable/Disable</entry> + <entry>MNP5 & V.42bis (<acronym>BTLZ</acronym>) Enabled</entry> + </row> + <row> + <entry><command>%D0</command> or + <command>%D</command></entry> + <entry>Data compression</entry> + <entry>512 BLTZ dictionary size</entry> + </row> + <row> + <entry><command>%D1</command></entry> + <entry>Data compression</entry> + <entry>1024 BLTZ dictionary size</entry> + </row> + <row> + <entry><command>%D2</command></entry> + <entry>Data compression</entry> + <entry>2048 BLTZ dictionary size</entry> + </row> + <row> + <entry><command>%D3</command></entry> + <entry>Data compression</entry> + <entry>4096 BLTZ dictionary size</entry> + </row> + <row> + <entry><command>%E0</command> or + <command>%E1</command></entry> + <entry>Escape method</entry> + <entry>ESCAPE DISABLED</entry> + </row> + <row> + <entry><command>%E1</command></entry> + <entry>Escape method</entry> + <entry><command>+++AT</command> method (default)</entry> + </row> + <row> + <entry><command>%E2</command></entry> + <entry>Escape method</entry> + <entry><computeroutput>Break</computeroutput> <command>AT</command> + method</entry> + </row> + <row> + <entry><command>%E3</command></entry> + <entry>Escape method</entry> + <entry>BOTH methods enabled</entry> + </row> + <row> + <entry><command>%E4</command></entry> + <entry>Escape method</entry> + <entry>Disable <computeroutput>OK</computeroutput> to + <command>+++</command></entry> + </row> + <row> + <entry><command>%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>>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 dialing, 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 (Initial 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> (⪚ +<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> diff --git a/doc/kppp/index.docbook b/doc/kppp/index.docbook new file mode 100644 index 00000000..ea172828 --- /dev/null +++ b/doc/kppp/index.docbook @@ -0,0 +1,268 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&kppp;"> + <!ENTITY package "kdenetwork"> + <!ENTITY getting-online SYSTEM "getting-online.docbook"> + <!ENTITY wizard SYSTEM "wizard.docbook"> + <!ENTITY dialog-setup SYSTEM "dialog-setup.docbook"> + <!ENTITY global-settings SYSTEM "global-settings.docbook"> + <!ENTITY security SYSTEM "security.docbook"> + <!ENTITY chap-and-pap SYSTEM "chap.docbook"> + <!ENTITY tricks SYSTEM "tricks.docbook"> + <!ENTITY callback SYSTEM "callback.docbook"> + <!ENTITY kppp-faq SYSTEM "kppp-faq.docbook"> + <!ENTITY hayes-reference SYSTEM "hayes.docbook"> + <!ENTITY accounting SYSTEM "accounting.docbook"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kppp; Handbook</title> + +<authorgroup> +<author> +<firstname>Lauri</firstname> +<surname>Watts</surname> +<affiliation> +<address><email>lauri@kde.org</email></address> +</affiliation> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2001</year> +<holder>Lauri Watts</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2001-06-11</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>dialer</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 dialer, and that it eases your way onto the +internet.</para> + +</chapter> + +&getting-online; + +&wizard; + +&dialog-setup; + +&global-settings; + +&security; + +&chap-and-pap; + +&tricks; + +&callback; + +&kppp-faq; + +<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ä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>lauri@kde.org</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> + +&install.intro.documentation; + +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +&install.compile.documentation; + +</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 dialing) +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 command 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>to be written</para> +</sect2> --> + +</sect1> + +</appendix> + +&hayes-reference; + +&accounting; + +&documentation.index; +</book> +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +End: +--> + diff --git a/doc/kppp/kppp-account-accounting-tab.png b/doc/kppp/kppp-account-accounting-tab.png Binary files differnew file mode 100644 index 00000000..a0c4321d --- /dev/null +++ b/doc/kppp/kppp-account-accounting-tab.png diff --git a/doc/kppp/kppp-account-dial-tab.png b/doc/kppp/kppp-account-dial-tab.png Binary files differnew file mode 100644 index 00000000..2c0dc3ae --- /dev/null +++ b/doc/kppp/kppp-account-dial-tab.png diff --git a/doc/kppp/kppp-account-dns-tab.png b/doc/kppp/kppp-account-dns-tab.png Binary files differnew file mode 100644 index 00000000..b6215c2f --- /dev/null +++ b/doc/kppp/kppp-account-dns-tab.png diff --git a/doc/kppp/kppp-account-execute-tab.png b/doc/kppp/kppp-account-execute-tab.png Binary files differnew file mode 100644 index 00000000..ef0e5ed1 --- /dev/null +++ b/doc/kppp/kppp-account-execute-tab.png diff --git a/doc/kppp/kppp-account-gateway-tab.png b/doc/kppp/kppp-account-gateway-tab.png Binary files differnew file mode 100644 index 00000000..cebf1f5a --- /dev/null +++ b/doc/kppp/kppp-account-gateway-tab.png diff --git a/doc/kppp/kppp-account-ip-tab.png b/doc/kppp/kppp-account-ip-tab.png Binary files differnew file mode 100644 index 00000000..ccc9b7db --- /dev/null +++ b/doc/kppp/kppp-account-ip-tab.png diff --git a/doc/kppp/kppp-account-login-script-tab.png b/doc/kppp/kppp-account-login-script-tab.png Binary files differnew file mode 100644 index 00000000..293cfb2f --- /dev/null +++ b/doc/kppp/kppp-account-login-script-tab.png diff --git a/doc/kppp/kppp-config.png b/doc/kppp/kppp-config.png Binary files differnew file mode 100644 index 00000000..d9a5000d --- /dev/null +++ b/doc/kppp/kppp-config.png diff --git a/doc/kppp/kppp-device-tab.png b/doc/kppp/kppp-device-tab.png Binary files differnew file mode 100644 index 00000000..3d3b5257 --- /dev/null +++ b/doc/kppp/kppp-device-tab.png diff --git a/doc/kppp/kppp-dialler-tab.png b/doc/kppp/kppp-dialler-tab.png Binary files differnew file mode 100644 index 00000000..7dea2838 --- /dev/null +++ b/doc/kppp/kppp-dialler-tab.png diff --git a/doc/kppp/kppp-faq.docbook b/doc/kppp/kppp-faq.docbook new file mode 100644 index 00000000..57ef26ff --- /dev/null +++ b/doc/kppp/kppp-faq.docbook @@ -0,0 +1,477 @@ +<chapter id="faq"> +<title>Questions and Answers</title> + +&reporting.bugs; + +<qandaset id="faqlist"> + +<qandadiv id="faq-dialing"> +<title>Questions about Dialing</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>root</systemitem>. You may set this mode by issuing +<userinput><command>chmod</command> <option>u+s pppd</option></userinput> as +<systemitem>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>˜/.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>root</systemitem>. The proper way to proceed would +probably be creating a <systemitem>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>pppd died - The remote system is required to authenticate itself ...</para></question> + +<answer> +<para>Typical error message in system log:</para> +<screen> +pppd[699]: The remote system is required to authenticate itself +pppd[699]: but I couldn't find any suitable secret (password) for it to use to do so. +pppd[699]: (None of the available passwords would let it use an IP address.) +</screen> +<para>As far as I can tell there are two causes for this problem: </para> +<itemizedlist> +<listitem><para><filename>/etc/ppp/options</filename> contains the +<option>auth</option> option. Simply put a <prompt>#</prompt> comment in +front and try again. </para></listitem> <listitem><para>Your system already +has a default route. Have you set up a local network? In this case recent +versions of pppd will behave as if <option>auth</option> had been +specified. To override this you may add <option>noauth</option> to the pppd +arguments in kppp' setup dialog. Alternatively you could take down the local +network prior to dialing in. I'd be thankful if someone could provide +instructions on how to peacefully combine the two network +connections. </para></listitem> +</itemizedlist> +</answer> +</qandaentry> + +<qandaentry> +<question><para>pppd dies with 2.4.x Linux kernel</para></question> +<answer> +<para>Typical error messages in the system log:</para> + +<screen> +pppd[1182]: pppd 2.3.11 started by user, uid 500 +pppd[1182]: ioctl(PPPIOCGFLAGS): Invalid argument +pppd[1182]: tcsetattr: Invalid argument +pppd[1182]: Exit. +</screen> +<para>Install pppd 2.4.0b1 or better. See +<filename>Documentation/Changes</filename> in the kernel sources for more +info.</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>Why does &kppp; tell me <errorname>Unable to 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>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>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 $KDEDIR/bin/kppp</option></userinput> +<prompt>#</prompt> <userinput><command>chmod</command> <option>+s $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 folder 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>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 +initialization. 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 authorizations. 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, +⪚ <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 permission to the +folder (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 +dialing?</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 dialing. +Why?</para></question> + +<answer><para>The volume initialization 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 dialing instead of tone dialing (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 dialing</action></para></listitem> +</varlistentry> +<varlistentry> +<term><command>ATDP</command></term> +<listitem><para><action>Selects pulse dialing</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> diff --git a/doc/kppp/kppp-graph-tab.png b/doc/kppp/kppp-graph-tab.png Binary files differnew file mode 100644 index 00000000..0597810a --- /dev/null +++ b/doc/kppp/kppp-graph-tab.png diff --git a/doc/kppp/kppp-misc-tab.png b/doc/kppp/kppp-misc-tab.png Binary files differnew file mode 100644 index 00000000..b8bc0840 --- /dev/null +++ b/doc/kppp/kppp-misc-tab.png diff --git a/doc/kppp/kppp-modem-tab.png b/doc/kppp/kppp-modem-tab.png Binary files differnew file mode 100644 index 00000000..58534642 --- /dev/null +++ b/doc/kppp/kppp-modem-tab.png diff --git a/doc/kppp/kppp-wizard.png b/doc/kppp/kppp-wizard.png Binary files differnew file mode 100644 index 00000000..e648d413 --- /dev/null +++ b/doc/kppp/kppp-wizard.png diff --git a/doc/kppp/kppp.faq.question b/doc/kppp/kppp.faq.question new file mode 100644 index 00000000..e4800ab0 --- /dev/null +++ b/doc/kppp/kppp.faq.question @@ -0,0 +1,54 @@ +X-RDate: Fri, 12 Dec 1997 19:59:12 -0500 (EST) +X-UIDL: 26006 +Return-Path: <tuhlmann@debis.com> +Received: from cornell.edu (cornell.edu [132.236.56.6]) by + postoffice2.mail.cornell.edu (8.8.5/8.8.5) with ESMTP id BAA01394 for + <bw18@POSTOFFICE2.MAIL.CORNELL.EDU>; Fri, 12 Dec 1997 01:06:00 -0500 (EST) +Received: (from daemon@localhost) by cornell.edu (8.8.5/8.8.5) id BAA05503 for + bw18@postoffice3.mail.cornell.edu; Fri, 12 Dec 1997 01:06:00 -0500 (EST) +Received: from polygon.math.cornell.edu (POLYGON.MATH.CORNELL.EDU + [128.84.234.110]) by cornell.edu (8.8.5/8.8.5) with SMTP id BAA05461 for + <bw18@cornell.edu>; Fri, 12 Dec 1997 01:05:58 -0500 (EST) +Received: from sun03.berlin2.debis-sfi.de (proxy.debis-sfi.de) by + polygon.math.cornell.edu (5.x/SMI-SVR4) id AA14318; + Fri, 12 Dec 1997 01:05:52 -0500 +Received: from merlin.debis-sfi.de(138.201.4.1) by sun03 via smap (V2.0) id + xma001088; Fri, 12 Dec 97 07:04:21 +0100 +Received: by b1.debis.com id HAA28426; Fri, 12 Dec 1997 07:05:37 +0100 +Received: by c1.debis.com id HAA16797; Fri, 12 Dec 1997 07:05:39 +0100 (MET) +Message-Id: <199712120605.HAA16797-c1@debis.com> +X-PH: V4.1@cornell.edu (Cornell Modified) +Date: Fri, 12 Dec 97 07:04:48 +0100 +Reply-To: "Torsten Uhlmann" <tuhlmann@debis.com> +X-Mailer: debis Systemhaus's Registered PMMail 1.9 For OS/2 +Mime-Version: 1.0 +Content-Type: text/plain; charset="iso-8859-1" +Content-Transfer-Encoding: 7bit +XFMstatus: 0002 +From: Torsten Uhlmann <tuhlmann@debis.com> +To: Bernd Johannes Wuebben <wuebben@math.cornell.edu> +Subject: RE: kppp + +On Wed, 10 Dec 1997 14:07:24 -0500 (EST), Bernd Johannes Wuebben wrote: + +> +>Hello Torsten, +> +>On 10-Dec-97 Torsten Uhlmann wrote: +>> I've got a problem using kppp (I think it's the latest version, I got it +>> recently from your project page). I use S.u.S.E. Linux 5.0 and KDE +>> beta 2. +>> +> +>OK this is a problem with you pppd options and PAP configuration. +>However lots of Germans are using kppp and I imagine that if you +>were to post your question to kde@kde.org and kde-user@kde.org +>someone will be able to help you. Let me know... +> +>Bernd +> + +I figured it out. The problem was I handed over USER "LOGIN" as it has to be in ppp-up. +(At T-Online LOGIN is <Number><Tel-No>#<Number> which has to be quoted in order +to not be substituted by any shell. Well between kppp and pppd there is probably no shell, +so the quotes are obsolete :-) diff --git a/doc/kppp/security.docbook b/doc/kppp/security.docbook new file mode 100644 index 00000000..d3012f8b --- /dev/null +++ b/doc/kppp/security.docbook @@ -0,0 +1,96 @@ +<chapter id="security"> +<title>&kppp; and security issues</title> + +<para>This section is mainly for superusers (<systemitem>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>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>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>fred</systemitem>, +<systemitem>karl</systemitem> and <systemitem>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 dialer 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> operations +(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>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> diff --git a/doc/kppp/tricks.docbook b/doc/kppp/tricks.docbook new file mode 100644 index 00000000..c2abc3bf --- /dev/null +++ b/doc/kppp/tricks.docbook @@ -0,0 +1,175 @@ +<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&V</command> can be used to +view them all. The default profile is usually 0 (this can be changed via +<command>AT&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&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&F&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&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&V</command>, and you can see among the displayed +settings for the active profile a <command>&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&D2</command></userinput> <lineannotation># Set to hang up on DTR drop</lineannotation> +<userinput><command>AT&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&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&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-dialing-speedup"> +<title>Make Tone dialing faster</title> + +<para>If you can use tone dialing, 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 dialing. 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 dialing, use a higher number if it doesn't work</lineannotation> +<userinput><command>AT&W</command></userinput> <lineannotation># write to default profile</lineannotation> +</screen> + +</sect1> +</chapter> diff --git a/doc/kppp/ttyS-cua.txt b/doc/kppp/ttyS-cua.txt new file mode 100644 index 00000000..2369fd5e --- /dev/null +++ b/doc/kppp/ttyS-cua.txt @@ -0,0 +1,46 @@ +From: "Theodore Y. Ts'o" <tytso@mit.edu> +To: Tony Nugent <tonyn@sctnugen.ppp.gu.edu.au> +Cc: linux-net@vger.rutgers.edu, linux-ppp@vger.rutgers.edu +Subject: Re: /dev/cua? Vs /dev/ttyS? (was: Re: co-existence of pppd and mgetty ?) +Date: Mon, 13 May 1996 19:51:04 +0200 +Status: ROr + + Date: Mon, 13 May 1996 07:57:09 +1000 + From: Tony Nugent <tonyn@sctnugen.ppp.gu.edu.au> + + Can someone kindly explain the difference between the /dev/cua? and + /dev/ttyS? devices? + +/dev/ttySxx devices are fully POSIX-compliant TTY devices. If you are +only going to be using one set of tty devices, you should be using +/dev/ttySxx. + +/dev/cuaXX devices are different from /dev/ttySXX in two ways --- first +of all, they will allow you to open the device even if CLOCAL is not set +and the O_NONBLOCK flag was not given to the open device. This allows +programs that don't use the POSIX-mondated interface for opening +/dev/ttySxx devices to be able to use /dev/cuaXX to make outgoing phone +calls on their modem (cu stands for "callout", and is taken from SunOS). + +The second way in which /dev/cuaXX differs from /dev/ttySXX is that if +they are used, they will trigger a simplistic kernel-based locking +scheme: If /dev/ttySXX is opened by one or more processes, then an +attempt to open /dev/cuaXX will return EAGAIN. If /dev/cuaXX is opened +by one or more processes, then an attempt to open /dev/ttySXX will +result the open blocking until /dev/cuaXX is closed, and the carrier +detect line goes high. + +While this will allow for simple lockouts between a user using a modem +for callout and a getty listening on the line for logins, it doesn't +work if you need to arbitrate between multiple programs wanting to do +dialout --- for example, users wanting to do dialout and UUCP. + +I originally implemented the cuaXX/ttySXX lockout mechanism back before +FSSTND established a standard convention for the use of tty lock files. +Now that it's there, people should use the tty lock files and not try +using /dev/cuaXX. The only reason why /dev/cuaXX hasn't disappeared yet +is for backwards compatibility reasons. + + - Ted + + diff --git a/doc/kppp/wizard.docbook b/doc/kppp/wizard.docbook new file mode 100644 index 00000000..6f26e711 --- /dev/null +++ b/doc/kppp/wizard.docbook @@ -0,0 +1,117 @@ +<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 +dialer 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> |
