and found a bunch of the older DocBook docs in the output directory
|
@ -0,0 +1,882 @@
|
|||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
|
||||
<article>
|
||||
|
||||
<artheader>
|
||||
<title>BTinternet pppd mini-HOWTO</title>
|
||||
|
||||
<author>
|
||||
<firstname>Matt</firstname>
|
||||
<surname>Wright</surname>
|
||||
<affiliation>
|
||||
<orgname><ulink url="http://www.consultmatt.co.uk">Matt Wright Consulting</ulink></orgname>
|
||||
<address>
|
||||
<email>matt@consultmatt.co.uk</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<othercredit role="converter">
|
||||
<firstname>Greg</firstname>
|
||||
<surname>Ferguson</surname>
|
||||
<contrib>Converted the mini-HOWTO from HTML to Docbook 3.1 (SGML).</contrib>
|
||||
</othercredit>
|
||||
|
||||
<pubdate>2002-03-26</pubdate>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>v0.29</revnumber>
|
||||
<date>2002-03-26</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Added a small bit of first-hand tech support about
|
||||
cross-talk. Thanks goto Bill Staehle once again for typing,
|
||||
technical and grammar points.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.28</revnumber>
|
||||
<date>2002-01-17</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
New information about PPPoATM involving kernels and
|
||||
distibutions.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.27</revnumber>
|
||||
<date>2001-12-20</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Minor technical problems highlighted by Robert Smith.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.26</revnumber>
|
||||
<date>2001-11-21</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Added a point about the Kernel HOWTO.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.25</revnumber>
|
||||
<date>2001-11-17</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Added a troubleshooting answer about "_mmx_memcpy". Other minor updates as well.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.24</revnumber>
|
||||
<date>2001-11-09</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Technical detail with the chatscript timeout (and found a spelling mistake or two!). Thanks again to Bill Staehle.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.23</revnumber>
|
||||
<date>2001-11-07</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Changed the Chatscript dialing method, thanks go to TonyC from btinternet.linux newsgroup.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.22</revnumber>
|
||||
<date>2001-11-06</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Changed a couple more little botches. Thanks again go to Bill Staehle.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.21</revnumber>
|
||||
<date>2001-11-03</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Changed discrepancies reported by Bill Staehle.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.20</revnumber>
|
||||
<date>2001-11-01</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Added Alcatel Speedtouch Information.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v0.19</revnumber>
|
||||
<date>2001-10-31</date>
|
||||
<authorinitials>mww</authorinitials>
|
||||
<revremark>
|
||||
Initial public release.
|
||||
</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
This document describes how to setup a modem pppd link to
|
||||
Btinternet in the UK.
|
||||
</para>
|
||||
</abstract>
|
||||
|
||||
</artheader>
|
||||
|
||||
<sect1 id="intro">
|
||||
<title>Introduction</title>
|
||||
<para>
|
||||
This HOWTO exists because a mate of mine needed to easily set up an
|
||||
Internet connection to BTinternet and here is a quick and concise way
|
||||
to get a running PPPd to Btinternet. This HOWTO also briefly covers
|
||||
Howto setup basic IP Masquerading to allow connection sharing.
|
||||
</para>
|
||||
|
||||
<sect2 id="copyright">
|
||||
<title>Copyright and License</title>
|
||||
<para>
|
||||
This document is Copyright 2001 by Matt Wright. Permission is granted
|
||||
to copy, distribute and/or modify this document under the terms of
|
||||
the GNU Free Documentation License, Version 1.1 or any later version
|
||||
published by the Free Software Foundation; with no Invariant
|
||||
Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A
|
||||
copy of the license is available at
|
||||
<ulink url="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</ulink>
|
||||
</para>
|
||||
|
||||
<para>Send feedback to
|
||||
<ulink url="mailto:matt@consultmatt.co.uk"><citetitle>matt@consultmatt.co.uk</citetitle></ulink>.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="mailing">
|
||||
<title>Mailing Lists</title>
|
||||
|
||||
<para>Please note: There is a mailing list available for this howto. If you wish to join please email <email>majordomo@consultmatt.co.uk</email> with the body:</para>
|
||||
|
||||
<para><filename>subscribe bti-howto</filename></para>
|
||||
|
||||
<para>This will then be followed up by the mailing list bot and subsequent emails should arrive confirming your request. The list is intended to be for annoucing changes to this HOWTO and also to dicuss the finer points of getting pppd to work on BTinternet.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="author">
|
||||
<title>About the author</title>
|
||||
|
||||
<para> My name is Matt Wright. I'm 16 year-old student in Blackburn,
|
||||
Lancashire. I'm a freelance Linux consultant. I am the proud owner of
|
||||
a Duron 950Mhz (all I could easily afford) with 256MB SDRAM, Voodoo 4
|
||||
Video Card, ATI All-in-Wonder Pro Video Card. I also have a 266Mhz Cyrix
|
||||
that runs my USB ADSL connection, of which if you are reading this from
|
||||
<ulink url="http://www.consultmatt.co.uk">http://www.consultmatt.co.uk</ulink>
|
||||
you will be using. </para>
|
||||
|
||||
<para>
|
||||
You can find me at <ulink url="http://www.consultmatt.co.uk">www.consultmatt.co.uk</ulink>. Or at <ulink url="mailto:matt@consultmatt.co.uk">matt@consultmatt.co.uk</ulink>.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="greetz">
|
||||
<title>Acknowledgements</title>
|
||||
<para>A major thanks of gratitude to the guys at Linuxdoc in particular Greg Ferguson and David Merrill for help with getting this into trusty SGML. Also to Rob Smith the guy behind me writing this :) (As he couldn't sort his own Linux box out :P). A great vote of thanks to Bill Staehle for his input in ironing out some major flaws. Also a thank you goes to TonyC at btinternet.linux and the rest of that newsgroup for originally getting me on my feet with BTi. Finally and most importantly my thanks goto my Lord and Saviour Jesus Christ, without whom I'd be lost.</para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="req">
|
||||
<title>Requirements</title>
|
||||
<para>
|
||||
The following is needed to use this HOWTO:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>A working modem, external or internal hardware modems are the easiest to get working, see <ulink url="http://www.linuxdoc.org/HOWTO/Modem-HOWTO.html">Modem-HOWTO</ulink>. If you have a WinModem then see <ulink url="http://www.linuxdoc.org/HOWTO/Winmodems-and-Linux-HOWTO.html">Winmodems and Linux HOWTO</ulink></para></listitem>
|
||||
|
||||
<listitem><para>An account with Btinternet, this HOWTO covers
|
||||
BTi Surftime and Anytime</para></listitem>
|
||||
|
||||
<listitem><para>Some basic understanding of the Linux OS and
|
||||
its layout</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="surf">
|
||||
<title>Surftime</title>
|
||||
|
||||
<sect2>
|
||||
<title>PPPd Setup</title>
|
||||
|
||||
<para> Right, to start off you will need a working installation of
|
||||
PPPd, I know from experience that Mandrake 8.0 that sometime is
|
||||
doesn't install pppd so check its installed first. Once it is it
|
||||
usually resides in <filename>/usr/sbin/pppd</filename> check that any
|
||||
users you want to access it have setuid access.
|
||||
</para>
|
||||
<para>Note: Setuid allows pppd to run as-if root allowing non-superusers to run pppd without less problems. To do this use the command <command>chmod 4750 /usr/sbin/pppd</command>. Beware: Some distributions have a watchdog program that will change the pppd permissions back to normal. I have not tested this but on RedHat derived systems with Linuxconf installed then removing the <filename>/usr/lib/linuxconf/redhat/perm/ppp</filename> should stop this happening.</para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2>
|
||||
<title>Chatscript (Dialup)</title>
|
||||
|
||||
<para> The Chatscript is a text file, usually residing in
|
||||
<filename>/etc/ppp</filename> that contains the commands passed to
|
||||
the modem to make it dial to BTi. If you want to compare this to DUN
|
||||
in Windows then this is the phone number and init commands. </para>
|
||||
|
||||
<para> Below is the chatscript used to dial BTi, I've now opted for putting the \T metacharacter in the script. The means when we run <command>chat</command>, inside the pppd command, we can use a <filename>-T</filename> parameter and supply the needed telephone number.</para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
"" "ATZ"
|
||||
|
||||
# The next two lines should be left commented out until
|
||||
# the script works.
|
||||
|
||||
# "OK" "ATL0"
|
||||
# "OK" "ATM0"
|
||||
|
||||
SAY "Dialing modem...\n"
|
||||
"OK" "ATDT \T"
|
||||
ABORT BUSY
|
||||
ABORT "NO CARRIER"
|
||||
TIMEOUT 60
|
||||
CONNECT \c
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> This script will dial BTi providing you put in the \T so we can added the telephone number later. I suggest saving the chatscript as something like <filename>/etc/ppp/chatscript</filename> Once you've saved it we can move onto setting up BTi's CHAP authentication.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2>
|
||||
<title>Authentication</title>
|
||||
|
||||
<para> With PPP dialup's the most widely used authentication method,
|
||||
apparently, is PAP (Password Authentication Protocol). However, just
|
||||
to be a pain in the backside BTi use CHAP (Challenge Handshake
|
||||
Authentication Protocol). To be fair CHAP is a more secure authentication method than PAP but it's still a pain. Now PPPd does support this but not through
|
||||
nice easy to use Linuxconf dialogs. </para>
|
||||
|
||||
<para>In the
|
||||
<filename>/etc/ppp</filename> directory should be a
|
||||
<filename>chap-secrets</filename> that looks roughly like this when
|
||||
first installed: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
# Secrets for authentication using CHAP
|
||||
# client server secret IP addresses
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> We can safely ignore the IP Address column but the others me
|
||||
must worry about. So fill in the gaps like this: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
# Secrets for authentication using CHAP
|
||||
# client server secret IP addresses
|
||||
"bloggs@btinternet.com" * "mypasswordhere"
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> These two extra lines will try and authenticate ANY outgoing
|
||||
PPP connection that responds using CHAP using your BTi details. It
|
||||
goes without saying that you replace
|
||||
<emphasis>bloggs@btinternet.com</emphasis> and
|
||||
<emphasis>mypasswordhere</emphasis> with your details. Also, the second line is not strictly needed but I've found it helps sometimes.</para>
|
||||
|
||||
<para><emphasis role="strong">Note</emphasis>: If you're not using BTi at this point you can usually get away with having identical <filename>chap-secrets</filename> and <filename>pap-secrets</filename>. If you the same kind of pattern as above it should work.</para>
|
||||
|
||||
<para>I suggest that you do a "<command>chmod 600 /etc/ppp/*secrets</command>". It was pointed out to me that it stops pppd shouting about security.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2>
|
||||
<title>Setting your global options</title>
|
||||
|
||||
<para> In your <filename>/etc/ppp</filename> directory there is a
|
||||
file called <filename>options</filename>. If your open it with your
|
||||
favourite text editor you should see:</para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
lock
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> And thats it, now we need to add some more settings in here so
|
||||
make it look like: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
lock
|
||||
usepeerdns
|
||||
defaultroute
|
||||
noipdefault
|
||||
noauth
|
||||
asyncmap 0
|
||||
crtscts
|
||||
modem
|
||||
115200
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Don't worry what they do, if you're interested look at the man
|
||||
page for pppd. As a passing note if you would like PPPd to redial
|
||||
dropped connections then add <emphasis>persist</emphasis> to the end
|
||||
of your options file. </para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2>
|
||||
<title>Testing your link</title>
|
||||
|
||||
<para> Now you've created your Chatscript there are only two steps
|
||||
left till you should be on the Internet. First is getting a working
|
||||
link and second is creating a couple of easy dialup scripts to help
|
||||
you. </para>
|
||||
|
||||
<para>
|
||||
To test your link try this command:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<command>pppd ttyS0 connect '/usr/sbin/chat -v -TPHONE_NUM_HERE -f /etc/ppp/chatscript' updetach debug name bloggs@btinternet.com</command></para>
|
||||
|
||||
<para> Now obviosuly if your testing at Daytiem rate add the Daytiem number where instead of <filename>PHONE_NUM_HERE</filename> and similar with Surftime.</para>
|
||||
<para> This will tell PPPd to dial the modem on ttyS0 (COM1) using the chatscript. The <option>updetach</option> tells PPPd to only fork away to the commandline after the connection is established and the <option>debug</option> will show all authentication commands onscreen (providing updetach it set) while it trys to connect. </para>
|
||||
|
||||
<para> If that connected then move onto the next section and we can
|
||||
make a set of scripts to allow easy dialing. </para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2>
|
||||
<title>Dialing scripts</title>
|
||||
|
||||
<para> Here I'll just set out a set of scripts that will let your
|
||||
dial BTi from a command line easily. The following should be
|
||||
self-explanatory, the italic filename is the filename to put the data
|
||||
into and the proceeding text the file contents: </para>
|
||||
|
||||
<para><command>/etc/ppp/peers/bt-surf</command></para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
ttyS0 connect '/usr/sbin/chat -v -TSURFTIME_NUMBER_HERE -f /etc/ppp/chatscript'
|
||||
updetach name bloggs@btinternet.com
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para><command>/etc/ppp/peers/bt-day</command></para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
ttyS0 connect '/usr/sbin/chat -v -TDAYTIME_NUMBER HERE -f /etc/ppp/chatscript'
|
||||
updetach name bloggs@btinternet.com
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Change any of the filenames to suit what you called them and
|
||||
the username. Do the same with this: </para>
|
||||
|
||||
<para><command>/usr/bin/internet</command></para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
#!/bin/bash
|
||||
# a script to dial BTi
|
||||
case "$1" in
|
||||
daytime)
|
||||
/usr/sbin/pppd call bt-day
|
||||
;;
|
||||
surftime)
|
||||
/usr/sbin/pppd call bt-surf
|
||||
;;
|
||||
off)
|
||||
killall pppd
|
||||
;;
|
||||
esac
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Once you've done that run this command at the command prompt:
|
||||
</para>
|
||||
|
||||
<para><command>chmod a+x /usr/bin/internet</command></para>
|
||||
|
||||
<para> Now you've done, simply type
|
||||
<command>internet daytime/surftime/off</command> and it
|
||||
will connect you to the internet. </para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1>
|
||||
<title>BTi Anytime</title>
|
||||
|
||||
<para> I'm sorry, for all you Anytime customers its really hard!
|
||||
NOT! Read all the instructions for Surftime above. They all apply in
|
||||
most places, the only things to watch out for is you obviously don't
|
||||
need any of the Surftime/daytime distinctions. So only have one
|
||||
peers file (using the correct phoen number) and one dialup option in your <filename>/usr/bin/internet</filename> file. (eg. dial and off)</para>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1>
|
||||
<title>BTOpenworld Home 500 (Alcatel Speedtouch USB)</title>
|
||||
|
||||
<sect2>
|
||||
<title>About this section</title>
|
||||
|
||||
<para> There is rather a large amount of credit due here, to
|
||||
<ulink url="mailto:chris@black-sun.co.uk">Chris Jones</ulink> for writing the
|
||||
<ulink url="http://www.linuxdoc.org/HOWTO/DSL-HOWTO/speedtouchusb.html">Alcatel
|
||||
Speedtouch USB ASDL Modem mini-HOWTO</ulink> that is now part of the
|
||||
<ulink url="http://www.linuxdoc.org/HOWTO/DSL-HOWTO/">DSL HOWTO</ulink>.
|
||||
This helped me a great deal when trying to get my Speedtouch to work. </para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Warning</title>
|
||||
|
||||
<para>At home I use Linux Mandrake, although the version of the kernel I had was patched with the ATM kernel source I did end up patching a different kernel source to get it working. Please, please inspect your kernel source to see if you have the PPPoATM source patched against your kernel. To do this go into you kernel source directory, usually <filename>/usr/src/linux</filename> and do a <command>make menuconfig</command>. In the Network Device Support section check for:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Network device support->PPP over ATM</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>If it does exist then make sure it is present it you current kernel and you can skim-read the "Patching you kernel" section to make sure you have the correc toptions compiled in and then carry on.</para>
|
||||
|
||||
<para>This was just a minor warning as I orginially had a kernel patched with PPPoATM and without realising managed to trash my kernel tree by trying to force the patch onto it.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Distribution Specific Information</title>
|
||||
|
||||
<para>I have had reports about different distros that have varying
|
||||
PPPoATM support already builtin to the kernel:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Mandrake 8.0: The default 2.4.3 kernel already has the
|
||||
PPPoATM patch applied, I cannot remember if it compiled in but ignore
|
||||
steps refering the "Patching the Kernel" below. PS: You still need to
|
||||
configure the kernel.</para></listitem>
|
||||
<listitem><para>Mandrake 8.1: Mandrake 8.1 supports the Speedtouch
|
||||
automatically, I have no had first hand experience but from what I can
|
||||
gather you simply have to download the Alcatel binaries and then use
|
||||
DrakNet to sort it out.</para></listitem>
|
||||
<listitem><para>Debian: I have had reports that the standard Debian
|
||||
installtion does not include libpam, this must be installed for the
|
||||
PPPoATM plugin modules to work.</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>NOTE: From roughly kernel 2.4.16 the PPPoATM patch is included in
|
||||
Linus' main source tree. Therefore you can miss out patching the kernel
|
||||
and just configure it.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Requirements</title>
|
||||
|
||||
<para> To get your Speedtouch USB working in Linux you have a fairly
|
||||
heavyweight task ahead of you, but hey, if I could do it so can you!
|
||||
This is what you'll need to get it working: </para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>You must have the kernel source installed and
|
||||
know the procedure for installing and compiling a new kernel.
|
||||
If this is a problem then read the <ulink url="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html">Kernel HOWTO</ulink>.</para></listitem>
|
||||
|
||||
<listitem><para>You must be running one of the following
|
||||
Kernels: 2.3.39, 2.4.0-test4, 2.4.1-pre7, 2.4.7, 2.4.8-pre5.
|
||||
This is because the PPPoATM patch for the kernel exists patched
|
||||
against specific kernels, some may work with similar kernel
|
||||
versions but I cannot vouch for that</para></listitem>
|
||||
|
||||
<listitem><para>You, obviously, need a USB controller of some
|
||||
description with at least one free plug. It also must be Linux
|
||||
compatible, nowadays this is most USB controllers that are
|
||||
UHCI/OHCI based. If you don't have one your local supplier
|
||||
would probably have a PCI USB Controller.</para></listitem>
|
||||
|
||||
<listitem><para>A heap-load of confidence with meddling with
|
||||
your config. eg: kernel recompiling, program
|
||||
installation...</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Software Downloads</title>
|
||||
|
||||
<para> To get the Speedtouch working under Linux you will need some
|
||||
software and kernel patches found below: </para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>The kernel patch for your kernel. They can be found at <ulink url="http://www.kernel.org/pub/linux/kernel/people/axboe/PPPoATM/">http://www.kernel.org/pub/linux/kernel/people/axboe/PPPoATM/</ulink>. Please note not all the kernels have patches.</para></listitem>
|
||||
|
||||
<listitem><para>The latest SpeedTouch driver from <ulink url="http://sourceforge.net/project/showfiles.php?group_id=3581">http://sourceforge.net/project/showfiles.php?group_id=3581</ulink></para></listitem>
|
||||
|
||||
<listitem><para>The latest SARlib library from <ulink url="http://sourceforge.net/project/showfiles.php?group_id=22221">http://sourceforge.net/project/showfiles.php?group_id=22221</ulink></para></listitem>
|
||||
|
||||
<listitem><para>The Alcatel speed management software. You can get it from <ulink url="http://www.alcatel.com/consumer/dsl/dvrreg_lx.htm">http://www.alcatel.com/consumer/dsl/dvrreg_lx.htm</ulink>. I can't distribute this because of Alcatel's licensing scheme so get it from them.</para></listitem>
|
||||
|
||||
<listitem><para>Some description of PPPoATM aware PPPd binary:</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Red Hat 7 RPM (glibc 2.2): <ulink url="http://sourceforge.net/project/showfiles.php?group_id=23818">http://sourceforge.net/project/showfiles.php?group_id=23818</ulink></para></listitem>
|
||||
<listitem><para>Debian (.deb): <ulink url="http://sourceforge.net/project/showfiles.php?group_id=23818">http://sourceforge.net/project/showfiles.php?group_id=23818</ulink></para></listitem>
|
||||
<listitem><para>Tarball: <ulink url="http://sourceforge.net/project/showfiles.php?group_id=23818">http://sourceforge.net/project/showfiles.php?group_id=23818</ulink></para></listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
|
||||
<listitem><para>The Linux Hotplug software from <ulink url="http://linux-hotplug.sourceforge.net">http://linux-hotplug.sourceforge.net</ulink>. Get it installed as per their instructions. It seemed simple enough so I won't cover it here</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Patching your kernel</title>
|
||||
|
||||
<para> Once you have the PPPoATM kernel patch (this assumes you use
|
||||
the patch against kernel 2.4.7) you need to make sure you have a
|
||||
working 2.4.7 kernel tree, next unzip the PPPoATM patch by doing:
|
||||
</para>
|
||||
|
||||
<para>NOTE: From rougly kernel 2.4.16 (I haven't tested to see hwo far
|
||||
back it goes) the PPPoATM patch is included in Linus' main kernel tree,
|
||||
therefore you may skip the patching below and resume ready to configure
|
||||
the kernel.</para>
|
||||
|
||||
<para><command>gzip -d pppoatm-2.zip</command></para>
|
||||
|
||||
<para> Next we will need to test-patch the kernel using the following
|
||||
commands: </para>
|
||||
|
||||
<para><command>patch -p1 -s -E --dry-run < /point/to/pppoatm-2</command></para>
|
||||
|
||||
<para> If that ran without failure then patch the kernel by removing
|
||||
the <option>--dry-run</option> as such: </para>
|
||||
|
||||
<para><command>patch -p1 -s -E < /point/to/pppoatm-2</command></para>
|
||||
|
||||
<para> That should have patched the kernel good-and-proper so we can
|
||||
go ahead and configure it, make sure the following options are
|
||||
selected along with your personal build options: </para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Code maturity levels->Prompt for development and/or incomplete code/drivers</para></listitem>
|
||||
<listitem><para>Networking options->Asynchronous Transfer Mode (ATM)</para></listitem>
|
||||
<listitem><para>Network device support->PPP (point-to-point protocol) support</para></listitem>
|
||||
<listitem><para>Network device support->PPP support for async serial ports</para></listitem>
|
||||
<listitem><para>Network device support->PPP Deflate compression</para></listitem>
|
||||
<listitem><para>Network device support->PPP BSD-Compress compression</para></listitem>
|
||||
<listitem><para>Network device support->PPP over ATM</para></listitem>
|
||||
<listitem><para>USB support->Support for USB</para></listitem>
|
||||
<listitem><para>USB support->Preliminary USB device filesystem</para>
|
||||
<para>You have to make a choice here, if your USB controller is
|
||||
UHCI based then select:</para>
|
||||
<para>USB support->UHCI (Intel, PIIX4, VIA, ...) support</para>
|
||||
<para>Alternatively choose:</para>
|
||||
<para>USB Support->OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para> You could select any of these as modules or compiled-in but as
|
||||
I followed Chris Jones' HOWTO I compiled the all but UHCI/OHCI as
|
||||
compiled-in code. Save the kernel config and compile the kernel and
|
||||
modules as you normally do. </para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Kernel Drivers and Software</title>
|
||||
|
||||
<para> Now that the kernel will support using PPPoATM we can start
|
||||
compiling the bits to run the modem. Well start with the Kernel mode
|
||||
driver; first decompress the SARlib sources to a build directory.
|
||||
(Personally I build all my non-kernel sources
|
||||
in <filename>~/sources</filename>) and do a
|
||||
<command>make</command> on it. There is no need to do
|
||||
a <command>make install</command> with this library.</para>
|
||||
|
||||
<para> Next return to your source root and decompress your Speedtouch
|
||||
drivers (from Sourceforge not Alcatel!), go in there and do a
|
||||
<command>make</command>, and then a <command>make install</command>.</para>
|
||||
|
||||
<para> <emphasis role="strong">Note:</emphasis> If you get an "Error
|
||||
1" then check the <filename>Makefile</filename> for a line starting
|
||||
<option>SARLIB:=</option> and check it points to the right directory, the
|
||||
one where you just compiled SARlib. </para>
|
||||
|
||||
<para> Next install the Hotplug software and make sure it works. Once
|
||||
you've done that decompress Alcatel's binary management software and
|
||||
do a <command>make</command> on that. Then do a <command>make
|
||||
install</command>, the clever bit here is their installation
|
||||
registers the Speedtouch kernel driver and their binary to be run
|
||||
when the USB device is "hotplugged" (or coldplugged) into the system.
|
||||
<emphasis>Kiss goodbye to the hours of trying to writing modules
|
||||
loading scripts that always fail.</emphasis> </para>
|
||||
|
||||
<para> Next install the new PPPoATM aware PPPd program, I had no luck
|
||||
getting it compile from source on my machine so I used the RPM. Sorry
|
||||
you're on your own there! </para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>PPPd Configuration</title>
|
||||
|
||||
<para> <emphasis role="strong">Warning:</emphasis> The action will
|
||||
remove all the default settings for any previous PPPd connection.
|
||||
(Not that you want them now you've got shiny new ADSL ;P) </para>
|
||||
|
||||
<para> In the <filename>/etc/ppp</filename> directory there is a file called
|
||||
<filename>options</filename> in that file put the following: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
lock
|
||||
defaultroute
|
||||
noipdefault
|
||||
noauth
|
||||
passive
|
||||
asyncmap 0
|
||||
name bloggs@hg5.btinternet.com
|
||||
user bloggs@hg5.btinternet.com
|
||||
plugin /usr/lib/pppd/plugins/pppoatm.so
|
||||
0.38
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Make sure of the following things: </para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>That you replace both name
|
||||
<emphasis role="strong">and</emphasis> user variables with your
|
||||
username.</para></listitem>
|
||||
|
||||
<listitem><para>That you get the correct VPI/VCI ATM pair,
|
||||
these are in the windows information software, from BTi my
|
||||
VPI:0 and VCI:38 so I use <option>0.38</option>. Make sure
|
||||
you get this right or it <emphasis role="strong">will not
|
||||
work</emphasis>.</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para> Next in your <filename>/etc/ppp/chap-secrets</filename> put:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
# Secrets for authentication using CHAP
|
||||
# client server secret IP addresses
|
||||
"bloggs@hg5.btinternet.com" * "mypasswordhere"
|
||||
</screen>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Testing your link</title>
|
||||
|
||||
<para> Next thing to do is get the link up and test it. If you've got
|
||||
a nice distro like Mandrake you should find it will auto-init your
|
||||
USB drivers and filesystem, if not then the following can be used:
|
||||
</para>
|
||||
|
||||
<para><command>/sbin/modprobe usb-uhci</command></para>
|
||||
<para><command>mount none /proc/bus/usb -tusbdevfs</command></para>
|
||||
|
||||
<para> Next load the Speedtouch driver by doing:
|
||||
<command>/sbin/modprobe speedtch</command>. Next use the speedmgmt
|
||||
program to get the modem init'ed: <command>/usr/sbin/mgmt</command>.
|
||||
After a while of the lights flashing on the modem the main console
|
||||
(and/or the syslog) should report: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
Speedmgmt[2074]: Modem initialised at 576 kbit/s downstream and 288 kbit/s upstream
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Once the modem has been init'ed now make sure the PPPoATM
|
||||
module is loaded by doing: </para>
|
||||
|
||||
<para><command>modprobe pppoatm</command></para>
|
||||
|
||||
<para> Now start the PPP link by typing <command>pppd</command> You
|
||||
should see something similar to this: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
Oct 28 14:01:25 ds9 pppd: PPPoATM plugin_init
|
||||
Oct 28 14:01:25 ds9 pppd: PPPoATM setdevname_pppoatm
|
||||
Oct 28 14:01:25 ds9 pppd: PPPoATM setdevname_pppoatm - SUCCESS
|
||||
Oct 28 14:01:26 ds9 pppd: Using interface ppp0
|
||||
Oct 28 14:01:26 ds9 pppd: Connect: ppp0 <--> 0.38
|
||||
Oct 28 14:01:28 ds9 pppd: local IP address 255.255.255.255
|
||||
Oct 28 14:01:28 ds9 pppd: remote IP address 255.255.255.255
|
||||
Oct 28 14:01:28 ds9 pppd: primary DNS address 213.120.62.100
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Once that's done you're in luck, now just configure the pppd
|
||||
to autodial at startup (beyond the scope of this HOWTO, sorry!).
|
||||
Hopefully HotPlug will get your device up and going before pppd needs
|
||||
it! :). </para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1>
|
||||
<title>Simple IP Masquerading</title>
|
||||
|
||||
<para> To allow sharing of your internet conenction you can eitehr
|
||||
use a proxy server or IP Masquerading. I'll cover IP Masquerding as
|
||||
it's simple to set up on the other client machines. I use a 2.4.x
|
||||
generation kernel and in effect I use IPTables. If you use a 2.2.x or
|
||||
2.0.x kernel then you need the
|
||||
<ulink url="http://www.linuxdoc.org/HOWTO/IP-Masquerade-HOWTO.html">IP
|
||||
Masquerading HOWTO</ulink>. </para>
|
||||
|
||||
<para> This part of the HOWTO assumes that your Netfilter software is
|
||||
modularised, if it isnt then no big deal, either ignore the
|
||||
<option>modprobe</option> lines or recompile your kernel. </para>
|
||||
|
||||
|
||||
<para> Simple now, just run the commands: </para>
|
||||
|
||||
<para><command>modprobe iptable_nat</command></para>
|
||||
<para><command>iptables -t nat -F POSTROUTING</command></para>
|
||||
<para><command>iptables -t nat -A POSTROUTING -o ppp0 -s 10.0.0.0/16 -j MASQUERADE</command></para>
|
||||
<para><command>echo 1 > /proc/sys/net/ipv4/ip_forward</command></para>
|
||||
<para><emphasis role="strong">Note:</emphasis> The space between 1 and > is vital. It seems not to activate the IP Forwarding if the space is not there.</para>
|
||||
|
||||
<para> Change the <option>ppp0</option> and/or the
|
||||
<option>10.0.0.0/16</option> for your relevant network settings and
|
||||
put that file either before the <option>case "$1" in</option> in the
|
||||
<filename>internet</filename> file or somewhere in your startup.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1>
|
||||
<title>Troubleshooting</title>
|
||||
|
||||
<sect2>
|
||||
<title>Help! Lynx gives unable to access document</title>
|
||||
|
||||
<para><emphasis role="strong">Problem:</emphasis>
|
||||
Lynx is unable to access document or ping gives "No
|
||||
route to host" but the link is stable! </para>
|
||||
|
||||
<para> <emphasis role="strong">Solution:</emphasis> Have a look at
|
||||
the output of <command>route -n</command> you should see a
|
||||
refenence specifing a gateway of either your Remote PPP IP
|
||||
and using the adapter/dev of ppp0. If not here is how to fix it. In
|
||||
your <filename>/etc/ppp/ip-up</filename> file above
|
||||
<option>exit 0</option> on the last line type: </para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
route del default
|
||||
route add default gw $4 $1
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para> Save the file and redial. The problem should be solved.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>My kernel < 2.4.2 crashes using the Alcatel driver</title>
|
||||
|
||||
<para><emphasis role="strong">Problem:</emphasis>
|
||||
Your kernel below 2.4.2 crashes using the Alcatel driver.
|
||||
</para>
|
||||
|
||||
<para> <emphasis role="strong">Solution:</emphasis>
|
||||
You're probably using a kernel compiled with SMP support either don't
|
||||
use SMP or try here:
|
||||
<ulink url="http://sourceforge.net/project/showfiles.php?group_id=23818">http://sourceforge.net/project/showfiles.php?group_id=23818</ulink>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>PPPd crashes when it loads the PPPoATM module</title>
|
||||
|
||||
<para><emphasis role="strong">Problem:</emphasis>
|
||||
When PPPd attempts to access the ATM device it crashes.
|
||||
</para>
|
||||
|
||||
<para> <emphasis role="strong">Solution:</emphasis> The kernel was
|
||||
probably compiled on a different type of processor. I tried to get
|
||||
the kernel compiled quicker by compiling the kernel on my 950Mhz
|
||||
Duron, even with the processor type to suit the target 266Mhz Cyrix
|
||||
the ATM module crashes. So dont take short cuts and compile on the
|
||||
target processor. </para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>insmod speedtch.o gives: "Unresolved symbol: _mmx_memcpy"</title>
|
||||
<para><emphasis role="strong">Problem:</emphasis>
|
||||
When you have compiled the Speedtouch Kernel driver (speedtch.o) trying to insmod/modprobe returns: "Unresolved symbol: _mmx_memcpy" or similar.
|
||||
</para>
|
||||
|
||||
<para><emphasis role="strong">Solution:</emphasis>
|
||||
Right, I haven't got a concrete answer here but I couldn't find it anywhere on the internet so here goes. I found this error come up when I recompiled my kernel once. It did it the first time but I forgot how to fix it. A combination of things fixed it for me:
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Configured the kernel module support to ignore kernel version checking</para></listitem>
|
||||
<listitem><para>Recompiled SARlib (this is what ultimately fixed it) before recompiling speedtch.o</para></listitem>
|
||||
<listitem><para>Recompiled speedtch.o and reinstalled. Et voila!</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
As I said I can't be sure about this one but it worked for me.
|
||||
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>There are strange noises on the telephone line when I pick up the
|
||||
phone.</title>
|
||||
|
||||
<para><emphasis role="strong">Problem:</emphasis>
|
||||
When you pick up the phone there are strange noises present, more over
|
||||
the use of the phone line causes the internet to disconnect.</para>
|
||||
|
||||
<para><emphasis role="strong">Solution:</emphasis>
|
||||
You seem to have something which I think is called cross-talk. The
|
||||
ADSL modem works by sending data down the unused frequencies of your
|
||||
copper phone line. If the hardware is set up so the ADSL and phone
|
||||
ranges overlap the two can "hear" each other. The best advice is to
|
||||
Ring BTO Customer Support and they should be able to help.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1>
|
||||
<title>Further Reading</title>
|
||||
|
||||
<para>
|
||||
For further reading on related topics see this list:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>The <ulink url="http://www.linuxdoc.org/HOWTO/PPP-HOWTO/index.html">PPP-HOWTO</ulink></para></listitem>
|
||||
<listitem><para>The <ulink url="http://www.linuxdoc.org/HOWTO/IP-Masquerade-HOWTO.html">IP Masquerading HOWTO</ulink></para></listitem>
|
||||
<listitem><para>The <ulink url="http://www.linuxdoc.org/HOWTO/DSL-HOWTO/index.html">DSL HOWTO</ulink></para></listitem>
|
||||
<listitem><para>The <ulink url="http://www.linuxdoc.org/HOWTO/Modem-HOWTO.html">Modem-HOWTO</ulink>.</para></listitem>
|
||||
<listitem><para>The <ulink url="http://www.linuxdoc.org/HOWTO/Winmodems-and-Linux-HOWTO.html">Winmodems and Linux HOWTO</ulink></para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
||||
</article>
|
|
@ -0,0 +1,260 @@
|
|||
<?xml version="1.0"?>
|
||||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://docbook.org/xml/4.2/docbookx.dtd"
|
||||
>
|
||||
<article id="spm">
|
||||
<articleinfo><title>Complete System Performance Monitor HOWTO</title>
|
||||
<abstract>
|
||||
<para>This HOWTO provides an overview of the Complete System Performance Monitor, including a description of the product and installation and configuration information.</para>
|
||||
</abstract>
|
||||
<author>
|
||||
<firstname>Chris</firstname>
|
||||
<surname>Lorenz</surname>
|
||||
<affiliation>
|
||||
<address><email>lorenzc@us.ibm.com</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<pubdate>2003-06-10</pubdate>
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>2.0</revnumber>
|
||||
<date>2003-06-10</date>
|
||||
<authorinitials>CL</authorinitials>
|
||||
</revision>
|
||||
</revhistory>
|
||||
</articleinfo>
|
||||
<sect1 id="copy"><title>Copyright and legal notice</title>
|
||||
<para>Copyright © 2003 IBM Corporation. All
|
||||
rights reserved.
|
||||
</para>
|
||||
<para>This document is provided "AS IS," with no
|
||||
express or implied warranties. Use the information in
|
||||
this document at your own risk.
|
||||
</para>
|
||||
<para>Linux is a registered trademark of Linus Torvalds. Other company, product, and service
|
||||
names may be trademarks or service marks of others.
|
||||
</para>
|
||||
<para>Permission is granted to copy, distribute, and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover text, and no Back-Cover text. A copy of the license can be found at <ulink url="http://www.gnu.org/licenses/fdl.txt">http://www.gnu.org/licenses/fdl.txt</ulink>.</para>
|
||||
</sect1>
|
||||
<sect1><title>What Is the Complete System Performance Monitor?</title>
|
||||
<para>The Complete System Performance Monitor (CSPM), written by Don Dupuis of Compaq Computer Corporation, is a graphical tool that monitors a Linux® system's CPU, memory, storage, network, and IRQ utilization. CSPM gathers all the data automatically and then generates histogram displays of system usage. </para></sect1>
|
||||
|
||||
<sect1><title>Requirements</title>
|
||||
<para>CSPM V1.0 and later require the following:</para>
|
||||
<itemizedlist><listitem><para>Red Hat Linux 7.2 or later, Mandrake 8.2 or later, or any Linux
|
||||
kernel that has Stephen Tweedie's <command>sar</command> or <command>sysstat</command> patch applied (such as 2.4.20).</para></listitem>
|
||||
<listitem><para>The Trolltech Qt 3.0 or later C++ application development environment, which is available for download from Trolltech for free.</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
||||
<sect1><title>Installing CSPM and its requirements</title>
|
||||
<para>This section describes how to acquire the Qt application development environment and install CSPM.</para>
|
||||
<sect2><title>Installing Qt 3.0 or later</title>
|
||||
|
||||
<para>Qt 3.0 or later must be installed on the system before you install CSPM.
|
||||
Follow these steps to acquire and configure Qt:
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>Download the Qt X/11 Free Edition from <ulink url="www.trolltech.com">http://www.trolltech.com</ulink> for the latest version of Qt. </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Follow Trolltech's instructions for installing Qt. </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Run .<command>/configure</command> with the <constant>-thread</constant> switch to the configure
|
||||
program so that Qt is installed to run in multithreaded mode.</para>
|
||||
<programlisting># ./configure -thread</programlisting>
|
||||
</listitem>
|
||||
<listitem><para>Be sure to export the variables QTDIR and LD_LIBRARY_PATH, as
|
||||
described in the Qt installation instructions that are downloaded with the software.</para>
|
||||
</listitem></orderedlist>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title>Installing CSPM</title>
|
||||
<para>The following sections describe how to download and install CSPM.
|
||||
These steps must be run by the root user.
|
||||
The installation process creates a directory called <filename>spm</filename> and places all the files in that directory.
|
||||
|
||||
</para>
|
||||
<sect3><title>Installing from rpm</title>
|
||||
<para>Follow these steps to install CSPM from the rpm file:</para>
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>Download the CSPM rpm file from SourceForge at <ulink url="http://sourceforge.net/projects.cspm">http://sourceforge.net/projects/cspm</ulink>. The program name
|
||||
for CSPM is <filename>spm2</filename>. </para>
|
||||
</listitem>
|
||||
<listitem><para>Install the software:</para>
|
||||
<programlisting># rpm -ihv --nodeps spm2-1.0-1.586.rpm</programlisting>
|
||||
<para>The rpm creates the binary call <command>spm2</command> in the current directory.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
</sect3>
|
||||
<sect3><title>Installing from tar</title>
|
||||
<para>Follow these steps to install CSPM from the tar file:</para>
|
||||
<orderedlist>
|
||||
<listitem><para>Download the CSPM tar file from SourceForge at <ulink url="http://sourceforge.net/projects.cspm">http://sourceforge.net/projects/cspm</ulink>. The program name
|
||||
for CSPM is <filename>spm2</filename>. </para></listitem>
|
||||
|
||||
<listitem><para>Untar the <filename>spm2.tar.gz</filename> file:</para>
|
||||
<programlisting># tar xvzf spm2.tar.gz</programlisting></listitem>
|
||||
<listitem><para>Compile CSPM:</para>
|
||||
<programlisting># make all</programlisting>
|
||||
<para>The <command>make</command> command creates the binary call <command>spm2 </command>in the current directory.</para></listitem>
|
||||
</orderedlist>
|
||||
</sect3>
|
||||
</sect2>
|
||||
|
||||
<sect2><title>Starting the CSPM monitor</title>
|
||||
<para>The <filename>spm2</filename> program should be run by a user other than root so that any changes to
|
||||
the default preference settings can be changed.</para>
|
||||
<para>Enter the following command from the directory where CSPM is installed:</para>
|
||||
<para><programlisting># ./spm2</programlisting></para>
|
||||
<para>If a segmentation fault occurs when <command>spm2</command> is starting up, make sure that you have set the QTDIR and LD_LIBRARY_PATH variables, as described in the Qt installation instructions that are downloaded with the software.</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1><title>Modifying CSPM defaults</title>
|
||||
<para>By default, the number of "range bars" along the y-coordinate of each histogram
|
||||
is five. When there is no activity for a particular device, CSPM provides default values
|
||||
of 0, 0.2, 0.4, 0.6, and 0.8. Once activity begins on the device, CSPM sets the
|
||||
five values in equal increments from 0 to the peak data value collected in each
|
||||
collection interval. Sometimes the grid lines fall directly on the range bar numbers,
|
||||
making the numbers hard to read. You can either adjust the color of the grid lines,
|
||||
adjust the collection interval, or try to ignore the grid lines.
|
||||
</para>
|
||||
|
||||
<para>You can modify the default grid, sizing, and monitoring settings for each of the views from
|
||||
the <menuchoice><guimenu>Preferences</guimenu></menuchoice> pulldown. From the
|
||||
<menuchoice><guimenu>Preferences</guimenu></menuchoice> pulldown, you can select <guilabel>System</guilabel>,
|
||||
<guilabel>Tests</guilabel>, <guilabel>CPU</guilabel>, <guilabel>Memory</guilabel>, <guilabel>Network</guilabel>,
|
||||
<guilabel>Storage</guilabel> or <guilabel>IRQs</guilabel>. Once you select a particular item, you
|
||||
can view the <guilabel>Grid</guilabel>, <guilabel>Monitoring</guilabel>, or <guilabel>Sizing</guilabel> tab
|
||||
(if applicable) for that item.</para>
|
||||
<para>From the <guilabel>Grid</guilabel> tab you can change such things as:</para>
|
||||
|
||||
<itemizedlist><listitem><para>the color of the grid lines</para></listitem>
|
||||
<listitem><para>the distance (or time), in seconds, between intervals when data is collected (horizontal lines appear at each interval)</para></listitem>
|
||||
<listitem><para>the color of the various data bars (such as read, write, user, nice, and "sys")</para></listitem>
|
||||
<listitem><para>the number of horizontal range bars (default is 5)</para></listitem>
|
||||
<listitem><para>the size of the histogram titles</para></listitem></itemizedlist>
|
||||
|
||||
<para>From the <guilabel>Monitor</guilabel> tab you can change things such as:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>the height and width of the display boxes (in pixels)</para></listitem>
|
||||
<listitem><para>the colors of the display boxes</para></listitem>
|
||||
<listitem><para>the type of data to be monitored (IOs, data, reads and writes, sectors and blocks)</para></listitem></itemizedlist>
|
||||
|
||||
<para>From the <guilabel>Sizing</guilabel> tab you can change the minimum height and width of the
|
||||
display boxes (in pixels).</para>
|
||||
</sect1>
|
||||
<sect1><title>How CSPM displays data</title>
|
||||
<para>CSPM displays histograms that provide information about system usage.
|
||||
The program has 8 display tabs for the different types of system information CSPM
|
||||
collects. These tabs are:</para>
|
||||
<itemizedlist>
|
||||
<listitem><para><guilabel>System Overview</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>IRQs</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>CPU Utilization</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>Memory</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>Network</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>Storage</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>Tests</guilabel></para>
|
||||
</listitem>
|
||||
<listitem><para><guilabel>Test Summary</guilabel></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>The key at the bottom of the histogram tables on each of the tabs tells how to interpret
|
||||
the various colors representing data in the tables.</para>
|
||||
<para>Use the horizontal and vertical scroll bars to view any histograms that do not
|
||||
fit on the initial screen.</para>
|
||||
|
||||
<sect2><title><guilabel>System Overview</guilabel> tab</title>
|
||||
<para>When CSPM starts up, the <guilabel>System Overview</guilabel> screen is displayed. The histograms
|
||||
on the <guilabel>System Overview</guilabel> screen show data for the total system, including CPU, memory,
|
||||
network, and storage usage. The following screenshot shows a sample view of a
|
||||
System Overview screen. </para>
|
||||
<para><graphic fileref="sysover.png"/></para>
|
||||
<para>Below each histogram is a key that describes the data that is represented. For example, in the
|
||||
CPU total histogram, the red line represents user CPU usage, the green line represents commands run with a modified scheduling priority (nice), and the blue line represents system CPU usage.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>IRQs</guilabel> tab</title>
|
||||
|
||||
<para>When you click the <guilabel>IRQs</guilabel> tab, a histogram opens for each IRQ line that
|
||||
runs to an ISA slot
|
||||
on the system. The following screenshot shows a sample view of the IRQs screen.</para>
|
||||
<para><note><title>Note</title>
|
||||
<para>With Qt 3.0, the horizontal scroll bars on the Irqs tab does not work properly. This
|
||||
problem does not occur with Qt 3.1.</para></note></para>
|
||||
<para><graphic fileref="irqs.png"/></para>
|
||||
<para>The large blue number to the left of the histogram is the number of the IRQ.
|
||||
The
|
||||
red line on each histogram represents the number of IRQs per second utilitized by the device
|
||||
connected to the IRQ's ISA slot.</para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2><title><guilabel>CPU Utilization</guilabel> tab</title>
|
||||
<para>When you click the <guilabel>CPU Utilization</guilabel> tab, histograms open for each CPU
|
||||
on the system, as
|
||||
shown in the following screenshot:
|
||||
</para>
|
||||
<para><graphic fileref="cpu.png"/></para>
|
||||
<para>The histograms show information about user (red), system (blue), and nice priority (green) command utilization.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>Memory</guilabel> tab</title>
|
||||
<para>The <guilabel>Memory</guilabel> tab is still under development. In a future release of CSPM,
|
||||
the <guilabel>Memory</guilabel> tab will graphically show how much memory processes use, from most to least. </para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>Network</guilabel> tab</title>
|
||||
<para>When you click the <guilabel>Network</guilabel> tab, histograms that show the amount of traffic on the system's loopback device and each network device are displayed, as shown in the following screenshot.
|
||||
</para>
|
||||
<para><graphic fileref="network.png"/></para>
|
||||
<para>Sends are shown in red and receives are shown in blue.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>Storage</guilabel> tab</title>
|
||||
<para>When you click the <guilabel>Storage</guilabel> tab, a collection of histograms opens that
|
||||
show data
|
||||
for controllers, disks, and partitions.
|
||||
The key at the bottom of the histograms tells which
|
||||
color of histogram box corresponds to which type of device.
|
||||
</para>
|
||||
<para><graphic fileref="storage.png"/></para>
|
||||
<para>The screenshot
|
||||
displays purple for controllers, green for disks, and orange for partitions.
|
||||
The red lines represent
|
||||
reads from the devices and the blue lines represent writes to the devices.</para>
|
||||
<para>To see information about a partition (such as file system name, space used, and
|
||||
space available), right-click the partition's histogram and then left-click <guimenuitem>Properties</guimenuitem>. A
|
||||
Partition Status window opens that displays information about the selected partition.</para>
|
||||
<para><graphic fileref="snapshot9.png"/></para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>Tests</guilabel> tab</title>
|
||||
<para>The <guilabel>Tests</guilabel> tab opens a list of tests that can be run on the system
|
||||
and is useful, for example, for quality assurance personnel who need to load test systems when testing hardware or software.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2><title><guilabel>Test Summary</guilabel> tab</title>
|
||||
<para>The <guilabel>Test Summary</guilabel> tab contains test output and utilization numbers for test runs.
|
||||
You can print these test results and keep them for your records.</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
</article>
|
||||
|
After Width: | Height: | Size: 8.6 KiB |
After Width: | Height: | Size: 10 KiB |
After Width: | Height: | Size: 8.5 KiB |
After Width: | Height: | Size: 102 KiB |
After Width: | Height: | Size: 7.7 KiB |
After Width: | Height: | Size: 8.4 KiB |
After Width: | Height: | Size: 5.0 KiB |
After Width: | Height: | Size: 15 KiB |
After Width: | Height: | Size: 15 KiB |
After Width: | Height: | Size: 1.7 KiB |
After Width: | Height: | Size: 1.2 KiB |
After Width: | Height: | Size: 6.1 KiB |
After Width: | Height: | Size: 5.9 KiB |
After Width: | Height: | Size: 3.9 KiB |
After Width: | Height: | Size: 5.0 KiB |
After Width: | Height: | Size: 4.5 KiB |
After Width: | Height: | Size: 969 B |
After Width: | Height: | Size: 1.9 KiB |
After Width: | Height: | Size: 1.6 KiB |
After Width: | Height: | Size: 3.1 KiB |
|
@ -0,0 +1,881 @@
|
|||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
|
||||
|
||||
<article id="index">
|
||||
<title>Ext2fs Undeletion of Directory Structures mini-HOWTO</title>
|
||||
|
||||
<artheader>
|
||||
|
||||
<author>
|
||||
|
||||
<firstname>Tomas</firstname>
|
||||
<surname>Ericsson</surname>
|
||||
<affiliation>
|
||||
<address>
|
||||
<email>tomase@matematik.su.se</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
|
||||
</author>
|
||||
|
||||
<revhistory>
|
||||
|
||||
<revision>
|
||||
<revnumber>v0.1.1</revnumber>
|
||||
<date>14 November 2000</date>
|
||||
<authorinitials>T.E.</authorinitials>
|
||||
<revremark>Initial release.</revremark>
|
||||
</revision>
|
||||
|
||||
</revhistory>
|
||||
|
||||
<abstract>
|
||||
|
||||
<para>
|
||||
This document is supposed to be as an complementary to the
|
||||
<emphasis>Ext2fs-Undeletion mini-HOWTO</emphasis> written by
|
||||
Aaron Crane. I really recommend you to carefully study that one before
|
||||
reading this.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Here I will describe a straight forward way of recovering whole
|
||||
directory structures, instead of file by file, that have been removed
|
||||
by a misplaced <emphasis>rm -rf</emphasis>.
|
||||
</para>
|
||||
|
||||
</abstract>
|
||||
|
||||
</artheader>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<sect2>
|
||||
<title>Disclaimer</title>
|
||||
|
||||
<para>
|
||||
The author is not responsible for damages due actions taken based on
|
||||
this document. You will do everything at your own risk.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>License</title>
|
||||
|
||||
<para>
|
||||
This document may be distributed only subject to the terms and
|
||||
conditions set forth in the LDP license available at
|
||||
<ulink url="http://www.linuxdoc.org/manifesto.html">
|
||||
http://www.linuxdoc.org/manifesto.html
|
||||
</ulink>
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Feedback</title>
|
||||
|
||||
<para>
|
||||
Any kind of feedback is welcome. Corrections of errors in this text are
|
||||
of great interest. If someone find things described here useful I really
|
||||
would appreciate to hear that from you.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>New versions of this document</title>
|
||||
|
||||
<para>
|
||||
The latest version of this document will be found at
|
||||
<ulink url="http://www.matematik.su.se/~tomase/ext2fs-undeletion/">
|
||||
http://www.matematik.su.se/~tomase/ext2fs-undeletion/</ulink>
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Acknowledgements</title>
|
||||
|
||||
<para>
|
||||
Thanks to the following persons for correctures etc (in alphabetic
|
||||
order).
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Gabriel Kihlman</para></listitem>
|
||||
<listitem><para>Richard Nyberg</para></listitem>
|
||||
<listitem><para>Mats Oldin</para></listitem>
|
||||
<listitem><para>Tobias Westerblom</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Background</title>
|
||||
|
||||
<para>
|
||||
This text has been written while solving my own undeletion problems that
|
||||
I had some time ago. I was about to move some directories from one disk
|
||||
to another. The problem was that the extra disk went corrupted directly
|
||||
after the move for some reason.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
So I wanted to get the moved directories back from my original disk.
|
||||
There were totally about 40000 files to recover and I did not feel very
|
||||
much like to search and rename each one of them by hand.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
I wanted to get back the whole structure of directories. The same
|
||||
situation would have appeared if I had made an
|
||||
<emphasis>rm -rf</emphasis> to those directories.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
|
||||
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="precond">
|
||||
<title>Preconditions</title>
|
||||
|
||||
<para>
|
||||
It is really important that you unmount the affected partition immediately
|
||||
before doing anything else with it. If you have copied around some files
|
||||
in this partition after the accident, then the chance for this method to
|
||||
work has lowered a lot.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Also you must have a quite new kernel, because the
|
||||
2.0.x and below zeroes indirect blocks, which will
|
||||
not make this process to work for files with more than 12 blocks of data.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
I will describe one method of recovery and I will not leave out much for
|
||||
error handling. If you suspect that some step described below went wrong,
|
||||
I do not recommend you to go any further.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="prep">
|
||||
<title>Preparation</title>
|
||||
|
||||
<para>
|
||||
Unmount the partition where you got your deleted files at. I will denote
|
||||
that partition with /dev/hdx1.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# umount /dev/hdx1</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Check the size in blocks of /dev/hdx1.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# fdisk -l /dev/hdx</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now you need to have an extra partition of the same size as
|
||||
/dev/hdx1, to be able to act safely. Suppose that you
|
||||
have an empty harddrive located at /dev/hdy.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# fdisk /dev/hdy</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Create a partition with the same size as /dev/hdx1.
|
||||
Here <emphasis>size</emphasis> is the size in blocks (each block is
|
||||
1024 kB) of /dev/hdx1 taken from above.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
I am using <emphasis>fdisk</emphasis> version 2.10f
|
||||
and if you have another version the <emphasis>fdisk</emphasis>
|
||||
interaction below may not be the same.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
fdisk: n <- Add a new partition.
|
||||
fdisk: p <- Primary partition.
|
||||
fdisk: <- Just press return to chose the default first cylinder.
|
||||
fdisk: +sizeK <- Make a partition of the same size as /dev/hdx1.
|
||||
fdisk: w <- Write table to disk and exit.</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now copy the content of the original partition to that extra one.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# dd if=/dev/hdx1 of=/dev/hdy1 bs=1k</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This process may take quite a long time dependent of how big the partition
|
||||
is. You can get the job done faster by increasing the blocksize,
|
||||
<emphasis>bs</emphasis>, but then you need to get the division of the
|
||||
partition by <emphasis>bs</emphasis> to have a remainder of zero.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
From now on we will only work with that copy of the source partition to
|
||||
be able to step back if something goes wrong.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="find">
|
||||
<title>Finding inodes for deleted directories</title>
|
||||
|
||||
<para>
|
||||
We will try to find out the inode numbers of the deleted directories.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# debugfs /dev/hdy1</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Walk to that place in the structure where the directories were located
|
||||
before the deletion. You can use <emphasis>ls</emphasis> and
|
||||
<emphasis>cd</emphasis> inside <emphasis>debugfs</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
debugfs: ls -l</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Example of output from the above command.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
179289 20600 0 0 0 17-Feb-100 18:26 file-1
|
||||
918209 40700 500 500 4096 16-Jan-100 15:18 file-2
|
||||
160321 41777 0 0 4096 3-Jun-100 06:13 file-3
|
||||
177275 60660 0 6 0 5-May-98 22:32 file-4
|
||||
229380 100600 500 500 89891 19-Dec-99 15:40 file-5
|
||||
213379 120777 0 0 17 16-Jan-100 14:24 file-6</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Description of the fields.
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Inode number.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
||||
<para>
|
||||
First two (or one) numbers represents the kind of inode we got:
|
||||
</para>
|
||||
|
||||
<para>2 = Character device</para>
|
||||
<para>4 = Directory</para>
|
||||
<para>6 = Block device</para>
|
||||
<para>10 = Regular file</para>
|
||||
<para>12 = Symbolic link</para>
|
||||
|
||||
<para>
|
||||
Last four numbers are the usual Unix rights.
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Owner in number representation.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Group in number representation.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Size in bytes.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Date (Here we can see the Y2K bug =)).
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Time.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Filename.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</orderedlist>
|
||||
|
||||
<para>
|
||||
Now dump the mother directory to disk. Here <emphasis>inode</emphasis> is
|
||||
the corresponding inode number (do not forget the '<' and '>').
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
debugfs: dump <inode> debugfs-dump</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Get out of <emphasis>debugfs</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
debugfs: quit</programlisting>
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="analyse">
|
||||
<title>Analyse of directory dump</title>
|
||||
|
||||
<para>
|
||||
View the dumped inode in a readable format.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# xxd debugfs-dump | less</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Every entry consist of five fields. For the first two fields the bytes
|
||||
representing the field comes in backward order. That means the first byte
|
||||
is the least significant.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Description of the fields.
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Four bytes - Inode number.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Two bytes - Directory entry length.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
One byte - Filename length (1-255).
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
||||
<para>
|
||||
One byte - File type (0-7).
|
||||
</para>
|
||||
|
||||
<para>0 = Unknown</para>
|
||||
<para>1 = Regular file</para>
|
||||
<para>2 = Directory</para>
|
||||
<para>3 = Character device</para>
|
||||
<para>4 = Block device</para>
|
||||
<para>5 = FIFO</para>
|
||||
<para>6 = SOCK</para>
|
||||
<para>7 = Symbolic link</para>
|
||||
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Filename (1-255 characters).
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</orderedlist>
|
||||
|
||||
<para>
|
||||
If an entry in the directory is to be deleted, then the second field at
|
||||
the entry before will be increased by the value of the deleted entrys
|
||||
second field.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If a filename is renamed to a shorter one, then the third field will be
|
||||
decreased.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The first entry you will see is the directory itself, represented by a
|
||||
dot.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Suppose that we have the following directory entry.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
c1 02 0e 00 40 00 05 01 'u' 't' 'i' 'l' 's'</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Then the inode would be e02c1 in hexadecimal representation or 918209 in
|
||||
decimal. The next entry would be located after 64 bytes (40 in hex). We
|
||||
see that the filename consist of 5 bytes ("utils") and the file type (01)
|
||||
is a regular file.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now recalculate the directories inode numbers in decimal representation.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you do not like to calculate this by hand I have made a small program
|
||||
in C that will do this for you. The program takes as input a directory
|
||||
dump (created by <emphasis>debugfs</emphasis> as described in
|
||||
<xref linkend="find">). The output (at stdout) consist of each entrys
|
||||
inode number and filename.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Before you run the program you need to load the dump into a hexeditor and
|
||||
change the <emphasis>directory entry length</emphasis> field at the entry
|
||||
before the one you want to get back. But it is simple. If we name the
|
||||
field before to <emphasis>x</emphasis> and the field at the entry you want
|
||||
to get back to <emphasis>y</emphasis>. Then change <emphasis>x</emphasis>
|
||||
to <emphasis>x - y</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The program called <emphasis>e2dirana</emphasis> (ext2fs directory
|
||||
analyse) can be found at
|
||||
<ulink url="http://www.matematik.su.se/~tomase/ext2fs-undeletion/">
|
||||
http://www.matematik.su.se/~tomase/ext2fs-undeletion/</ulink>
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="locate">
|
||||
<title>Locating deleted inodes</title>
|
||||
|
||||
<para>
|
||||
Get a list of all deleted inodes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# echo lsdel | debugfs /dev/hdy1 > lsdel.out</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
One problem here is that <emphasis>debugfs</emphasis> will not give the
|
||||
inode numbers to files that are zero in size (you probably have some in
|
||||
your /etc directory for instance). I will tell how to solve this problem
|
||||
in <xref linkend="recalc"> and <xref linkend="final">.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Load "lsdel.out" into a texteditor. The list of inodes should be sorted in
|
||||
time. Try to remember exactly what time you did that
|
||||
<emphasis>rm -rf</emphasis>. Probably it was the the last items you
|
||||
deleted and then they will be located at the bottom of the list, because it
|
||||
is sorted in time. Delete all lines that has nothing of interest. Save as
|
||||
"lsdel.out-selected".
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now we will cut away everything except the inodes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# cut -b 1-8 lsdel.out-selected | tr -d " " > inodes</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To be sure, check that the deleted directories found above have their
|
||||
inodes in the list.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# grep ^inode$ inodes</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Where <emphasis>inode</emphasis> is the corresponding inode number.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="activate">
|
||||
<title>Activating inodes</title>
|
||||
|
||||
<para>
|
||||
Now it is time for changing some flags of the deleted inodes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Copy the following 6 lines into a file named "make-debugfs-input".
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
#!/bin/sh
|
||||
awk '{ print "mi <" $1 ">\n"\
|
||||
"\n\n\n\n\n\n\n"\
|
||||
"0\n"\
|
||||
"1\n"\
|
||||
"\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n" }'</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This will simulate the user input when editing the inodes manually.
|
||||
We will set <emphasis>deletion time</emphasis> to 0
|
||||
and <emphasis>link count</emphasis> to 1.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
I am using <emphasis>debugfs</emphasis> version 1.18 and if you have
|
||||
another version you should check if you need to adjust the number of
|
||||
returns above.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
Now change the inodes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# ./make-debugfs-input < inodes | debugfs -w /dev/hdy1 | tail -c 40</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If all went well it should end with "Triple Indirect Block [0] debugfs:".
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="add">
|
||||
<title>Adding directory entries</title>
|
||||
|
||||
<para>
|
||||
Start up <emphasis>debugfs</emphasis> in read-write mode.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# debugfs -w /dev/hdy1</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now you should add the deleted directories to the directory were they were
|
||||
located before deletion.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
debugfs: link <inode> directoryname</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Where <emphasis>inode</emphasis> is the inode number and
|
||||
<emphasis>directoryname</emphasis> is the directoryname.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
After you have added the links you will notice that the directories have
|
||||
popped up in the current directory. You can now list their contents (from
|
||||
<emphasis>debugfs</emphasis>).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
But the size shown for each directory is zero and that need to be fixed,
|
||||
otherwise they will look empty with <emphasis>ls</emphasis> from the
|
||||
shell.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Get out of <emphasis>debugfs</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
debugfs: quit</programlisting>
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="recalc">
|
||||
<title>Recalculation</title>
|
||||
|
||||
<para>
|
||||
Now it is time to call <emphasis>e2fsck</emphasis> to recalculate the
|
||||
sizes and checksums.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
I am using <emphasis>e2fsck</emphasis> version 1.18 and if you have
|
||||
another version you should check if some parameters or interaction have
|
||||
changed.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
If you know that you do <emphasis>not</emphasis> have any files with the
|
||||
size of zero that you want to recover you can do the following and skip
|
||||
the rest of this section (Of course you can leave out the
|
||||
<emphasis>y</emphasis> parameter, but then you need to answer all
|
||||
questions by hand and it may take a lot of time.).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# e2fsck -f -y /dev/hdy1 > e2fsck.out 2>&1</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you instead want the zero files back you have to answer
|
||||
<emphasis>no</emphasis> to all questions about clearing entries and
|
||||
<emphasis>yes</emphasis> to the other ones.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Copy the following 7 lines into a file named "e2fsck-wrapper".
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
#!/usr/bin/expect -f
|
||||
set timeout -1
|
||||
spawn /sbin/e2fsck -f $argv
|
||||
expect {
|
||||
"Clear<y>? " { send "n" ; exp_continue }
|
||||
"<y>? " { send "y" ; exp_continue }
|
||||
}</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Run the script.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# ./e2fsck-wrapper /dev/hdy1 > e2fsck.out 2>&1</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Examine "e2fsck.out" to see what <emphasis>e2fsck</emphasis> thought about
|
||||
your partition.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="lostnfnd">
|
||||
<title>If /lost+found not empty</title>
|
||||
|
||||
<para>
|
||||
Some of the directory and files may not pop-up at their right places.
|
||||
Instead they will be located in /lost+found with names after their inode
|
||||
numbers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In this case the pointer at the ".." directory entry probably have been
|
||||
increased and will point to one of the later entrys in the directory (of
|
||||
some reason I do not know, maybe it is a fs bug).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Examine <emphasis>pass 3</emphasis> (where directory connectivity is
|
||||
checked) of "e2fsck.out". There you will find which directories that are
|
||||
affected. Dump those to disk (as described in <xref linkend="find">).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Run
|
||||
<ulink url="http://www.matematik.su.se/~tomase/ext2fs-undeletion/">
|
||||
<emphasis>e2dirana</emphasis></ulink>
|
||||
both with and without the <emphasis>p</emphasis> parameter (it changes the
|
||||
pointer at the ".." directory entry). Here <emphasis>dump</emphasis> is
|
||||
the dumped directory.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# e2dirana dump > dump1
|
||||
# e2dirana -p dump > dump2</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Compare the outputs.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# diff dump1 dump2</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If they are not the same there are missing files in that directory. Then
|
||||
move those files from /lost+found to their right place. Here
|
||||
<emphasis>dest</emphasis> is a symbolic link to the destination directory.
|
||||
Put the output in a script and run it if you agree.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
# diff dump1 dump2 |\
|
||||
tail -n $[`diff dump1 dump2 | wc -l`-1] | cut -b 3- |\
|
||||
sed -e 's/^\([^ ]*\) \(.*\)$/mv lost+found\/#\1 dest\/"\2"/' |\
|
||||
sed -e 's/!/"\\\!"/g'</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Repeat all this until /lost+found is empty.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="final">
|
||||
<title>Final touch</title>
|
||||
|
||||
<para>
|
||||
If in <xref linkend="recalc"> you choosed to get files with the size of
|
||||
zero back you now have a problem, because those files has a non-zero
|
||||
deletion time and their link count is zero. That means that every time
|
||||
<emphasis>e2fsck</emphasis> is running it will prompt to remove (clear)
|
||||
those files.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The easy way to solve this is to copy the whole directory structure to
|
||||
another place (it can be the same partition) and then delete the old
|
||||
directory structure. Otherwise you will have to locate those inodes and
|
||||
change them with <emphasis>debugfs</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now if everything have went well, things should have been restored to its
|
||||
original state before deletion. At least it did for me and in those tests
|
||||
I have made while writing this. Be sure that you have brought up to the
|
||||
preconditions described in <xref linkend="precond">.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="ref">
|
||||
<title>References</title>
|
||||
|
||||
<para>
|
||||
<emphasis>Linux Ext2fs Undeletion mini-HOWTO</emphasis>, v1.3
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Aaron Crane</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
<emphasis>Design and Implementation of the Second Extended Filesystem</emphasis>,
|
||||
<ulink url="http://e2fsprogs.sourceforge.net/ext2intro.html">
|
||||
http://e2fsprogs.sourceforge.net/ext2intro.html</ulink>
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Rémy Card, Laboratoire MASI--Institut Blaise Pascal</para></listitem>
|
||||
<listitem><para>Theodore Ts'o, Massachussets Institute of Technology</para></listitem>
|
||||
<listitem><para>Stephen Tweedie, University of Edinburgh</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
<emphasis>Kernel Source for Linux 2.2.16</emphasis>
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>linux/include/linux/ext2_fs.h</para></listitem>
|
||||
<listitem><para>linux/fs/ext2/namei.c</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect1>
|
||||
|
||||
</article>
|
|
@ -0,0 +1,674 @@
|
|||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
|
||||
|
||||
<article id="index">
|
||||
|
||||
<!-- Header -->
|
||||
|
||||
<artheader>
|
||||
|
||||
<!-- title of HOWTO, include the word HOWTO -->
|
||||
|
||||
<title>KDE Kiosk Mode HOWTO</title>
|
||||
|
||||
<author>
|
||||
<firstname>Roland</firstname>
|
||||
<surname>Fehrenbacher</surname>
|
||||
<affiliation>
|
||||
<address>
|
||||
<email>rfehrenb@transtec.de</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Peter</firstname>
|
||||
<surname>Kruse</surname>
|
||||
<affiliation>
|
||||
<address>
|
||||
<email>Peter.Kruse@wolnet.de</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>1.4</revnumber>
|
||||
<date>2002-09-26</date>
|
||||
<authorinitials>gjf</authorinitials>
|
||||
<revremark>Archived.</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>$Revision: 1.1 $</revnumber>
|
||||
<date>$Date: 2002/09/26 15:20:35 $</date>
|
||||
<authorinitials>$Author: gferg $</authorinitials>
|
||||
<revremark>
|
||||
|
||||
<comment>
|
||||
$Log: KDE-Kiosk-Mode.sgml,v $
|
||||
Revision 1.1 2002/09/26 15:20:35 gferg
|
||||
archived
|
||||
|
||||
Revision 1.3 2001/08/14 07:44:07 kruse
|
||||
nicer formatting.
|
||||
|
||||
Revision 1.2 2001/08/14 07:42:50 pkruse
|
||||
.
|
||||
|
||||
Revision 1.1 2001/08/03 13:56:20 pkruse
|
||||
almost published.
|
||||
|
||||
Revision 1.4 2001/07/31 14:15:21 pkruse
|
||||
prepare to check in linuxdoc cvs.
|
||||
|
||||
Revision 1.3 2001/07/31 13:39:12 pkruse
|
||||
variable and filename docbook tags added.
|
||||
|
||||
Revision 1.2 2001/07/31 11:05:51 pkruse
|
||||
first revision.
|
||||
|
||||
Revision 1.1 2001/07/31 10:49:51 pkruse
|
||||
Initial revision
|
||||
</comment>
|
||||
|
||||
</revremark>
|
||||
</revision>
|
||||
|
||||
<!-- Additional (*earlier*) revision histories go here -->
|
||||
</revhistory>
|
||||
|
||||
<abstract>
|
||||
|
||||
<para>
|
||||
The requirements for the desktop environment of users in a large
|
||||
network environment is often very different to a typical homeuser. The
|
||||
number of applications that these users need to run is usually very
|
||||
limited, and the users themselves are not very experienced in solving
|
||||
computing related problems. The administrators of the network
|
||||
therefore need to ensure that the required applications run reliably,
|
||||
and can be started by the users with a minimum of hassle. For
|
||||
security, stability, and also administrative reasons it is then
|
||||
advisable to provide only the absolutely necessary applications and
|
||||
functionality.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
With the advent of modern desktop technology like KDE, this goal has become
|
||||
harder to achieve. Interoperability between different desktop programs, ease
|
||||
of configuration by configuration engines, etc. allow the user a great deal
|
||||
of control over her/his desktop, which is great when needed. The above large
|
||||
network scenario, however, is not addressable in standard KDE. This is where
|
||||
the restricted mode tries to fill in the gap.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<important>
|
||||
<para>
|
||||
<emphasis role="strong">Archived Document Notice: </emphasis>
|
||||
This document has been archived by the LDP because it does not apply
|
||||
to modern Linux systems. It is no longer being actively maintained.
|
||||
Further information on this topic can be found at
|
||||
<ulink url="http://www.brigadoon.de/peter/kde/">http://www.brigadoon.de/peter/kde/</ulink>.
|
||||
</para>
|
||||
</important>
|
||||
</para>
|
||||
</abstract>
|
||||
|
||||
</artheader>
|
||||
|
||||
|
||||
<!-- Section1: intro -->
|
||||
|
||||
<sect1 id="intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
This document describes a by-product of a project, in which a large
|
||||
number of Linux based workstations were provided. Although a
|
||||
kiosk-mode patch exists for KDE 1, this document assumes KDE 2 and the
|
||||
patches apply to KDE version 2.1.1(2).
|
||||
</para>
|
||||
|
||||
<!-- Section2: copyright -->
|
||||
|
||||
<sect2 id="copyright">
|
||||
<title>Copyright Information</title>
|
||||
|
||||
<para>
|
||||
This document is copyrighted (c) 2001 Peter Kruse and Roland
|
||||
Fehrenbacher and is distributed under the terms of the Linux
|
||||
Documentation Project (LDP) license, stated below.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Unless otherwise stated, Linux HOWTO documents are
|
||||
copyrighted by their respective authors. Linux HOWTO documents may
|
||||
be reproduced and distributed in whole or in part, in any medium
|
||||
physical or electronic, as long as this copyright notice is
|
||||
retained on all copies. Commercial redistribution is allowed and
|
||||
encouraged; however, the authors would like to be notified of any
|
||||
such distributions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All translations, derivative works, or aggregate works
|
||||
incorporating any Linux HOWTO documents must be covered under this
|
||||
copyright notice. That is, you may not produce a derivative work
|
||||
from a HOWTO and impose additional restrictions on its
|
||||
distribution. Exceptions to these rules may be granted under
|
||||
certain conditions; please contact the Linux HOWTO coordinator at
|
||||
the address given below.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In short, we wish to promote dissemination of this
|
||||
information through as many channels as possible. However, we do
|
||||
wish to retain copyright on the HOWTO documents, and would like to
|
||||
be notified of any plans to redistribute the HOWTOs.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you have any questions, please contact
|
||||
<email>linux-howto@metalab.unc.edu</email>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<!-- Section2: disclaimer -->
|
||||
|
||||
<sect2 id="disclaimer">
|
||||
<title>Disclaimer</title>
|
||||
|
||||
<para>
|
||||
No liability for the contents of this documents can be accepted.
|
||||
Use the concepts, examples and other content at your own risk.
|
||||
As this is a new edition of this document, there may be errors
|
||||
and inaccuracies, that may of course be damaging to your system.
|
||||
Proceed with caution, and although this is highly unlikely,
|
||||
the authors do not take any responsibility for that.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All copyrights are held by their by their respective owners, unless
|
||||
specifically noted otherwise. Use of a term in this document
|
||||
should not be regarded as affecting the validity of any trademark
|
||||
or service mark.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Naming of particular products or brands should not be seen
|
||||
as endorsements.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You are strongly recommended to take a backup of your system
|
||||
before major installation and backups at regular intervals.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<!-- Section2: newversions-->
|
||||
|
||||
<sect2 id="newversions">
|
||||
<title>New Versions</title>
|
||||
|
||||
<para>
|
||||
This document and the patches are available at
|
||||
<ulink url="http://www.brigadoon.de/peter/kde">http://www.brigadoon.de/peter/kde</ulink>.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<!-- Section2: credits -->
|
||||
|
||||
<sect2 id="credits">
|
||||
<title>Credits</title>
|
||||
|
||||
<para>
|
||||
<email>Werner.Westerkamp (at) lbbw.de</email> for giving useful
|
||||
tips, and proof-reading this HOWTO
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<email>remalone (at) sympatico.ca</email> for first-time testing
|
||||
the instructions given here
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<!-- Section2: feedback -->
|
||||
|
||||
<sect2 id="feedback">
|
||||
<title>Feedback</title>
|
||||
|
||||
<para>
|
||||
Please send any comments, corrections or additions to one of the authors.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- Section1: intro: END -->
|
||||
|
||||
|
||||
<sect1 id="motivation">
|
||||
<title>Motivation</title>
|
||||
|
||||
<para>
|
||||
The following requirements had to be met:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem>
|
||||
<para>The user should not be able to open an interactive shell
|
||||
(Terminal), or run arbitrary commands,
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
The user should not have a view to the filesystem, so no
|
||||
filemanager,
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>The user should not be able to modify or create files
|
||||
directly by means provided by KDE (no editor, menuedit, etc.).
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Note that these are not requirements for the applications that run under KDE.
|
||||
Every application should make sure by itself, that these requirements are met.
|
||||
It is known, that of course many applications have an Open File Dialog, and
|
||||
thus could modify Files under .kde and so make it possible to run arbitrary
|
||||
commands.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The restrictions should only apply when an environment variable
|
||||
<EnVar>KDE_MODE</EnVar> is
|
||||
set to ``restricted''. If it is not set, a normal KDE Desktop should open.
|
||||
|
||||
It follows, that the user can only run applications that are found in
|
||||
the Application menu. So the administrator must be able to provide the
|
||||
applications. A tool is needed to add, remove and modify entries in
|
||||
the menu.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- Section1: samples: END -->
|
||||
|
||||
|
||||
<!-- Section1: structure -->
|
||||
|
||||
<sect1 id="implementation">
|
||||
<title>Implementation</title>
|
||||
|
||||
<sect2 id="patches">
|
||||
<title>Source Code Patches</title>
|
||||
|
||||
<para>
|
||||
Some files in kdebase-2.1.1 have to be patched:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
appletop_mnu.cpp.patch: Applets on the panel can be moved and removed, but
|
||||
the Preferences dialog is disabled.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
k_mnu.cpp.patch: <guimenuitem>Run Command...</guimenuitem> and
|
||||
<guisubmenu>Configure Panel</guisubmenu> entries are
|
||||
removed from the standard <guimenu>K</guimenu> Menu
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
khc_man.cc.patch: Online Help is completely disabled. This would
|
||||
open konqueror.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
konq_popupmenu.cc.patch: right-mouse menu on icons on the desktop
|
||||
are reduced to <guimenuitem>Cut</guimenuitem>,
|
||||
<guimenuitem>Copy</guimenuitem>, <guimenuitem>Paste</guimenuitem>,
|
||||
<guimenuitem>Delete</guimenuitem>, ... but no <guimenuitem>Open With
|
||||
...</guimenuitem>,
|
||||
no <guimenuitem>Edit File Type...</guimenuitem> and no
|
||||
<guimenuitem>Poperties...</guimenuitem> dialogs.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
pagerapplet.cpp.patch: on minipager selection of type
|
||||
(<guimenuitem>Preview</guimenuitem>,
|
||||
<guimenuitem>Number</guimenuitem>,
|
||||
<guimenuitem>Name</guimenuitem>) is disabled. this caused trouble in
|
||||
multihead environment.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
panel.cpp.patch: right mouse menu on Panel is disabled.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="global-modification">
|
||||
<title>Global modifications</title>
|
||||
|
||||
<para>
|
||||
|
||||
Instead of a dcop call, a program <command>screensaver</command> is
|
||||
executed, which must be found in the <envar>PATH</envar>. Just create
|
||||
a script called <command>screensaver</command>
|
||||
with the following contents:
|
||||
|
||||
<programlisting>
|
||||
#!/bin/bash
|
||||
|
||||
dcop kdesktop KScreensaverIface lock
|
||||
</programlisting>
|
||||
|
||||
make it executable and put it in <filename>$KDEDIR/bin</filename>.
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
Instead of the normal procedure, a program <command>klogout</command>
|
||||
is called, which must be found in the <envar>PATH</envar>. Create a
|
||||
script called <command>klogout</command> with the following contents:
|
||||
|
||||
<programlisting>
|
||||
#!/bin/bash
|
||||
|
||||
dcop kdesktop KDesktopIface logout
|
||||
</programlisting>
|
||||
make it executable and put it in <filename>$KDEDIR/bin</filename>,
|
||||
where <filename>$KDEDIR</filename> is the install directory of KDE and
|
||||
<filename>$KDEDIR/bin</filename> is found in your
|
||||
<EnVar>PATH</EnVar>.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
krootwm.cc.patch: klogout is executed instead of a dcop call
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
systemtrayapplet.cpp.patch: again call of klogout and screensaver
|
||||
instead of dcop calls.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
workspace.cpp.patch: call of klogout instead of dcop call.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
Everything else can be done with normal configuration, that is:
|
||||
|
||||
(Configuration files can be found in <filename>$KDEDIR/share/config</filename>)
|
||||
|
||||
Remove Trash, Templates and Autostart Icons from the desktop and disable
|
||||
<keycombo action="Simul"><keycap>Alt</keycap><keycap>F2</keycap></keycombo>
|
||||
by modifying <filename>kdeglobals</filename>. Make sure the following
|
||||
entries exist:
|
||||
|
||||
<programlisting>
|
||||
[Paths]
|
||||
|
||||
Trash=$HOME/.kde2/Trash/
|
||||
|
||||
Autostart=$HOME/.kde2/Autostart/
|
||||
|
||||
Templates=$HOME/.kde2/Templates/
|
||||
|
||||
Desktop=$HOME/.kde2/Desktop/
|
||||
|
||||
|
||||
[Global Keys]
|
||||
|
||||
Execute command=
|
||||
</programlisting>
|
||||
|
||||
(it may be <filename>.kde</filename> instead of <filename>.kde2</filename>)
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
disable Desktop menu and tips on start. Make sure the following entry
|
||||
exists in <filename>kdesktoprc</filename>:
|
||||
|
||||
<programlisting>
|
||||
[Mouse Buttons]
|
||||
|
||||
Right=
|
||||
|
||||
[General]
|
||||
|
||||
TipsOnStart=false
|
||||
</programlisting>
|
||||
|
||||
You could also login as the special user, and configure it only for
|
||||
him, then the config files are found in <filename>$KDEHOME/share/config</filename> where
|
||||
<filename>$KDEHOME</filename> is normally <filename>$HOME/.kde</filename>.
|
||||
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="kde-mode">
|
||||
<title>How to set the variable KDE_MODE</title>
|
||||
|
||||
<para>
|
||||
To answer this, you must understand what happens after you
|
||||
successfully authorized yourself to the system: Depending on your
|
||||
distribution, some scripts are executed, from which one should be
|
||||
modified to set <EnVar>KDE_MODE</EnVar>. There is a script called
|
||||
<Command>Xsession</Command> under <filename>/etc/X11/xdm</filename> or
|
||||
<filename>/usr/X11R6/lib/xdm</filename>, which you could modify, or
|
||||
<Command>startkde</Command>, that is located under
|
||||
<filename>$KDEDIR/bin</filename>. Note however, that the variable
|
||||
must be set prior to calling the kde processes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Since we had the need to make a setup for a big environment (now
|
||||
reaching 300 users) we wrote an application that enables us to
|
||||
administer. It also creates the KDE Menus. It writes a file called
|
||||
<filename>.env.sh</filename> in a user's home directory, that will be
|
||||
sourced in <Command>Xsession</Command>. That is what you could do. So
|
||||
you could put in <filename>.env.sh</filename> of that specific user's
|
||||
home directory:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
#!/bin/sh
|
||||
|
||||
KDE_MODE="restricted"
|
||||
|
||||
export KDE_MODE
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
and add to Xsession, somewhere prior to calling startkde:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
if [ -f $HOME/.env.sh ]; then
|
||||
|
||||
. $HOME/.env.sh
|
||||
|
||||
fi
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
We also have two kdedirs that looks like to separate installations of
|
||||
KDE, this was neccessary so "normal" users could still have a
|
||||
full-featured KDE. So we have an original kdedir, and a restricted
|
||||
kdedir, in which we removed entries under
|
||||
<filename>share/applnk</filename> and set the variable
|
||||
<envar>KDEDIR</envar> (under KDE 2 the variable <envar>KDEDIRS</envar>
|
||||
was introduced but <envar>KDEDIR</envar> is still used). The files
|
||||
under <filename>share/applnk</filename> make up the menu. Caution, you
|
||||
cannot just remove all files there, because some are needed to
|
||||
initialize KDE.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You also set the Variable <envar>KDEDIR</envar> in
|
||||
<command>Xsession</command>, after sourcing
|
||||
<filename>.env.sh</filename> like this:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
case "$KDE_MODE" in
|
||||
|
||||
restricted)
|
||||
|
||||
KDEDIR=/usr/local/kde/restricted_kdedir
|
||||
|
||||
;;
|
||||
|
||||
*)
|
||||
|
||||
KDEDIR=/usr/local/kde
|
||||
|
||||
esac
|
||||
|
||||
export KDEDIR
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
Replace <filename>/usr/local/kde</filename> with the install directory
|
||||
of your KDE. The contents of
|
||||
<filename>/usr/local/kde/restricted_kdedir</filename> looks like:
|
||||
|
||||
<screen>
|
||||
|
||||
bin -> ../bin
|
||||
|
||||
cgi-bin -> ../cgi-bin
|
||||
|
||||
etc -> ../etc
|
||||
|
||||
lib -> ../lib
|
||||
|
||||
share
|
||||
|
||||
</screen>
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
only share is a real directory, every other directory is a symbolic
|
||||
link pointing to original
|
||||
kdedir. <filename>/usr/local/kde/restricted_kdedir/share</filename>
|
||||
has the following contents:
|
||||
|
||||
<screen>
|
||||
|
||||
aclocal -> ../../share/aclocal
|
||||
|
||||
applnk
|
||||
|
||||
apps -> ../../share/apps
|
||||
|
||||
autostart -> ../../share/autostart
|
||||
|
||||
config -> ../../share/config
|
||||
|
||||
doc -> ../../share/doc
|
||||
|
||||
fonts -> ../../share/fonts
|
||||
|
||||
icons -> ../../share/icons
|
||||
|
||||
locale -> ../../share/locale
|
||||
|
||||
mimelnk -> ../../share/mimelnk
|
||||
|
||||
services -> ../../share/services
|
||||
|
||||
servicetypes -> ../../share/servicetypes
|
||||
|
||||
sounds -> ../../share/sounds
|
||||
|
||||
templates -> ../../share/templates
|
||||
|
||||
wallpapers -> ../../share/wallpapers
|
||||
|
||||
</screen>
|
||||
|
||||
</para>
|
||||
|
||||
<para>
|
||||
only applnk is a real directory. As a minimal requirement remove
|
||||
everything except:
|
||||
|
||||
<screen>
|
||||
|
||||
Settings/Peripherals/mouse.desktop
|
||||
|
||||
Settings/LookNFeel/background.desktop
|
||||
|
||||
/colors.desktop
|
||||
|
||||
/kwinoptions.desktop
|
||||
|
||||
/style.desktop
|
||||
|
||||
/virtualdesktops.desktop
|
||||
|
||||
</screen>
|
||||
|
||||
under <filename>/usr/local/kde/restricted_kdedir/share/applnk</filename>
|
||||
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
</article>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-namecase-general:t
|
||||
sgml-general-insert-case:lower
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:nil
|
||||
sgml-parent-document:nil
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
-->
|
|
@ -0,0 +1,110 @@
|
|||
<!doctype article public "-//OASIS//DTD DocBook V4.1//EN"
|
||||
[
|
||||
<!entity header system "header.sgml">
|
||||
<!entity sectionpamnss SYSTEM "section-pamnss.sgml">
|
||||
<!entity sectionsasl SYSTEM "section-sasl.sgml">
|
||||
<!entity sectionradius SYSTEM "section-radius.sgml">
|
||||
<!entity sectionsamba SYSTEM "section-samba.sgml">
|
||||
<!entity sectiondns SYSTEM "section-dns.sgml">
|
||||
<!entity sectionsendmail SYSTEM "section-sendmail.sgml">
|
||||
<!entity sectionaddress SYSTEM "section-address.sgml">
|
||||
<!entity sectionroaming SYSTEM "section-roaming.sgml">
|
||||
<!entity sectioncertificates SYSTEM "section-certificates.sgml">
|
||||
<!entity sectionssl SYSTEM "section-ssl.sgml">
|
||||
<!entity sectionsecurity SYSTEM "section-security.sgml">
|
||||
<!entity sectionperformance SYSTEM "section-performance.sgml">
|
||||
<!entity sectionttt SYSTEM "section-ttt.sgml">
|
||||
<!entity sectionschemas SYSTEM "section-schemas.sgml">
|
||||
<!entity sectionfiles SYSTEM "section-files.sgml">
|
||||
<!entity fileslapdconf SYSTEM "lih-slapd.conf">
|
||||
<!entity fileldapconf SYSTEM "lih-ldap.conf">
|
||||
<!entity fileschema SYSTEM "lih-schema.conf">
|
||||
<!entity fileldifstructure SYSTEM "lih-structure.ldif">
|
||||
]>
|
||||
<ARTICLE ID="INDEX"><ARTICLEINFO><TITLE>LDAP Implementation HOWTO</TITLE>
|
||||
<PUBDATE>v0.5, 2001-03-30</PUBDATE>
|
||||
<AUTHOR><FIRSTNAME>Roel</FIRSTNAME>
|
||||
<OTHERNAME>van</OTHERNAME>
|
||||
<SURNAME>Meer</SURNAME>
|
||||
<AFFILIATION><ORGNAME><ULINK URL="http://www.linvision.com">Linvision BV</ULINK></ORGNAME>
|
||||
<ADDRESS FORMAT="LINESPECIFIC"><EMAIL>r.vanmeer@linvision.com</EMAIL></ADDRESS></AFFILIATION></AUTHOR>
|
||||
<AUTHOR><FIRSTNAME>Giuseppe</FIRSTNAME>
|
||||
<OTHERNAME>Lo</OTHERNAME>
|
||||
<SURNAME>Biondo</SURNAME>
|
||||
<AFFILIATION><ORGNAME><ULINK
|
||||
URL="http://www.mi.infn.it">INFN MI</ULINK></ORGNAME>
|
||||
<ADDRESS FORMAT="LINESPECIFIC"><EMAIL>giuseppe.lobiondo@mi.infn.it</EMAIL></ADDRESS></AFFILIATION></AUTHOR>
|
||||
<ABSTRACT><PARA>This document describes the technical aspects of storing application data in an ldap server. It focuses on the configuration of various applications to make them ldap-aware. Some applications that assist in handling ldap data are also discussed.</PARA></ABSTRACT>
|
||||
|
||||
<REVHISTORY>
|
||||
<REVISION>
|
||||
<REVNUMBER>0.5</REVNUMBER>
|
||||
<DATE>2001-03-30</DATE>
|
||||
<AUTHORINITIALS>rvm</AUTHORINITIALS>
|
||||
<REVREMARK>Cleanup, fixes, overview rewritten.</REVREMARK></REVISION>
|
||||
<REVISION>
|
||||
<REVNUMBER>0.4</REVNUMBER>
|
||||
<DATE>2001-02-01</DATE>
|
||||
<AUTHORINITIALS>rvm</AUTHORINITIALS>
|
||||
<REVREMARK>Added dns section.</REVREMARK></REVISION>
|
||||
<REVISION>
|
||||
<REVNUMBER>0.3</REVNUMBER>
|
||||
<DATE>2001-01-18</DATE>
|
||||
<AUTHORINITIALS>rvm</AUTHORINITIALS>
|
||||
<REVREMARK>Added MTA sections.</REVREMARK></REVISION>
|
||||
<REVISION>
|
||||
<REVNUMBER>0.2</REVNUMBER>
|
||||
<DATE>2000-11-12</DATE>
|
||||
<AUTHORINITIALS>glb</AUTHORINITIALS>
|
||||
<REVREMARK>Improved section on nss. Added sections about certificates and wrappers.</REVREMARK></REVISION>
|
||||
</REVHISTORY>
|
||||
</ARTICLEINFO>
|
||||
|
||||
<SECT1 ID="OVERVIEW"><TITLE>Overview</TITLE>
|
||||
<SECT2><TITLE>Why this howto?</TITLE>
|
||||
<PARA>I started learning about ldap when my company felt the need for a centralized storage of user account information, and wanted to use ldap for this. I soon found that there were bits and pieces of documantation everywhere, but that there was no document that put it all together. This has been the reason to start it.</PARA>
|
||||
<PARA>Furthermore, Ldap is becoming more widely used every day. I think it is useful that when people are considering to use Ldap, they can get a full overview of which applications are Ldap aware. This might help them to choose their system setup carefully, without throwing everything about every time they want to change something or add functionality.</PARA>
|
||||
|
||||
<PARA>It started out as a project roadmap on how we wanted to implement Ldap for our own uses. But thanks to my employer, <ULINK URL="http://www.linvision.com">Linvision</ULINK>, who gave me the opportunity to do some research on things that weren't really useful to our own cause, it changed from a roadmap to a technical overview of applications that are ldap aware.</PARA>
|
||||
</SECT2>
|
||||
<SECT2><TITLE>What is it about?</TITLE>
|
||||
<PARA>Most of the common services can be authenticated through PAM, Pluggable Authentication Modules. With the pam_ldap and nss_ldap modules, all pamified programs can get their information from LDAP. More information about PAM in general can be found on <ULINK URL="http://www.kernel.org/pub/linux/libs/pam/">the Linux-PAM site</ULINK>. Information about pam_ldap and nss_ldap can be found on the <ULINK URL="http://www.padl.com">padl software</ULINK> site.</PARA>
|
||||
<PARA>For Samba, things are a little difficult at this moment. The current stable Samba versions do not have Ldap support. Ldap support can be found in the HEAD and TNG branch, and probably also in the combined tree. The problem is that samba has it's own usernames and passwords. It does have usage for PAM, in fact, but that is not sufficient to do all the authentication and retrieval of user information. Because the implementation of LDAP in samba is not fully finished yet, there are a few limitations to the use of ldap with samba. From my experiences, the HEAD is at this time (early June 2000) not stable enough, and the performance is unsatisfying. However, when the ldap support is fully functional in the new releases, samba too can be configured to get all of it's user information from ldap.</PARA>
|
||||
<PARA>Another thing that can be stored into an ldap database is DNS. When the amount of machines connected to your network increases, it is no longer feasable to edit the DNS files by hand. When machine accounts are stored into ldap, two simple DNS entries (one for the lookup, and one for the reverse lookup) can easily be added at the same time. This too provides a simplification of system management. Although the storage of DNS entries in an ldap database may not be neccesary for most systems, it may prove useful to some people.</PARA>
|
||||
<PARA>Since sendmail version 8.9 (see <ULINK URL="http://www.sendmail.net/">sendmail.net</ULINK>
|
||||
for more details), sendmail has Ldap support. Postfix and QMail are ldap-aware too. When setting up an email system which has multiple mailhosts and or fallback hosts, it is convenient to store all the information in one place. Normally, every system needs to be configured separately, with the same information. When using ldap, this can be avoided.</PARA>
|
||||
<PARA>Roaming access can also be used with LDAP. Netscape versions 4.5 and up have the possibility to store user data like bookmarks and such via an HTML or LDAP server. This gives users their good old preferences, wherever they log in and use Netscape.</PARA>
|
||||
<PARA>Microsoft's office programs can import address books. Thay can also use an Active Directory service to automagically match emailaddresses to user names or nicknames. With Ldap this can be done on a Linux system, without the need for Microsoft Exchange Server or something the like.</PARA></SECT2>
|
||||
|
||||
<SECT2><TITLE>What is it NOT about?</TITLE>
|
||||
<PARA>First thing: I will try not to talk too much about the actual setup and administration of Ldap itself.
|
||||
There is an excellent Ldap HOWTO available at the Linux Documentation Project that discusses this.</PARA>
|
||||
<PARA>Secondly, I will not discuss things regarding the applications itself, when they have nothing to do with Ldap.</PARA>
|
||||
<PARA>Lastly, in most cases, I cannot tell you if it is wise to use Ldap. I don't have that kind of experience. I can tell you how to do it, if you want, but i cannot tell you if you should. There is plenty documentaion available that discusses the useability of Ldap in general.</PARA>
|
||||
</SECT2>
|
||||
|
||||
<SECT2><TITLE>Acknowledgements</TITLE>
|
||||
<PARA>At first, I would like to thank my employer, <ULINK URL="http://www.linvision.com">Linvision</ULINK>, for giving me the opportunity to work on this document in their time.</PARA>
|
||||
<PARA>Furthermore, I would like to thank the following people, who have contributed to this document in some way (in no particular order): Giuseppe Lo Biondo.</PARA></SECT2>
|
||||
|
||||
<SECT2><TITLE>Disclaimer</TITLE>
|
||||
<PARA>This document is provided as is and should be considered as a work in progress. Several sections are as yet unfinished, and probably a lot of things that should be in here, aren't. I would greatly appreciate any comments on this document, of whatever nature they may be.</PARA>
|
||||
<PARA>In any case, think before you go messing around with your system and don't come to me if it breaks.</PARA></SECT2>
|
||||
|
||||
<SECT2><TITLE>Copyright and license</TITLE>
|
||||
<PARA>Copyright (c) by Roel van Meer, Giuseppe Lo Biondo. This document
|
||||
may be distributed only subject to the terms and conditions set forth in
|
||||
the LDP License at the <ULINK URL="http://www.linuxdoc.org/COPYRIGHT.html">Linux Documentation Project</ULINK>.</PARA></SECT2></SECT1>
|
||||
§ionpamnss;
|
||||
§ionradius;
|
||||
§ionsamba;
|
||||
§iondns;
|
||||
§ionsendmail;
|
||||
§ionaddress;
|
||||
§ionroaming;
|
||||
§ioncertificates;
|
||||
§ionssl;
|
||||
§ionschemas;
|
||||
§ionfiles;
|
||||
</ARTICLE>
|
||||
|
|
@ -0,0 +1,632 @@
|
|||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!-- for extra DocBook help check http://www-106.ibm.com/developerworks/linux/library/l-docbk.html -->
|
||||
|
||||
<article>
|
||||
<articleinfo>
|
||||
<title>Linux + XFS HOWTO</title><subtitle>Linux on Steroids</subtitle>
|
||||
<author>
|
||||
<firstname>Russel</firstname>
|
||||
<surname>Ingram</surname>
|
||||
<affiliation>
|
||||
<address>
|
||||
<email>ringram@gargoylecc.com</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<date>v1.1, May 12, 2002</date>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>v1.1</revnumber>
|
||||
<date>2002-05-12</date>
|
||||
<authorinitials>ri</authorinitials>
|
||||
<revremark>
|
||||
Updated sgi cvs info to match current state; made various changes/clarifications based on reader feedback
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v1.02</revnumber>
|
||||
<date>2001-10-08</date>
|
||||
<authorinitials>ri</authorinitials>
|
||||
<revremark>
|
||||
Added some note, blockquote and ulink tags.
|
||||
Corrected error in command section of "Finishing Up".
|
||||
Changed note about e2fsprogs-devel to refer to libuuid.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v1.01</revnumber>
|
||||
<date>2001-10-04</date>
|
||||
<authorinitials>ri</authorinitials>
|
||||
<revremark>
|
||||
Corrected error in "Finishing up" section; various formatting changes
|
||||
</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
||||
<abstract><para>
|
||||
This document describes how to build a Linux system that runs
|
||||
on top of the SGI XFS journaling filesystem.
|
||||
</para></abstract>
|
||||
|
||||
</articleinfo>
|
||||
<sect1>
|
||||
<title>Introduction</title>
|
||||
<sect2>
|
||||
<title> Introduction to XFS for Linux </title>
|
||||
<para>
|
||||
This document describes how to build a Linux system that runs
|
||||
on top of the SGI XFS journaling filesystem. From the XFS FAQ: "XFS
|
||||
is a journalling filesystem developed by SGI and used in SGI's IRIX
|
||||
operating system. It is now also available under GPL for linux. It
|
||||
is extremely scalable, using btrees extensively to support large
|
||||
sparse files, and extremely large directories. The journalling capability
|
||||
means no more waiting for fsck's or worrying about meta-data corruption."
|
||||
Essentialy XFS is the filesystem SGI designed for its highend server
|
||||
systems, hence the subtitle of this document, "Linux on Steroids".
|
||||
:-)
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title> Foreword, Feedback, & Credits </title>
|
||||
<para>
|
||||
As a fairly new member of the Irix System Administrator community
|
||||
I have fallen in love with the robustness of the filesystem that
|
||||
has been developed to support Irix (XFS of course). So, needless
|
||||
to say I've been following the porting effort to Linux for quite
|
||||
some time and have dreamed of being able to run my Linux systems
|
||||
on top of an all XFS filesystem since the beginning. The project
|
||||
has come to a point (actually nearly a year ago at the time of this
|
||||
writing) that this could actually be a reallity. However, as is
|
||||
the case with a great deal of programming/porting projects, the documentation
|
||||
for such task is not always as readily available or easy to follow
|
||||
as one might hope. This document is an attempt to remedy that situation.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
The information contained in this document is based on messages
|
||||
from Jason Walker and Russell Cattelan taken from the XFS development
|
||||
mailing list, information gathered from various places on the SGI
|
||||
Open Source Development web site, and from my own experiences setting
|
||||
up such a system.
|
||||
</para>
|
||||
<para>
|
||||
Please feel free to email me at <email>ringram@gargoylecc.com</email> if you
|
||||
have any corrections or if any imformation/URLs/etc. is missing.
|
||||
The more feedback I get on this HOWTO the more helpful it will be
|
||||
for all.
|
||||
</para>
|
||||
<para>
|
||||
The latest version of this document can be found at
|
||||
<ulink url="http://www.gargoylecc.com/Linux+XFS-HOWTO/t1.html">
|
||||
Gargoyle Computer Consulting
|
||||
</ulink>.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Copyright & Disclaimer</title>
|
||||
<para>
|
||||
This document is copyright(c) 2001 Russel Ingram and it is a
|
||||
FREE document. You may redistribute it under terms of the GNU General
|
||||
Public License.
|
||||
</para>
|
||||
<para>
|
||||
The information contained in this document is, to the best of
|
||||
Russel's knowledge, correct. However, the XFS Linux port is written
|
||||
by humans and thus, there is the chance that mistakes, bugs, etc.
|
||||
might happen from time to time.
|
||||
</para>
|
||||
<para>
|
||||
No person, group, or other body is responsible for any damage
|
||||
on your computer(s) and any other losses by using the information
|
||||
in this document. i.e.
|
||||
</para>
|
||||
<para>
|
||||
|
||||
</para>
|
||||
<para>
|
||||
<emphasis>
|
||||
THE AUTHOR IS NOT RESPONSIBLE FOR ANY DAMAGES INCURRED DUE TO
|
||||
ACTIONS TAKEN BASED ON THE INFORMATION IN THIS DOCUMENT.
|
||||
</emphasis>
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1>
|
||||
<title> Preparation for XFS Installation </title>
|
||||
<sect2>
|
||||
<title> Downloading the Linux 2.4.x-XFS Kernel Source </title>
|
||||
<para>
|
||||
Currently the only place to get the source code for the XFS enabled
|
||||
Linux kernel is straight from SGI's Open Source Development site
|
||||
via CVS.
|
||||
</para>
|
||||
<note>
|
||||
<title>Note</title>
|
||||
<para>two distinct trees are available:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>linux-2.5-xfs: development tree</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>linux-2.4-xfs: stable bug fix only tree</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
My experience has been with the 2.4 tree, but I imagine everything
|
||||
will work the same with the development tree. Both trees are kept
|
||||
in sync with their respective mainline kernel tree at least to the
|
||||
point of major release numbers.
|
||||
</para>
|
||||
<para>
|
||||
Here are the steps to download the kernel source tree:
|
||||
|
||||
</para>
|
||||
<para>
|
||||
A. Normally the linux kernel source is installed in the /usr/src
|
||||
directory, so you should start off by switching to that directory.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cd /usr/src
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
B. Next, you should set the CVSROOT environment variable so that
|
||||
it points to the proper cvs server.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
If you are running sh, bash, ksh, etc...:
|
||||
<programlisting>
|
||||
$ export CVSROOT=':pserver:cvs@oss.sgi.com:/cvs'
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
If you are running csh or tcsh:
|
||||
<programlisting>
|
||||
$ setenv CVSROOT :pserver:cvs@oss.sgi.com:/cvs
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
If you plan on updating your kernel often (to keep up with the
|
||||
latest changes) you might want to put this in your login script.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
C. Then log in to the cvs server.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cvs login (the password is "cvs")
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
This needs to be done only ONCE, not everytime you access CVS.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
D. Now grab linux-2.4-xfs. The first time you will want to do
|
||||
something like:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cvs -z3 co linux-2.4-xfs
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
After you have checked the code out, you can use:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cvs -z3 update linux-2.4-xfs
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
to update your copy to the latest version from the CVS server.
|
||||
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title> XFS Support as Modules or Compiled Into the Kernel? </title>
|
||||
<para>
|
||||
The option to build XFS support for the Linux kernel as modules
|
||||
is available and will work (or so I am told) with the help of an
|
||||
initial RAM disk and a couple of additions to the lilo configuration.
|
||||
I have not tried this (yet), so I will not include documentation
|
||||
on how this is done other than just to qoute from a message to the
|
||||
development mailing list from Russell Cattelan:
|
||||
</para>
|
||||
<blockquote>
|
||||
<attribution>
|
||||
<author>
|
||||
<firstname>Russell</firstname><surname>Cattelan</surname>
|
||||
</author>
|
||||
</attribution>
|
||||
<para>
|
||||
Actually running xfs as a module isn't very hard. in the
|
||||
directory cmd/xfs/misc there is a modified mkinitrd the will always
|
||||
generate a ram disk with pagebuf xfs_support and xfs.
|
||||
</para>
|
||||
<para>
|
||||
Once that is done just add the initrd line in lilo.conf AND
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
append = "ramdisk_size=25000"
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
The default size is 4096 which isn't nearly large enough to hold
|
||||
xfs.
|
||||
</para>
|
||||
<para>
|
||||
This is from my laptop.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
punch[12:57am]-=>mount
|
||||
/dev/ide/host0/bus0/target0/lun0/part8 on / type xfs (rw,noatime)
|
||||
none on /proc type proc (rw)
|
||||
/dev/ide/host0/bus0/target0/lun0/part6 on /boot type ext2 (rw,noatime)
|
||||
none on /dev/pts type devpts (rw,mode=0620)
|
||||
/dev/ide/host0/bus0/target0/lun0/part1 on /mnt/windows type vfat (rw,nosuid,nodev,umask=0)
|
||||
/dev/ide/host0/bus0/target0/lun0/part9 on /blam type xfs (rw)
|
||||
|
||||
punch[12:57am]-=>lsmod
|
||||
Module Size Used by
|
||||
autofs 13180 1 (autoclean)
|
||||
usb-uhci 24918 0 (unused)
|
||||
usbcore 35339 0 [usb-uhci]
|
||||
3c59x 25149 1 (autoclean)
|
||||
maestro 29757 0 (unused)
|
||||
soundcore 6085 2 [maestro]
|
||||
vfat 13075 1 (autoclean)
|
||||
fat 37733 0 (autoclean) [vfat]
|
||||
xfs 447888 2
|
||||
xfs_support 13954 0 [xfs]
|
||||
pagebuf 39935 2 [xfs]
|
||||
|
||||
|
||||
image=/boot/vmlinuz-2.4.0-XFS-test13-pre4
|
||||
label=t13p4
|
||||
root=/dev/hda8
|
||||
initrd=/boot/initrd-2.4.0-XFS-test13p4.img
|
||||
append="ramdisk_size=25000"
|
||||
read-only
|
||||
</programlisting>
|
||||
</para>
|
||||
</blockquote>
|
||||
<para>
|
||||
It seems to me that compiling the support into the kernel would
|
||||
be much simpler, so that is how I am doing it at this point. I will
|
||||
try it as a module at a later time and add more detailed instructions
|
||||
then. If anyone has time to document this method before I get around
|
||||
to it please email it to me and I will include it with credit given
|
||||
where credit is due. :-)
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1>
|
||||
<title> Kernel Configuration and Installation </title>
|
||||
<sect2>
|
||||
<title>Configuring your kernel for XFS support</title>
|
||||
<note>
|
||||
<title>Note</title>
|
||||
<para>
|
||||
If you have never configured and compiled a new linux kernel
|
||||
you might consider reading the Linux Kernel HOWTO before doing this
|
||||
step. It can be found at the
|
||||
<ulink url="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html">
|
||||
Linux Documentation Project (LDP)
|
||||
</ulink>
|
||||
or one of its mirrors.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
After having downloaded the cvs source tree the actual kernel
|
||||
source will be in /usr/src/linux-2.4-xfs(-beta)/linux, so you should
|
||||
switch to that directory before running the make config command of
|
||||
your choice. The main things that must be included in your kernel
|
||||
to provide XFS support are "Page Buffer support" and (duh)
|
||||
"SGI XFS filesystem support." Both options are available
|
||||
in the "File systems" section of the kernel configuration.
|
||||
You will need to have "Prompt for development and/or incomplete
|
||||
code/drivers" selected under "Code maturity level options"
|
||||
for those options to be available to you. Optionally, you may also
|
||||
want to select "Enable XFS Debug mode" and "Enable
|
||||
XFS Vnode Tracing" under "SGI XFS filesystem support."
|
||||
These options may slow your XFS implementation some, but may be useful
|
||||
in tracing the cause of a crash if a crash occurs.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Building the kernel and modules</title>
|
||||
<para>
|
||||
As with any kernel build, the following commands must be run
|
||||
to actually build the new kernel:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ make dep
|
||||
$ make bzImage
|
||||
$ make modules
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Installing the new kernel and modules</title>
|
||||
<para>
|
||||
Again this is standard for any kernel installation:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ make modules_install
|
||||
$ cp arch/i386/boot/bzImage /boot/vmlinuz-2.4.0-XFS
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Add a new entry to your lilo configuration and re-install lilo</title>
|
||||
|
||||
<para>
|
||||
<programlisting>
|
||||
$ vi /etc/lilo.conf
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Add a new image section to your lilo.conf file similar to the
|
||||
following:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
image=/boot/vmlinuz-2.4.0-XFS label=xfs read-only root=/dev/hda2
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
The "root=" line should match the "root="
|
||||
line from the existing image sections in your lilo.conf file. Don't
|
||||
forget to run lilo when you're through editing lilo.conf to make
|
||||
the changes effective.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Build and install the XFS utilities</title>
|
||||
<para>
|
||||
There are a number of tools that come with the XFS filesystem that allow
|
||||
you to build and manage your XFS filesystems that must be built as well.
|
||||
These tools are in the /usr/src/linux-2.4-xfs(-beta)/cmd/xfsprogs directory.
|
||||
</para>
|
||||
<note>
|
||||
<title>Note</title>
|
||||
<para>These tools rely on the /usr/lib/libuuid.a shared library. If you
|
||||
do not have this library installed you will need it in order for
|
||||
the XFS utilities to compile. You can find the rpm package for
|
||||
your version of Linux from <ulink url="http://www.rpmfind.net">Rpmfind.net</ulink> by searching for "/usr/lib/libuuid.a." The debian package that contains libuuid is uuid-dev. There will no doubt be other distributions that package this library in another place. A good way to find the correct package on those distributions is to search on the <ulink url="http://www.google.com/linux">Google Linux</ulink> search engine.
|
||||
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
Change to that directory:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cd ../cmd/xfsprogs
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Build and install the xfs utilities:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ make install
|
||||
</programlisting>
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Boot the new kernel</title>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ reboot
|
||||
</programlisting>
|
||||
</para>
|
||||
<note>
|
||||
<title>Note</title>
|
||||
<para>
|
||||
Unless you changed the default label to boot in your lilo.conf
|
||||
file you will need to enter "xfs" at the "LILO Boot:"
|
||||
prompt in order to boot the new kernel image.
|
||||
</para>
|
||||
</note>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1>
|
||||
<title>Filesystem Migration</title>
|
||||
<para>
|
||||
The final part of this whole process is probably actually the
|
||||
trickiest and most dangerous as far as the possibility of losing
|
||||
your data goes. I strongly suggest that you make a complete backup
|
||||
of the system (or at least all important data) before attempting
|
||||
the migration to XFS. This part is also the most difficult to explain
|
||||
as there are probably hundreds of ways you can do this based on
|
||||
the set up of your existing filesystem. I will give you the basic
|
||||
commands for creating the new filesystems, try to give some pointers
|
||||
on how to go about shuffling filesystems, and in general just relay
|
||||
to you the way I went about migrating my own filesystems.
|
||||
</para>
|
||||
<sect2>
|
||||
<title>Migrating the / filesystem</title>
|
||||
<para>
|
||||
Probably the trickiest part of creating a fully XFS system is
|
||||
migrating the / filesystem since that is the system that supports
|
||||
the entire rest of the system and it cannot actually be unmounted
|
||||
while the system is running. If you have extra partitions that
|
||||
can be mounted as / then you will be able to do it something like
|
||||
this(I am using /dev/hda4 as the spare partition and /dev/hda2 as
|
||||
/ for this example):
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ mkfs -t ext2 /dev/hda4
|
||||
$ mkdir /mnt/temp
|
||||
$ mount -t ext2 /dev/hda4 /mnt/temp
|
||||
$ cd /
|
||||
$ tar lcf - .|(cd /mnt/temp; tar xpvf - )
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Notice I have used tar here to copy the files from the / fs to
|
||||
the spare partition. Alternatively you could use cp -dpR, but if
|
||||
you use tar like I've shown here with the -l flag it will copy only
|
||||
files from within the / fs (i.e. if you have another partition mounted
|
||||
as /usr it won't copy those).
|
||||
</para>
|
||||
<para>
|
||||
The next step will be to change all references to /dev/hda2 to
|
||||
/dev/hda4 in /etc/fstab and in /etc/lilo.conf and run lilo. You'll
|
||||
then need to reboot the system again.
|
||||
</para>
|
||||
<para>
|
||||
After rebooting the system /dev/hda4 will be mounted as / and
|
||||
your original / filesystem (/dev/hda2) will not be mounted. You
|
||||
can now create the new XFS filesystem on /dev/hda2.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ mkfs -t xfs /dev/hda2
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Then mount the new xfs fs:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ mount -t xfs /dev/hda2 /mnt/temp
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
And copy the original / fs back to its original home:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cd /
|
||||
$ tar lcf - .|(cd /mnt/temp; tar xpvf -)
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Once again you will need to change all instances of /dev/hda4
|
||||
in /etc/fstab and /etc/lilo.conf and run lilo. You will also need
|
||||
to change the filesystem type for / in /etc/fstab. It should now
|
||||
look something like this:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
/dev/hda2 / xfs defaults 1 1
|
||||
</programlisting>
|
||||
</para>
|
||||
<note>
|
||||
<title>Note</title>
|
||||
<para>
|
||||
On some linux distributions the options given to the out-of-box
|
||||
fstab may be more in depth than just "defaults." For
|
||||
instance, on Debian systems they use "defaults,errors=remount-ro."
|
||||
The mount options are different for every filesystem with the exception
|
||||
of the keyword "defaults." Unless you know the specific
|
||||
XFS mount options you want you should stick with just the defaults
|
||||
option. In the Debian example given, the errors option is not available
|
||||
with XFS and will cause your filesystem not to mount.
|
||||
</para>
|
||||
<para>
|
||||
Additionally, filesystem labels are becoming more popular so you may see an
|
||||
entry in your fstab that looks something like this:
|
||||
<programlisting>
|
||||
LABEL=/ / ext2 defaults 1 1
|
||||
</programlisting>
|
||||
The easiest way to avoid problems is to simply replace the referenced label
|
||||
with the proper device file name (i.e. if /dev/hda1 is labeled / replace "LABEL=/"
|
||||
with "/dev/hda1").
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
Now reboot the system with the new xfs / filesystem.
|
||||
</para>
|
||||
<para>
|
||||
Of course there are a lot of other ways to accomplish the root
|
||||
filesystem migration and if you think you have a good one I would
|
||||
definitely like to hear it and will put it in this doc if it seems
|
||||
like a simpler way than what is here. I, myself, didn't have a
|
||||
spare partition to work with but had a CD burner so I burnt a cd
|
||||
of my root filesystem to mount as root while I created the new xfs
|
||||
/. In all cases, however, the basic commands for creating and mounting
|
||||
the new filesystem will be the same.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Finishing up</title>
|
||||
<para>
|
||||
The last of the process is fairly simple and essentially the
|
||||
same process of swapping around partitions while making new filesystems
|
||||
as was done for /. I recommend that you do the rest of this process
|
||||
with the system in single user mode so you can unmount everything
|
||||
other than / and do all of the swapping without having to reboot
|
||||
a million times. You can boot to single user mode by either issueing
|
||||
a runlevel change command to the init process like so:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ telinit 1
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
or by rebooting and asking for single user mode at the Lilo prompt:
|
||||
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
LILO Boot: xfs single
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
This will boot the system and drop you into a root shell with
|
||||
no outside connections or virtual terminals so there is no chance
|
||||
of any of the filesystems being in use by other users or processes
|
||||
(causing them to be busy so you can't unmount them). Now you can
|
||||
mount the spare partition, as before, copy one of the remaining filesystems
|
||||
to be migrated onto it (you will probably have to remove the existing
|
||||
contents leftover from /), unmount the old filesystem, create the
|
||||
xfs filesystem on it, remount it as xfs, and copy the old filesystem
|
||||
back onto it. Lets say you have a /dev/hda3 partition mounted as
|
||||
/usr. The process would go something like this:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ mount -t ext2 /dev/hda4 /mnt/temp
|
||||
$ cd /usr
|
||||
$ tar lcf - .|(cd /mnt/temp; tar xpvf - )
|
||||
$ cd /mnt/temp
|
||||
$ umount /usr
|
||||
$ mkfs -t xfs /dev/hda3
|
||||
$ mount -t xfs /dev/hda3 /usr
|
||||
$ tar lcf - .|(cd /usr; tar xpvf - )
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Don't forget to change the filesystem type in /etc/fstab for
|
||||
/usr to xfs.
|
||||
</para>
|
||||
<para>
|
||||
That's all there is to it. The rest of the filesystems to be
|
||||
migrated will work the same way, then you can reboot to full miltiuser
|
||||
mode and you've got your "Linux on Steroids!"
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</article>
|
|
@ -0,0 +1,417 @@
|
|||
<!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
|
||||
<article>
|
||||
<articleinfo>
|
||||
<title>Using Term to Pierce an Internet Firewall mini-HOWTO</title>
|
||||
|
||||
<copyright><year>1996</year><holder>Barak Pearlmutter</holder></copyright>
|
||||
<copyright><year>2001</year><holder>David C. Merrill</holder></copyright>
|
||||
|
||||
<author>
|
||||
<firstname>Barak</firstname>
|
||||
<surname>Pearlmutter</surname>
|
||||
<affiliation>
|
||||
<address><email>bap@cs.unm.edu</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>David</firstname>
|
||||
<othername>C.</othername>
|
||||
<surname>Merrill</surname>
|
||||
<affiliation>
|
||||
<address>david -AT- lupercalia.net</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>1.1</revnumber>
|
||||
<date>2001-07-14</date>
|
||||
<authorinitials>dcm</authorinitials>
|
||||
<revremark>
|
||||
Cleaned up a bit, reorganized a bit, converted to DocBook SGML
|
||||
and relicensed under GFDL.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>1.0</revnumber>
|
||||
<date>1996-07-15</date>
|
||||
<authorinitials>pb</authorinitials>
|
||||
<revremark>Initial Release.</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
This document explains how to use the <command>term</command> program
|
||||
to pierce a firewall from the inside, even without root privileges.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Term is an old program that almost no one uses anymore,
|
||||
because the 7-bit serial lines it is meant to cross are nowhere
|
||||
to be found anymore, and full IP ppp access is dirt cheap.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<important>
|
||||
<para>
|
||||
<emphasis role="strong">Archived Document Notice: </emphasis>
|
||||
This document has been archived by the LDP because it does not apply
|
||||
to modern Linux systems. It is no longer being actively maintained.
|
||||
</para>
|
||||
</important>
|
||||
</para>
|
||||
|
||||
</abstract>
|
||||
|
||||
</articleinfo>
|
||||
|
||||
<sect1 id="preface">
|
||||
<title>Preface</title>
|
||||
|
||||
<sect2 id="disclaimer">
|
||||
<title>Disclaimer</title>
|
||||
|
||||
<para>
|
||||
While every precaution has been taken in the preparation of this document,
|
||||
the Linux Documentation Project and the author(s) assume no responsibility
|
||||
for errors or omissions, or for damages resulting from the use of the
|
||||
information contained herein.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="license">
|
||||
<title>License</title>
|
||||
|
||||
<para>
|
||||
This document is made available under the terms of the
|
||||
<ulink url="http://www.gnu.org/copyleft/fdl.html"><citetitle>GNU Free Documentation License (GFDL)</citetitle></ulink>,
|
||||
which is hereby incorporated by reference.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="introduction">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
The <command>term</command> program is usually used to provide host-to-host services
|
||||
over a modem or serial line.
|
||||
|
||||
However, sometimes it is useful to establish a term
|
||||
connection between two machines that communicate via telnet.
|
||||
The most
|
||||
interesting example is connecting two hosts which are
|
||||
separated by ethernet firewalls or SOCKS servers. Such firewalls
|
||||
provide facilities for establishing a telnet connection through the
|
||||
firewall, typically by using the SOCKS protocol, to allow inside
|
||||
machines to get connections out, and requiring outside users to telnet
|
||||
first to a gateway machine which requires a one-time password. These
|
||||
firewalls make it impossible to, for instance, have X clients on an
|
||||
inside machine communicate with an X server on an outside machine.
|
||||
But, by setting up a term connection, these restrictions can all be
|
||||
bypassed quite conveniently, at the user level.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="basics">
|
||||
<title>The Basic Procedure</title>
|
||||
|
||||
<para>
|
||||
Setting up a term connection over a telnet substrate is a two-phase
|
||||
process. First your usual telnet client is used to set up a telnet
|
||||
connection and log in. Next, the telnet client is paused and control
|
||||
of the established telnet connection is given to term.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="details">
|
||||
<title>Detailed Directions</title>
|
||||
|
||||
<para>
|
||||
First, from a machine inside the firewall, telnet to a target machine
|
||||
outside the firewall and log in.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Unless you are under linux and will be using the proc filesystem (see
|
||||
below) make sure your shell is an sh style shell. Ie if your default
|
||||
shell is a csh variant, invoke telnet by:
|
||||
</para>
|
||||
|
||||
<para><screen>setenv SHELL /bin/sh; telnet machine.outside</screen></para>
|
||||
|
||||
<para>
|
||||
After logging in, on the remote (outside) machine invoke the command:
|
||||
</para>
|
||||
|
||||
<para><screen>term -r -n off telnet</screen></para>
|
||||
|
||||
<para>
|
||||
Now break back to the telnet prompt on the local (inside) machine,
|
||||
using <literal>^]</literal> or whatever, and use the telnet shell escape command
|
||||
<literal>!</literal> to invoke term:
|
||||
</para>
|
||||
|
||||
<para><screen>telnet> ! term -n on telnet >&3 <&3</screen></para>
|
||||
|
||||
<para>
|
||||
That's it!
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you have a variant telnet, you might have to use some other file
|
||||
descriptor than 3; easy to check using strace. But three seems to
|
||||
work on all bsd descendent telnet clients I've tried, under both SunOS
|
||||
4.x and the usual linux distributions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Some telnet clients do not have the ! shell escape command. Eg the
|
||||
telnet client distributed with Slackware 3.0 is one such client. The
|
||||
sources that the Slackware telnet client is supposedly built from
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<ulink url="ftp://ftp.cdrom.com:/pub/linux/slackware-3.0/source/n/tcpip/NetKit-B-0.05.tar.gz">
|
||||
<citetitle>ftp://ftp.cdrom.com:/pub/linux/slackware-3.0/source/n/tcpip/NetKit-B-0.05.tar.gz</citetitle></ulink>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A simple solution is therefore to
|
||||
obtain these sources and recompile them. This unfortunately is a task
|
||||
I have had no luck with. Plus, if you are running from inside a SOCKS
|
||||
firewall, you will need a SOCKSified telnet client anyway. To that
|
||||
end, I was able to compile a SOCKSified telnet client from:
|
||||
</para>
|
||||
|
||||
<para><ulink url="ftp://ftp.nec.com/pub/security/socks.cstc/socks.cstc.4.2.tar.gz">
|
||||
<citetitle>ftp://ftp.nec.com/pub/security/socks.cstc/socks.cstc.4.2.tar.gz</citetitle></ulink>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
or, if you're outside the USA,
|
||||
</para>
|
||||
|
||||
<para><ulink url="ftp://ftp.nec.com/pub/security/socks.cstc/export.socks.cstc.4.2.tar.gz">
|
||||
<citetitle>ftp://ftp.nec.com/pub/security/socks.cstc/export.socks.cstc.4.2.tar.gz</citetitle></ulink>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Alternatively, under linux kernels up to 1.2.13, you can pause the
|
||||
telnet with <literal>^]^z</literal>, figure out its pid, and invoke:
|
||||
</para>
|
||||
|
||||
<para><screen>term -n on -v /proc/&,t;telnetpid>/fd/3 telnet</screen></para>
|
||||
|
||||
<para>
|
||||
This doesn't work with kernels after 1.3.x, which closed some
|
||||
mysterious security hole by preventing access to these fd's by
|
||||
processes other than the owner process and its children.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="termsockets">
|
||||
<title>Multiple Term Sockets</title>
|
||||
|
||||
<para>
|
||||
It is a good idea to give the term socket an explicit name.
|
||||
This is the <literal>telnet</literal>; argument in the invocations
|
||||
of term above.
|
||||
Unless you have the TERMSERVER environment variable set to telnet as
|
||||
appropriate, you invoke term clients with the -t switch,
|
||||
e.g., <literal>trsh -t telnet</literal>.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="termrc.telnet">
|
||||
<title>The <<filename>˜/.term/termrc.telnet</filename> Init File</title>
|
||||
|
||||
<para>
|
||||
I have checked line clarity using linecheck over this medium.
|
||||
I expected it to be completely transparent, but it is not.
|
||||
However, the only bad character seems to be 255.
|
||||
The <filename>˜/.term/termrc.telnet</filename> I use
|
||||
(the <filename>.telnet</filename> is the name of the term connection, see above)
|
||||
contains:
|
||||
</para>
|
||||
|
||||
<para><screen>baudrate off
|
||||
escape 255
|
||||
ignore 255
|
||||
timeout 600</screen></para>
|
||||
|
||||
<para>
|
||||
Perhaps it could be improved by diddling,
|
||||
I am getting a throughput of only about 30k cps over
|
||||
a long-haul connection through a slow firewall.
|
||||
Ftp can move about 100k cps over the same route.
|
||||
A realistic baudrate might avoid some timeouts.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="direction">
|
||||
<title>Direction</title>
|
||||
|
||||
<para>
|
||||
Obviously, if you are starting from outside the firewall and zitching
|
||||
in using a SecureID card or something, you will want to reverse the
|
||||
roles of the remote vs local servers given above. (If you don't
|
||||
understand what this means, perhaps you are not familiar enough with
|
||||
term to use the trick described in this file responsibly.)
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="security">
|
||||
<title>Security</title>
|
||||
|
||||
<para>
|
||||
This is not much more of a vulnerability than the current possibility
|
||||
of having a telnet connection hijacked on an unsecured outside
|
||||
machine. The primary additional risk comes from people being able to
|
||||
use the term socket you set up without you even being aware of it. So
|
||||
be careful out there. (Personally, I do this with an outside machine
|
||||
I know to be pretty secure, namely a linux laptop I maintain myself
|
||||
that does not accept any incoming connections.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Another possibility is to add
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<screen>socket off</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
to the remote <filename>˜/.term/termrc.telnet</filename> file, or
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<screen>add "-u off"</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
to the invocation of term.
|
||||
This prevents the socket from being hijacked from the remote end,
|
||||
with only a minor loss of functionality.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="telnet">
|
||||
<title>Telnet Mode</title>
|
||||
|
||||
<para>
|
||||
Be sure the remote telnetd is not in some nasty seven-bit mode.
|
||||
Or if it is, you have to tell term about it when you invoke term,
|
||||
by adding the <literal>-a</literal> switch at both ends.
|
||||
(I sometimes use <literal>>^] telnet> set outbin</literal> or
|
||||
<literal>set bin</literal>, or invoke telnet with a <literal>-8</literal> switch
|
||||
to put the connection into eight-bit mode.)
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="bugs">
|
||||
<title>Bugs and Term Wish List</title>
|
||||
|
||||
<para>
|
||||
The <command>linecheck</command> program has some problems checking telnet connections
|
||||
sometimes. This is sometimes because it doesn't check the return code
|
||||
of the <function>read()</function> call it makes. For network connections,
|
||||
this call to <function>read()</function> can return <literal>-1</literal>
|
||||
with an <literal>EINTR</literal> (interrupted) or
|
||||
<literal>EAGAIN</literal> (try again) error code.
|
||||
Obviously this should be checked for.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
There are a number of features that could ease the use of term over
|
||||
telnet. These primarily relate to an assumption that influenced the
|
||||
design of term, namely that the connection is low bandwidth, low
|
||||
latency, and somewhat noisy.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A telnet connection is in general high bandwidth, high latency, and
|
||||
error free. This means that the connection could be better utilized
|
||||
if (a) the maximum window size was raised, well above the limit
|
||||
imposed by term's <literal>N_PACKETS/2=16</literal>,
|
||||
(b) there was an option to turn off sending and checking packet checksums,
|
||||
and (c) larger packets were permitted when appropriate.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Also, to enhance security, it would be nice to have a term option to
|
||||
log all connections through the socket it monitors to a log file, or
|
||||
to <literal>stderr</literal>, or both. This would allow one to see if one's term
|
||||
connection is being subverted by nasty hackers on the outside insecure
|
||||
machine.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="tricks">
|
||||
<title>Tricks That Do Not Seem to Work</title>
|
||||
|
||||
<para>
|
||||
Some telnet clients and servers agree to encrypt their communications,
|
||||
to prevent eavesdropping on the connection. Unfortunately, the hack
|
||||
used above (using the network connection that the telnet client has
|
||||
set up while the telnet client is idle) won't work in that case.
|
||||
Instead, one really must go through the telnet client itself, so it
|
||||
can do its encryption. It seems like that requires a simple hack to
|
||||
the telnet client itself, to add a command that runs a process with
|
||||
its <literal>stdin</literal> and <literal>stdout</literal> are connected
|
||||
to the live telnet connection.
|
||||
This would also be useful for various bots, so perhaps someone has
|
||||
already hacked it up.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="resources">
|
||||
<title>Related Resources</title>
|
||||
|
||||
<para>
|
||||
A vaguely related trick is to SOCKSify one's Term library.
|
||||
Details, including patches to SOCKS, are available from
|
||||
Steven Danz <ulink url="mailto:danz@wv.mentorg.com"><citetitle>danz@wv.mentorg.com</citetitle></ulink>.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="acknowledgements">
|
||||
<title>Acknowledgments</title>
|
||||
|
||||
<para>
|
||||
Thanks for valuable suggestions from:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Gary Flake <ulink url="flake@scr.siemens.com"><citetitle>flake@scr.siemens.com</citetitle></ulink></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Bill Riemers <ulink url="bcr@physics.purdue.edu"><citetitle>bcr@physics.purdue.edu</citetitle></ulink></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Greg Louis <ulink url="glouis@dynamicro.on.ca"><citetitle>glouis@dynamicro.on.ca</citetitle></ulink></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect1>
|
||||
|
||||
</article>
|
||||
|