HOWTO-template for Big HOWTOs

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.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:

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.3. Images

Avoid diagrams if possible as this cannot be rendered in the ASCII outputs which are still needed by many around the world.

Here is another variation which allows for ALT text:

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.

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.