HOWTO-template for Big HOWTOs
Stein Gjoen
           <sgjoen@nyx.net>
       Â
Gregory Leblanc
           <gleblanc@cu-portland.edu>
       Â
Greg Ferguson
           <gferg@sgi.com>
       Â
Revision History
Revision 0.06 2001-01-08 Revised by: gjf
Changed date format (YYYY-MM-DD)
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.
SGML_source for this document is available and should be consulted while
reading.
-------------------------------------------------------------------------------
Table of Contents
1. Introduction
1.1. Copyright_Information
1.2. Disclaimer
1.3. New_Versions
1.4. Credits
1.5. Feedback
1.6. Translations
2. Samples
2.1. Lists
2.2. Links
2.3. Images
3. Structure
3.1. Logical_structure
3.2. Document_structure
3.3. Reading_plan
4. Technologies
5. Implementation
6. Maintenance
7. Advanced_Issues
8. Further_Information
8.1. News_groups
8.2. Mailing_Lists
8.3. HOWTO
8.4. Local_Resources
8.5. Web_Sites
9. Getting_Help
10. Concluding_Remarks
11. Questions_and_Answers
12. Bits_and_Pieces
13. Examples
1. Introduction
For various reasons this brand new release is codenamed the release release.
New code names will appear as per industry standard guidelines to emphasize the
state-of-the-art-ness of this document.
This document was written when I read a feedback asking for a template to fill
in to make new HOWTOs. This template was initially made by extracting the
skeletal structure of the Multi Disk HOWTO which is a rather large HOWTO. It
then went through extensive editing.
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.
-------------------------------------------------------------------------------
1.1. Copyright Information
This document is copyrighted (c) 2000 Stein Gjoen and is distributed under the
terms of the Linux Documentation Project (LDP) license, stated below. Replace
with your name, or supply a new license, when you use this skeleton for a new
HOWTO.
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 author would like to be notified of any
such distributions.
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.
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.
If you have any questions, please contact <linux-howto@metalab.unc.edu>
-------------------------------------------------------------------------------
1.2. Disclaimer
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 author(s) do not take any responsibility for that.
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.
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.
-------------------------------------------------------------------------------
1.3. New Versions
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 updates to the
document.
This is the initial release.
Tell people where the document home page is so the very newest release could be
found in case of problems with the main Linux_Documentation_Project homepage.
The following is a sample from the Multi Disk HOWTO:
The latest version number of this document can be gleaned from my plan entry if
you finger my Nyx account.
If you have the capability, it would be nice to make the HOWTO available in a
number of formats.
The newest version of this HOWTO will always be made available on my website,
in a variety of formats:
* HTML.
* plain_text.
* compressed_postscript_(US_letter_format).
* SGML_source.
Note that paper sizes vary in the world, A4 and US letter differ significantly.
You might also wish to consider using the universal format (8.27x11in;
210x279mm).
-------------------------------------------------------------------------------
1.4. Credits
It is always nice to acknowledge people who help you with input; it is also
regarded by many as important in the Linux world new economy.
In this version I have the pleasure of acknowledging:
<name_(at)_site.org>
Please scramble the addresses so email harvesters cannot get addresses from
your HOWTO and then spam people. That has happened in the past.
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 labeled.
-------------------------------------------------------------------------------
1.5. Feedback
Feedback is most certainly welcome for this document. Without your submissions
and input, this document wouldn't exist. Please send your additions, comments
and criticisms to the following email address : <sgjoen@nyx.net>.
-------------------------------------------------------------------------------
1.6. Translations
Not everyone speaks English, pointers to translations are nice. Also your
translators tend to give very important inputs.
* German_Translation by <someone_(at)_somewhere.de>
* French_Translation by <someone_(at)_somewhere.fr>
* Italian_Translation by <someone_(at)_somewhere.it>
-------------------------------------------------------------------------------
2. Samples
This section gives some simple SGML examples you could use. Read the SGML
source to see how it was done.
Further information and examples can be obtained from the publication DocBook:
The_Definitive_Guide. Written by Norman Walsh and Leonard Muellner; 1st
Edition, October 1999.
-------------------------------------------------------------------------------
2.1. Lists
Lists are used frequently, and are available in a number of formats shown
below.
A list in which each entry is marked with a bullet or other dingbat:
* Apples
* Oranges
* Bananas
A list in which each entry is composed of a set of one or more terms and an
associated description:
Fruits
such as apples, oranges, and more.
Nuts
Don't eat too many; you are what you eat.
Vegetables
Potatos are spelled with care.
A list in which each entry is marked with a sequentially incremented label:
1. Step one
2. Step two
-------------------------------------------------------------------------------
2.2. Links
Links can be used within your documents to refer to different sections and
chapters or to refer to documents external to yours.
-------------------------------------------------------------------------------
2.2.1. Internal links
Click on the Section_2 link to jump to the top of this chapter. Note the anchor
at the section tag.
-------------------------------------------------------------------------------
2.2.2. External links
Click on this link to jump to the LDP site. Note you can use http, ftp, news
and other protocols in the locator if required.
-------------------------------------------------------------------------------
2.3. Images
Avoid diagrams if possible as this cannot be rendered in the ASCII outputs
which are still needed by many around the world.
Figure 1. Graphics Test Image
Here is another variation which allows for ALT text:
Caption for the graphic goes here: This is a Green Ball.
-------------------------------------------------------------------------------
3. Structure
A quick overview on how all parts fit together in the overall structure. An
example from the Multi Disk HOWTO is used.
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.
-------------------------------------------------------------------------------
3.1. Logical structure
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.
_____________________________________________________________________
| |
| ___________________________________________________________|
| |__ 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) __||
| -----------------------------------------------------------|
|_____________________________________________________________________|
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.
-------------------------------------------------------------------------------
3.2. Document structure
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.
-------------------------------------------------------------------------------
3.3. Reading plan
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, an example follows from the Multi Disk HOWTO.
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.
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 Section
12chapter.
Experienced
(aka Competent). If you are familiar with computers in general you can go
straight to the chapters on Section_4 and continue from there on.
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.
-------------------------------------------------------------------------------
4. Technologies
Introduction of technology for the newbie with a few references to detailed
works. Remember that not everyone has Internet access so you have to explain in
sufficient details so even the newbie can get by.
-------------------------------------------------------------------------------
5. Implementation
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.
-------------------------------------------------------------------------------
6. Maintenance
Few systems and designs are maintenance free, here you explain how to keep the
system running.
-------------------------------------------------------------------------------
7. Advanced Issues
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.
-------------------------------------------------------------------------------
8. Further Information
A HOWTO cannot describe everything, some times the user has to venture out on
th enet to get more information or just updates. Here is the place to tell
where and how. Again examples from the Multi Disk HOWTO, replace as needed.
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:
-------------------------------------------------------------------------------
8.1. News groups
Some of the most interesting news groups are:
* Storage.
* PC_storage.
* AFS.
* SCSI.
* Linux_setup.
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 FAQ_main_archive_FTP_site. The WWW
versions can be browsed at the FAQ_main_archive_WWW_site.
Some FAQs have their own home site, of particular interest:
* SCSI_FAQ and
* comp.arch.storage_FAQ.
-------------------------------------------------------------------------------
8.2. Mailing Lists
These are low-noise channels mainly for developers. Think twice before asking
questions there as noise delays the development. Some relevant lists are
<linux-raid>, <linux-scsi> and <linux-ext2fs>. Many of the most useful mailing
lists run on the vger.rutgers.edu server but this is notoriously overloaded, so
try to find a mirror. There are some lists mirrored at The_Redhat_Home_Page.
Many lists are also accessible at linuxhq, and the rest of the web site
contains useful information as well.
If you want to find out more about the lists available you can send a message
with the line lists to the list server at <majordomo@vger.rutgers.edu>. If you
need help on how to use the mail server just send the line 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 subscribe
command.
There is also a number of other majordomo list servers that can be of interest
such as the EATA driver list (<linux-eata@mail.uni-mainz.de>) and the
Intelligent IO list <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 Linux_Documentation_Homepage.
-------------------------------------------------------------------------------
8.3. HOWTO
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 Bootdisk, Installation, SCSI and UMSDOS. The main site for these is
the LDP_archiveat Metalab (formerly known as Sunsite).
There is a new HOWTO out that deals with setting up a DPT RAID system, check
out the DPT_RAID_HOWTO_homepage.
-------------------------------------------------------------------------------
8.4. Local Resources
In most distributions of Linux there is a document directory installed, have a
look in the /usr/doc directory. where most packages store their main
documentation and README files etc. Also you will here find the HOWTO archive
(/usr/doc/HOWTO) of ready formatted HOWTOs and also the mini-HOWTO archive (/
usr/doc/HOWTO/mini) of plain text documents.
Many of the configuration files mentioned earlier can be found in the /etc
directory. In particular you will want to work with the /etc/fstab file that
sets up the mounting of partitions and possibly also /etc/raidtab file that is
used for the md system to set up RAID.
The kernel source in /usr/src/linux is, of course, the ultimate documentation.
In other words, "use the source, Luke". 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 /usr/src/linux/Documentation. 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 (/var/log/messages) to see what is
going on and in particular how the booting went if too much scrolled off your
screen. Using tail -f /var/log/messages 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 /proc file system that is a window into the
inner workings of your system. Use cat rather than more to view the files as
they are reported as being zero length. Reports are that less works well here.
-------------------------------------------------------------------------------
8.5. Web Sites
There are a huge number of informative web sites available. By their very
nature they change quickly so do not be surprised if these links become quickly
outdated.
A good starting point is of course the Linux_Documentation_Project home page,
an information central for documentation, project pages and much more.
Please let me know if you have any other leads that can be of interest.
-------------------------------------------------------------------------------
9. Getting Help
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 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 the following information about your system:
Remember that booting text is logged to /var/log/messages 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 SHIFT and 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 brief as a complete log
file dumped to Usenet News is more than a little annoying.
-------------------------------------------------------------------------------
10. Concluding Remarks
Just summing up... Also a place for general recommendations.
-------------------------------------------------------------------------------
11. Questions and Answers
Check the newsgroups and try to determine some frequent problems and cover them
here. Again an example from the Multi Disk HOWTO.
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.
* Q:How many physical disk drives (spindles) does a Linux system need?
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.
* Q: Are there any disadvantages in this scheme?
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 df
gives you a good overview of the situation. Also check the swap partition(s)
using free to make sure you are not about to run out of virtual memory.
* Q: OK, so should I split the system into as many partitions as possible for a
single drive?
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.
(rest deleted.)
-------------------------------------------------------------------------------
12. Bits and Pieces
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.
-------------------------------------------------------------------------------
13. Examples
Example designs and sample configuration files and other relevant details is
always handy