X-Git-Url: https://projects.mako.cc/source/fspm_howto/blobdiff_plain/febb7957a8feb7e38610ebf3f920c7090fca1e74..ec9b2cf542c7c2b959b872379f0f507c7cf397fc:/FreeSoftwareDevelopmentHOWTO.sgml diff --git a/FreeSoftwareDevelopmentHOWTO.sgml b/FreeSoftwareDevelopmentHOWTO.sgml index 98e1607..56a1ce2 100644 --- a/FreeSoftwareDevelopmentHOWTO.sgml +++ b/FreeSoftwareDevelopmentHOWTO.sgml @@ -1,1439 +1,1470 @@ - - -
- - - - - Free Software Development HOWTO - - - Benjamin - Mako - Hill - -
- mako@debian.org -
- - - - - - v0.01 - 1 January 2001 - bch - - Initial Release - - - - - - - fswd - - - - This HOWTO is designed for people with experience in programming - and some skills in managing a software project but who are new to - the world of Free Software. This document is meant to act as a - guide to the non-technical aspects of programming and is meant as - a crash course in the people skills that can make or break a free - software project. - - - - - - - - - Introduction - - - fswd!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 - - - - - - - - - - - - - - Starting a Project - - - - - Choosing a Project - - - - - - Deciding on a License - - - - - - Choosing a Method of Version Numbering - - - - - - Documentation - - - - - - Other Presentation Issues - - - - - - Nuturing Future Development - - - - - - - - - - Maintaining a Project: Interacting with Developers - - - - - Delegating Work - - - - - - Stable and Development Branches - - - - - - Freezing - - - - - - Avoiding the Code Cram Effect - - - - - - Accepting and Rejecting Patches - - - - - - - Maintaining a Project: Interacting with Users - - - - - Announcing Your Project - - - - - - Testing and Testers - - - - - - - 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 - - - - - - -
- - + + +
+ + + + + Free Software Development HOWTO + + + Benjamin + Mako + Hill + +
+ mako@debian.org + +
+ + + + + + v0.01 + 1 January 2001 + bch + + Initial Release + + + + + + + fswd + + + + This HOWTO is designed for people with experience in programming + and some skills in managing a software project but who are new to + the world of Free Software. This document is meant to act as a + guide to the non-technical aspects of programming and was written + to act as a crash course in the people skills that aren't taught + to commercial coders but that can make or break a free software + project. + + + + + + + + + Introduction + + + fswd!introduction + + + + For various reasons, this realease has been codenamed the + homade yogurt release. + + + + New code names will appear as per industry standard + guidelines to emphasize the state-of-the-art-ness of this + document. + + + + Skimming through Freshmeat provides mountains of reasons for this + HOWTO's existence--the Internet is littered with excellently + written and useful programs that have faded away into the Universe + of Free Software Forgottenness. This dismal scene made me ask + myself, "Why?" + + + + This HOWTO tries to do a lot of thing (probably too many), but it + can't answer that question and won't attempt it. What this HOWTO + will attempt to do is give your Free Software project a fighting + chance-an edge. If you write a piece of crap that no one is + interested in, you can read this HOWTO until you recite it in your + sleep and your project will probably fail. Then again, you can + write a beautiful, relevent piece of software and follow every + instruction in this HOWTO and your software may still not make + it. Sometimes life is like that. However, I'll go out a limb and + say that if you write a great, relevant pieces of software and + ignore the advise in this HOWTO, you'll probably fail + more often. + + + + A lot of the information in this HOWTO is best called common + sense. Of course, as any debate on interfaces will prove, what is + common sense to some programmers proves totally unintuitive to + others. After explaining bites and pieces of this HOWTO to Free + Software developers on several occasions, I realized that that + writing this HOWTO might provide a useful resource and a forum for + programmers to share ideas about what has and has not worked for + them. + + + + + + + + As anyone involved in any of what seems like an unending parade of + ridiculous intellectual property clashes will attest to, a little + bit of legalese proves 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 the initial release. It is written to be released to + developers for critique and brainstorming and submitted to + Hampshire College for academic credit. Please keep in mind that + this version of the HOWTO is still in an infant stage and will be + revised extensively before it hits the LDP. + + + + The latest version number of this document should always be listed + at my webpage at + http://people.debian.org/~mako/ Debian. + + + + The newest version of this HOWTO will always be made available at + the same website, in a variety of formats: + + + + + + + HTML. + + + + + + plain text. + + + + + + compressed + postscript (US letter format). + + + + + + compressed + postscript (Universal format / 8.27x11in; 210x279mm). + + + + + + SGML source. + + + + + + + + + + Credits + + + In this version I have the pleasure of acknowledging: + + + + Karl Fogel, the author of Open + Source Development with CVS published by the Coriolis + Open Press. Larges parts of the book are available on the web. 225 pages of + the book are available under the GPL and constitute the best + tutorial on CVS I have ever seen. The rest of the book covers, + "the challenges and philosophical issues inherent in running an + Open Source project using CVS." The book does a good job of + covering some of the subjects brought up in this HOWTO and much + more. The book's + website has information on ordering the book and provides + several translations of the chapters on CVS. I you are seriously + interested in running a Free Software project, you want this book. + + + + Karl Fogel can be reached at kfogel (at) red-bean (dot) + com + + + Also providing support and material, and inspiration for this + HOWTO is Eric S. Raymond for his prolific, consitent, and + carefully crafted arguments, to Lawrence Lessig for reminding me + of the importance of Free Software and to every user and developer + involved with the Debian + Project. The project has provided me with a home, a place + to practice Free Software advocacy and to make a difference, a + place to learn from those how have been involved with the movement + much longer than I, and an proof of a Free Software project that + definately, definately works. + + + + Above all, I want to thank Richard Stallman + for his work at the Free Software Foundation and for never giving + up. Stallman provided the philosphical basis that attracts me to + Free Software and that drives me towards writing a document to + make sure it succeeds. RMS can always be emailed at rms + (at) gnu (dot) org. + + + + + + + + Feedback + + + Feedback is most certainly welcome for this document. Without your + submissions and input, this document wouldn't exist. Something + missing? Don't hesitate to contact me and to write a chapter. I + want this document to be as much a product of the Free Software + development process that it heralds and I think its ultimate + success will be rooted in this fact. Please send your additions, + comments and criticisms to the following email address : + mako (at) debian (dot) org. + + + + + + + Translations + + + I know that not everyone speaks English. Translations are nice and + I'd love for this HOWTO to gain the kind of international reach + afforded by a translated version. + + + However, this HOWTO is still young and I have to yet to be + contacted about a translation so English is all that is + available. If you would like to help with or do a translation, you + will gain my utmost respect and admiration and you'll get to be + part of a cool process. If you are at all interested, please don't + hesitate to contact me at: mako (at) debian (dot) + org. + + + + + + + + + + Starting a Project + + + fswd!starting + + + + + + + + Choosing a Project + + + + + + Deciding on a License + + + + + + Choosing a Method of Version Numbering + + + + + + Documentation + + + + + + Other Presentation Issues + + + + + + Nuturing Future Development + + + + + + + + + + Maintaining a Project: Interacting with Developers + + + fswd!developers + + + + + + Delegating Work + + + + + + Stable and Development Branches + + + + + + Freezing + + + + + + Avoiding the Code Cram Effect + + + + + + Accepting and Rejecting Patches + + + + + + + Maintaining a Project: Interacting with Users + + + fswd!users + + + + + + + Announcing Your Project + + + + + + Testing and Testers + + + + + + + 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 + + + + + + +
+ +