From: Benj. Mako Hill Date: Sat, 4 Jun 2005 00:06:57 +0000 (+0000) Subject: Initial revision X-Git-Url: https://projects.mako.cc/source/fspm_howto/commitdiff_plain/2d412c2c3c17321b235b6e0153accf850667ed10 Initial revision Author: makolee Date: 2001/01/02 20:59:48 Initial revision --- 2d412c2c3c17321b235b6e0153accf850667ed10 diff --git a/big-howto-template-ld.sgml b/big-howto-template-ld.sgml new file mode 100644 index 0000000..73fd364 --- /dev/null +++ b/big-howto-template-ld.sgml @@ -0,0 +1,859 @@ + + + + + +
+ + +HOWTO-template for big HOWTOs <!-- insert your title here --> +<author>Stein Gjoen, <tt/sgjoen@nyx.net/ <!-- insert your name here --> +<date>v0.05, 24 July 2000 <!-- always have a version number and a date --> +<abstract> <!-- the abstract: a short and precise description --> +<nidx>template</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> +<nidx>template!introduction</nidx> <!-- here introduction is a sub entry of template, exclamationamrk 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> + +<!-- +This HOWTO is copyrighted 2000 Stein Gjoen. <em>Replace with your name +when you use this skeleton for a new HOWTO</em> + +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 questions, please contact +at linux-howto@metalab.unc.edu via email. + +--> + + +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 fowarded +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 it news. 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>disk!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 exerpts 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 th enet 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>disk!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>disk!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>disk!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>disk!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>disk!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>disk!information resources!WWW</nidx> +<nidx>disk!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>disk!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> + + +</article> diff --git a/big-howto-template.sgml b/big-howto-template.sgml new file mode 100644 index 0000000..6ee0003 --- /dev/null +++ b/big-howto-template.sgml @@ -0,0 +1,1372 @@ +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> + +<article> + +<!-- Header --> + + <artheader> + <title>HOWTO-template for big HOWTOs + + + Stein + Gjoen + +
+ sgjoen@nyx.net +
+ + + + + Gregory + Leblanc + +
+ gleblanc@cu-portland.edu +
+ + + + + Greg + Ferguson + +
+ gferg@sgi.com +
+ + + + + + v0.05 + 8 June 2000 + gjf + + Fixed ids and comments + + + + + v0.04 + 1 June 2000 + gjf + + Additional spacing, layout changes, added new sections + + + + + + + template + + + + 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. + + + + + + + + + + Introduction + + + disk!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. + + + + + + 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 + + + + + + + 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. + + + + + + + New Versions + + + (your index root)!news on + + + + 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). + + + + + + + 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. + + + + + + + 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. + + + + + + + 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 + + + + + + + + + + + + + + + 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. + + + + + + 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: + + + + + + + Step one + + + + Step two + + + + + + + + + + Links + + + Links can be used within your documents to refer to + different sections and chapters or to refer to documents external + to yours. + + + + Internal links + + + Click on the link to jump to the top of + this chapter. Note the anchor at the section tag. + + + + + 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. + + + + + + + + + Images + + + Avoid diagrams if possible as this cannot be rendered + in the ASCII outputs which are still needed by many around the + world. + + + +
+ Graphics Test Image + +
+ + + + Here is another variation which allows for ALT text: + + + + + + + + + + + + ALT text to be used: Green Ball + + + + + + Caption for the graphic goes here: This is a Green Ball. + + + + + + + + + + + + + + + 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. + + + + + + Logical structure + + + disk!structure, I/O subsystem + + + + 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. + + + + + + + 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. + + + + + + + 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 chapter. + + + + + + Experienced + + + (aka Competent). If you are familiar with computers in + general you can go straight to the chapters on + 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. + + + + + + + + + + + + + + + + + Technologies + + + (your index root)!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. + + + + + + + + + + + Implementation + + + (your index root)!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. + + + + + + + + + + + Maintenance + + + (your index root)!maintenance + + + + Few systems and designs are maintenance free, here you + explain how to keep the system running. + + + + + + + + + + + Advanced Issues + + + (your index root)!advanced topics + + + + 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. + + + + + + + + + + + Further Information + + + (your index root)!information resources + + + + 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: + + + + + + News groups + + + disk!information resources!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. + + + + + + + + + + + Mailing Lists + + + disk!information resources!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. + + + + + + + HOWTO + + + disk!information resources!HOWTOs + + + + 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 a new HOWTO out that deals with setting up a DPT RAID + system, check out the + DPT RAID + HOWTO homepage. + + + + + + + Local Resources + + + disk!information resources!local + + + + 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. + + + + + + + Web Sites + + + disk!information resources!WWW + + + disk!information resources!web pages + + + + 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. + + + + + + + + + + + + Getting Help + + + (your index root)!assistance, obtaining + + + + 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: + + + + + + + Hardware + + + + + Processor + + + + DMA + + + + IRQ + + + + Chip set (LX, BX etc) + + + + Bus (ISA, VESA, PCI etc) + + + + + Expansion cards used (Disk controllers, video, IO + etc.) + + + + + + + + + + Software + + + + + + BIOS (On motherboard and possibly SCSI host adapters) + + + + LILO, if used + + + + + Linux kernel version as well as possible modifications + and patches + + + + + Kernel parameters, if any + + + + + Software that shows the error (with version number + or date) + + + + + + + + + + + Peripherals + + + + + + + Type of disk drives with manufacturer name, version and type + + + + + Other relevant peripherals + + + + + + + + + + + + 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. + + + + + + + + + + + Concluding Remarks + + + (your index root)!conclusion + + + + Just summing up... Also a place for general + recommendations. + + + + + + + + + + + Questions and Answers + + + (your index root)!FAQ + + + (your index root)!frequently asked questions + + + + 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. + + + + + + + Greg Leblanc: Depending on how big this FAQ gets, perhaps it + would be worthwhile to have, say, the 5 most FAQ, and put the + rest into an external FAQ. Dunno. Comments? + + + (rest deleted.) + + + + + + + + + + + Bits and Pieces + + + disk!miscellaneous + + + + 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. + + + + + + + + + + + Examples + + + (your index root)!examples + + + + Example designs and sample configuration files and other + relevant details is always handy + + + + + + +
+ +