From ae8609581b76e7c110f119824bdb1deab42114bd Mon Sep 17 00:00:00 2001 From: "Benj. Mako Hill" Date: Sat, 4 Jun 2005 00:07:14 +0000 Subject: [PATCH] I've gone through from the beginning and got up to "Credits" in the Intro. Author: mako Date: 2001/02/07 05:11:05 I've gone through from the beginning and got up to "Credits" in the Intro. I've done a good once over on the intro text but it will need to be revised and the rest of it is probably spelled horribly with bad grammer. "Credits" is the first section that I have not done. --- FreeSoftwareDevelopmentHOWTO.sgml | 2886 ++++++++++++----------- FreeSoftwareProjectManagementHOWTO.sgml | 2886 ++++++++++++----------- 2 files changed, 2894 insertions(+), 2878 deletions(-) diff --git a/FreeSoftwareDevelopmentHOWTO.sgml b/FreeSoftwareDevelopmentHOWTO.sgml index 98e1607..0e629ff 100644 --- a/FreeSoftwareDevelopmentHOWTO.sgml +++ b/FreeSoftwareDevelopmentHOWTO.sgml @@ -1,1439 +1,1447 @@ - - -
- - - - - 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 + + + 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 + + + + + + +
+ + diff --git a/FreeSoftwareProjectManagementHOWTO.sgml b/FreeSoftwareProjectManagementHOWTO.sgml index 98e1607..0e629ff 100644 --- a/FreeSoftwareProjectManagementHOWTO.sgml +++ b/FreeSoftwareProjectManagementHOWTO.sgml @@ -1,1439 +1,1447 @@ - - -
- - - - - 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 + + + 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 + + + + + + +
+ + -- 2.39.5