mirror of https://github.com/tLDP/LDP
872 lines
30 KiB
Plaintext
872 lines
30 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<!--
|
|
The line above starts a comments section
|
|
|
|
|
|
A changelog is useful if you don't use cvs etc.
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
Changelog:
|
|
010200: Created this Template for big HOWTOs
|
|
070500: Continued writing, no release yet.
|
|
280500: Released. Added examples for diagrams
|
|
050600: Clarified intent, added acknowledgements and note on conventions, moved samples to the end, added table sample, added small section on style
|
|
190600: Updated and corrected copyright section
|
|
240700: Added Troubleshooting section, cleaned up Getting Help and Bits and Pieces, fixed typo
|
|
161000: Added sample scripts to generate outputs from SGML-file and removed typos
|
|
291000: Updated sample scripts to generate outputs from SGML-file and removed old copyright
|
|
311000: Fixed a typo
|
|
|
|
The line below ends the comments section.
|
|
-->
|
|
|
|
|
|
<article>
|
|
|
|
<!-- insert title here, include the word HOWTO -->
|
|
<title>HOWTO-template for Big HOWTOs
|
|
|
|
<author>Stein Gjoen, <tt/sgjoen@nyx.net/ <!-- insert your name and email here -->
|
|
|
|
<!-- always have a version number and a date (YYYY-MM-DD format) -->
|
|
<date>0.06, 2001-01-08
|
|
|
|
<abstract> <!-- the abstract: a short and precise description -->
|
|
<nidx>(your index root)</nidx> <!-- add indexing keywords as you go along -->
|
|
<!-- nidx means the indexed word is not in output of main text, only in the index -->
|
|
This is a fully working template for big HOWTOs. The source contains
|
|
fully described slots to make a convenient framework for you to fill in
|
|
for making your own HOWTO, suggesting some names, conventions and contents
|
|
for the chapters.
|
|
</abstract>
|
|
|
|
|
|
<!-- Table of contents -->
|
|
<toc>
|
|
|
|
<!-- Begin the document -->
|
|
|
|
|
|
<sect>Introduction
|
|
|
|
<p> <!-- always use a p tag (paragraph) immediately after a sect tag -->
|
|
<nidx>(your index root)!introduction</nidx> <!-- here introduction is a sub entry of template, exclamationmark is separator -->
|
|
<em>My comments to the reader is in this style (emphasized)</em>.
|
|
Example lines are in plain roman style.
|
|
<em>Note that extra comments and advice is found in comments
|
|
within the SGML source.</em> <!-- such as this comment -->
|
|
|
|
For various reasons this brand new release is codenamed
|
|
the <bf/release/ release.
|
|
|
|
New code names will appear as per industry standard guidelines
|
|
to emphasize the state-of-the-art-ness of this document.
|
|
|
|
<p>
|
|
This document was written when I read a feedback asking for a
|
|
template to fill in to make new HOWTOs. This template is made
|
|
by extracting the skeletal structure of the Multi Disk HOWTO
|
|
which is a rather large HOWTO.
|
|
|
|
<em>This Template is a suggestion and a starting point, a check list
|
|
and examples for authors; it is not a requirement to be followed
|
|
slavishly. Over time HOWTOs might also outgrow any template since
|
|
in the end the goal is to inform readers efficiently.</em>
|
|
|
|
Stating the background is a simple way to getting started
|
|
writing the intro.
|
|
|
|
First of all we need a bit of legalese. Recent development shows it is
|
|
quite important.
|
|
|
|
<sect1>Copyright
|
|
<p>
|
|
<em>Copyright is a source of much and continuous debate on the
|
|
LDP mailing list. For more in depth information please consult
|
|
the Manifesto at the </em>
|
|
<url url="http://www.LinuxDoc.org/"
|
|
name="LinuxDoc">
|
|
site.
|
|
<em>
|
|
The purpose of having a license is to allow appropriate distribution.
|
|
You can use any license that meets the Manifesto.
|
|
What follows is a boilerplate licence.
|
|
</em>
|
|
|
|
<!--
|
|
Old style copyright removed
|
|
-->
|
|
|
|
Copyright (c) 2000 by John Doe (change to your name)
|
|
<P>
|
|
Please freely copy and distribute (sell or give away) this document in
|
|
any format. It's requested that corrections and/or comments be forwarded
|
|
to the document maintainer. You may create a derivative work and distribute
|
|
it provided that you:
|
|
|
|
<itemize>
|
|
<item>
|
|
Send your derivative work (in the most suitable format such as
|
|
sgml) to the LDP (Linux Documentation Project) or the like for posting
|
|
on the Internet. If not the LDP, then let the LDP know where it is
|
|
available.
|
|
<item>
|
|
License the derivative work with this same license or use GPL.
|
|
Include a copyright notice and at least a pointer to the license used.
|
|
<item>
|
|
Give due credit to previous authors and major contributors.
|
|
</itemize>
|
|
|
|
<P>
|
|
If you're considering making a derived work other than a translation,
|
|
it's requested that you discuss your plans with the current maintainer.
|
|
|
|
|
|
|
|
<sect1>Disclaimer
|
|
<p>
|
|
|
|
Use the information in this document at your own risk. I disavow any
|
|
potential liability for the contents of this document. Use of the
|
|
concepts, examples, and/or other content of this document is entirely
|
|
at your own risk.
|
|
|
|
All copyrights are owned by their 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.
|
|
|
|
Naming of particular products or brands should not be seen as endorsements.
|
|
|
|
You are strongly recommended to take a backup of your system before
|
|
major installation and backups at regular intervals.
|
|
|
|
|
|
<sect1>News
|
|
<p>
|
|
<nidx>(your index root)!news on</nidx>
|
|
<em>This is where you make a summary of what is new. When a HOWTO exceeds
|
|
20 pages it takes more than a casual read to find the updates. This is
|
|
where you help your readers with that, alerting them to specific and
|
|
important news.</em>
|
|
|
|
This is the second release featuring more samples and an improved structure.
|
|
<!-- This is the first release. No news yet. -->
|
|
<!-- Note that you might wish to keep old news commented out for reference
|
|
and perhaps state news as latest and next to latest update. -->
|
|
|
|
<em>Tell people where the document home page is so the very newest
|
|
release could be found in case of problems with the main
|
|
<url url="http://www.linuxdoc.org/"
|
|
name="Linux Documentation Project">
|
|
homepage.
|
|
</em>
|
|
|
|
The latest version number of this document can be gleaned from my
|
|
plan entry if you <!-- do "finger sgjoen@nox.nyx.net" -->
|
|
<url url="http://www.cs.indiana.edu/finger/nox.nyx.net/sgjoen"
|
|
name="finger"> my Nyx account.
|
|
|
|
<em>If you have the capacity it would be nice to make the HOWTO
|
|
available in a number of formats.</em>
|
|
|
|
Also, the latest version of the Template will be available on
|
|
my web space on Nyx in a number of formats:
|
|
<itemize>
|
|
<item>
|
|
<url url="http://www.nyx.net/˜sgjoen/template.html"
|
|
name="HTML">.
|
|
|
|
<item>
|
|
<url url="http://www.nyx.net/˜sgjoen/template.txt"
|
|
name="plain ASCII text">.
|
|
|
|
<!-- consider PostScript and perhaps also PDF formates
|
|
<item>
|
|
<url url="http://www.nyx.net/˜sgjoen/disk-US.ps.gz"
|
|
name="compressed postscript US letter format">.
|
|
|
|
<item>
|
|
<url url="http://www.nyx.net/˜sgjoen/disk-A4.ps.gz"
|
|
name="compressed postscript European A4 format">.
|
|
-->
|
|
<item>
|
|
<url url="http://www.nyx.net/˜sgjoen/template.sgml"
|
|
name="SGML source">.
|
|
</itemize>
|
|
|
|
<em>Note that paper sizes vary in the world, A4 and US letter differ
|
|
significantly.</em>
|
|
|
|
<sect1>Credits
|
|
<p>
|
|
<em>It is always nice to acknowledge people who help you with inputs, it
|
|
is also regarded by many as important in the Linux world new economy</em>
|
|
|
|
In this version I have the pleasure of acknowledging
|
|
|
|
<tscreen><verb>
|
|
corff (at) ZEDAT.FU-Berlin.DE
|
|
dwood (at) plugged.net.au
|
|
lcl (at) spiretech.com
|
|
kgh12351 (at) nifty.ne.jp
|
|
dave (at) lafn.org
|
|
name (at) site.org
|
|
</verb></tscreen>
|
|
|
|
<em>Scramble the addresses so email harvesters cannot get
|
|
addresses from your HOWTO and then spam people. That has
|
|
happened in the past.</em>
|
|
|
|
|
|
<sect1>Translations
|
|
<p>
|
|
Not everyone speaks English, pointers to translations are nice.
|
|
Also your translators tend to give very important inputs.
|
|
<itemize>
|
|
<item><url url="http://linuxdoc.org/"
|
|
name="German Translation"> by <tt/someone (at) somewhere.de/
|
|
|
|
<item><url url="http://www.swe-doc.linux.nu"
|
|
name="Swedish Translation "> by <tt/someone (at) somewhere.se/
|
|
|
|
<item><url url="http://linuxdoc.org/"
|
|
name="French Translation"> by <tt/someone (at) somewhere.fr/
|
|
|
|
<item><url url="http://linuxdoc.org/"
|
|
name="Chinese Translation"> by <tt/someone (at) somewhere.cn/
|
|
|
|
<item><url url="http://linuxdoc.org/"
|
|
name="Italian Translation"> by <tt/someone (at) somewhere.it/
|
|
</itemize>
|
|
|
|
|
|
|
|
|
|
Also Somecompany is acknowledged for sending me documentation
|
|
on their gizmos as well as permission to quote from the material.
|
|
These quotes have been approved before appearing here and will
|
|
be clearly labelled.
|
|
|
|
Any comments or suggestions can be mailed to my mail address on Nyx:
|
|
<htmlurl url="mailto:sgjoen@nyx.net/"
|
|
name="sgjoen@nyx.net">.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<!--
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
-->
|
|
|
|
|
|
<sect>Structure
|
|
<p>
|
|
<em>A quick overview on how all parts fit together in the structure.
|
|
Here I use an example from my Multi Disk HOWTO.</em>
|
|
|
|
As this type of document is supposed to be as much for learning
|
|
as a technical reference document I have rearranged the structure
|
|
to this end. For the designer of a system it is more useful to
|
|
have the information presented in terms of the goals of this exercise
|
|
than from the point of view of the logical layer structure of the
|
|
devices themselves. Nevertheless this document would not be complete
|
|
without such a layer structure the computer field is so full of, so
|
|
I will include it here as an introduction to how it works.
|
|
|
|
<sect1>Logical structure
|
|
<p>
|
|
<nidx>(your index root)!structure, I/O subsystem</nidx>
|
|
This is based on how each layer access each other, traditionally
|
|
with the application on top and the physical layer on the bottom.
|
|
It is quite useful to show the interrelationship between each of
|
|
the layers used in controlling drives.
|
|
<tscreen><verb>
|
|
___________________________________________________________
|
|
|__ File structure ( /usr /tmp etc) __|
|
|
|__ File system (ext2fs, vfat etc) __|
|
|
|__ Volume management (AFS) __|
|
|
|__ RAID, concatenation (md) __|
|
|
|__ Device driver (SCSI, IDE etc) __|
|
|
|__ Controller (chip, card) __|
|
|
|__ Connection (cable, network) __|
|
|
|__ Drive (magnetic, optical etc) __|
|
|
-----------------------------------------------------------
|
|
|
|
</verb></tscreen>
|
|
|
|
In the above diagram both volume management and RAID and concatenation
|
|
are optional layers. The 3 lower layers are in hardware.
|
|
All parts are discussed at length later on in this document.
|
|
|
|
<sect1>Document structure
|
|
<p>
|
|
Most users start out with a given set of hardware and some plans on
|
|
what they wish to achieve and how big the system should be. This is
|
|
the point of view I will adopt in this document in presenting the
|
|
material, starting out with hardware, continuing with design constraints
|
|
before detailing the design strategy that I have found to work well.
|
|
I have used this both for my own personal computer at home, a multi
|
|
purpose server at work and found it worked quite well. In addition my
|
|
Japanese co-worker in this project have applied the same strategy on
|
|
a server in an academic setting with similar success.
|
|
|
|
Finally at the end I have detailed some configuration tables for use
|
|
in your own design. If you have any comments regarding this or notes
|
|
from your own design work I would like to hear from you so this
|
|
document can be upgraded.
|
|
|
|
<sect1>Reading plan
|
|
<p>
|
|
<em>As you go beyond 50 pages or so there will be a lot of text that
|
|
experts and even the experienced do not need to read. Keeping in mind
|
|
that we wish to care for all kinds of people in the Linux world we
|
|
might have to make a reading plan. Again example follows from my
|
|
HOWTO.</em>
|
|
|
|
Although not the biggest HOWTO it is nevertheless rather big already
|
|
and I have been requested to make a reading plan to make it possible
|
|
to cut down on the volume
|
|
|
|
<descrip>
|
|
<tag/Expert/ (aka the elite). If you are familiar with Linux as well
|
|
as disk drive technologies you will find most of what you need in the
|
|
appendices. Additionally you are recommended to read the FAQ and the
|
|
<ref id="bits-n-pieces" name="Bits'n'pieces">
|
|
chapter.
|
|
|
|
<tag/Experienced/ (aka Competent). If you are familiar with computers
|
|
in general you can go straight to the chapters on
|
|
<ref id="technologies" name="technologies">
|
|
and continue from there on.
|
|
|
|
<tag/Newbie/ (mostly harmless). You just have to read the whole thing.
|
|
Sorry. In addition you are also recommended to read all the other disk
|
|
related HOWTOs.
|
|
</descrip>
|
|
|
|
|
|
<sect>Technologies <label id="technologies">
|
|
<p>
|
|
<nidx>(your index root)!technologies</nidx>
|
|
<em>Introduction of technology for the newbie with a few
|
|
references to detailled works. Remember that not everyone
|
|
has Internet access so you have to explain in sufficient
|
|
details so even the newbie can get by.</em>
|
|
|
|
|
|
<sect>Implementation
|
|
<p>
|
|
<nidx>(your index root)!implementation</nidx>
|
|
<em>Now your readers should have a sufficient knowledge of what
|
|
this is about and now we come to the hands on of implementing
|
|
your clever scheme.</em>
|
|
|
|
|
|
<sect>Maintenance
|
|
<p>
|
|
<nidx>(your index root)!maintenance</nidx>
|
|
<em>Few systems and designs are maintenance free, here you explain
|
|
how to keep the system running.</em>
|
|
|
|
|
|
<sect>Advanced Issues
|
|
<p>
|
|
<nidx>(your index root)!advanced topics</nidx>
|
|
<em>You can get most things up and running in a quick and dirty
|
|
fashion, useful for testing and getting used to how things work.
|
|
For more serious use you would need to be a little more advanced.
|
|
This is the place to explain it all, if applicable.</em>
|
|
|
|
|
|
<sect>Troubleshooting <label id="troubleshooting">
|
|
<p>
|
|
<nidx>(your index root)!troubleshooting</nidx>
|
|
<em>Many problems can be solved by a simple structured approach,
|
|
analysing the symptoms, finding the cause and determining the
|
|
solution. The following is an excerpts from the Multi Disk HOWTO.</em>
|
|
|
|
<sect1>During Installation
|
|
|
|
<sect2>Locating Disks
|
|
<p>
|
|
<descrip>
|
|
<tag/Symptoms/Cannot find disk
|
|
<tag/Problem/How to find what drive letter corresponds to what disk/partition
|
|
<tag/Solution/Remember Linux does not use drive letters but device names. More
|
|
information can be found in section "Drive names".
|
|
</descrip>
|
|
<p>
|
|
<descrip>
|
|
<tag/Symptoms/Cannot partition disk
|
|
<tag/Problem/Most likely wrong input to the command line for <tt/fdisk/ or similar tool.
|
|
<tag/Solution/Remember to use <tt>/dev/hda</tt> rather than just <tt>hda</tt>. Also
|
|
do not use numbers behind <tt>hda</tt>, those indicate partitions.
|
|
</descrip>
|
|
|
|
|
|
<sect2>Formatting
|
|
<p>
|
|
<descrip>
|
|
<tag/Symptoms/Cannot format disk.
|
|
<tag/Problem/Strictly speaking you format partitions not disks.
|
|
<tag/Solution/Make sure you add the partition number after the device name
|
|
of the disk, for instance <tt>/dev/hda1</tt> to the command line.
|
|
</descrip>
|
|
|
|
|
|
<sect>Further Information
|
|
<p>
|
|
<nidx>(your index root)!information resources</nidx>
|
|
<em>A HOWTO cannot describe everything, some times the user
|
|
has to venture out on the net to get more information or just
|
|
updates. Here is the place to tell where and how. Again examples
|
|
from my HOWTO, replace as needed.</em>
|
|
There is wealth of information one should go through when setting up a
|
|
major system, for instance for a news or general Internet service provider.
|
|
The FAQs in the following groups are useful:
|
|
|
|
<sect1>News groups
|
|
<p>
|
|
<nidx>(your index root)!information resources!news groups</nidx>
|
|
Some of the most interesting news groups are:
|
|
<itemize>
|
|
<item><url url="news:comp.arch.storage" name="Storage">.
|
|
<item><url url="news:comp.sys.ibm.pc.hardware.storage" name="PC storage">.
|
|
<item><url url="news:alt.filesystems.afs" name="AFS">.
|
|
<item><url url="news:comp.periphs.scsi" name="SCSI">.
|
|
<item><url url="news:comp.os.linux.setup" name="Linux setup">.
|
|
</itemize>
|
|
|
|
Most newsgroups have their own FAQ that are designed to answer most of your
|
|
questions, as the name Frequently Asked Questions indicate. Fresh versions
|
|
should be posted regularly to the relevant newsgroups. If you cannot find it
|
|
in your news spool you could go directly to the
|
|
<url url="ftp://rtfm.mit.edu"
|
|
name="FAQ main archive FTP site">. The WWW versions can be browsed at
|
|
<url url="http://www.cis.ohio-state.edu/hypertext/faq/usenet/FAQ-List.html"
|
|
name="FAQ main archive WWW site">.
|
|
|
|
Some FAQs have their own home site, of particular interest here are
|
|
<itemize>
|
|
<item><url url="http://www.paranoia.com/˜filipg/HTML/LINK/F_SCSI.html"
|
|
name="SCSI FAQ"> and
|
|
<item><url url="http://alumni.caltech.edu/˜rdv/comp_arch_storage/FAQ-1.html"
|
|
name="comp.arch.storage FAQ">.
|
|
</itemize>
|
|
|
|
|
|
<sect1>Mailing Lists
|
|
<p>
|
|
<nidx>(your index root)!information resources!mailing lists</nidx>
|
|
These are low noise channels mainly for developers. Think
|
|
twice before asking questions there as noise delays the development.
|
|
Some relevant lists are <tt/linux-raid/, <tt/linux-scsi/ and <tt/linux-ext2fs/.
|
|
Many of the most useful mailing lists run on the <tt>vger.rutgers.edu</tt> server
|
|
but this is notoriously overloaded, so try to find a mirror. There are some lists mirrored at
|
|
<url url="http://www.redhat.com"
|
|
name="The Redhat Home Page">.
|
|
Many lists are also accessible at
|
|
<url url="http://www.linuxhq.com/lnxlists"
|
|
name="linuxhq">,
|
|
and the rest of the web site is a gold mine of useful information.
|
|
|
|
If you want to find out more about the lists available you can send a message
|
|
with the line <tt/lists/ to the list server at vger.rutgers.edu (
|
|
<htmlurl url="mailto:majordomo@vger.rutgers.edu"
|
|
name="majordomo@vger.rutgers.edu">).
|
|
If you need help on how to use the mail server just send the line <tt/help/
|
|
to the same address.
|
|
Due to the popularity of this server it is likely it takes a bit to time before
|
|
you get a reply or even get messages after you send a <tt/subscribe/ command.
|
|
|
|
There is also a number of other majordomo list servers that can be of interest
|
|
such as the EATA driver list (
|
|
<htmlurl url="mailto:linux-eata@mail.uni-mainz.de"
|
|
name="linux-eata@mail.uni-mainz.de">)
|
|
and the Intelligent IO list
|
|
<htmlurl url="mailto:linux-i2o@dpt.com"
|
|
name="linux-i2o@dpt.com">.
|
|
|
|
Mailing lists are in a state of flux but you can find links to a number of
|
|
interesting lists from the
|
|
<url url="http://metalab.unc.edu/LDP/"
|
|
name="Linux Documentation Homepage">.
|
|
|
|
|
|
<sect1>HOWTO
|
|
<p>
|
|
<nidx>(your index root)!information resources!HOWTOs</nidx>
|
|
These are intended as the primary starting points to
|
|
get the background information as well as show you how to solve
|
|
a specific problem.
|
|
Some relevant HOWTOs are <tt/Bootdisk/, <tt/Installation/, <tt/SCSI/ and <tt/UMSDOS/.
|
|
The main site for these is the
|
|
<url url="http://metalab.unc.edu/LDP/"
|
|
name="LDP archive">
|
|
at Metalab (formerly known as Sunsite).
|
|
|
|
There is a a new HOWTO out that deals with setting up a
|
|
DPT RAID system, check out the
|
|
<url url="http://www.ram.org/computing/linux/dpt_raid.html"
|
|
name="DPT RAID HOWTO homepage">.
|
|
|
|
|
|
|
|
<sect1>Mini-HOWTO
|
|
<p>
|
|
<nidx>(your index root)!information resources!mini-HOWTOs</nidx>
|
|
These are the smaller free text relatives to the HOWTOs.
|
|
Some relevant mini-HOWTOs are
|
|
<tt/Backup-With-MSDOS/, <tt/Diskless/, <tt/LILO/, <tt/Large Disk/,
|
|
<tt/Linux+DOS+Win95+OS2/, <tt/Linux+OS2+DOS/, <tt/Linux+Win95/,
|
|
<tt/NFS-Root/, <tt/Win95+Win+Linux/, <tt/ZIP Drive/ .
|
|
You can find these at the same place as the HOWTOs, usually in a sub directory
|
|
called <tt/mini/. Note that these are scheduled to be converted into SGML and
|
|
become proper HOWTOs in the near future.
|
|
|
|
The old <tt/Linux Large IDE mini-HOWTO/ is no longer valid, instead read
|
|
<tt>/usr/src/linux/drivers/block/README.ide</tt> or
|
|
<tt>/usr/src/linux/Documentation/ide.txt</tt>.
|
|
|
|
<sect1>Local Resources
|
|
<p>
|
|
<nidx>(your index root)!information resources!local</nidx>
|
|
In most distributions of Linux there is a document directory installed,
|
|
have a look in the
|
|
<htmlurl url="file:///usr/doc"
|
|
name="/usr/doc"> directory.
|
|
where most packages store their main documentation and README files etc.
|
|
Also you will here find the HOWTO archive (
|
|
<htmlurl url="file:///usr/doc/HOWTO"
|
|
name="/usr/doc/HOWTO">)
|
|
of ready formatted HOWTOs
|
|
and also the mini-HOWTO archive (
|
|
<url url="file:///usr/doc/HOWTO/mini"
|
|
name="/usr/doc/HOWTO/mini">)
|
|
of plain text documents.
|
|
|
|
Many of the configuration files mentioned earlier can be found in the
|
|
<htmlurl url="file:///etc"
|
|
name="/etc">
|
|
directory. In particular you will want to work with the
|
|
<htmlurl url="file:///etc/fstab"
|
|
name="/etc/fstab">
|
|
file that sets up the mounting of partitions
|
|
and possibly also
|
|
<htmlurl url="file:///etc/mdtab"
|
|
name="/etc/mdtab">
|
|
file that is used for the <tt/md/ system to set up RAID.
|
|
|
|
The kernel source in
|
|
<url url="file:///usr/src/linux"
|
|
name="/usr/src/linux">
|
|
is, of course, the ultimate documentation. In other
|
|
words, <em>use the source, Luke</em>.
|
|
It should also be pointed out that the kernel comes not only with
|
|
source code which is even commented (well, partially at least)
|
|
but also an informative
|
|
<url url="file:///usr/src/linux/Documentation"
|
|
name="documentation directory">.
|
|
If you are about to ask any questions about the kernel you should
|
|
read this first, it will save you and many others a lot of time
|
|
and possibly embarrassment.
|
|
|
|
Also have a look in your system log file (
|
|
<htmlurl url="file:///var/log/messages"
|
|
name="/var/log/messages">)
|
|
to see what is going on and in particular how the booting went if
|
|
too much scrolled off your screen. Using <tt>tail -f /var/log/messages</tt>
|
|
in a separate window or screen will give you a continuous update of what is
|
|
going on in your system.
|
|
|
|
You can also take advantage of the
|
|
<htmlurl url="file:///proc"
|
|
name="/proc">
|
|
file system that is a window into the inner workings of your system.
|
|
Use <tt/cat/ rather than <tt/more/ to view the files as they are
|
|
reported as being zero length. Reports are that <tt/less/ works well here.
|
|
|
|
|
|
<sect1>Web Pages
|
|
<p>
|
|
<nidx>(your index root)!information resources!WWW</nidx>
|
|
<nidx>(your index root)!information resources!web pages</nidx>
|
|
There is a huge number of informative web pages out there and by their very
|
|
nature they change quickly so don't be too surprised if these links become
|
|
quickly outdated.
|
|
|
|
A good starting point is of course the
|
|
<url url="http://www.linuxdoc.org/"
|
|
name="Linux Documentation Project"> home page,
|
|
an information central for documentation, project pages and much, much more.
|
|
|
|
Please let me know if you have any other leads that can be of interest.
|
|
|
|
|
|
<sect>Getting Help
|
|
<p>
|
|
<nidx>(your index root)!assistance, obtaining</nidx>
|
|
<em>Your reader might still end up in a situation where extra help is
|
|
needed from someone else, perhaps on the net. In order to get fast and
|
|
efficient help it is best first to get some details on your system.
|
|
What details matter depends on type of problem. For disk problems you
|
|
need to know the disk controllers etc, for networking problems you
|
|
have to know what ethernet card is used and version of drivers etc.
|
|
Here is the place to suggest what details to have ready when asking
|
|
for help.</em>
|
|
|
|
In the end you might find yourself unable to solve your problems and need
|
|
help from someone else. The most efficient way is either to ask someone
|
|
local or in your nearest Linux user group, search the web for the nearest
|
|
one.
|
|
|
|
Another possibility is to ask on Usenet News in one of the many, many
|
|
newsgroups available. The problem is that these have such a high
|
|
volume and noise (called low signal-to-noise ratio) that your question
|
|
can easily fall through unanswered.
|
|
|
|
No matter where you ask it is important to ask well or you will not be
|
|
taken seriously. Saying just <it/my disk does not work/ is not going
|
|
to help you and instead the noise level is increased even further and if
|
|
you are lucky someone will ask you to clarify.
|
|
|
|
Instead describe your problems in some detail that
|
|
will enable people to help you. The problem could lie somewhere you did
|
|
not expect. Therefore you are advised to list up the following information
|
|
on your system:
|
|
|
|
<descrip>
|
|
<tag/Hardware/
|
|
<itemize>
|
|
<item>Processor
|
|
<item>DMA
|
|
<item>IRQ
|
|
<item>Chip set (LX, BX etc)
|
|
<item>Bus (ISA, VESA, PCI etc)
|
|
<item>Expansion cards used (Disk controllers, video, IO etc)
|
|
</itemize>
|
|
|
|
<tag/Software/
|
|
<itemize>
|
|
<item>BIOS (On motherboard and possibly SCSI host adapters)
|
|
<item>LILO, if used
|
|
<item>Linux kernel version as well as possible modifications and patches
|
|
<item>Kernel parameters, if any
|
|
<item>Software that shows the error (with version number or date)
|
|
</itemize>
|
|
|
|
<tag/Peripherals/
|
|
<itemize>
|
|
<item>Type of disk drives with manufacturer name, version and type
|
|
<item>Other relevant peripherals connected to the same busses
|
|
</itemize>
|
|
|
|
</descrip>
|
|
|
|
Remember that booting text is logged to <tt>/var/log/messages</tt> which can
|
|
answer most of the questions above. Obviously if the drives fail you might not
|
|
be able to get the log saved to disk but you can at least scroll back up the
|
|
screen using the <tt/SHIFT/ and <tt/PAGE UP/ keys. It may also be useful to
|
|
include part of this in your request for help but do not go overboard, keep
|
|
it <em/brief/ as a complete log file dumped to Usenet News is more than a
|
|
little annoying.
|
|
|
|
|
|
<sect>Concluding Remarks
|
|
<p>
|
|
<nidx>(your index root)!conclusion</nidx>
|
|
<em>Just summing up... Also a place for general recommendations.</em>
|
|
|
|
|
|
<sect>Questions and Answers
|
|
<p>
|
|
<nidx>(your index root)!FAQ</nidx>
|
|
<nidx>(your index root)!frequently asked questions</nidx>
|
|
<em>Check the newsgroups and try to determine some frequent
|
|
problems and cover them here. Again an example from my HOWTO.</em>
|
|
|
|
This is just a collection of what I believe are the most common
|
|
questions people might have. Give me more feedback and I will
|
|
turn this section into a proper FAQ.
|
|
|
|
<itemize>
|
|
|
|
<item>Q:How many physical disk drives (spindles) does a Linux system need?
|
|
<p>
|
|
A: Linux can run just fine on one drive (spindle). Having enough
|
|
RAM (around 32 MB, and up to 64 MB) to support swapping is a
|
|
better price/performance choice than getting a second disk.
|
|
(E)IDE disk is usually cheaper (but a little slower) than SCSI.
|
|
|
|
<item>Q: Are there any disadvantages in this scheme?
|
|
<p>
|
|
A: There is only a minor snag: if even a single partition overflows
|
|
the system might stop working properly. The severity depends of course
|
|
on what partition is affected. Still this is not hard to monitor, the
|
|
command <tt/df/ gives you a good overview of the situation. Also check
|
|
the swap partition(s) using <tt/free/ to make sure you are not about
|
|
to run out of virtual memory.
|
|
|
|
<item>Q: OK, so should I split the system into as many partitions
|
|
as possible for a single drive?
|
|
<p>
|
|
A: No, there are several disadvantages to that. First of all maintenance
|
|
becomes needlessly complex and you gain very little in this. In fact if your
|
|
partitions are too big you will seek across larger areas than needed.
|
|
This is a balance and dependent on the number of physical drives you have.
|
|
|
|
</itemize>
|
|
<em>(rest deleted.)</em>
|
|
|
|
<sect>Bits and Pieces <label id="bits-n-pieces">
|
|
<p>
|
|
<nidx>(your index root)!miscellaneous</nidx>
|
|
<em>This is basically a section where I stuff all the bits I have not yet
|
|
decided where should go, yet that I feel is worth knowing about. It is
|
|
a kind of transient area.</em>
|
|
|
|
<sect>Examples
|
|
<p>
|
|
<nidx>(your index root)!examples</nidx>
|
|
<em>Example designs and sample configuration files and other
|
|
relevant details is always handy. Keep large samples at the
|
|
end to avoid breaking the flow of the HOWTO reading. Small
|
|
samples are useful within the main body of the HOWTO.</em>
|
|
|
|
|
|
<sect>Samples <label id="samples">
|
|
<p>
|
|
<em>This section gives some simple SGML examples you could copy.
|
|
Read the source to see how it was done.</em>
|
|
|
|
<!-- you can also have comments in the SGML source -->
|
|
|
|
<sect1>Lists
|
|
<p>
|
|
<em>Lists appears many times, in a number of formats:</em>
|
|
<p>
|
|
Unlisted bullets:
|
|
<p>
|
|
<itemize>
|
|
<item>Apples
|
|
<item>Oranges
|
|
<item>Bananas
|
|
</itemize>
|
|
<p>
|
|
Tagged lists
|
|
<p>
|
|
<descrip>
|
|
<tag/Fruits/ such as apples, oranges, and more.
|
|
<tag/Nuts/ Don't eat too many; you are what you eat.
|
|
<tag/Vegetables/ Potatos are spelled with care.
|
|
</descrip>
|
|
|
|
|
|
<sect1>Links
|
|
<p>
|
|
<em>Links can be used within your documents
|
|
to refer to different sections and chapters or
|
|
to refer to documents external to yours.</em>
|
|
<p>
|
|
Internal links
|
|
<p>
|
|
Click on
|
|
<ref id="samples" name="this">
|
|
link to jump to the top of this chapter. Note the
|
|
anchor at the section tag.
|
|
|
|
<p>
|
|
External links
|
|
<p>
|
|
Click on
|
|
<url url="http://www.LinuxDoc.org/"
|
|
name="this">
|
|
link to jump to the LDP site.
|
|
Note you can use http, ftp, news and other protocols
|
|
in the locator if required.
|
|
Note that the character ˜ has to be escaped, see the source
|
|
for details.
|
|
<!-- ˜ is the way of writing the tilde character -->
|
|
|
|
<sect1>Images
|
|
<p>
|
|
<em>Avoid diagrams if possible as this cannot be rendered in the
|
|
ascii outputs which are still needed by many around the world.</em>
|
|
|
|
<figure loc="tbp">
|
|
<eps file="somegraphics.eps">
|
|
<img src="somegraphics.jpg">
|
|
<caption>Graphics Test Image</caption>
|
|
</figure>
|
|
|
|
<!-- <img file="/usr/src/linux/logo.gif"> -->
|
|
|
|
|
|
<sect>Table Samples <label id="tblsamples">
|
|
<p>
|
|
<em>This section gives an example of writing a table.</em>
|
|
|
|
<table loc=p>
|
|
<tabular ca="rll">
|
|
Line No.<colsep>Country <colsep>Capital <rowsep><hline>
|
|
1 <colsep>Norway <colsep>Oslo <rowsep>
|
|
2 <colsep>Japan <colsep>Tokyo <rowsep>
|
|
3 <colsep>Finland <colsep>Helsinki <rowsep>
|
|
</tabular>
|
|
<caption>Some capitals</caption>
|
|
</table>
|
|
|
|
|
|
<sect>Notes on Style <label id="style">
|
|
<p>
|
|
<em>
|
|
Not much here yet but I would like to suggest a few points.
|
|
</em>
|
|
|
|
|
|
<descrip>
|
|
<tag/Tags/ Try to use tags extensively
|
|
<tag/Types/ Try using functional tags such as em rather than it.
|
|
<tag/Files/ Try using functional links to files such as
|
|
<tt><htmlurl url="file:///usr/doc" name="/usr/doc"></tt>
|
|
rather than just /usr/doc.
|
|
<tag/Commands/ Try to refer to man pages including section number
|
|
<tt>df (1)</tt> rather than just df.
|
|
</descrip>
|
|
|
|
<sect>Converting the SGML File
|
|
<p>
|
|
Having made the SGML file we are now ready to convert it to
|
|
the various output formats we need. The following is my
|
|
script to process my Multi Disk HOWTO:
|
|
|
|
<code>
|
|
sgml2txt -f disk.sgml
|
|
sgml2html disk.sgml
|
|
|
|
sgml2latex --papersize=a4 --language=english --output=ps ~stein/doc/disk.sgml
|
|
mv disk.ps disk-A4.ps
|
|
gzip -9 disk-A4.ps
|
|
|
|
sgml2latex --papersize=letter --language=english --output=ps ~stein/doc/disk.sgml
|
|
mv disk.ps disk-US.ps
|
|
gzip -9 disk-US.ps
|
|
|
|
</code>
|
|
|
|
The template can be converted as is, substitute "disk.sgml" with
|
|
the filename of this template to see what it looks like.
|
|
|
|
If your document is small (such as this template)
|
|
you might find it more convenient to
|
|
keep formatted versions in one single file
|
|
rather than splitting it for every chapter:
|
|
|
|
<code>
|
|
sgml2html --split=0 template.sgml
|
|
</code>
|
|
|
|
</article>
|