diff options
Diffstat (limited to 'en_US.ISO8859-1/articles')
108 files changed, 0 insertions, 46207 deletions
diff --git a/en_US.ISO8859-1/articles/5-roadmap/Makefile b/en_US.ISO8859-1/articles/5-roadmap/Makefile deleted file mode 100644 index b3b8bbb0e0..0000000000 --- a/en_US.ISO8859-1/articles/5-roadmap/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# -# $FreeBSD$ -# -# Article: FreeBSD 5-STABLE roadmap - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -CSS_SHEET_ADDITIONS= extra.css - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/5-roadmap/article.sgml b/en_US.ISO8859-1/articles/5-roadmap/article.sgml deleted file mode 100644 index 596a39016f..0000000000 --- a/en_US.ISO8859-1/articles/5-roadmap/article.sgml +++ /dev/null @@ -1,645 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; - -<!ENTITY t.releng.3 "<literal>RELENG_3</literal>"> -<!ENTITY t.releng.4 "<literal>RELENG_4</literal>"> -<!ENTITY t.releng.5 "<literal>RELENG_5</literal>"> -<!ENTITY t.releng.5.1 "<literal>RELENG_5_1</literal>"> -<!ENTITY t.releng.5.2 "<literal>RELENG_5_2</literal>"> -<!ENTITY t.releng.5.3 "<literal>RELENG_5_3</literal>"> -<!ENTITY t.releng.head "<literal>HEAD</literal>"> -]> - -<article> - <articleinfo> - <title>The Road Map for 5-STABLE</title> - - <authorgroup> - <corpauthor>The &os; Release Engineering Team</corpauthor> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <copyright> - <year>2003</year> - <holder role="mailto:re@FreeBSD.org">The &os; Release - Engineering Team</holder> - </copyright> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.ieee; - &tm-attrib.intel; - &tm-attrib.sparc; - &tm-attrib.sun; - &tm-attrib.opengroup; - &tm-attrib.general; - </legalnotice> - </articleinfo> - - <sect1 id="intro"> - <title>Introduction and Background</title> - - <para>After nearly three years of work, &os; 5.0 was released in January - of 2003. Features like the GEOM block layer, Mandatory Access Controls, - ACPI, &sparc64; and ia64 platform support, and UFS snapshots, background - filesystem checks, and 64-bit inode sizes make it an exciting operating - system for both desktop and enterprise users. However, some important - features are not complete. The foundations for fine-grained locking - and preemption in the kernel exist, but much more work is left to be - done. Performance and stability compared to &os; - 4.<replaceable>X</replaceable> has declined and must be restored and - surpassed.</para> - - <para>This is somewhat similar to the situation that &os; faced in the - 3.<replaceable>X</replaceable> series. Work on 3-CURRENT trudged along - seemingly forever, and finally a cry was made to <quote>just ship it</quote> and - clean up later. This decision resulted in the 3.0 and 3.1 releases - being very unsatisfying for most, and it wasn't until 3.2 that the - series was considered <quote>stable</quote>. To make matters worse, the &t.releng.3; - branch was created along with the 3.0 release, and the &t.releng.head; branch was - allowed to advance immediately towards 4-CURRENT. This resulted in a - quick divergence between &t.releng.head; and &t.releng.3;, making maintenance of the - &t.releng.3; branch very difficult. &os; 2.2.8 was left for quite a while - as the last production-quality version of &os;.</para> - - <para>Our intent is to avoid repeating that scenario with &os; 5.x. - Delaying the &t.releng.5; branch until it is stable and production quality - will ensure that it stays maintainable and provides a compelling reason - to upgrade from 4.<replaceable>X</replaceable>. To do this, we must - identify the current areas of weakness and set clear goals for - resolving them. This document contains what we as the release - engineering team feel are the milestones and issues that must be - resolved for the &t.releng.5; branch. It does not dictate every aspect of - &os; development, and we welcome further input. Nothing that follows - is meant to be a sleight against any person or group, or to trivialize - any work that has been done. There are some significant issues, - though, that need decisive and unbiased action.</para> - </sect1> - - <sect1 id="major-issues"> - <title>Major issues</title> - - <para>The success of the 5.<replaceable>X</replaceable> series hinges on - the ability to deliver fine-grained threading and re-entrancy in the - kernel (also known as SMPng) and kernel-supported POSIX threads in - userland, while not sacrificing overall system stability or - performance.</para> - - <sect2 id="SMPng"> - <title>SMPng</title> - - <para>The state of SMPng and kernel lockdown is the biggest concern for - 5.<replaceable>X</replaceable>. To date, few major systems have come - out from under the kernel-wide mutex known as <quote>Giant</quote>. - The SMP status page at <ulink url="&url.base;/smp"></ulink> - provides a comprehensive breakdown - of the overall SMPng status. Status specific to SMPng progress in - device drivers can be found at at - <ulink url="&url.base;/projects/busdma"></ulink>. - In summary:</para> - - <itemizedlist> - <listitem> - <para>VM: Kernel malloc is locked and free of Giant. The UMA zone - allocator is also free of Giant. vm_object locking is in progress - and is an important step to making the buffer/cache free of - Giant. Pmap locking remains to be started.</para> - </listitem> - - <listitem> - <para>GEOM: The GEOM block layer was designed to run free of Giant - and allow GEOM modules and underlying block drivers to run free - of Giant. Currently, only the &man.ata.4; and &man.aac.4; drivers - are locked and run without Giant. Work on other block drivers is - in progress. Locking the CAM subsystem is required for nearly all - SCSI drivers to run without Giant; this work has not started - yet.</para> - <para>Additionally, GEOM has the potential to suffer performance loss - due to its upcall and downcall data paths happening in kernel threads. - Improved lightweight context switches might help this.</para> - </listitem> - - <listitem> - <para>Network: Work has restarted on locking the network stack. - Routing tables, ARP, bridge, IPFW, Fast-Forward, TCP, UDP, IP, - Fast IPSEC, and interface layers are being targeted initially, along - with several Ethernet device drivers. The socket layer, IPv6, and - other protocol layers will be targeted later. The primary goal - of this work is to regain the performance found in - &os; 4.<replaceable>X</replaceable>. The cost of context switching - to the device driver ithreads and the netisr is still hampering - performance.</para> - </listitem> - - <listitem> - <para>VFS: Initial pre-cleanup started.</para> - </listitem> - - <listitem> - <para>buffer/cache: Initial work complete on locking the buffer.</para> - </listitem> - - <listitem> - <para>Proc: Initial proc locking is in place, further progress is - expected for &os; 5.2.</para> - </listitem> - - <listitem> - <para>CAM: No significant work has occurred on the CAM SCSI - layer.</para> - </listitem> - - <listitem> - <para>Newbus: some work has started on locking down the device_t - structure.</para> - </listitem> - - <listitem> - <para>Pipes: complete</para> - </listitem> - - <listitem> - <para>File descriptors: complete.</para> - </listitem> - - <listitem> - <para>Process accounting: jails, credentials, MAC labels, and - scheduler are out from under Giant.</para> - </listitem> - - <listitem> - <para>MAC Framework: complete</para> - </listitem> - - <listitem> - <para>Timekeeping: complete</para> - </listitem> - - <listitem> - <para>kernel encryption: crypto drivers and core &man.crypto.4; - framework are Giant-free. KAME IPsec has not been locked.</para> - </listitem> - - <listitem> - <para>Sound subsystem: complete, but lock order reversal problems seem - to persist.</para> - </listitem> - - <listitem> - <para>kernel preemption: preemption for interrupt threads is enabled. - However, contention due to Giant covering much of the kernel and - most of the device driver interrupt routines causes excessive - context switches and might actually be hurting performance. Work - is underway to explore ways to make preemption be - conditional.</para> - </listitem> - </itemizedlist> - - </sect2> - - <sect2 id="interrupts"> - <title>Interrupt latency and servicing</title> - - <para>SMPng introduced the concept of dedicating kernel threads, known as - ithreads, to servicing interrupts. With this, driver interrupt - service routines are allowed to block for mutexes, memory allocations, - etc. While this makes writing drivers easier, it introduces considerable - latency into the system due to the complete process context switch must - be performed in order to service the ithread. This is aggravated by the - extensive coverage over the kernel by the Giant mutex, and often results - in multiple sleeps and context switches in order to service an interrupt. - Drivers that register their interrupt as INTR_MPSAFE are less likely to - feel these aggravating effects, but the overhead of doing a context - switch remains. Interrupt service routines that are registered as - INTR_FAST are run directly from the interrupt context and do not suffer - these problems at all. However, the INTR_FAST property forces the - interrupt line to be exclusive; no sharing can occur on it. The - proliferation of shared interrupts on PC systems makes this - undesirable.</para> - - <para>Several ideas have been proposed to help combat this problem:</para> - <itemizedlist> - <listitem> - <para>Special casing ithreads to be lightweight is a possibility. This - might involve reducing the amount of saved context for the ithread, - stack-borrowing from another kthread, and/or creating a new fast-path - to avoid the mi_switch() routine.</para> - </listitem> - - <listitem> - <para>A new interrupt model can be introduced to allow drivers to - register an 'interrupt filter' along with a normal service routine. - This would be similar to the Mac OS X model in use today. Interrupt - filter routines would allow the driver to determine if it is - interested in servicing the interrupt, allow it to squelch the - interrupt source, and possibly determine and schedule service - actions. It would run in the same context as the low-level interrupt - service routine, so sleeping would be strictly forbidden. If actions - that result in sleeping or blocking for long periods are required, - the filter would signal to the caller that its normal ithread routine - should be scheduled.</para> - </listitem> - </itemizedlist> - - </sect2> - - <sect2 id="KSE"> - <title>Kernel-supported application threads</title> - - <para>The FreeBSD 5.1 development cycle saw the KSE package jump into a - highly usable state. THR, an alternate threading package based on some - of the KSE kernel primitives but implementing purely 1:1 scheduling - semantics also appeared and is in a similarly experimental but usable - state. Users may interchange these two libraries along with the legacy - libc_r library via relinking their apps or by using the new libmap - feature of the runtime linker. This excellent progress must be driven - to completion before the &t.releng.5; branch point so that the libc_r - package can be deprecated.</para> - - <itemizedlist> - <listitem> - <para>The kernel and userland components for KSE and THR must be - completed for all Tier-1 platforms. The decision on which thread - package to sanction as the default will likely be made on a - per-platform basis depending on the stability and completeness of - each package.</para> - - <para> - <table id=KSETable> - <title>KSE Status</title> - <tgroup cols="4"> - <thead> - <row> - <entry>Platform</entry> - <entry>Kernel</entry> - <entry>Userland</entry> - <entry>Works?</entry> - </row> - </thead> - - <tbody> - <row> - <entry>i386</entry> - <entry>YES</entry> - <entry>YES</entry> - <entry>YES</entry> - </row> - - <row> - <entry>alpha</entry> - <entry>NO</entry> - <entry>YES</entry> - <entry>NO</entry> - </row> - - <row> - <entry>sparc64</entry> - <entry>YES</entry> - <entry>NO</entry> - <entry>NO</entry> - </row> - - <row> - <entry>ia64</entry> - <entry>YES</entry> - <entry>YES</entry> - <entry>YES</entry> - </row> - - <row> - <entry>amd64</entry> - <entry>YES</entry> - <entry>YES</entry> - <entry>YES</entry> - </row> - </tbody> - </tgroup> - </table> - - <table id=THRTable> - <title>THR Status</title> - <tgroup cols="4"> - <thead> - <row> - <entry>Platform</entry> - <entry>Kernel</entry> - <entry>Userland</entry> - <entry>Works?</entry> - </row> - </thead> - - <tbody> - <row> - <entry>i386</entry> - <entry>YES</entry> - <entry>YES</entry> - <entry>YES</entry> - </row> - - <row> - <entry>alpha</entry> - <entry>YES</entry> - <entry>YES</entry> - <entry>YES</entry> - </row> - - <row> - <entry>sparc64</entry> - <entry>YES</entry> - <entry>YES</entry> - <entry>NO</entry> - </row> - - <row> - <entry>ia64</entry> - <entry>YES</entry> - <entry>YES</entry> - <entry>YES</entry> - </row> - - <row> - <entry>amd64</entry> - <entry>NO</entry> - <entry>NO</entry> - <entry>NO</entry> - </row> - </tbody> - </tgroup> - </table> - </para> - </listitem> - - <listitem> - <para>KSE must pass the ACE test suite on all Tier-1 platforms. - Additional real-world testing must also be performed to ensure - that the libraries are indeed useful. At a minimum, the following - packages should be tested:</para> - <itemizedlist> - <listitem><para>OpenOffice</para></listitem> - <listitem><para>KDE Desktop</para></listitem> - <listitem><para>Apache 2.x</para></listitem> - <listitem><para>BIND 9.2.x</para></listitem> - <listitem><para>MySQL</para></listitem> - <listitem><para>&java; 1.4.x</para></listitem> - </itemizedlist> - </listitem> - - </itemizedlist> - - </sect2> - </sect1> - - <sect1 id="goals"> - <title>Requirements for 5-STABLE</title> - - <para>The &t.releng.5 branch must offer users the same stability and - performance that is currently enjoyed in the &t.releng.4 branch. - While the goal of SMPng is to allow performance to far exceed what - is found in &t.releng.4; and its siblings BSD's, regaining performance - to the basic level is of the utmost importance. The branch must also - be mature enough to avoid ABI and API changes while still allowing - potential problems to be resolved.</para> - - <sect2 id="API"> - <title>ABI/API/Infrastructure stability</title> - <para>Enough infrastructure must be in place and stable to allow - fixes from &t.releng.head; to easily and safely be merged into - &t.releng.5;. Also, we must draw a line as to what subsystems are - to be locked down when we go into 5-STABLE.</para> - - <itemizedlist> - <listitem> - <para>KSE: Both kernel and userland components must - reach the same level of functionality for all Tier-1 platforms - in both UP and SMP configurations. The definition of <quote>Tier-1 - platforms</quote> can be found in - <ulink url="&url.articles.committers-guide;/archs.html"></ulink>. - Continued testing against the ACE test - suite must be made as the &t.releng.5; branch draws near. KSE - must pose no functional regressions for the ongoing &java; - certification program. Common desktop and server applications - must run seamlessly under KSE. A policy must be decided on as - to which platforms will enable KSE as the default threading - package, how to allow the user to switch threading packages, and - how third-party packages will be made aware of these choices.</para> - </listitem> - - <listitem> - <para>busdma interface and drivers: architectures like PAE/&i386; and - sparc64 which don't have a direct mapping between host memory - address space and expansion bus address space require the - elimination for vtophys() and friends. The busdma interface was - created to handle exactly this problem, but many drivers do not use - it yet. The busdma project at - <ulink url="&url.base;/projects/busdma"></ulink> - tracks the - progress of this and should be used to determine which drivers - must be converted for &t.releng.5; and which can be left behind. - No new storage or network drivers shall be allowed into the - &os; source tree. Exceptions for other classes of drivers must - be justified in public discussion.</para> - </listitem> - - <listitem> - <para>PCI resource allocation: PC2003 compliance requires that x86 - systems no longer configure PCI devices from the system BIOS, - leaving this task solely to the OS. &os; must gain the ability to - manage and allocate PCI memory resources on its own. Implementing - this should take into account cardbus, PCI-HotPlug, and laptop - dock station requirements. This feature will become increasingly - critical through the lifetime of &t.releng.5;, and therefore is a - requirement for the &t.releng.5; branch.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="performance"> - <title>Performance</title> - <para>Performance hinges on the progress of SMPng infrastructure and - the following areas:</para> - - <itemizedlist> - <listitem> - <para>Storage: The GEOM block layer allows storage drivers to - run without Giant. All drivers that interface directly with - GEOM (as opposed to sitting underneath CAM or another middleware) - must be locked and free of Giant in both their strategy and - completion paths. Their interrupt handlers must also run free - of Giant.</para> - </listitem> - - <listitem> - <para>Network: The layers in the IPv4 path below the socket layer - must be locked and free of Giant. This includes the protocol, - routing, bridging, filtering, and hardware layers. Allowances must - be made for protocols that are not locked, especially IPv6. - Testing must also be performed to ensure stability, correctness, - and performance.</para> - </listitem> - - <listitem> - <para>Interrupt and context switching: As discussed above, interrupt - latency and context switching have a severe impact of performance. - Context switching for ithreads and kthreads must be improved on - platforms. New interrupt handling models that allow for faster - more flexible handling of both traditional and MSI interrupts must - be investigated and implemented.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="benchmarks"> - <title>Benchmarks and performance testing</title> - <para>Having a source of reliable and useful benchmarks is essential - to identifying performance problems and guarding against performance - regressions. A <quote>performance team</quote> that is made up of - people and resources for formulating, developing, and executing - benchmark tests should be put into place soon. Comparisons should - be made against both &os; 4.<replaceable>X</replaceable> and Linux - 2.4/2.6. Tests to consider are:</para> - - <itemizedlist> - <listitem> - <para>the classic <quote>worldstone</quote></para> - </listitem> - - <listitem> - <para>webstone: <filename role="package">www/webstone</filename></para> - </listitem> - - <listitem> - <para>Fstress: <ulink url="http://www.cs.duke.edu/ari/fstress/"></ulink></para> - </listitem> - - <listitem> - <para>ApacheBench: <filename role="package">www/p5-ApacheBench</filename></para> - </listitem> - - <listitem> - <para>netperf: <filename role="package">benchmarks/netperf</filename></para> - </listitem> - - <listitem> - <para>Web Polygraph: <ulink url="http://www.web-polygraph.org/"></ulink> - Note: does not compile with gcc 3.x yet.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="features"> - <title>Features:</title> - - <itemizedlist> - <listitem> - <para>NEWCARD/OLDCARD: The NEWCARD subsystem was made the default - for &os; 5.0. Unfortunately, it contains no support for - non-Cardbus bridges and falls victim to interrupt routing - problems on some laptops. The classic 16-bit bridge support, - OLDCARD, still exists and can be compiled in, but this is highly - inconvenient for users of older laptops. If OLDCARD cannot be - completely deprecated for &t.releng.5;, then provisions must be made - to allow users to easily install an OLDCARD-enabled kernel. - Documentation should be written to help transition users from - OLDCARD to NEWCARD and from &man.pccardd.8; to - &man.devd.8;. The power management and - <quote>dumpcis</quote> functionality of &man.pccardc.8; needs to be - brought forward to work with NEWCARD, along with the ability to - load CIS quirk entries. Most of this functionality can be - integrated into &man.devd.8; and - &man.devctl.4;.</para> - </listitem> - - <listitem> - <para>New scheduler framework: The new scheduler framework is in - place, and users can select between the classic 44BSD scheduler - and the new ULE scheduler. A scheduler that demonstrates - processor affinity, HyperThreading and KSE awareness, and no - regressions in performance or interactivity characteristics must - be available for &t.releng.5;.</para> - </listitem> - - <listitem> - <para>GDB: GDB in the base system must work for sparc64, and - must also understand KSE thread semantics. GDB 5.3 is available - and is reported to address the sparc64 issues.</para> - </listitem> - - </itemizedlist> - </sect2> - - <sect2 id="documentation"> - <title>Documentation:</title> - - <itemizedlist> - <listitem> - <para>The manual pages, Handbook, and FAQ should be free from - content specific to &os; 4.<replaceable>X</replaceable>, i.e. all - text should be equally applicable to &os; - 5.<replaceable>X</replaceable>. The installation section of the - handbook needs the most work in this area.</para> - </listitem> - - <listitem> - <para>The release documentation needs to be complete and accurate - for all Tier-1 architectures. The hardware notes and - installation guides need specific attention.</para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1 id="schedule"> - <title>Schedule</title> - - <para>The original schedule of releasing &os; 5.2 and branching - &t.releng.5; in September 2003 is being pushed back due to the - complexity of the remaining tasks. The new schedule follows:</para> - - <itemizedlist> - <listitem> - <para>Nov 18, 2003: 5.2-BETA, general code freeze</para> - </listitem> - <listitem> - <para>Dec 6, 2003: 5.2-RC1, &t.releng.5.2; branched</para> - </listitem> - <listitem> - <para>Dec 9, 2003: 5.2-RC2</para> - </listitem> - <listitem> - <para>Dec 16, 2003: 5.2-RELEASE</para> - </listitem> - <listitem> - <para>Mar 1, 2004: 5.3-BETA, general code freeze</para> - </listitem> - <listitem> - <para>Mar 15, 2004: 5.3-RC1, &t.releng.5; and &t.releng.5.3; branched</para> - </listitem> - <listitem> - <para>Mar 22, 2004: 5.3-RC2</para> - </listitem> - <listitem> - <para>Mar 29, 2004: 5.3-RELEASE</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="future"> - <title>Post &t.releng.5; direction</title> - - <para>The focus should be bug fixes and incremental improvements, as with - all the -STABLE development branches. Following the usual procedure, - everything should be vetted through the &t.releng.head; branch first and - committed to &t.releng.5; with caution. New device drivers, incremental - features, etc, will be welcome in the branch once they have been tested - in &t.releng.head; and found stable enough.</para> - - <para>Further SMPng lockdowns will be divided into two categories: driver - and subsystem. The only subsystem that will be sufficiently locked - down for &t.releng.5; will be GEOM, so incrementally locking down device - drivers under it is a worthy goal for the branch. Full subsystem - lockdowns will have to be fully tested and proven in &t.releng.head; before - consideration will be given to merging them into &t.releng.5;.</para> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/5-roadmap/extra.css b/en_US.ISO8859-1/articles/5-roadmap/extra.css deleted file mode 100644 index 8d13ebf887..0000000000 --- a/en_US.ISO8859-1/articles/5-roadmap/extra.css +++ /dev/null @@ -1,16 +0,0 @@ -/* - * Netscape 4 does not recognize the @import directive of CSS, so we - * can't add an additional stylesheet layer on top of the default one. - * Instead, we use this hack to copy this file to the end of - * docbook.css. - * - * $FreeBSD$ - */ - -/* @import "docbook.css"; */ - -/* Customization that looks good for this particular article. */ - -DIV.TITLEPAGE { - text-align: center; -} diff --git a/en_US.ISO8859-1/articles/Makefile b/en_US.ISO8859-1/articles/Makefile deleted file mode 100644 index 17422513d9..0000000000 --- a/en_US.ISO8859-1/articles/Makefile +++ /dev/null @@ -1,48 +0,0 @@ -# $FreeBSD$ - -SUBDIR = -SUBDIR+= 5-roadmap -SUBDIR+= checkpoint -SUBDIR+= committers-guide -SUBDIR+= console-server -SUBDIR+= contributing -SUBDIR+= contributors -SUBDIR+= cvs-freebsd -SUBDIR+= cvsup-advanced -SUBDIR+= dialup-firewall -SUBDIR+= diskless-x -SUBDIR+= euro -SUBDIR+= explaining-bsd -SUBDIR+= fbsd-from-scratch -SUBDIR+= filtering-bridges -SUBDIR+= fonts -SUBDIR+= formatting-media -SUBDIR+= freebsd-questions -SUBDIR+= hats -SUBDIR+= hubs -SUBDIR+= ipsec-must -SUBDIR+= java-tomcat -SUBDIR+= laptop -SUBDIR+= mailing-list-faq -SUBDIR+= mh -SUBDIR+= multi-os -SUBDIR+= new-users -SUBDIR+= pam -SUBDIR+= portbuild -SUBDIR+= pr-guidelines -SUBDIR+= problem-reports -SUBDIR+= pxe -SUBDIR+= relaydelay -SUBDIR+= releng -SUBDIR+= releng-packages -SUBDIR+= serial-uart -SUBDIR+= solid-state -SUBDIR+= storage-devices -SUBDIR+= vinum -SUBDIR+= vm-design -SUBDIR+= zip-drive - -# ROOT_SYMLINKS+= new-users - -DOC_PREFIX?= ${.CURDIR}/../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/Makefile.inc b/en_US.ISO8859-1/articles/Makefile.inc deleted file mode 100644 index feb3008c1c..0000000000 --- a/en_US.ISO8859-1/articles/Makefile.inc +++ /dev/null @@ -1,5 +0,0 @@ -# -# $FreeBSD: doc/en_US.ISO8859-1/articles/Makefile.inc,v 1.3 1999/09/06 06:52:35 peter Exp $ -# - -DESTDIR?= ${DOCDIR}/en_US.ISO8859-1/articles/${.CURDIR:T} diff --git a/en_US.ISO8859-1/articles/checkpoint/Makefile b/en_US.ISO8859-1/articles/checkpoint/Makefile deleted file mode 100644 index 309d6cbcd8..0000000000 --- a/en_US.ISO8859-1/articles/checkpoint/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Integration of Check Point Firewall-1 and FreeBSD IPsec - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml -IMAGES_EN= networks.pic - -URL_RELPREFIX?= ../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/checkpoint/article.sgml b/en_US.ISO8859-1/articles/checkpoint/article.sgml deleted file mode 100644 index b64291c214..0000000000 --- a/en_US.ISO8859-1/articles/checkpoint/article.sgml +++ /dev/null @@ -1,437 +0,0 @@ -<!-- Copyright (c) 2001 The FreeBSD Documentation Project - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "AS - IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, - THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY - DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -<!ENTITY legalnotice SYSTEM "../../share/sgml/legalnotice.sgml"> -]> - -<article> - <articleinfo> - <title>Integration of Check Point <trademark class='registered'>VPN-1</trademark>/<trademark class='registered'>Firewall-1</trademark> and FreeBSD IPsec</title> - - <authorgroup> - <author> - <firstname>Jon</firstname> - <surname>Orbeton</surname> - - <affiliation> - <address><email>jono@securityreports.com</email></address> - </affiliation> - </author> - - <author> - <firstname>Matt</firstname> - <surname>Hite</surname> - - <affiliation> - <address><email>mhite@hotmail.com</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <copyright> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <holder role="mailto:jono@securityreports.com">Jon Orbeton</holder> - </copyright> - - &legalnotice; - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.check-point; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This document explains how to configure a <acronym>VPN</acronym> - tunnel between FreeBSD and Check Point's - <trademark class='registered'>VPN-1</trademark>/ - <trademark class='registered'>Firewall-1</trademark>. Other - documents provide similar information, but do not contain instructions - specific to VPN-1/Firewall-1 and its integration with FreeBSD. These - documents are listed at the conclusion of this paper for further - reference.</para> - </abstract> - </articleinfo> - - <sect1 id="prerequisites"> - <title>Prerequisites</title> - - <para>The following is a diagram of the machines and networks referenced - in this document.</para> - - <mediaobject> - <imageobject> - <imagedata fileref="networks"> - </imageobject> - - <textobject> - <literallayout class="monospaced">External Interface External Interface - 208.229.100.6 216.218.197.2 - | | - +--> Firewall-1 <--> Internet <--> FreeBSD GW <--+ - | | -FW-1 Protected Nets Internal Nets -199.208.192.0/24 192.168.10.0/24</literallayout> - </textobject> - - <textobject> - <phrase>FW-1 net and FreeBSD net</phrase> - </textobject> - </mediaobject> - - <para>The FreeBSD gateway <acronym>GW</acronym> serves as a firewall and - <acronym>NAT</acronym> device for <quote>internal nets.</quote></para> - - <para>The FreeBSD kernel must be compiled to support IPsec. Use the - following kernel options to enable IPsec support in your kernel:</para> - -<programlisting>options IPSEC -options IPSEC_ESP -options IPSEC_DEBUG</programlisting> - - <para>For instructions on building a custom kernel, refer to the - <ulink url="&url.books.handbook;/kernelconfig.html">FreeBSD - handbook</ulink>. Please note that <acronym>IP</acronym> - protocol 50 (<acronym>ESP</acronym>) and <acronym>UDP</acronym> - port <literal>500</literal> must be open between the <trademark class='registered'>Firewall-1</trademark> - host and the FreeBSD <acronym>GW</acronym>.</para> - - <para>Also, <application>racoon</application> must be installed to support - key exchange. <application>Racoon</application> is part of the FreeBSD - ports collection in <filename role="package">security/racoon</filename>. - The <application>racoon</application> configuration file will be covered - later in this document.</para> - </sect1> - - <sect1 id="object"> - <title>Firewall-1 Network Object Configuration</title> - - <para>Begin by configuring the Firewall-1 Policy. Open the Policy Editor - on the Firewall-1 Management server and create a new - <quote>Workstation</quote> Network Object representing FreeBSD - <acronym>GW</acronym>.</para> - -<programlisting>General Tab: - Set name and IP address - -VPN Tab: - Encryption Schemes Defined: IKE ---> Edit - -IKE Properties: - Key Negotiation Encryption Methods: 3DES - -Authentication Method: - Pre-Shared Secret ---> Edit</programlisting> - - <para>Select the Firewall Object and set a pre-shared secret. - (Do not use our example.)</para> - -<programlisting>Support Aggressive Mode: Checked -Supports Subnets: Checked</programlisting> - - <para>After setting the pre-shared secret in the Firewall-1 Network Object - definition, place this secret in the - <filename>/usr/local/etc/racoon/psk.txt</filename> file on FreeBSD - <acronym>GW</acronym>. The format for <filename>psk.txt</filename> - is:</para> - -<programlisting>208.229.100.6 rUac0wtoo?</programlisting> - - </sect1> - - <sect1 id="rulecfg"> - <title>Firewall-1 VPN Rule Configuration</title> - - <para>Next, create a Firewall-1 rule enabling encryption between the - FreeBSD <acronym>GW</acronym> and the Firewall-1 protected network. - In this rule, the network services permitted through the - <acronym>VPN</acronym> must be defined.</para> - -<programlisting>Source | Destination | Service | Action | Track ------------------------------------------------------------------------- -FreeBSD GW | FW-1 Protected Net | VPN services | Encrypt | Long -FW-1 Protected Net| FreeBSD GW | | |</programlisting> - - <para><quote>VPN services</quote> are any services (i.e. - <command>telnet</command>, <acronym>SSH</acronym>, - <acronym>NTP</acronym>, etc.) which remote hosts are permitted to access - through the <acronym>VPN</acronym>. Use caution when permitting - services; hosts connecting through a <acronym>VPN</acronym> still - represent a potential security risk. Encrypting the traffic between the - two networks offers little protection if a host on either side of the - tunnel has been compromised.</para> - - <para>Once the rule specifying data encryption between the FreeBSD - <acronym>GW</acronym> and the Firewall-1 protected network has been - configured, review the <quote>Action Encrypt</quote> settings.</para> - -<programlisting>Encryption Schemes Defined: IKE ---> Edit -Transform: Encryption + Data Integrity (ESP) -Encryption Algorithm: 3DES -Data Integrity: MD5 -Allowed Peer Gateway: Any or Firewall Object -Use Perfect Forward Secrecy: Checked</programlisting> - - <para>The use of Perfect Forward Secrecy (<acronym>PFS</acronym>) is - optional. Enabling <acronym>PFS</acronym> will add another layer of - encryption security, but does come at the cost of increased - <acronym>CPU</acronym> overhead. If <acronym>PFS</acronym> is not used, - uncheck the box above and comment out the - <literal>pfs_group 1</literal> line in the - <filename>racoon.conf</filename> file on FreeBSD <acronym>GW</acronym>. - An example <filename>racoon.conf</filename> file is provided later in - this document.</para> - - </sect1> - - <sect1 id="policy"> - <title>FreeBSD <acronym>VPN</acronym> Policy Configuration</title> - - <para>At this point, the <acronym>VPN</acronym> policy on FreeBSD - <acronym>GW</acronym> must be defined. The &man.setkey.8; tool performs - this function.</para> - - <para>Below is an example shell script which will flush &man.setkey.8; and - add your <acronym>VPN</acronym> policy rules.</para> - -<programlisting># -# /etc/vpn1-ipsec.sh -# -# IP addresses -# -# External Interface External Interface -# 208.229.100.6 216.218.197.2 -# | | -# +--> Firewall-1 <--> Internet <--> FreeBSD GW <--+ -# | | -# FW-1 Protected Nets Internal Nets -# 199.208.192.0/24 192.168.10.0/24 -# -# Flush the policy -# -setkey -FP -setkey -F -# -# Configure the Policy -# -setkey -c << END -spdadd 216.218.197.2/32 199.208.192.0/24 any -P out ipsec -esp/tunnel/216.218.197.2-208.229.100.6/require; -spdadd 199.208.192.0/24 216.218.197.2/32 any -P in ipsec -esp/tunnel/208.229.100.6-216.218.197.2/require; -END -#</programlisting> - - <para>Execute the &man.setkey.8; commands:</para> - - <screen>&prompt.root; <userinput>sh /etc/vpn1-ipsec.sh</userinput></screen> - </sect1> - - <sect1 id="racoon"> - <title>FreeBSD <application>Racoon</application> Configuration</title> - - <para>To facilitate the negotiation of IPsec keys on the FreeBSD - <acronym>GW</acronym>, the - <filename role="package">security/racoon</filename> port must be - installed and configured.</para> - - <para>The following is a <application>racoon</application> configuration - file suitable for use with the examples outlined in this document. - Please make sure you fully understand this file before using it in a - production environment.</para> - -<programlisting># racoon.conf for use with Check Point VPN-1/Firewall-1 -# -# search this file for pre_shared_key with various ID key. -# - path pre_shared_key "/usr/local/etc/racoon/psk.txt" ; - log debug; -# -# "padding" defines some parameter of padding. You should not touch these. -# - padding - { - maximum_length 20; # maximum padding length. - randomize off; # enable randomize length. - strict_check off; # enable strict check. - exclusive_tail off; # extract last one octet. - } - - listen - { - #isakmp ::1 [7000]; - #isakmp 0.0.0.0 [500]; - #admin [7002]; # administrative port by kmpstat. - #strict_address; # required all addresses must be bound. - } -# -# Specification of default various timers. -# - timer - { -# -# These values can be changed per remote node. -# - counter 5; # maximum trying count to send. - interval 20 sec; # maximum interval to resend. - persend 1; # the number of packets per a send. -# -# timer for waiting to complete each phase. -# - phase1 30 sec; - phase2 15 sec; - } - - remote anonymous - { - exchange_mode aggressive,main; # For Firewall-1 Aggressive mode - - #my_identifier address; - #my_identifier user_fqdn ""; - #my_identifier address ""; - #peers_identifier address ""; - #certificate_type x509 "" ""; - - nonce_size 16; - lifetime time 10 min; # sec,min,hour - lifetime byte 5 MB; # B,KB,GB - initial_contact on; - support_mip6 on; - proposal_check obey; # obey, strict or claim - - proposal { - encryption_algorithm 3des; - hash_algorithm md5; - authentication_method pre_shared_key; - dh_group 2 ; - } - } - - sainfo anonymous - { - pfs_group 1; - lifetime time 10 min; - lifetime byte 50000 KB; - encryption_algorithm 3des; - authentication_algorithm hmac_md5; - compression_algorithm deflate ; - }</programlisting> - - <para>Ensure that the <filename>/usr/local/etc/racoon/psk.txt</filename> - file contains the pre-shared secret configured in the <quote>Firewall-1 - Network Object Configuration</quote> section of this document and has - mode <literal>600</literal> permissions.</para> - - <screen>&prompt.root; <userinput>chmod 600 /usr/local/etc/racoon/psk.txt</userinput></screen> - - </sect1> - - <sect1 id="startingvpn"> - <title>Starting the <acronym>VPN</acronym></title> - - <para>You are now ready to launch <application>racoon</application> and - test the <acronym>VPN</acronym> tunnel. For debugging purposes, open - the Firewall-1 Log Viewer and define a log filter to isolate entries - pertaining to FreeBSD <acronym>GW</acronym>. You may also find it - helpful to &man.tail.1; the <application>racoon</application> - log:</para> - - <screen>&prompt.root; <userinput>tail -f /var/log/racoon.log</userinput></screen> - - <para>Start <application>racoon</application> using the following - command:</para> - - <screen>&prompt.root; <userinput>/usr/local/sbin/racoon -f /usr/local/etc/racoon/racoon.conf</userinput></screen> - - <para>Once <application>racoon</application> has been launched, - &man.telnet.1; to a host on the Firewall-1 protected network.</para> - - <screen>&prompt.root; <userinput>telnet -s 192.168.10.3 199.208.192.66 22</userinput></screen> - - <para>This command attempts to connect to the &man.ssh.1; port on <hostid - role="ipaddr">199.208.192.66</hostid>, a machine in the Firewall-1 - protected network. The <option>-s</option> switch indicates the source - interface of the outbound connection. This is particularly important - when running <acronym>NAT</acronym> and <acronym>IPFW</acronym> on - FreeBSD <acronym>GW</acronym>. Using <literal>-s</literal> and - specifying an explicit source address prevents <acronym>NAT</acronym> - from mangling the packet prior to tunneling.</para> - - <para>A successful <application>racoon</application> key exchange will - output the following to the <filename>racoon.log</filename> log - file:</para> - -<programlisting>pfkey UPDATE succeeded: ESP/Tunnel 216.218.197.2->208.229.100.6 -pk_recvupdate(): IPSec-SA established: ESP/Tunnel 216.218.197.2->208.229.100.6 -get pfkey ADD message IPsec-SA established: ESP/Tunnel 208.229.100.6->216.218.197.2</programlisting> - - <para>Once key exchange completes (which takes a few seconds), an - &man.ssh.1; banner will appear. If all went well, two <quote>Key - Install</quote> messages will be logged in the Firewall-1 Log - Viewer.</para> - -<programlisting>Action | Source | Dest. | Info. -Key Install | 216.218.197.2 | 208.229.100.6 | IKE Log: Phase 1 (aggressive) completion. -Key Install | 216.218.197.2 | 208.229.100.6 | scheme: IKE methods</programlisting> - - <para>Under the information column, the full log detail will read:</para> - -<programlisting>IKE Log: Phase 1 (aggressive) completion. 3DES/MD5/Pre shared secrets Negotiation Id: -scheme: IKE methods: Combined ESP: 3DES + MD5 + PFS (phase 2 completion) for host:</programlisting> - </sect1> - - <sect1 id="References"> - <title>References</title> - - <itemizedlist> - <listitem> - <para>The FreeBSD Handbook: VPN over IPsec. - <ulink url="&url.books.handbook;/ipsec.html"></ulink></para> - </listitem> - - <listitem> - <para>KAME Project. - <ulink url="http://www.kame.net"></ulink></para> - </listitem> - - <listitem> - <para>FreeBSD IPsec mini-HOWTO. - <ulink url="http://www.x-itec.de/projects/tuts/ipsec-howto.txt"></ulink></para> - </listitem> - </itemizedlist> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/committers-guide/Makefile b/en_US.ISO8859-1/articles/committers-guide/Makefile deleted file mode 100644 index 890bd6e2b2..0000000000 --- a/en_US.ISO8859-1/articles/committers-guide/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# -# $FreeBSD$ -# -# Article: The FreeBSD Committers Guide - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/committers-guide/article.sgml b/en_US.ISO8859-1/articles/committers-guide/article.sgml deleted file mode 100644 index 1cc7043e53..0000000000 --- a/en_US.ISO8859-1/articles/committers-guide/article.sgml +++ /dev/null @@ -1,3181 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Committer's Guide</title> - - <authorgroup> - <author> - <surname>The FreeBSD Documentation Project</surname> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <copyright> - <year>1999</year> - <year>2000</year> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <year>2004</year> - <holder>The FreeBSD Documentation Project</holder> - </copyright> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.cvsup; - &tm-attrib.ibm; - &tm-attrib.intel; - &tm-attrib.sparc; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This document provides information for the FreeBSD committer - community. All new committers should read this document before they - start, and existing committers are strongly encouraged to review it - from time to time.</para> - </abstract> - </articleinfo> - - <sect1 id="admin"> - <title>Administrative Details</title> - - <informaltable frame="none" orient="port"> - <tgroup cols="2"> - <tbody> - <row> - <entry><emphasis>Main Repository Host</emphasis></entry> - <entry><hostid role="fqdn">ncvs.FreeBSD.org</hostid></entry> - </row> - - <row> - <entry><emphasis>Login Methods</emphasis></entry> - <entry>&man.ssh.1;, protocol 2 only</entry> - </row> - - <row> - <entry><emphasis>Main CVSROOT</emphasis></entry> - <entry> - <hostid role="fqdn">ncvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/ncvs</filename> (although also see <xref linkend="cvs.operations">). - </entry> - </row> - - <row> - <entry><emphasis>Main &a.cvs;</emphasis></entry> - <entry>&a.peter; and &a.markm;, as well as &a.joe; and &a.marcus; for - <filename>ports/</filename></entry> - </row> - - <row> - <entry><emphasis>Mailing Lists</emphasis></entry> - <entry>&a.doc-developers;, &a.doc-committers;; - &a.ports-developers;, &a.ports-committers;; - &a.src-developers;, &a.src-committers;. (Each project - repository has its own -developers and -committers mailing - lists. Archives for these lists may be found in files - <filename>/home/mail/<replaceable>repository-name</replaceable>-developers-archive</filename> - and - <filename>/home/mail/<replaceable>repository-name</replaceable>-committers-archive</filename> - on the <hostid role="domainname">FreeBSD.org</hostid> - cluster.) - </entry> - </row> - - - <row> - <entry><emphasis>Core Team monthly reports</emphasis></entry> - <entry><filename>/home/core/public/monthly-report</filename> - on the <hostid role="domainname">FreeBSD.org</hostid> cluster. - </entry> - </row> - - <row> - <entry><emphasis>Noteworthy CVS Tags</emphasis></entry> - <entry><literal>RELENG_4</literal> (4.X-STABLE), <literal>HEAD</literal> (-CURRENT)</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>It is required that you use &man.ssh.1; or &man.telnet.1; - with Kerberos 5 to connect to the project hosts. For - &man.ssh.1; only protocol 2 is allowed. - These are generally more secure than plain &man.telnet.1; or - &man.rlogin.1; since credential negotiation will always be - encrypted. All traffic is encrypted by default with &man.ssh.1;. - With utilities like &man.ssh-agent.1; and &man.scp.1; also - available, &man.ssh.1; is also far more convenient. If you do - not know anything about &man.ssh.1;, please see - <xref linkend="ssh.guide">.</para> - </sect1> - - <sect1 id="committer.types"> - <title>Commit Bit Types</title> - - <para>The FreeBSD CVS repository has a number of components which, - when combined, support the basic operating system source, - documentation, third party application ports infrastructure, and - various maintained utilities. When FreeBSD commit bits are - allocated, the areas of the tree where the bit may be used are - specified. Generally, the areas associated with a bit reflect who - authorized the allocation of the commit bit. Additional areas of - authority may be added at a later date: when this occurs, the - committer should follow normal commit bit allocation procedures for - that area of the tree, seeking approval from the appropriate entity - and possibly getting a mentor for that area for some period of time. - </para> - - <informaltable frame="none"> - <tgroup cols="3"> - <tbody> - <row> - <entry><emphasis>Committer Type</emphasis></entry> - <entry><emphasis>Responsible</emphasis></entry> - <entry><emphasis>Tree Components</emphasis></entry> - </row> - - <row> - <entry>src</entry> - <entry>core@</entry> - <entry>src/, doc/ subject to appropriate review</entry> - </row> - - <row> - <entry>doc</entry> - <entry>doceng@</entry> - <entry>doc/, www/, src/ documentation</entry> - </row> - - <row> - <entry>ports</entry> - <entry>portmgr@</entry> - <entry>ports/</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Commit bits allocated prior to the development of the notion of - areas of authority may be appropriate for use in many parts of the - tree. However, common sense dictates that a committer who has not - previously worked in an area of the tree seek review prior to - committing, seek approval from the appropriate responsible party, - and/or work with a mentor. Since the rules regarding code - maintenance differ by area of the tree, this is as much for the - benefit of the committer working in an area of less familiarity as - it is for others working on the tree.</para> - - <para>Committers are encouraged to seek review for their work as part - of the normal development process, regardless of the area of the - tree where the work is occurring.</para> - - <sect2> - <title>Policy for <filename>doc/</filename> committer activity - in <filename>src/</filename></title> - - <itemizedlist> - <listitem><para>doc committers may commit documentation - changes to src files, such as man pages, READMEs, fortune - databases, calendar files, and comment fixes without - approval from a src committer, subject to the normal care - and tending of commits.</para></listitem> - - <listitem><para>doc committers may commit minor src changes - and fixes, such as build fixes, small features, etc, with an - "Approved by" from a src committer.</para></listitem> - - <listitem><para>doc committers may seek an upgrade to a src - commit bit by acquiring a mentor, who will propose the doc - committer to core. When approved, they will be added to - 'access' and the normal mentoring period will ensue, which - will involve a continuing of <quote>Approved by</quote> for - some period.</para></listitem> - - <listitem><para>"Approved by" is only acceptable from - non-mentored src committers -- mentored committers can - provide a "Reviewed by" but not an "Approved - by".</para></listitem> - </itemizedlist> - </sect2> - - </sect1> - - <sect1 id="cvs.operations"> - <title>CVS Operations</title> - - <para>It is assumed that you are already familiar with the basic operation - of CVS.</para> - - <para>The &a.cvs; are the <quote>owners</quote> of the CVS repository and - are responsible for direct modification of it for the purposes of - cleanup or fixing some grievous abuse of CVS by a committer. - Should you cause some repository accident, say a bad <command>cvs - import</command> or <command>cvs tag</command> operation, mail the &a.cvs; - (or call one of them) and report the problem to one of them. The only - ones able to directly fiddle the repository bits on the repository hosts - are the repomeisters. To enforce this, there are no login shells - available on the repository machines, except to the repomeisters.</para> - - <para>The CVS tree is currently split into four distinct repositories, - namely <literal>doc</literal>, <literal>ports</literal>, - <literal>projects</literal> and <literal>src</literal>. These are - combined under a single <literal>CVSROOT</literal> when distributed - via <application>CVSup</application> for the convenience of our users.</para> - - <note><para>Note that the <literal>www</literal> module containing sources - for the <ulink url="http://www.FreeBSD.org">FreeBSD website</ulink> is - contained within the <literal>doc</literal> repository.</para></note> - - <para>The CVS repositories are hosted on the repository machines. - Currently, each of the repositories above reside on the same physical - machine, <hostid role="hostname">ncvs.FreeBSD.org</hostid>, but to allow for - the possibility of placing each on a separate machine in the future, - there is a separate hostname for each that committers should use. - Additionally, each repository is stored in a separate directory. The - following table summarizes the situation.</para> - - <table frame="none" id="cvs-repositories-and-hosts"> - <title>&os; CVS Repositories, Hosts and Directories</title> - - <tgroup cols="3"> - <thead> - <row> - <entry>Repository</entry> - <entry>Host</entry> - <entry>Directory</entry> - </row> - </thead> - - <tbody> - <row> - <entry>doc</entry> - <entry>dcvs.FreeBSD.org</entry> - <entry>/home/dcvs</entry> - </row> - - <row> - <entry>ports</entry> - <entry>pcvs.FreeBSD.org</entry> - <entry>/home/pcvs</entry> - </row> - - <row> - <entry>projects</entry> - <entry>projcvs.FreeBSD.org</entry> - <entry>/home/projcvs</entry> - </row> - - <row> - <entry>src</entry> - <entry>ncvs.FreeBSD.org</entry> - <entry>/home/ncvs</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>CVS operations are done remotely by setting the - <envar>CVSROOT</envar> environment variable to the appropriate host - and top-level directory (for example, - <hostid role="fqdn">ncvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/ncvs</filename>), - the <envar>CVS_RSH</envar> variable to <command>ssh</command>, and then - doing the appropriate check-out/check-in operations. Many committers - define aliases which expand to the correct <application>cvs</application> - invocation for the appropriate repository. For example, a &man.tcsh.1; - user may add the following to their <filename>.cshrc</filename> for this - purpose:</para> - - <programlisting>alias dcvs env CVS_RSH=ssh cvs -d <replaceable>user</replaceable>@dcvs.FreeBSD.org:/home/dcvs -alias pcvs env CVS_RSH=ssh cvs -d <replaceable>user</replaceable>@pcvs.FreeBSD.org:/home/pcvs -alias projcvs env CVS_RSH=ssh cvs -d <replaceable>user</replaceable>@projcvs.FreeBSD.org:/home/projcvs -alias scvs env CVS_RSH=ssh cvs -d <replaceable>user</replaceable>@ncvs.FreeBSD.org:/home/ncvs</programlisting> - - <para>This way they can do all CVS operations - locally and use <command><replaceable>X</replaceable>cvs commit</command> for committing - to the official CVS tree. If you wish to add - something which is wholly new (like contrib-ified - sources, etc), <command>cvs import</command> should be used. - Refer to the &man.cvs.1; manual page for usage.</para> - - <note> - <para>Please do <emphasis>not</emphasis> use - <command>cvs checkout</command> or - <command>update</command> with the official repository machine set - as the CVS Root for keeping your source tree up to date. - Remote CVS is not optimized for network distribution - and requires a big work/administrative overhead on the server side. - Please use our advanced <command>cvsup</command> distribution - method for obtaining the repository bits, and only do the actual - <command>commit</command> operation on the repository host. - We provide an extensive cvsup replication network for this purpose, - as well as give access to <hostid>cvsup-master</hostid> if you - really need to stay current to the latest changes. - <hostid>cvsup-master</hostid> has got the horsepower to deal with - this, the repository master server does not. &a.kuriyama; is in - charge of <hostid>cvsup-master</hostid>. - </para> - </note> - - <para>If you need to use CVS <command>add</command> and - <command>delete</command> operations in a manner that is - effectively a &man.mv.1; operation, then a repository - copy is in order rather than using CVS <command>add</command> and - <command>delete</command>. In a repository copy, a <link - linkend="conventions">CVS Meister</link> will copy the file(s) - to their new name and/or location and let you know when it is - done. The purpose of a repository copy is to preserve file - change history, or logs. We in the FreeBSD Project greatly - value the change history that CVS gives to the project.</para> - - <para>CVS reference information, tutorials, and FAQs can be found at: - <ulink url="http://www.cvshome.org/docs/"></ulink>. - The information in <ulink url="http://cvsbook.red-bean.com/cvsbook.html">Karl Fogel's - chapters from <quote>Open Source Development with CVS</quote></ulink> is also very - useful.</para> - - <para>&a.des; also supplied the following <quote>mini primer</quote> for - CVS.</para> - - <orderedlist> - <listitem> - <para>Check out a module with the <command>co</command> or - <command>checkout</command> command.</para> - - <screen>&prompt.user; <userinput>cvs checkout shazam</userinput></screen> - - <para>This checks out a copy of the <filename>shazam</filename> module. If - there is no <filename>shazam</filename> module in the modules file, it looks for a - top-level directory named <filename>shazam</filename> instead.</para> - - <table frame="none"> - <title>Useful <command>cvs checkout</command> options</title> - - <tgroup cols=2> - <tbody> - <row> - <entry><option>-P</option></entry> - <entry>Do not create empty directories</entry> - </row> - - <row> - <entry><option>-l</option></entry> - <entry>Check out a single level, no subdirectories</entry> - </row> - - <row> - <entry><option>-r<replaceable>rev</replaceable></option></entry> - <entry>Check out revision, branch or tag - <replaceable>rev</replaceable></entry> - </row> - - <row> - <entry><option>-D<replaceable>date</replaceable></option></entry> - <entry>Check out the sources as they were on date - <replaceable>date</replaceable></entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Practical FreeBSD examples:</para> - - <itemizedlist> - <listitem> - <para>Check out the <filename>miscfs</filename> module, - which corresponds to <filename>src/sys/miscfs</filename>:</para> - - <screen>&prompt.user; <userinput>cvs co miscfs</userinput></screen> - - <para>You now have a directory named <filename>miscfs</filename> - with subdirectories <filename>CVS</filename>, - <filename>deadfs</filename>, <filename>devfs</filename>, and so - on. One of these (<filename>linprocfs</filename>) is - empty.</para> - </listitem> - - <listitem> - <para>Check out the same files, but with full path:</para> - - <screen>&prompt.user; <userinput>cvs co src/sys/miscfs</userinput></screen> - - <para>You now have a directory named <filename>src</filename>, - with subdirectories <filename>CVS</filename> and - <filename>sys</filename>. The <filename>src/sys</filename> directory has - subdirectories <filename>CVS</filename> and - <filename>miscfs</filename>, etc.</para> - </listitem> - - <listitem> - <para>Check out the same files, but prunes empty - directories:</para> - - <screen>&prompt.user; <userinput>cvs co -P miscfs</userinput></screen> - - <para>You now have a directory named - <filename>miscfs</filename> with subdirectories - <filename>CVS</filename>, <filename>deadfs</filename>, - <filename>devfs</filename>... but note that there is no - <filename>linprocfs</filename> subdirectory, because there - are no files in it.</para> - </listitem> - - <listitem> - <para>Check out the directory <filename>miscfs</filename>, but - none of the subdirectories:</para> - - <screen>&prompt.user; <userinput>cvs co -l miscfs</userinput></screen> - - <para>You now have a directory named <filename>miscfs</filename> - with just one subdirectory named - <filename>CVS</filename>.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as - it is in the 4.X branch:</para> - - <screen>&prompt.user; <userinput>cvs co -rRELENG_4 miscfs</userinput></screen> - - <para>You can modify the sources and commit along this - branch.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as - it was in 3.4-RELEASE.</para> - - <screen>&prompt.user; <userinput>cvs co -rRELENG_3_4_0_RELEASE miscfs</userinput></screen> - - <para>You will not be able to commit modifications, since - <literal>RELENG_3_4_0_RELEASE</literal> is a point in time, not a branch.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as it was - on Jan 15 2000.</para> - - <screen>&prompt.user; <userinput>cvs co -D'01/15/2000' miscfs</userinput></screen> - - <para>You will not be able to commit modifications.</para> - </listitem> - - <listitem> - <para>Check out the <filename>miscfs</filename> module as it was - one week ago.</para> - - <screen>&prompt.user; <userinput>cvs co -D'last week' miscfs</userinput></screen> - - <para>You will not be able to commit modifications.</para> - </listitem> - </itemizedlist> - - <para>Note that cvs stores metadata in subdirectories named - <filename>CVS</filename>.</para> - - <para>Arguments to <option>-D</option> and <option>-r</option> - are sticky, which means cvs will remember them later, e.g. - when you do a <command>cvs update</command>.</para> - </listitem> - - <listitem> - <para>Check the status of checked-out files with the - <command>status</command> command.</para> - - <screen>&prompt.user; <userinput>cvs status shazam</userinput></screen> - - <para>This displays the status of the - file <filename>shazam</filename> or of every file in the - <filename>shazam</filename> directory. For every file, the - status is given as one of:</para> - - <informaltable frame="none"> - <tgroup cols=2> - <tbody> - <row> - <entry>Up-to-date</entry> - <entry>File is up-to-date and unmodified.</entry> - </row> - - <row> - <entry>Needs Patch</entry> - <entry>File is unmodified, but there is a newer revision in - the repository.</entry> - </row> - - <row> - <entry>Locally Modified</entry> - <entry>File is up-to-date, but modified.</entry> - </row> - - <row> - <entry>Needs Merge</entry> - <entry>File is modified, and there is a newer revision in the - repository.</entry> - </row> - - <row> - <entry>File had conflicts on merge</entry> - <entry>There were conflicts the last time this file was - updated, and they have not been resolved yet.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>You will also see the local revision and date, - the revision number of the newest applicable version - (<quote>newest applicable</quote> because if you have a - sticky date, tag or branch, it may not be the actual newest - revision), and any sticky tags, dates or options.</para> - </listitem> - - <listitem> - <para>Once you have checked something out, you can update it with the - <command>update</command> command.</para> - - <screen>&prompt.user; <userinput>cvs update shazam</userinput></screen> - - <para>This updates the file <filename>shazam</filename> or the - contents of the <filename>shazam</filename> directory to the - latest version along the branch you checked out. If you - checked out a <quote>point in time</quote>, does nothing - unless the tags have moved in the repository or some other weird - stuff is going on.</para> - - <para>Useful options, in addition to those listed above for - <command>checkout</command>:</para> - - <informaltable frame="none"> - <tgroup cols=2> - <tbody> - <row> - <entry><option>-d</option></entry> - <entry>Check out any additional missing directories.</entry> - </row> - - <row> - <entry><option>-A</option></entry> - <entry>Update to head of main branch.</entry> - </row> - - <row> - <entry><option>-j<replaceable>rev</replaceable></option></entry> - <entry>More magic (see below).</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>If you checked out a module with <option>-r</option> or - <option>-D</option>, running <command>cvs update</command> - with a different <option>-r</option> or <option>-D</option> - argument or with <option>-A</option> will select a new branch, - revision or date. The <option>-A</option> option clears all - sticky tags, dates or revisions whereas <option>-r</option> - and <option>-D</option> set new ones.</para> - - <para>Theoretically, specifying <literal>HEAD</literal> as the - argument to <option>-r</option> will give you the same result - as <option>-A</option>, but that is just theory.</para> - - <para>The <option>-d</option> option is useful if:</para> - - <itemizedlist> - <listitem> - <para>somebody has added subdirectories to the module - you have checked out after you checked it out.</para> - </listitem> - - <listitem> - <para>you checked out with <option>-l</option>, and later - change your mind and want to check out the subdirectories - as well.</para> - </listitem> - - <listitem> - <para>you deleted some subdirectories and want to check - them all back out.</para> - </listitem> - </itemizedlist> - - <para><emphasis>Watch the output of the <command>cvs - update</command> with care.</emphasis> The letter in front of - each filename indicates what was done with it:</para> - - <informaltable frame="none"> - <tgroup cols=2> - <tbody> - <row> - <entry><literal>U</literal></entry> - <entry>The file was updated without trouble.</entry> - </row> - - <row> - <entry><literal>P</literal></entry> - <entry>The file was updated without trouble (you will only see - this when working against a remote repository).</entry> - </row> - - <row> - <entry><literal>M</literal></entry> - <entry>The file had been modified, and was merged without - conflicts.</entry> - </row> - - <row> - <entry><literal>C</literal></entry> - <entry>The file had been modified, and was merged with - conflicts.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Merging is what happens if you check out a copy of - some source code, modify it, then someone else commits a - change, and you run <command>cvs update</command>. CVS notices - that you have made local changes, and tries to merge your - changes with the changes between the version you originally - checked out and the one you updated to. If the changes are to - separate portions of the file, it will almost always work fine - (though the result might not be syntactically or semantically - correct).</para> - - <para>CVS will print an <literal>M</literal> in front of every locally modified - file even if there is no newer version in the repository, so - <command>cvs update</command> is handy for getting a summary - of what you have changed locally.</para> - - <para>If you get a <literal>C</literal>, then your changes - conflicted with the changes in the repository (the changes - were to the same lines, or neighboring lines, or you changed - the local file so much that <command>cvs</command> can not - figure out how to apply the repository's changes). You will have - to go through the file manually and resolve the conflicts; - they will be marked with rows of <literal><</literal>, - <literal>=</literal> and <literal>></literal> signs. For - every conflict, there will be a marker line with seven - <literal><</literal> signs and the name of the file, - followed by a chunk of what your local file contained, - followed by a separator line with seven <literal>=</literal> - signs, followed by the corresponding chunk in the - repository version, followed by a marker line with seven - <literal>></literal> signs and the revision number you - updated to.</para> - - <para>The <option>-j</option> option is slightly voodoo. It - updates the local file to the specified revision as if you - used <option>-r</option>, but it does not change the recorded - revision number or branch of the local file. It is not really - useful except when used twice, in which case it will merge the - changes between the two specified versions into the working - copy.</para> - - <para>For instance, say you commit a change to - <filename>shazam/shazam.c</filename> in &os.current; and later - want to MFC it. The change you want to MFC was revision - 1.15:</para> - - <itemizedlist> - <listitem> - <para>Check out the &os.stable; version of the - <filename>shazam</filename> module:</para> - - <screen>&prompt.user; <userinput>cvs co -rRELENG_4 shazam</userinput></screen> - </listitem> - - <listitem> - <para>Apply the changes between rev 1.14 and 1.15:</para> - - <screen>&prompt.user; <userinput>cvs update -j1.14 -j1.15 shazam/shazam.c</userinput></screen> - </listitem> - </itemizedlist> - - <para>You will almost certainly get a conflict because - of the <literal>$Id: article.sgml,v 1.207 2004-08-08 13:43:53 hrs Exp $</literal> (or in FreeBSD's case, - <literal>$<!-- stop expansion -->FreeBSD<!-- stop expansion -->$</literal>) - lines, so you will have to edit the file to resolve the conflict - (remove the marker lines and the second <literal>$Id: article.sgml,v 1.207 2004-08-08 13:43:53 hrs Exp $</literal> line, - leaving the original <literal>$Id: article.sgml,v 1.207 2004-08-08 13:43:53 hrs Exp $</literal> line intact).</para> - </listitem> - - <listitem> - <para>View differences between the local version and the - repository version with the <command>diff</command> - command.</para> - - <screen>&prompt.user; <userinput>cvs diff shazam</userinput></screen> - - <para>shows you every modification you have made to the - <filename>shazam</filename> file or module.</para> - - <table frame="none"> - <title>Useful <command>cvs diff</command> options</title> - - <tgroup cols=2> - <tbody> - <row> - <entry><option>-u</option></entry> - <entry>Uses the unified diff format.</entry> - </row> - - <row> - <entry><option>-c</option></entry> - <entry>Uses the context diff format.</entry> - </row> - - <row> - <entry><option>-N</option></entry> - <entry>Shows missing or added files.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>You always want to use <option>-u</option>, since - unified diffs are much easier to read than almost any other - diff format (in some circumstances, context diffs generated with - the <option>-c</option> option may be - better, but they are much bulkier). A unified diff consists of - a series of hunks. Each hunk begins with a line that starts - with two <literal>@</literal> signs and specifies where in the - file the differences are and how many lines they span. This - is followed by a number of lines; some (preceded by a blank) - are context; some (preceded by a <literal>-</literal> sign) - are outtakes and some (preceded by a <literal>+</literal>) are - additions.</para> - - <para>You can also diff against a different version - than the one you checked out by specifying a version - with <option>-r</option> or <option>-D</option> as in - <command>checkout</command> or <command>update</command>, - or even view the diffs between two arbitrary versions - (without regard for what you have locally) by specifying - <emphasis>two</emphasis> versions with <option>-r</option> or - <option>-D</option>.</para> - </listitem> - - <listitem> - <para>View log entries with the <command>log</command> - command.</para> - - <screen>&prompt.user; <userinput>cvs log shazam</userinput></screen> - - <para>If <filename>shazam</filename> is a file, this will print a - <emphasis>header</emphasis> with information about this file, such - as where in the repository this file is stored, which revision is - the <literal>HEAD</literal> for this file, what branches this file - is in, and any tags that are valid for this file. Then, for each - revision of this file, a log message is printed. This includes - the date and time of the commit, who did the commit, how many lines - were added and/or deleted, and finally the log message that the - committer who did the change wrote.</para> - - <para>If <filename>shazam</filename> is a directory, then the log - information described above is printed for each file in the - directory in turn. Unless you give the <option>-l</option> to - <command>log</command>, the log for all subdirectories of - <filename>shazam</filename> is printed too, in a recursive - manner.</para> - - <para>Use the <command>log</command> command to view the history of - one or more files, as it is stored in the CVS repository. You can - even use it to view the log message of a specific revision, if you - add the <option>-r<replaceable>rev</replaceable></option> to the - <command>log</command> command:</para> - - <screen>&prompt.user; <userinput>cvs log -r1.2 shazam</userinput></screen> - - <para>This will print only the log message for revision - <literal>1.2</literal> of file <filename>shazam</filename> if it is - a file, or the log message for revision <literal>1.2</literal> of - each file under <filename>shazam</filename> if it is a - directory.</para> - </listitem> - - <listitem> - <para>See who did what with the <command>annotate</command> command. - This command shows you each line of the specified file or - files, along with which user most recently changed that - line.</para> - - <screen>&prompt.user; <userinput>cvs annotate shazam</userinput></screen> - </listitem> - - <listitem> - <para>Add new files with the <command>add</command> command.</para> - - <para>Create the file, <command>cvs add</command> it, then - <command>cvs commit</command> it.</para> - - <para>Similarly, you can add new directories by creating them - and then <command>cvs add</command>ing them. Note that you - do not need to commit directories.</para> - </listitem> - - <listitem> - <para>Remove obsolete files with the <command>remove</command> command.</para> - - <para>Remove the file, then <command>cvs rm</command> it, then - <command>cvs commit</command> it.</para> - </listitem> - - <listitem> - <para>Commit with the <command>commit</command> or - <command>checkin</command> command.</para> - - <table frame="none"> - <title>Useful <command>cvs commit</command> options</title> - - <tgroup cols=2> - <tbody> - <row> - <entry><option>-f</option></entry> - <entry>Force a commit of an unmodified file.</entry> - </row> - - <row> - <entry><option>-m<replaceable>msg</replaceable></option></entry> - <entry>Specify a commit message on the command line rather - than invoking an editor.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Use the <option>-f</option> option if you realize that - you left out important information from the commit message.</para> - - <para>Good commit messages are important. They tell others - why you did the changes you did, not just right here and now, - but months or years from now when someone wonders why some - seemingly illogical or inefficient piece of code snuck into - your source file. It is also an invaluable aid to deciding - which changes to MFC and which not to MFC.</para> - - <para>Commit messages should be clear, concise and provide - a reasonable summary to give an indication of what was - changed and why.</para> - - <para>Commit messages should provide enough information to - enable a third party to decide if the change is relevant to - them and if they need to read the change itself.</para> - - <para>Avoid committing several unrelated changes in one go. It - makes merging difficult, and also makes it harder to determine - which change is the culprit if a bug crops up.</para> - - <para>Avoid committing style or whitespace fixes and - functionality fixes in one go. It makes merging difficult, - and also makes it harder to understand just what functional - changes were made. In the case of documentation files, it - can make the job of the translation teams more complicated, - as it becomes difficult for them to determine exactly what - content changes need to be translated.</para> - - <para>Avoid committing changes to multiple files in one go - with a generic, vague message. Instead, commit each file (or - small, related groups of files) with tailored commit messages.</para> - - <para>Before committing, <emphasis>always</emphasis>:</para> - - <itemizedlist> - <listitem> - <para>verify which branch you are committing to, using - <command>cvs status</command>.</para> - </listitem> - - <listitem> - <para>review your diffs, using - <command>cvs diff</command></para> - </listitem> - </itemizedlist> - - <para>Also, ALWAYS specify which files to commit explicitly on - the command line, so you do not accidentally commit other files - than the ones you intended - <command>cvs commit</command> - without any arguments will commit every modification in your - current working directory and every subdirectory.</para> - </listitem> - </orderedlist> - - <para>Additional tips and tricks:</para> - - <orderedlist> - <listitem> - - <para>You can place commonly used options in your - <filename>~/.cvsrc</filename>, like this:</para> - - <programlisting>cvs -z3 -diff -Nu -update -Pd -checkout -P</programlisting> - - <para>This example says:</para> - - <itemizedlist> - <listitem> - <para>always use compression level 3 when talking to a - remote server. This is a life-saver when working over a - slow connection.</para> - </listitem> - - <listitem> - <para>always use the <option>-N</option> (show added or - removed files) and <option>-u</option> (unified diff - format) options to &man.diff.1;.</para> - </listitem> - - <listitem> - <para>always use the <option>-P</option> (prune empty - directories) and <option>-d</option> (check out new - directories) options when updating.</para> - </listitem> - - <listitem> - <para>always use the <option>-P</option> (prune empty - directories) option when checking out.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Use Eivind Eklund's <command>cdiff</command> script to - view unidiffs. It is a wrapper for &man.less.1; that adds ANSI - color codes to make hunk headers, outtakes and additions stand - out; context and garbage are unmodified. It also expands tabs - properly (tabs often look wrong in diffs because of the extra - character in front of each line).</para> - - <para><ulink url="http://people.FreeBSD.org/~eivind/cdiff"></ulink></para> - - <para>Simply use it instead of &man.more.1; or &man.less.1;:</para> - - <screen>&prompt.user; <userinput>cvs diff -Nu shazam | cdiff</userinput></screen> - - <para>Alternatively some editors like &man.vim.1; - (<filename role="package">editors/vim5</filename>) have color support and when used as - a pager with color syntax highlighting switched on will - highlight many types of file, including diffs, patches, - and CVS/RCS logs. </para> - - <screen>&prompt.user; <userinput>echo "syn on" >> ~/.vimrc </userinput> -&prompt.user; <userinput>cvs diff -Nu shazam | vim -</userinput> -&prompt.user; <userinput>cvs log shazam | vim -</userinput> </screen> - </listitem> - - <listitem> - <para>CVS is old, arcane, crufty and buggy, and sometimes - exhibits non-deterministic behavior which some claim as proof - that it is actually merely the Newtonian manifestation of a - sentient transdimensional entity. It is not humanly possible - to know its every quirk inside out, so do not be afraid to ask - the resident AI (&a.cvs;) for help.</para> - </listitem> - - <listitem> - <para>Do not leave the <command>cvs commit</command> command in commit - message editing mode for too long (more than 2–3 minutes). It - locks the directory you are working with and will prevent other - developers from committing into the same directory. If you have - to type a long commit message, type it before executing - <command>cvs commit</command>, and insert it into the commit - message.</para> - </listitem> - </orderedlist> - - </sect1> - - <sect1 id="conventions"> - <title>Conventions and Traditions</title> - - <para>As a new committer there are a number of things you should do - first.</para> - - <itemizedlist> - <listitem> - <para>Add your author entity to - <filename>doc/en_US.ISO8859-1/share/sgml/authors.ent</filename>; - this should be done first since an omission of this commit will - cause the next commits to break the doc/ build.</para> - - <para>This is a relatively easy task, but remains a good first test of - your CVS skills.</para> - </listitem> - - <listitem> - <para>Add yourself to the <quote>Developers</quote> section of - the <ulink url="&url.articles.contributors;/index.html">Contributors List</ulink> - and remove yourself from the <quote>Additional - Contributors</quote> section.</para> - </listitem> - - <listitem> - <para>Add an entry for yourself to - <filename>www/en/news/news.xml</filename>. Look for the other - entries that look like <quote>A new committer</quote> and follow the - format.</para> - </listitem> - - <listitem> - <para>You should add your PGP or GnuPG key to - <filename>doc/share/pgpkeys</filename> (and if you do not - have a key, you should create one). Do not forget to commit - the updated <filename>doc/share/pgpkeys/pgpkeys.ent</filename>.</para> - - <para>&a.des; has - written a shell script to make this extremely simple. See the - <ulink - url="http://cvsweb.FreeBSD.org/doc/share/pgpkeys/README">README</ulink> - file for more information.</para> - - <note> - <para>It is important to have an up-to-date PGP/GnuPG key in - the Handbook, since the key may be required for positive - identification of a committer, e.g. by the &a.admins; for - account recovery. A complete keyring of <hostid - role="domainname">FreeBSD.org</hostid> users is available - for download from <ulink - url="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</ulink>.</para> - </note> - </listitem> - - <listitem> - <para>Some people add an entry for themselves to - <filename>ports/astro/xearth/files/freebsd.committers.markers</filename>.</para> - </listitem> - - <listitem> - <para>Some people add an entry for themselves to - <filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename>.</para> - </listitem> - - <listitem> - <para>Introduce yourself to the other committers, otherwise no one - will have any idea who you are or what you are working on. You do - not have to write a comprehensive biography, just write a paragraph - or two about who you are and what you plan to be working on as a - committer in FreeBSD. Email this to the &a.developers; and you will - be on your way!</para> - </listitem> - - <listitem> - <para>Log into <hostid>hub.FreeBSD.org</hostid> and create a - <filename>/var/forward/<replaceable>user</replaceable></filename> - (where <replaceable>user</replaceable> is your username) file - containing the e-mail address where you want mail addressed to - <replaceable>yourusername</replaceable>@FreeBSD.org to be forwarded. - This includes all of the commit messages as well as any other mail - addressed to the &a.committers; and the &a.developers;. Really - large mailboxes which have taken up permanent residence on - <hostid>hub</hostid> often get <quote>accidentally</quote> truncated - without warning, so forward it or read it and you will not lose - it.</para> - - <para>Due to the severe load dealing with SPAM places on - the central mail servers that do the mailing list processing - the front-end server does do some basic checks and will - drop some messages based on these checks. At the moment - proper DNS information for the connecting host is the only - check in place but that may change. Some people blame these - checks for bouncing valid email. If you want these checks - turned off for your email you can place a file named - <filename>~/.spam_lover</filename> in your home directory - on <hostid role="fqdn">freefall.FreeBSD.org</hostid> to - disable the checks for your email.</para> - </listitem> - - <listitem> - <para>If you are subscribed to the &a.cvsall;, you will - probably want to unsubscribe to avoid receiving duplicate - copies of commit messages and their followups.</para> - </listitem> - </itemizedlist> - - <para>All new committers also have a mentor assigned to them for - the first few months. Your mentor is responsible for teaching - you the rules and conventions of the project and guiding your - first steps in the committer community. He or she is also - personally responsible for your actions during this initial - period. Until your mentor decides (and announces with a forced - commit to <filename>access</filename>) that you have learned the - ropes and are ready to commit on your own, you should not commit - anything without first getting your mentor's review and - approval, and you should document that approval with an - <literal>Approved by:</literal> line in the commit - message.</para> - - <para>All <filename>src</filename> commits should go to - &os.current; first before being merged to &os.stable;. No major - new features or high-risk modifications should be made to the - &os.stable; branch.</para> - </sect1> - - <sect1 id="pref-license"> - <title>Preferred License for New Files</title> - - <para>Currently the &os; Project suggests and uses the following - text as the preferred license scheme:</para> - -<programlisting>Copyright © <Year> <Author>. All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -SUCH DAMAGE.</programlisting> - - <para>The &os; project strongly discourages the so called - advertising clause in new code. Due to the large number of - contributors to the &os; project, complying with this clause for - many commercial vendors has become difficult. If you have code - in the tree with the advertising clause, please consider - removing it. In fact, please consider using the above license - for your code.</para> - - <para>The &os; project discourages completely new licenses and - variations on the standard licenses. New licenses require the - approval of <email>core@FreeBSD.org</email> to reside in the - main repository. The more different licenses that are used in - the tree, the more problems that this causes to those wishing to - utilize this code, typically from unintended consequences from a - poorly worded license.</para> - - </sect1> - - <sect1 id="developer.relations"> - <title>Developer Relations</title> - - <para>If you are working directly on your own code or on code - which is already well established as your responsibility, then - there is probably little need to check with other committers - before jumping in with a commit. If you see a bug in an area of - the system which is clearly orphaned (and there are a few such - areas, to our shame), the same applies. If, however, you are - about to modify something which is clearly being actively - maintained by someone else (and it is only by watching the - <literal>cvs-committers</literal> mailing list that you can - really get a feel for just what is and is not) then consider - sending the change to them instead, just as you would have - before becoming a committer. For ports, you should contact the - listed <makevar>MAINTAINER</makevar> in the - <filename>Makefile</filename>. For other parts of the - repository, if you are unsure who the active maintainer might - be, it may help to scan the output of <command>cvs log</command> - to see who has committed changes in the past. &a.fenner; has - written a nice shell script that can help determine who the - active maintainer might be. It lists each person who has - committed to a given file along with the number of commits each - person has made. It can be found on <hostid>freefall</hostid> - at <filename>~fenner/bin/whodid</filename>. If your queries go - unanswered or the committer otherwise indicates a lack of - proprietary interest in the area affected, go ahead and commit - it.</para> - - <para>If you are unsure about a commit for any reason at - all, have it reviewed by <literal>-hackers</literal> - before committing. Better to have it flamed then and there - rather than when it is part of the CVS repository. If you do - happen to commit something which results in controversy - erupting, you may also wish to consider backing the change out - again until the matter is settled. Remember – with CVS we - can always change it back.</para> - - <para>Do not impugn the intentions of someone you disagree with. - If they see a different solution to a problem than you, or even - a different problem, it is not because they are stupid, because - they have questionable parentage, or because they are trying to - destroy your hard work, personal image, or FreeBSD, but simply - because they have a different outlook on the world. Different - is good.</para> - - <para>Disagree honestly. Argue your position from its merits, - be honest about any shortcomings it may have, and be open to - seeing their solution, or even their vision of the problem, - with an open mind.</para> - - <para>Accept correction. We are all fallible. When you have made - a mistake, apologize and get on with life. Do not beat up - yourself, and certainly do not beat up others for your mistake. - Do not waste time on embarrassment or recrimination, just fix - the problem and move on.</para> - - <para>Ask for help. Seek out (and give) peer reviews. One of - the ways open source software is supposed to excel is in the - number of eyeballs applied to it; this does not apply if nobody - will review code.</para> - </sect1> - - <sect1 id="gnats"> - <title>GNATS</title> - - <para>The FreeBSD Project utilizes - <application>GNATS</application> for tracking bugs and change - requests. Be sure that if you commit a fix or suggestion found - in a <application>GNATS</application> PR, you use - <command>edit-pr <replaceable>pr-number</replaceable></command> - on <hostid>freefall</hostid> to close it. It is also considered - nice if you take time to close any PRs associated with your - commits, if appropriate. You can also make use of - &man.send-pr.1; yourself for proposing any change which you feel - should probably be made, pending a more extensive peer-review - first.</para> - - <para>You can find out more about <application>GNATS</application> - at:</para> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html"></ulink></para> - </listitem> - - <listitem> - <para><ulink url="&url.base;/support.html">http://www.FreeBSD.org/support.html</ulink></para> - </listitem> - - <listitem> - <para>&man.send-pr.1;</para> - </listitem> - </itemizedlist> - - <para>You can run a local copy of GNATS, and then integrate the FreeBSD - GNATS tree in to it using CVSup. Then you can run GNATS commands - locally, or use other interfaces, such as <command>tkgnats</command>. - This lets you query the PR database without needing to be connected to - the Internet.</para> - - <procedure> - <title>Using a local GNATS tree</title> - - <step> - <para>If you are not already downloading the GNATS tree, add this line - to your <filename>supfile</filename>, and re-sup. Note that since - GNATS is not under CVS control it has no tag, so if you are adding - it to your existing <filename>supfile</filename> it should appear - before any <quote>tag=</quote> entry as these remain active once set. - </para> - - <programlisting>gnats release=current prefix=/usr</programlisting> - - <para>This will place the FreeBSD GNATS tree in - <filename>/usr/gnats</filename>. You can use a - <emphasis>refuse</emphasis> file to control which categories to - receive. For example, to only receive <literal>docs</literal> PRs, - put this line in - <filename>/usr/local/etc/cvsup/sup/refuse</filename><footnote> - <para>The precise path depends on the <literal>*default - base</literal> setting in your - <filename>supfile</filename>.</para> - </footnote>.</para> - - <programlisting>gnats/[a-ce-z]*</programlisting> - - <para>The rest of these examples assume you have only supped the - <literal>docs</literal> category. Adjust them as necessary, - depending on the categories you are syncing.</para> - </step> - - <step> - <para>Install the GNATS port from - <filename>ports/databases/gnats</filename>. This will place the - various GNATS directories under - <filename>$PREFIX/share/gnats</filename>.</para> - </step> - - <step> - <para>Symlink the GNATS directories you are supping under the version - of GNATS you have installed.</para> - - <screen>&prompt.root; <userinput>cd /usr/local/share/gnats/gnats-db</userinput> -&prompt.root; <userinput>ln -s /usr/gnats/docs</userinput></screen> - - <para>Repeat as necessary, depending on how many GNATS categories you - are syncing.</para> - </step> - - <step> - <para>Update the GNATS <filename>categories</filename> file with these - categories. The file is - <filename>$PREFIX/share/gnats/gnats-db/gnats-adm/categories</filename>.</para> - - <programlisting># This category is mandatory -pending:Category for faulty PRs:gnats-admin: -# -# FreeBSD categories -# -docs:Documentation Bug:freebsd-doc:</programlisting> - </step> - - <step> - <para>Run <filename>$PREFIX/libexec/gnats/gen-index</filename> to - recreate the GNATS index. The output has to be redirected to - <filename>$PREFIX/share/gnats/gnats-db/gnats-adm/index</filename>. - You can do this periodically from &man.cron.8;, or run &man.cvsup.1; - from a shell script that does this as well.</para> - - <screen>&prompt.root; <userinput>/usr/local/libexec/gnats/gen-index \ - > /usr/local/share/gnats/gnats-db/gnats-adm/index</userinput></screen> - </step> - - <step> - <para>Test the configuration by querying the PR database. This - command shows open <literal>docs</literal> PRs.</para> - - <screen>&prompt.root; <userinput>query-pr -c docs -s open</userinput></screen> - - <para>Other interfaces, such as that provided by the - <filename role="package">databases/tkgnats</filename> port should also work - nicely.</para> - </step> - - <step> - <para>Pick a PR and close it.</para> - </step> - </procedure> - - <note> - <para>This procedure only works to allow you to view and query the PRs - locally. To edit or close them you will still have to log in to - <hostid>freefall</hostid> and do it from there.</para> - </note> - </sect1> - - <sect1 id="people"> - <title>Who's Who</title> - - <para>Besides the repository - meisters, there are other FreeBSD project members and teams whom you will - probably get to know in your role as a committer. Briefly, - and by no means all-inclusively, these are:</para> - - <!-- XXX The TRB are missing --> - - <variablelist> - - <varlistentry> - <term>&a.jhb;</term> - - <listitem> - <para>John is the manager of the SMPng Project, and has - authority over the architectural design and implementation - of the move to fine-grained kernel threading and locking. - He's also the editor of the SMPng Architecture Document. - If you are working on fine-grained SMP and locking, please - coordinate with John. You can learn more about the - SMPng Project on its home page: - <ulink url="http://www.FreeBSD.org/smp/"></ulink></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.jake;, &a.tmm;</term> - - <listitem> - <para>Jake and Thomas are the maintainers of the &sparc64; hardware - port.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.doceng;</term> - - <listitem> - <para>doceng is the group responsible for the documentation build - infrastructure, approving new documentation committers, and - ensuring that the FreeBSD website and documentation on the FTP - site is up to date with respect to the CVS tree. It is not a - conflict resolution body. The vast majority of documentation - related discussion takes place on the &a.doc;. More details regarding the doceng team can be found in its <ulink url="http://www.FreeBSD.org/internal/doceng.html">charter</ulink>. Committers - interested in contributing to the documentation should familiarize - themselves with the <ulink - url="&url.books.fdp-primer;/index.html">Documentation Project - Primer</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.ru;</term> - - <listitem> - <para>Ruslan is Mister &man.mdoc.7;. If you are writing a - manual page and need - some advice on the structure, or the markup, ask Ruslan.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.bde;</term> - - <listitem> - <para>Bruce is the Style Police-Meister. - When you do a commit that could have been done better, - Bruce will be there to tell you. Be thankful that someone - is. Bruce is also very knowledgeable on the various - standards applicable to FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.gallatin;</term> - <term>&a.mjacob;</term> - <term>&a.dfr;</term> - <term>&a.obrien;</term> - - <listitem> - <para>These are the primary developers and overseers of the - DEC Alpha AXP platform.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.dg;</term> - - <listitem> - <para>David is the overseer of the - VM system. If you have a VM system change in mind, - coordinate it with David.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.dfr;</term> - <term>&a.marcel;</term> - <term>&a.peter;</term> - <term>&a.ps;</term> - - <listitem> - <para>These are the primary developers and overseers of the - Intel IA-64 platform, officially known as the &itanium; Processor - Family (IPF).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.murray;</term> - <term>&a.steve;</term> - <term>&a.rwatson;</term> - <term>&a.jhb;</term> - <term>&a.scottl;</term> - <term>&a.kensmith;</term> - <term>&a.hrs;</term> - - <listitem> - <para>These are the members of the &a.re;. This team is - responsible for setting release deadlines and controlling - the release process. During code freezes, the release - engineers have final authority on all changes to the - system for whichever branch is pending release status. If - there is something you want merged from &os.current; to - &os.stable; (whatever values those may have at any given - time), these are the people to talk to about it.</para> - - <para>Hiroki is also the keeper of the release documentation - (<filename>src/release/doc/*</filename>). If you commit a - change that you think is worthy of mention in the release notes, - please make sure he knows about it. Better still, send him - a patch with your suggested commentary.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.benno;</term> - - <listitem> - <para>Benno is the official maintainer of the &powerpc; port.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.brian;</term> - - <listitem> - <para>Official maintainer of - <filename>/usr/sbin/ppp</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.nectar;</term> - - <listitem> - <para>Jacques is the - <ulink url="&url.base;/security/">FreeBSD Security - Officer</ulink> - and oversees the &a.security-officer;. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.wollman;</term> - - <listitem> - <para>If you need advice on obscure network internals or - are not sure of some potential change to the networking - subsystem you have in mind, Garrett is someone to talk - to. Garrett is also very knowledgeable on the various - standards applicable to FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.committers;</term> - - <listitem> - <para>cvs-committers is the entity that CVS uses to send you all your - commit messages. You should <emphasis>never</emphasis> send email - directly to this list. You should only send replies to this list - when they are short and are directly related to a commit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.developers;</term> - - <listitem> - <para>All committers are subscribed to -developers. This list was created to be a - forum for the committers <quote>community</quote> issues. - Examples are Core - voting, announcements, etc. This list is - <emphasis>not</emphasis> intended as a place for code reviews or a - replacement for the &a.arch; or the &a.audit;. In fact - using it as such hurts the FreeBSD Project as it gives a sense of a - closed list where general decisions affecting all of the FreeBSD - using community are made without being <quote>open</quote>. - Last, but not least <emphasis>never, never ever, email - the &a.developers; and CC:/BCC: another FreeBSD list</emphasis>. - Never, ever email another FreeBSD email list and CC:/BCC: - the &a.developers;. Doing so can greatly diminish the benefits - of this list. Also, never publicly post or forward emails sent - to the &a.developers;. The act of sending to - the &a.developers; vs. a public list means the information in - the email is not for public consumption. - </para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="ssh.guide"> - <title>SSH Quick-Start Guide</title> - - <procedure> - <step> - <para>If you are using FreeBSD 4.0 or later, - OpenSSH is included in the base system. - If you are using an earlier release, - update and install one of the SSH ports. In general, - you will probably want to get OpenSSH from the - <filename role="package">security/openssh</filename> port. You - may also wish to check out the original ssh1 in the - <filename role="package">security/ssh</filename> port, but make - certain you pay attention to its license. Note that both - of these ports cannot be installed at the same time.</para> - </step> - - <step> - <para>If you do not wish to type your password in every - time you use &man.ssh.1;, and you use RSA or DSA keys to - authenticate, &man.ssh-agent.1; is there for your - convenience. If you want to use &man.ssh-agent.1;, make - sure that you run it before running other applications. X - users, for example, usually do this from their - <filename>.xsession</filename> or - <filename>.xinitrc</filename> file. See &man.ssh-agent.1; - for details.</para> - </step> - - <step> - <para>Generate a key pair using &man.ssh-keygen.1;. The key - pair will wind up in your - <filename><envar>$HOME</envar>/.ssh/</filename> - directory.</para> - </step> - - <step> - <para>Send your public key - (<filename><envar>$HOME</envar>/.ssh/id_dsa.pub</filename> - or <filename><envar>$HOME</envar>/.ssh/id_rsa.pub</filename>) - to the person setting you up as a committer so it can be put - into <filename><replaceable>yourlogin</replaceable></filename> file in - <filename class="directory">/c/ssh-keys/</filename> on - <hostid>freefall</hostid>. - </para> - </step> - </procedure> - - <para>Now you should be able to use &man.ssh-add.1; for - authentication once per session. This will prompt you for - your private key's pass phrase, and then store it in your - authentication agent (&man.ssh-agent.1;). If you no longer - wish to have your key stored in the agent, issuing - <command>ssh-add -d</command> will remove it.</para> - - <para>Test by doing something such as <command>ssh - freefall.FreeBSD.org ls /usr</command>.</para> - - <para>For more information, see - <filename role="package">security/openssh</filename>, &man.ssh.1;, - &man.ssh-add.1;, &man.ssh-agent.1;, &man.ssh-keygen.1;, and - &man.scp.1;.</para> - </sect1> - - <sect1 id="rules"> - <title>The FreeBSD Committers' Big List of Rules</title> - - <orderedlist> - <listitem> - <para>Respect other committers.</para> - </listitem> - - <listitem> - <para>Respect other contributors.</para> - </listitem> - - <listitem> - <para>Discuss any significant change - <emphasis>before</emphasis> committing.</para> - </listitem> - - <listitem> - <para>Respect existing maintainers (if listed in the - <makevar>MAINTAINER</makevar> field in - <filename>Makefile</filename> or in the - <filename>MAINTAINER</filename> file in the top-level - directory).</para> - </listitem> - - <listitem> - <para>Any disputed change must be backed out pending - resolution of the dispute if requested by a maintainer. - Security related changes may - override a maintainer's wishes at the Security Officer's - discretion.</para> - </listitem> - - <listitem> - <para>Changes go to &os.current; before - &os.stable; unless specifically permitted by - the release engineer or unless they are not applicable to - &os.current;. Any non-trivial or non-urgent - change which is applicable should also be allowed to sit in - &os.current; for at least 3 days before - merging so that it can be given sufficient testing. The - release engineer has the same authority over the - &os.stable; branch as outlined for the - maintainer in rule #5.</para> - </listitem> - - <listitem> - <para>Do not fight in public with other committers; it looks - bad. If you must <quote>strongly disagree</quote> about - something, do so only in private.</para> - </listitem> - - <listitem> - <para>Respect all code freezes and read the - <literal>committers</literal> and <literal>developers</literal> - mailing lists in a timely manner so you know when a code freeze is - in effect.</para> - </listitem> - - <listitem> - <para>When in doubt on any procedure, ask first!</para> - </listitem> - - <listitem> - <para>Test your changes before committing them.</para> - </listitem> - - <listitem> - <para>Do not commit to anything under the - <filename>src/contrib</filename>, - <filename>src/crypto</filename>, and - <filename>src/sys/contrib</filename> trees without - <emphasis>explicit</emphasis> approval from the respective - maintainer(s).</para> - </listitem> - </orderedlist> - - <para>As noted, breaking some of these rules can be grounds for - suspension or, upon repeated offense, permanent removal of - commit privileges. Individual members of core - have the power to temporarily suspend commit privileges until - core as a whole has the chance to review the - issue. In case of an <quote>emergency</quote> (a committer - doing damage to the repository), a temporary suspension may also - be done by the repository meisters. - Only a 2/3 majority of core - has the authority to suspend commit privileges for longer - than a week or to remove them permanently. - This rule does not exist to set core up as a bunch - of cruel dictators who can dispose of committers as casually as - empty soda cans, but to give the project a kind of safety fuse. - If someone is out of control, it is important to be - able to deal with this immediately rather than be paralyzed by - debate. In all cases, a committer whose privileges are - suspended or revoked is entitled to a <quote>hearing</quote> by core, - the total duration of the suspension being determined at that - time. A committer whose privileges are suspended may also - request a review of the decision after 30 days and every 30 days - thereafter (unless the total suspension period is less than 30 - days). A committer whose privileges have been revoked entirely - may request a review after a period of 6 months has elapsed. - This review policy is <emphasis>strictly informal</emphasis> - and, in all cases, core reserves the right to either act on or - disregard requests for review if they feel their original - decision to be the right one.</para> - - <para>In all other aspects of project operation, core is a subset - of committers and is bound by the <emphasis>same - rules</emphasis>. Just because someone is in core this does not mean - that they have special dispensation to step outside any of - the lines painted here; core's <quote>special powers</quote> - only kick in when it acts as a group, not on an individual - basis. As individuals, the core team members are all committers - first and core second.</para> - - <sect2> - <title>Details</title> - - <orderedlist> - <listitem id="respect"> - <para>Respect other committers.</para> - - <para>This means that you need to treat other committers as - the peer-group developers that they are. Despite our - occasional attempts to prove the contrary, one does not get - to be a committer by being stupid and nothing rankles more - than being treated that way by one of your peers. Whether - we always feel respect for one another or not (and - everyone has off days), we still have to - <emphasis>treat</emphasis> other committers with respect - at all times, on public forums and in private email.</para> - - <para>Being able to work together long term is this project's - greatest asset, one far more important than any set of - changes to the code, and turning arguments about code into - issues that affect our long-term ability to work - harmoniously together is just not worth the trade-off by - any conceivable stretch of the imagination.</para> - - <para>To comply with this rule, do not send email when you are - angry or otherwise behave in a manner which is likely to - strike others as needlessly confrontational. First calm - down, then think about how to communicate in the most - effective fashion for convincing the other person(s) that - your side of the argument is correct, do not just blow off - some steam so you can feel better in the short term at the - cost of a long-term flame war. Not only is this very bad - <quote>energy economics</quote>, but repeated displays of - public aggression which impair our ability to work well - together will be dealt with severely by the project - leadership and may result in suspension or termination of - your commit privileges. The project leadership will - take into account both public and private communications - brought before it. It will not seek the disclosure of - private communications, but it will take it into account - if it is volunteered by the committers involved in the - complaint.</para> - - <para>All of this is never an option which the - project's leadership enjoys in the slightest, but unity - comes first. No amount of code or good advice is worth - trading that away.</para> - </listitem> - - <listitem> - <para>Respect other contributors.</para> - - <para>You were not always a committer. At one time you were - a contributor. Remember that at all times. Remember what - it was like trying to get help and attention. Do not forget - that your work as a contributor was very important to - you. Remember what it was like. Do not discourage, belittle, - or demean contributors. Treat them with respect. They are - our committers in waiting. They are every bit as important - to the project as committers. Their contributions are as - valid and as important as your own. After all, you made - many contributions before you became a committer. Always - remember that. </para> - - <para>Consider the points raised under <xref linkend="respect"> - and apply them also to contributors.</para> - </listitem> - - <listitem> - <para>Discuss any significant change - <emphasis>before</emphasis> committing.</para> - - <para>The CVS repository is not where changes should be - initially submitted for correctness or argued over, that - should happen first in the mailing lists and the commit should - only happen once something resembling consensus has - been reached. This does not mean that you have to ask - permission before correcting every obvious syntax error or - manual page misspelling, simply that you should try to - develop a feel for when a proposed change is not quite such - a no-brainer and requires some feedback first. People - really do not mind sweeping changes if the result is - something clearly better than what they had before, they - just do not like being <emphasis>surprised</emphasis> by - those changes. The very best way of making sure that - you are on the right track is to have your code reviewed by - one or more other committers.</para> - - <para>When in doubt, ask for review!</para> - </listitem> - - <listitem> - <para>Respect existing maintainers if listed.</para> - - <para>Many parts of FreeBSD are not <quote>owned</quote> in - the sense that any specific individual will jump up and - yell if you commit a change to <quote>their</quote> area, - but it still pays to check first. One convention we use - is to put a maintainer line in the - <filename>Makefile</filename> for any package or subtree - which is being actively maintained by one or more people; - see <ulink - url="&url.books.developers-handbook;/policies.html"></ulink> - for documentation on this. Where sections of code have - several maintainers, commits to affected areas by one - maintainer need to be reviewed by at least one other - maintainer. In cases where the - <quote>maintainer-ship</quote> of something is not clear, - you can also look at the CVS logs for the file(s) in - question and see if someone has been working recently or - predominantly in that area.</para> - - <para>Other areas of FreeBSD fall under the control of - someone who manages an overall category of FreeBSD - evolution, such as internationalization or networking. - See <ulink - url="&url.articles.contributors;/staff-who.html"> - http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributors/staff-who.html</ulink> - for more information on this.</para> - </listitem> - - <listitem> - <para>Any disputed change must be backed out pending - resolution of the dispute if requested by a maintainer. - Security related changes may - override a maintainer's wishes at the Security Officer's - discretion.</para> - - <para>This may be hard to swallow in times of conflict (when - each side is convinced that they are in the right, of - course) but CVS makes it unnecessary to have an ongoing - dispute raging when it is far easier to simply reverse the - disputed change, get everyone calmed down again and then - try to figure out what is the best way to proceed. If the change - turns out to be the best thing after all, it can be easily - brought back. If it turns out not to be, then the users - did not have to live with the bogus change in the tree - while everyone was busily debating its merits. People - very very rarely call for back-outs in the repository - since discussion generally exposes bad or controversial - changes before the commit even happens, but on such rare - occasions the back-out should be done without argument so - that we can get immediately on to the topic of figuring - out whether it was bogus or not.</para> - </listitem> - - <listitem> - <para>Changes go to &os.current; before - &os.stable; unless specifically permitted - by the release engineer or unless they are not applicable - to &os.current;. Any non-trivial or - non-urgent change which is applicable should also be - allowed to sit in &os.current; for at least - 3 days before merging so that it can be given sufficient - testing. The release engineer has the same authority over - the &os.stable; branch as outlined in rule - #5.</para> - - <para>This is another <quote>do not argue about it</quote> - issue since it is the release engineer who is ultimately - responsible (and gets beaten up) if a change turns out to - be bad. Please respect this and give the release engineer - your full cooperation when it comes to the - &os.stable; branch. The management of - &os.stable; may frequently seem to be - overly conservative to the casual observer, but also bear - in mind the fact that conservatism is supposed to be the - hallmark of &os.stable; and different rules - apply there than in &os.current;. There is - also really no point in having &os.current; - be a testing ground if changes are merged over to - &os.stable; immediately. Changes need a - chance to be tested by the &os.current; - developers, so allow some time to elapse before merging - unless the &os.stable; fix is critical, - time sensitive or so obvious as to make further testing - unnecessary (spelling fixes to manual pages, obvious bug/typo - fixes, etc.) In other words, apply common sense.</para> - - <para>Changes to the security branches - (for example, <literal>RELENG_4_5</literal>) must be - approved by a member of the &a.security-officer;, or in - some cases, by a member of the &a.re;.</para> - </listitem> - - <listitem> - <para>Do not fight in public with other committers; it looks - bad. If you must <quote>strongly disagree</quote> about - something, do so only in private.</para> - - <para>This project has a public image to uphold and that - image is very important to all of us, especially if we are - to continue to attract new members. There will be - occasions when, despite everyone's very best attempts at - self-control, tempers are lost and angry words are - exchanged. The best thing that can be done in such cases is to minimize - the effects of this until everyone has cooled back down. That - means that you should not air your angry words in public - and you should not forward private correspondence to - public mailing lists or aliases. What people say - one-to-one is often much less sugar-coated than what they - would say in public, and such communications therefore - have no place there - they only serve to inflame an - already bad situation. If the person sending you a - flame-o-gram at least had the grace to send it privately, - then have the grace to keep it private yourself. If you - feel you are being unfairly treated by another developer, - and it is causing you anguish, bring the matter up with - core rather than taking it public. Core will do its best to - play peace makers and get things back to sanity. In cases - where the dispute involves a change to the codebase and - the participants do not appear to be reaching an amicable - agreement, core may appoint a mutually-agreeable 3rd party - to resolve the dispute. All parties involved must then - agree to be bound by the decision reached by this 3rd - party.</para> - <!-- XXX Mention TRB here too --> - </listitem> - - <listitem> - <para>Respect all code freezes and read the - <literal>committers</literal> and <literal>developers</literal> - mailing list on a timely basis so you know when a code freeze is - in effect.</para> - - <para>Committing unapproved changes during a code freeze is a really - big mistake and committers are expected to keep up-to-date - on what is going on before jumping in after a long absence - and committing 10 megabytes worth of accumulated stuff. - People who abuse this on a regular basis will have their - commit privileges suspended until they get back from the - FreeBSD Happy Reeducation Camp we run in Greenland.</para> - </listitem> - - <listitem> - <para>When in doubt on any procedure, ask first!</para> - - <para>Many mistakes are made because someone is in a hurry - and just assumes they know the right way of doing - something. If you have not done it before, chances are - good that you do not actually know the way we do things - and really need to ask first or you are going to - completely embarrass yourself in public. There is no shame - in asking <quote>how in the heck do I do this?</quote> We - already know you are an intelligent person; otherwise, you - would not be a committer.</para> - </listitem> - - <listitem> - <para>Test your changes before committing them.</para> - - <!-- XXX Needs update re sparc64 + pc98 - Also, needs more details on which machines are available for testing - --> - <para>This may sound obvious, but if it really were so - obvious then we probably would not see so many cases of - people clearly not doing this. If your changes are to the - kernel, make sure you can still compile both GENERIC and - LINT. If your changes are anywhere else, make sure you - can still make world. If your changes are to a branch, - make sure your testing occurs with a machine which is - running that code. If you have a change which also may - break another architecture, be sure and test on all - supported architectures. Please refer to the <ulink - url="http://www.FreeBSD.org/internal/">FreeBSD Internal - Page</ulink> for a list of available resources. As other - architectures are added to the FreeBSD supported platforms - list, the appropriate shared testing resources will be - made available.</para> - </listitem> - - <listitem> - <para>Do not commit to anything under the - <filename>src/contrib</filename>, - <filename>src/crypto</filename>, and - <filename>src/sys/contrib</filename> trees without - <emphasis>explicit</emphasis> approval from the respective - maintainer(s).</para> - - <para>The trees mentioned above are for contributed software - usually imported onto a vendor branch. Committing something - there, even if it does not take the file off the vendor branch, - may cause unnecessary headaches for those responsible for - maintaining that particular piece of software. Thus, unless - you have <emphasis>explicit</emphasis> approval from the - maintainer (or you are the maintainer), do - <emphasis>not</emphasis> commit there!</para> - - <para>Please note that this does not mean you should not try to - improve the software in question; you are still more than - welcome to do so. Ideally, you should submit your patches to - the vendor. If your changes are FreeBSD-specific, talk to the - maintainer; they may be willing to apply them locally. But - whatever you do, do <emphasis>not</emphasis> commit there by - yourself!</para> - - <para>Contact the &a.core; if you wish to take up maintainership - of an unmaintained part of the tree.</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Policy on Multiple Architectures</title> - - <para>FreeBSD has added several new arch ports during the 5.0 - release cycle and is truly no longer an &i386; centric operating - system. In an effort to make it easier to keep FreeBSD portable - across the platforms we support, core has developed the following - mandate:</para> - - <blockquote> - <para>Our 32 bit reference platform is i386, and our 64 bit - reference platform is Sparc64. Major design work (including - major API and ABI changes) must prove itself on at least one - 32 bit and at least one 64 bit platform, preferably the - primary reference platforms, before it may be committed - to the source tree.</para> - </blockquote> - - <para>The i386 and Sparc64 platforms were chosen due to being more - readily available to developers and as representatives of more - diverse processor and system designs - big vs little endian, - register file vs register stack, different DMA and cache - implementations, hardware page tables vs software TLB management - etc.</para> - - <para>While the Alpha is a 64 bit processor, it is a more - traditional processor design and does not provide as good a testbed - for many of the challenges that the other 64 bit platform ports - face. The ia64 platform has many of the same complications that - Sparc64 has, but is still limited in availability to - developers.</para> - - <para>We will continue to re-evaluate this policy as cost and - availability of the 64 bit platforms change.</para> - - <para>Developers should also be aware of our Tier Policy for - the long term support of hardware architectures. The rules - here are intended to provide guidance during the development - process, and are distinct from the requirements for features - and architectures listed in that section. The Tier rules for - feature support on architectures at release-time are more - strict than the rules for changes during the development - process.</para> - </sect2> - - <sect2> - <title>Other Suggestions</title> - - <para>When committing documentation changes, use a spell checker - before committing. For all SGML docs, you should also - verify that your formatting directives are correct by running - <command>make lint</command>.</para> - - <para>For all on-line manual pages, run <command>manck</command> - (from ports) over the manual page to verify all of the cross - references and file references are correct and that the man - page has all of the appropriate <makevar>MLINK</makevar>s - installed.</para> - - <para>Do not mix style fixes with new functionality. A style - fix is any change which does not modify the functionality of - the code. Mixing the changes obfuscates the functionality - change when using <command>cvs diff</command>, which can hide - any new bugs. Do not include whitespace changes with content - changes in commits to <filename>doc/</filename> or - <filename>www/</filename>. The extra clutter in the diffs - makes the translators' job much more difficult. Instead, make - any style or whitespace changes in separate commits that are - clearly labeled as such in the commit message.</para> - </sect2> - - <sect2> - <title>Deprecating Features</title> - - <para>When it is necessary to remove functionality from software - in the base system the following guidelines should be followed - whenever possible:</para> - - <orderedlist> - <listitem> - <para>Mention is made in the manual page and possibly the - release notes that the option, utility, or interface is - deprecated. Use of the deprecated feature generates a - warning.</para> - </listitem> - - <listitem> - <para>The option, utility, or interface is preserved until - the next major (point zero) release.</para> - </listitem> - - <listitem> - <para>The option, utility, or interface is removed and no - longer documented. It is now obsolete. It is also - generally a good idea to note its removal in the release - notes.</para> - </listitem> - </orderedlist> - </sect2> - </sect1> - - <sect1 id="archs"> - <title>Support for Multiple Architectures</title> - - <para>FreeBSD is a highly portable operating system intended to - function on many different types of hardware architectures. - Maintaining clean separation of Machine Dependent (MD) and Machine - Independent (MI) code, as well as minimizing MD code, is an important - part of our strategy to remain agile with regards to current - hardware trends. Each new hardware architecture supported by - FreeBSD adds substantially to the cost of code maintenance, - toolchain support, and release engineering. It also dramatically - increases the cost of effective testing of kernel changes. As such, - there is strong motivation to differentiate between classes of - support for various architectures while remaining strong in a few - key architectures that are seen as the FreeBSD "target audience". - </para> - - <sect2> - <title>Statement of General Intent</title> - - <para>The FreeBSD Project targets "production quality commercial - off-the-shelf (COTS) workstation, server, and high-end embedded - systems". By retaining a focus on a narrow set of architectures - of interest in these environments, the FreeBSD Project is able - to maintain high levels of quality, stability, and performance, - as well as minimize the load on various support teams on the - project, such as the ports team, documentation team, - security officer, and release engineering teams. Diversity in - hardware support broadens the options for FreeBSD consumers by - offering new features and usage opportunities (such as support - for 64-bit CPUs, use in embedded environments, etc.), but these - benefits must always be carefully considered in terms of the real-world - maintenance cost associated with additional platform support. - </para> - - <para>The FreeBSD Project differentiates platform targets into - four tiers. Each tier includes a specification of the - requirements for an architecture to be in that tier, - as well as specifying the obligations of developers with - regards to the platform. In addition, a policy is defined - regarding the circumstances required to change the tier - of an architecture.</para> - </sect2> - - <sect2> - <title>Tier 1: Fully Supported Architectures</title> - - <para>Tier 1 platforms are fully supported by the security - officer, release engineering, and toolchain maintenance staff. - New features added to the operating system must be fully - functional across all Tier 1 architectures for every release - (features which are inherently architecture-specific, such as - support for hardware device drivers, may be exempt from this - requirement). In general, all Tier 1 platforms must have build - and tinderbox support either in the FreeBSD.org cluster, or - easily available for all developers.</para> - - <para>Tier 1 architectures are expected to be Production Quality - with respects to all aspects of the FreeBSD operating system, - including installation and development environments.</para> - - <para>Current Tier 1 platforms are i386, Sparc64, AMD64, and PC98.</para> - </sect2> - - <sect2> - <title>Tier 2: Developmental Architectures</title> - - <para>Tier 2 platforms are not supported by the security officer - and release engineering teams. At the discretion of the - toolchain maintainer, they may be supported in the toolchain. New - features added to FreeBSD should be feasible to implement on these - platforms, but an implementation is not required before the - feature may be added to the FreeBSD source tree. The - implementation of a Tier 2 architecture may be committed to the - main FreeBSD tree as long as it does not interfere with - production work on Tier 1 platforms, or substantially with other - Tier 2 platforms. Before a Tier 2 platform can be added to the - FreeBSD base source tree, the platform must be able to boot to at - least single-user mode on real world commodity hardware. Some - exceptions to these rules may be made for new hardware that is - under development by hardware vendors, but not yet available to - the project.</para> - - <para>Tier 2 architectures are usually systems targeted at Tier 1 - support, but that are still under development. Architectures - reaching end of life may also be moved from Tier 1 status to Tier - 2 status as the availability of resources to continue to maintain - the system in a Production Quality state diminishes.</para> - - <para>Current Tier 2 platforms are Alpha, PowerPC and ia64.</para> - </sect2> - - <sect2> - <title>Tier 3: Experimental Architectures</title> - - <para>Tier 3 platforms are not supported by the security officer - and release engineering teams. At the discretion of the toolchain - maintainer, they may be supported in the toolchain. Tier 3 - platforms are architectures for which hardware is not or will not - be available to the project in the foreseeable future, for which - there are two or fewer active developers, that can not boot to at - least single-user mode on real hardware (or a simulator for new - hardware platforms), or which are considered legacy systems - unlikely to see broad future use. Tier 3 systems will not be - committed to the base source tree, although support for Tier 3 - systems may be worked on in the FreeBSD Perforce Repository, - providing source control and easier change integration from the - main FreeBSD tree.</para> - - <para>Current Tier 3 platforms are &s390;.</para> - </sect2> - - <sect2> - <title>Tier 4: Unsupported Architectures</title> - - <para>Tier 4 systems are not supported in any form by the project. - </para> - - <para>All systems not otherwise classified into a support tier - are Tier 4 systems.</para> - </sect2> - - <sect2> - <title>Policy on Changing the Tier of an Architecture</title> - - <para>Systems may only be moved from one tier to another by - approval of the FreeBSD Core Team, which shall make that - decision in collaboration with the Security Officer, Release - Engineering, and toolchain maintenance teams.</para> - </sect2> - </sect1> - - <sect1 id="ports"> - <title>Ports Specific FAQ</title> - - <qandaset> - <qandadiv> - <title>Adding a New Port</title> - - <qandaentry> - <question> - <para>How do I add a new port?</para> - </question> - - <answer> - <para>First, please read the section about repository - copies.</para> - - <para>The easiest way to add a new port is to use the - <command>addport</command> script on - <hostid>freefall</hostid>. It will add a port from the - directory you specify, determining the category automatically - from the port <filename>Makefile</filename>. - It will also add an entry to the - <filename>CVSROOT/modules</filename> file and the port's - category <filename>Makefile</filename>. It was - written by &a.mharo; and &a.will;, but Will is the current - maintainer so please send questions/patches about - <command>addport</command> to him.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Any other things I need to know when I add a new - port?</para> - </question> - - <answer> - <para>Check the port, preferably to make sure it compiles - and packages correctly. This is the recommended - sequence:</para> - - <screen>&prompt.root; <userinput>make install</userinput> -&prompt.root; <userinput>make package</userinput> -&prompt.root; <userinput>make deinstall</userinput> -&prompt.root; <userinput>pkg_add <replaceable>package you built above</replaceable></userinput> -&prompt.root; <userinput>make deinstall</userinput> -&prompt.root; <userinput>make reinstall</userinput> -&prompt.root; <userinput>make package</userinput> - </screen> - - <para>The - <ulink url="&url.books.porters-handbook;/index.html">Porters - Handbook</ulink> contains more detailed - instructions.</para> - - <para>Use &man.portlint.1; to check the syntax of the port. - You do not necessarily have to eliminate all warnings but - make sure you have fixed the simple ones.</para> - - <para>If the port came from a submitter who has not - contributed to the project before, add that person's - name to the <ulink - url="&url.articles.contributors;/contrib-additional.html">Additional - Contributors</ulink> section of the FreeBSD Contributors - List.</para> - - <para>Close the PR if the port came in as a PR. To close - a PR, just do - <userinput>edit-pr <replaceable>PR#</replaceable></userinput> - on <hostid>freefall</hostid> and change the - <varname>state</varname> from <constant>open</constant> - to <constant>closed</constant>. You will be asked to - enter a log message and then you are done.</para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv> - <title>Repository Copies</title> - - <qandaentry> - <question> - <para>When do we need a repository copy?</para> - </question> - - <answer> - <para>When you want to add a port that is related to - any port that is already in the tree in a separate - directory, you have to do a repository copy. - Here <wordasword>related</wordasword> means - it is a different version or a slightly modified - version. Examples are - <filename>print/ghostscript*</filename> (different - versions) and <filename>x11-wm/windowmaker*</filename> - (English-only and internationalized version).</para> - - <para>Another example is when a port is moved from one - subdirectory to another, or when you want to change the - name of a directory because the author(s) renamed their - software even though it is a - descendant of a port already in a tree.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>When do we <emphasis>not</emphasis> need a - repository copy?</para> - </question> - - <answer> - <para>When there is no history to preserve. If a port is - added into a wrong category and is moved immediately, - it suffices to simply <command>cvs remove</command> the - old one and <command>addport</command> the new - one.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What do I need to do?</para> - </question> - - <answer> - <para>File a PR in <application>GNATS</application>, listing the - reasons for the repository copy request. Assign it to - <literal>portmgr</literal> and set <varname>state</varname> to - <literal>repocopy</literal>. If &a.portmgr; approves it, - it will be reassigned to <literal>cvs</literal>. &a.cvs; will - do a repository copy from the old to the new location, and - reassign the PR back to you. Once everything is done, perform the - following:</para> - - <itemizedlist> - <listitem> - <para>When a port has been repo copied:</para> - - <procedure> - <step> - <para>Upgrade the copied port to the new version (remember - to change the <makevar>PORTNAME</makevar> so there - are not duplicate ports with the same name).</para> - </step> - - <step> - <para>Add the new subdirectory to the - <makevar>SUBDIR</makevar> listing in the parent - directory Makefile. You can run <command>make - checksubdirs</command> in the parent directory to check - this.</para> - </step> - - <step> - <para>If the port changed categories, modify the - <makevar>CATEGORIES</makevar> line of the port's - <filename>Makefile</filename> accordingly</para> - </step> - - <step> - <para>Add the new module entry.</para> - </step> - - <step> - <para>Add an entry to - <filename>ports/MOVED</filename>.</para> - </step> - </procedure> - </listitem> - - <listitem> - <para>When removing a port:</para> - - <procedure> - <step> - <para>Perform a thorough check of the ports collection for - any dependencies on the old port location/name, and - update them. Running <command>grep</command> on - <filename>INDEX</filename> is not enough because some - ports have dependencies enabled by compile-time options. - A full <command>grep -r</command> of the ports - collection is recommended.</para> - </step> - - <step> - <para>Remove the old port, the old - <makevar>SUBDIR</makevar> entry and the old module - entry.</para> - </step> - - <step> - <para>Add an entry to - <filename>ports/MOVED</filename>.</para> - </step> - </procedure> - </listitem> - - <listitem> - <para>After repo moves (<quote>rename</quote> operations where - a port is copied and the old location is removed):</para> - - <procedure> - <step> - <para>Follow the same steps that are outlined in the - previous two entries, to activate the new location of - the port and remove the old one.</para> - </step> - </procedure> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv> - <title>Ports Freeze</title> - - <qandaentry> - <question> - <para>What is a <quote>ports freeze</quote>?</para> - </question> - - <answer> - <para>Before a release, it is necessary to restrict - commits to the ports tree for a short period of time - while the packages and the release itself are being - built. This is to ensure consistency among the various - parts of the release, and is called the <quote>ports - freeze</quote>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How long is a ports freeze?</para> - </question> - - <answer> - <para>Usually an hour or two.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What does it mean to me?</para> - </question> - - <answer> - <para>During the ports freeze, you are not allowed to - commit anything to the tree without explicit approval - from the ports manager. <quote>Explicit - approval</quote> here means either of the - following:</para> - - <itemizedlist> - <listitem> - <para>You asked the ports manager and got a reply - saying, <quote>Go ahead and commit - it.</quote></para> - </listitem> - - <listitem> - <para>The ports manager sent a mail to you or the - mailing lists during the ports freeze pointing out - that the port is broken and has to be fixed.</para> - </listitem> - </itemizedlist> - - <para>Note that you do not have implicit permission to fix - a port during the freeze just because it is - broken.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I know when the ports freeze starts?</para> - </question> - - <answer> - <para>The ports manager will send out warning messages to - the &a.ports; and &a.committers; - announcing the start of the impending release, usually - two or three weeks in advance. The exact starting time - will not be determined until a few days before the - actual release. This is because the ports freeze has to - be synchronized with the release, and it is usually not - known until then when exactly the release will be - rolled.</para> - - <para>When the freeze starts, there will be another - announcement to the &a.committers;, of course.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I know when the ports freeze ends?</para> - </question> - - <answer> - <para>A few hours after the release, the ports manager - will send out a mail to the &a.ports; and &a.committers; - announcing the end of the ports freeze. Note that the - release being cut does not automatically end the freeze. - We have to make sure there will not be any last minute - snafus that result in an immediate re-rolling of the - release.</para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv> - <title>Creating a New Category</title> - - <qandaentry> - <question> - <para>What is the procedure for creating a new category?</para> - </question> - - <answer> - <para>A developer who wishes to propose a new category - should submit a detailed rationale for the new category, - including why existing categories are not sufficient, - and the list of ports proposed to move.</para> - - <para>Before submitting, keep in mind that there is a fair - amount of work involved from multiple parties; that the - changes affect everyone who wants to keep up-to-date with - the entire ports tree; and that such proposals tend to - attract controversy.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What do I need to do?</para> - </question> - - <answer> - <para>The procedure is a strict superset of the one to - repocopy individual ports (see above).</para> - - <para>File a PR in <application>GNATS</application>, listing the - reasons for the category request. Preferably, this should - also include patches for <filename>Makefile</filename>s for - the old ports, the <filename>Makefile</filename>s for their - old categories, and the <makevar>VALID_CATEGORIES</makevar> - definition in <filename>ports/Mk/bsd.port.mk</filename>. - Assign the PR to the &a.portmgr; (as <literal>portmgr</literal>). - If they approve it, it will be reassigned to &a.cvs; (as - <literal>cvs</literal>), who will do a repository copy from - the old to the new locations and reassign the PR back to you. - Once everything is done, perform the following steps:</para> - - <procedure> - <step> - <para>Upgrade each copied port's - <filename>Makefile</filename>. Do not connect the - new category to the build yet.</para> - - <para>To do this, you will need to:</para> - <procedure> - <step> - <para>Change the port's <makevar>CATEGORIES</makevar> - (this was the point of the exercise, remember?) - The new category should be listed - <emphasis>first</emphasis>. This will help to - ensure that the the <makevar>PKGORIGIN</makevar> - is correct.</para> - </step> - - <step> - <para>Run a <command>make describe</command>. Since - the top-level <command>make index</command> that - you will be running in a few steps is an iteration - of <command>make describe</command> over the entire - ports hierarchy, catching any errors here will - save you having to re-run that step later on.</para> - </step> - - <step> - <para>If you want to be really thorough, now might - be a good time to run &man.portlint.1;.</para> - </step> - </procedure> - </step> - - <step> - <para>Check that the <makevar>PKGORIGIN</makevar>s are - correct. The ports system uses each port's - <makevar>CATEGORIES</makevar> entry to create - its <makevar>PKGORIGIN</makevar>, which is used to - connect installed packages to the port directory they - were built from. If this entry is wrong, common port - tools like &man.pkg.version.1; and - &man.portupgrade.1; fail.</para> - - <para>To do this, use the <filename>chkorigin.sh</filename> - tool, as follows: <command>env - PORTSDIR=<replaceable>/path/to/ports</replaceable> - sh -e <replaceable>/path/to/ports</replaceable>/Tools/scripts/chkorigin.sh - </command>. This will check <emphasis>every</emphasis> - port in the ports tree, even those not connected to the - build, so you can run it directly after the repocopy. - Hint: do not forget to look at the - <makevar>PKGORIGIN</makevar>s of any slave ports of the - ports you just repocopied!</para> - </step> - - <step> - <para>On your own local system, test the proposed - changes: first, comment out the - <makevar>SUBDIR</makevar> entries in the old - ports' categories' <filename>Makefile</filename>s; - then enable building the new category in - <filename>ports/Makefile</filename>. - Run <command>make checksubdirs</command> in the - affected category directories to check the - <makevar>SUBDIR</makevar> entries. Next, in - the <filename class="directory">ports/</filename> - directory, run <command>make index</command>. This - can take over 40 minutes on even modern systems; - however, it is a necessary step to prevent problems - for other people.</para> - </step> - - <step> - <para>Once this is done, you can commit the - updated <filename>ports/Makefile</filename> to - connect the new category to the build and also - commit the <filename>Makefile</filename> changes - for the old category or categories.</para> - </step> - - <step> - <para>Change all the affected module entries in - <filename>CVSROOT-ports/modules</filename>.</para> - </step> - - <step> - <para>Add appropriate entries to - <filename>ports/MOVED</filename>.</para> - </step> - - <step> - <para>Update the instructions for &man.cvsup.1; by - modifying <filename>distrib/cvsup/sup/README</filename> - and adding the following files into - <filename>cvsup/sup/ports-categoryname</filename>: - <filename>list.cvs</filename> and - <filename>releases</filename>. (Note: these are - in the src, not the ports, repository).</para> - </step> - - <step> - <para>Submit a docs PR to add the new category to both the - <ulink url="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES"> - Porter's Handbook</ulink> and to - <filename>www/en/ports/categories</filename>.</para> - </step> - - <step> - <para>The procedure to update the <ulink - url="&url.base;/ports/index.html">ports web pages</ulink> - to reflect the new category is not yet defined.</para> - </step> - - <step> - <para>Only once all the above have been done, and - no one is any longer reporting problems with the - new ports, should the old ports be deleted from - their previous locations in the repository.</para> - </step> - </procedure> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv> - <title>Miscellaneous Questions</title> - - <qandaentry> - <question> - <para>How do I know if my port is building correctly or - not?</para> - </question> - - <answer> - <para>First, go check - <ulink url="http://pointyhat.FreeBSD.org/errorlogs/"></ulink>. - There you will find error logs from the latest package - building runs on all supported platforms for the most - recent branches.</para> - - <para>However, just because the port does not show up there - does not mean it is building correctly. (One of the - dependencies may have failed, for instance.) The relevant - directories are available on <hostid>pointyhat</hostid> under - <filename class="directory">/a/asami/portbuild/<arch>/<major_version></filename> - so feel free to dig around. Each architecture and version has - the following subdirectories:</para> - -<programlisting>errors error logs from latest <major_version> run on <arch> -logs all logs from latest <major_version> run on <arch> -packages packages from latest <major_version> run on <arch> -bak/errors error logs from last complete <major_version> run on <arch> -bak/logs all logs from last complete <major_version> run on <arch> -bak/packages packages from last complete <major_version> run on <arch></programlisting> - - <para>Basically, if the port shows up in - <filename>packages</filename>, or it is in - <filename>logs</filename> but not in - <filename>errors</filename>, it built fine. (The - <filename>errors</filename> directories are what you get - from the web page.)</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I added a new port. Do I need to add it to the - <filename>INDEX</filename>?</para> - </question> - - <answer> - <para>No. The ports manager will regenerate the - <filename>INDEX</filename> and commit it for each - &os; release.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Are there any other files I am not allowed to - touch?</para> - </question> - - <answer> - <para>Any file directly under <filename>ports/</filename>, or - any file under a subdirectory that starts with an - uppercase letter (<filename>Mk/</filename>, - <filename>Tools/</filename>, etc.). In particular, the - ports manager is very protective of - <filename>ports/Mk/bsd.port*.mk</filename> so do not - commit changes to those files unless you want to face his - wra(i)th.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What is the proper procedure for updating the checksum - for a port's distfile when the file changes without a - version change?</para> - </question> - - <answer> - <para>When the checksum for a port's distfile is updated due - to the author updating the file without changing the port's - revision, the commit message should include a summary of - the relevant diffs between the original and new distfile to - ensure that the distfile has not been corrupted or - maliciously altered. If the current version of the port - has been in the ports tree for a while, a copy of the old - distfile will usually be available on the ftp servers; - otherwise the author or maintainer should be contacted to - find out why the distfile has changed.</para> - </answer> - </qandaentry> - </qandadiv> - </qandaset> - </sect1> - - <sect1 id="perks"> - <title>Perks of the Job</title> - - <para>Unfortunately, there are not many perks involved with being a - committer. Recognition as a competent software engineer is probably - the only thing that will be of benefit in the long run. However, - there are at least some perks:</para> - - <variablelist> - - <varlistentry> - <term>Direct access to <hostid>cvsup-master</hostid></term> - - <listitem> - <para>As a committer, you may apply to &a.kuriyama; for direct access - to <hostid role="fqdn">cvsup-master.FreeBSD.org</hostid>, - providing the public key output from <command>cvpasswd - <replaceable>yourusername</replaceable>@FreeBSD.org - freefall.FreeBSD.org</command>. Please note: you must - specify <hostid>freefall.FreeBSD.org</hostid> on the - <command>cvpasswd</command> command line even though the - actual server is <hostid>cvsup-master</hostid>. Access to - <hostid>cvsup-master</hostid> should not be overused as it is - a busy machine.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>A Free 4-CD Set or DVD Subscription</term> - - <listitem> - <para><ulink url="http://www.freebsdmall.com">FreeBSD Mall, - Inc.</ulink> offers a free subscription of the 4-CD set or - the DVD product to all FreeBSD committers. Information about how - to obtain your free media is mailed to - <email>developers@FreeBSD.org</email> following each major - release.</para> - </listitem> - </varlistentry> - - </variablelist> - </sect1> - - <sect1 id="misc"> - <title>Miscellaneous Questions</title> - - <qandaset> - <qandaentry> - <question> - <para>Why are trivial or cosmetic changes to files on a vendor - branch a bad idea?</para> - </question> - - <answer> - <itemizedlist> - <listitem> - <para>From now on, every new vendor release of that file will - need to have patches merged in by hand.</para> - </listitem> - - <listitem> - <para>From now on, every new vendor release of that file will - need to have patches <emphasis>verified</emphasis> by hand.</para> - </listitem> - - <listitem> - <para>The <option>-j</option> option does not work very well. - Ask &a.obrien; for horror stories.</para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I add a new file to a CVS branch?</para> - </question> - - <answer> - <para>To add a file onto a branch, simply checkout or update - to the branch you want to add to and then add the file using - <command>cvs add</command> as you normally would. For - example, if you wanted to MFC the file - <filename>src/sys/alpha/include/smp.h</filename> from HEAD - to RELENG_4 and it does not exist in RELENG_4 yet, you would - use the following steps:</para> - - <example> - <title>MFC'ing a New File</title> - - <screen>&prompt.user; <userinput>cd sys/alpha/include</userinput> -&prompt.user; <userinput>cvs update -rRELENG_4</userinput> -cvs update: Updating . -U clockvar.h -U console.h -... -&prompt.user; <userinput>cvs update -kk -Ap smp.h > smp.h</userinput> -=================================================================== -Checking out smp.h -RCS: /usr/cvs/src/sys/alpha/include/smp.h,v -VERS: 1.1 -*************** -&prompt.user; <userinput>cvs add smp.h</userinput> -cvs add: scheduling file `smp.h' for addition on branch `RELENG_4' -cvs add: use 'cvs commit' to add this file permanently -&prompt.user; <userinput>cvs commit</userinput> - </screen> - </example> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What <quote>meta</quote> information should I include in a - commit message?</para> - </question> - - <answer> - <para>As well as including an informative message with each commit - you may need to include some additional information as - well.</para> - - <para>This information consists of one or more lines containing the - key word or phrase, a colon, tabs for formatting, and then the - additional information.</para> - - <para>The key words or phrases are:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry><literal>PR:</literal></entry> - <entry>The problem report (if any) which is affected - (typically, by being closed) by this commit.</entry> - </row> - - <row> - <entry><literal>Submitted by:</literal></entry> - <entry>The name and e-mail address of the person that - submitted the fix; for committers, just the username on - the FreeBSD cluster.</entry> - </row> - - <row> - <entry><literal>Reviewed by:</literal></entry> - <entry>The name and e-mail address of the person or people - that reviewed the change; for committers, just the - username on the FreeBSD cluster. If a patch was - submitted to a mailing list for review, and the review - was favorable, then just include the list name.</entry> - </row> - - <row> - <entry><literal>Approved by:</literal></entry> - <entry>The name and e-mail address of the person or people - that approved the change; for committers, just the - username on the FreeBSD cluster. It is customary to get - prior approval for a commit if it is to an area of the - tree to which you do not usually commit. In addition, - during the run up to a new release all commits - <emphasis>must</emphasis> be approved by the release - engineering team. If these are your first commits then - you should have passed them past your mentor first, and - you should list your mentor, as in - ``<replaceable>username-of-mentor</replaceable> - <literal>(mentor)</literal>''. - </entry> - </row> - - <row> - <entry><literal>Obtained from:</literal></entry> - <entry>The name of the project (if any) from which the code - was obtained.</entry> - </row> - - <row> - <entry><literal>MFC after:</literal></entry> - - <entry>If you wish to receive an e-mail reminder to - <acronym>MFC</acronym> at a later date, specify the - number of days, weeks, or months after which an - <acronym>MFC</acronym> is planned.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <example> - <title>Commit log for a commit based on a PR</title> - - <para>You want to commit a change based on a PR submitted by John - Smith containing a patch. The end of the commit message should - look something like this.</para> - - <programlisting>... - -PR: foo/12345 -Submitted by: John Smith <John.Smith@example.com></programlisting> - </example> - - <example> - <title>Commit log for a commit needing review</title> - - <para>You want to change the virtual memory system. You have - posted patches to the appropriate mailing list (in this case, - <literal>freebsd-arch</literal>) and the changes have been - approved.</para> - - <programlisting>... - -Reviewed by: -arch</programlisting> - </example> - - <example> - <title>Commit log for a commit needing approval</title> - - <para>You want to commit a change to a section of the tree with a - MAINTAINER assigned. You have collaborated with the listed - MAINTAINER, who has told you to go ahead and commit.</para> - - <programlisting>... - -Approved by: <replaceable>abc</replaceable></programlisting> - - <para>Where <replaceable>abc</replaceable> is the account name of - the person who approved.</para> - </example> - - <example> - <title>Commit log for a commit bringing in code from - OpenBSD</title> - - <para>You want to commit some code based on work done in the - OpenBSD project.</para> - - <programlisting>... - -Obtained from: OpenBSD</programlisting> - </example> - - <example> - <title>Commit log for a change to &os.current; with a planned - commit to &os.stable; to follow at a later date.</title> - - <para>You want to commit some code which will be merged from - &os.current; into the &os.stable; branch after two - weeks.</para> - - <programlisting>... - -MFC after: <replaceable>2 weeks</replaceable></programlisting> - - <para>Where <replaceable>2</replaceable> is the number of days, - weeks, or months after which an <acronym>MFC</acronym> is - planned. The <replaceable>weeks</replaceable> option may be - <literal>day</literal>, <literal>days</literal>, - <literal>week</literal>, <literal>weeks</literal>, - <literal>month</literal>, <literal>months</literal>, - or may be left off (in which case, days will be assumed).</para> - </example> - - <para>In some cases you may need to combine some of these.</para> - - <para>Consider the situation where a user has submitted a PR - containing code from the NetBSD project. You are looking at the - PR, but it is not an area of the tree you normally work in, so - you have decided to get the change reviewed by the - <literal>arch</literal> mailing list. Since the change is - complex, you opt to <acronym>MFC</acronym> after one month to - allow adequate testing.</para> - - <para>The extra information to include in the commit would look - something like</para> - - <programlisting>PR: foo/54321 -Submitted by: John Smith <John.Smith@example.com> -Reviewed by: -arch -Obtained from: NetBSD -MFC after: 1 month</programlisting> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I access <hostid - role="fqdn">people.FreeBSD.org</hostid> to put up personal - or project information?</para> - </question> - - <answer> - <para><hostid role="fqdn">people.FreeBSD.org</hostid> is the - same as <hostid - role="fqdn">freefall.FreeBSD.org</hostid>. Just create a - <filename>public_html</filename> directory. Anything you - place in that directory will automatically be visible - under <ulink url="http://people.FreeBSD.org/"></ulink>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Where are the mailing list archives stored?</para> - </question> - - <answer> - <para>The mailing lists are archived under <filename>/g/mail</filename> - which will show up as <filename>/hub/g/mail</filename> with &man.pwd.1;. - This location is accessible from any machine on the FreeBSD cluster.</para> - </answer> - </qandaentry> - </qandaset> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/console-server/Makefile b/en_US.ISO8859-1/articles/console-server/Makefile deleted file mode 100644 index fcb305cc9c..0000000000 --- a/en_US.ISO8859-1/articles/console-server/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Console Server - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml -IMAGES_EN= tk0231-9-1.png - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/console-server/article.sgml b/en_US.ISO8859-1/articles/console-server/article.sgml deleted file mode 100644 index a3faa6f3c0..0000000000 --- a/en_US.ISO8859-1/articles/console-server/article.sgml +++ /dev/null @@ -1,1475 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Console Server</title> - - <author> - <firstname>Gregory</firstname> - <surname>Bond</surname> - - <affiliation> - <address><email>gnb@itga.com.au</email></address> - </affiliation> - </author> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.cisco; - &tm-attrib.intel; - &tm-attrib.lantronix; - &tm-attrib.microsoft; - &tm-attrib.opengroup; - &tm-attrib.sun; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This document describes how you can use &os; - to set up a <quote>console server</quote>. A console server is - a machine that you can use to monitor the consoles of many other - machines, instead of a bunch of serial terminals.</para> - </abstract> - </articleinfo> - - <indexterm><primary>console-server</primary></indexterm> - - <sect1 id="problem"> - <title>The Problem</title> - - <para>You have a computer room with lots of &unix; server machines and lots - of communications hardware. Each of these machines needs a serial - console. But serial terminals are hard to find and quite expensive - (especially compared to a much more capable PC). And they take up a lot - of precious space in the computer room.</para> - - <para>You need access to the console because when things break, that is - where error messages go. And some tasks have to be done on the console - (e.g. boot problems or OS installs/upgrades). Some &unix; systems allow - the console to break out to the ROM monitor which can sometimes be the - only way to unstick a hung machine. This is often done with a - <literal>LINE BREAK</literal> sent on the console serial port.</para> - - <para>If we are going to play about with consoles, then there are a couple - of other things that would be great:</para> - - <itemizedlist> - <listitem> - <para>Remote access. Even in the same office, it would be convenient - to access all the consoles from your desk without walking into the - computer room. But often the machines are off-site, perhaps even in - another country.</para> - </listitem> - - <listitem> - <para>Logging. If something has gone wrong, you would like to be able - to have a look at the previous console output to see what is up. - Ordinary console screens give you the last 25 lines. More would be - better.</para> - </listitem> - - <listitem> - <para>Network Independence. The solution needs to work even if the - network is down. After all, a failed network is when you need - consoles the most! Even better is network independence with remote - access.</para> - </listitem> - - <listitem> - <para>No single-point failure. A console system that crashes every - machine when it fails is no use. This is particularly tricky with - Sun &unix; hosts as they will interpret a powered-off terminal as a - <literal>BREAK</literal>, and drop back to the ROM monitor.</para> - </listitem> - - <listitem> - <para>Interface with a pager or some similar alerter device.</para> - </listitem> - - <listitem> - <para>Ability to power-cycle machines remotely.</para> - </listitem> - - <listitem> - <para>Not be <emphasis>too</emphasis> expensive. Free is even - better!</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="possible-solutions"> - <title>Possible Solutions</title> - - <para>If you use PC hardware for your servers, then a so-called <quote><acronym>KVM</acronym> - switch</quote> is one possible solution. A <acronym>KVM</acronym> switch allows the use of - a single keyboard, video screen and mouse for multiple boxes. This cuts - down on the space problem, but only works for PC hardware (not any - communications gear you might have), and is not accessible from outside - the computer room. Nor does it have much scroll-back or logging, and - you have to handle alerting some other way. The big downside is that it - will not work for serial-only devices, such as communications hardware. - This means that even with a room full of PC-based servers, you are - probably still going to need some sort of serial console - solution.</para> - - <note> - <para>Actually, Doug Schache has pointed out that you - <emphasis>can</emphasis> get <acronym>KVM</acronym> switches that also do serial consoles - or Sun compatible <acronym>KVM</acronym> switching as well as PCs, but they are - expensive. See <ulink url="http://www.avocent.com/">Avocent</ulink> - for example.)</para> - </note> - - <para>You might be tempted to do without a console terminal, but when - things go pear-shaped you <emphasis>really</emphasis> need to see what - is on the console. And you have to use the console to boot the machine - and do things like OS upgrades or installs.</para> - - <para>You might try having a single console terminal and switching from - server to server as needed, either with a serial switch or just by - patching it into the required machine. Serial switches are also hard to - come by and not cheap, and may cause problems with sending - <literal>BREAK</literal> when they switch. And (if your computer room - is anything like ours) you never seem to have the right combination of - patch leads to connect to the machine you need to, and even if the leads - are there you can never work out exactly which combination of - <literal>DTE/DCE</literal> - headshells goes with which lead goes with which hardware. So you spend - the first 10 minutes fooling around with breakout boxes and a box of - leads, all while the server is down and the users are screaming. Of - course this does not deal with the logging or remote access - requirements. And inevitably the console is not switched to the machine - you need so you lose all the console messages that might tell you what - is going on.</para> - - <para>One popular solution is to use terminal server hardware. Typically, - the serial ports are connected to the various machine consoles, and set - up for <quote>reverse telnet</quote> access. This means a user can - telnet to a given IP/port and be connected to the appropriate console. - This can be very cost-effective, as suitable old terminal servers can be - picked up fairly cheaply (assuming you do not have a couple lying - around). And it is of course network-accessible so suitable for remote - access. But it suffers from one major drawback: if the network is down, - then you have <emphasis>no</emphasis> access to any console, even if you - are standing right next to the machine. (This may be partially - alleviated by having a suitable terminal connected to one of the - terminal server ports and connecting from there, but the terminal server - software may not support that.) Also there is no logging or replay of - console messages. But with a bit of work, and the addition of some - software such as <application>conserver</application> - (described below), this can be made to work pretty well.</para> - - <para>A possibility suggested by Bron Gondwana is similar to the above - solution. If you use servers with multiple serial ports, you can - connect each spare serial port to the console port of the - <quote>next</quote> server, creating a ring of console connections (in - some sort of order). This can be made to work reasonably well with the - aid of the <application>conserver</application> - software, but can be a bit confusing otherwise (i.e. remembering which - port is connected to which console). And you are stuck if you need to - use serial ports for other things (such as modems) or you have machines - without spare ports.</para> - - <para>Or, if your budget exceeds your willingness to hack, you can - buy an off-the-shelf solution. These vary in price and - capability. See, for example, - <ulink url="http://www.lightwavecom.com/">Lightwave</ulink>, - <ulink url="http://www.perle.com/">Perle</ulink>, - <ulink url="http://www.avocent.com/">Avocent</ulink> or - <ulink url="http://www.blackbox.com/faxbacks/23000/23362.PDF">Black Box</ulink>. - These solutions can be quite expensive - typically $USD100 - $USD400 per - port.</para> - </sect1> - - <sect1 id="our-solution"> - <title>Our Solution</title> - - <para>In light of the above requirements, we chose a solution based on a - dedicated PC running &unix; with a multiport serial card, and some - software designed to handle serial consoles.</para> - - <para>It includes the following elements:</para> - - <itemizedlist> - <listitem> - <para>A surplus PC. We used a &pentium; 166, with a PCI bus, 2Gbyte - hard disk and 64Mb of RAM. This is a massive overkill for this - task, and P-100, 500Mb, 32Mb would be more than enough.</para> - </listitem> - - <listitem> - <para>A PC &unix; system. We used <ulink - url="&url.base;/index.html">&os; 4.3</ulink> as that is used for - other tasks within our office.</para> - </listitem> - - <listitem> - <para>A multi-port serial card. We chose the <ulink - url="http://www.stallion.com/html/products/easyio.html">&easyio; PCI</ulink> - 8-port card from <ulink url="http://www.stallion.com/">Stallion - Technologies</ulink>. This cost us about $AUD740, or under - $100/port, from <ulink url="http://www.ht.com.au/">Harris - Technologies</ulink> (which has lots of stuff but is by no means the - cheapest place in town - shop around and you might get it a lot - cheaper). This card has a big DB80 connector on the back, and a - cable plugs into that which has a block with 8 RJ-45 sockets on it. - (We chose the RJ-45 version as our entire cable plant is RJ-45. - This allows us to patch connections from the required box to the - console server without any special cables.) This is the only thing - we needed to buy to make this all happen.</para> - </listitem> - - <listitem> - <para>We build two servers, one for each computer room, with 8 ports - in one and 16 ports (via two &easyio; PCI cards) in the other. If we - needed more than 16 ports, then another of the Stallion cards would - be more cost-effective. We could conceivably support 128 ports in - each server (with 2 EasyConnect 8/64 host cards and 8 16 port RJ-45 - modules) for about $AUD12,000.</para> - </listitem> - - <listitem> - <para>A modem for remote access to the console server host when the - network is down. We have not done this yet as the computer room is - next door, but when we put a server in Sydney we will add the modem. - The idea is that when the network is down, you can dial up and log - into the server machine and run the console program locally. For - security, we will probably leave the modem powered off and ask the - gopher in Sydney to turn on the well-labelled button when we need - it.</para> - </listitem> - - <listitem> - <para>A program called <ulink - url="http://www.conserver.com/">conserver</ulink>. This program - does all the magic required to enable remote access to consoles, and - do the replaying and logging etc. It comes in two parts: a server - called <application>conserver</application> that runs as a daemon - and connects to the serial ports, handles logging etc, and a client - program called <application>console</application> that can connect - to the server, display console messages, send keystrokes (and - <literal>BREAK</literal>), etc.</para> - </listitem> - </itemizedlist> - - <para>This design covers all the major requirements except remote power - cycling:</para> - - <itemizedlist> - <listitem> - <para>Remote access comes because the - <application>console</application> client program works across the - network.</para> - </listitem> - - <listitem> - <para>Logging is handled by the <application>conserver</application> - program.</para> - </listitem> - - <listitem> - <para>If the network is down, then we can use the console on the PC to - run the <application>console</application> client locally. For - remote sites, we can add a modem for dial-in access to the the - server command line to run the client.</para> - </listitem> - - <listitem> - <para>By patching the &solaris; servers (see <xref linkend="solaris">), - we can avoid pranging the whole computer room when the console - server PC crashes (or the power supply fails, or whatever).</para> - </listitem> - - <listitem> - <para>We already have pager alerts from another system we have - installed, but the console server has all the required log info so - that could easily be implemented if we needed. And it even has a - modem for calling the pager company!</para> - </listitem> - - <listitem> - <para>We do not currently support remote power cycling. Some versions - of the <application>conserver</application> program support this, but it does require - specialised serial-controlled power boards. We have no immediate - need for remote power cycling (we have a gopher in each remote - office who can do it by remote control) so this is not a major - problem, and we could add it easily should we ever see the need and - get the appropriate hardware.</para> - </listitem> - - <listitem> - <para>This solution was very cheap. Total cost for the 9-port server - was $AUD750 for the IO card, as we re-used a surplus PC and already - owned the hardware for the special cables. If we had to buy - everything, then it would still only cost around $AUD1500 for the - 8-port server.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="setting-up-server"> - <title>Setting Up The Server</title> - - <sect2 id="patching-stallion"> - <title>Checking the Stallion driver</title> - - <para>&os; has adequate support for modern Stallion cards since - 4.4 release. If you are running an older version of &os;, you - will need to upgrade to a more modern version of &os; (which - you should do anyway, to make sure your system is not - vulnerable to known security issues). See the <ulink - url="&url.books.handbook;/makeworld.html">&os; - Handbook</ulink> for information about updating your - system.</para> - - </sect2> - - <sect2 id="configuring-kernel"> - <title>Configuring a new kernel</title> - - <para>The Stallion driver is not included in the default - <literal>GENERIC</literal> kernel, so you will need to create a kernel - config file with the appropriate entries. See &man.stl.4; and the - appropriate section of the <ulink - url="&url.books.handbook;/kernelconfig.html">&os; - Handbook</ulink>.</para> - </sect2> - - <sect2 id="making-devices"> - <title>Making The Devices</title> - - <para>You will need to make the device notes for the Stallion card - (which are not made by default). A new version of - <filename>/dev/MAKEDEV</filename> with Stallion support will have been - created by the <application>mergemaster</application> run during the - above procedure. If you have a Stallion card with more than 8 ports, - then you will need to edit <filename>/dev/MAKEDEV</filename> and - change the definition of <literal>maxport</literal> at about line 250. - By default, <filename>MAKEDEV</filename> only makes device nodes for 8 - ports to keep the size of the <filename>/dev</filename> directory - down.</para> - - <para>Run a command like: - - <screen>&prompt.root; <userinput>cd /dev/ && sh MAKEDEV cuaE0</userinput></screen> - - to create dial-out devices for the first Stallion card. See the - comments in <filename>MAKEDEV</filename> and the &man.stl.4; man page - for more details.</para> - </sect2> - - <sect2 id="compiling-conserver"> - <title>Compiling conserver</title> - - <note> - <para>See the section on <application>conserver</application> versions - <xref linkend="conserver-versions">; the version I use is - available in the &os; ports collection; however, it is not the only - one.)</para> - </note> - - <para>There are two ways to install <application>conserver</application>. - You can either compile - from the source or use the &os; ports framework.</para> - - <sect3 id="using-ports"> - <title>Using the ports framework</title> - - <para>Using the ports is a bit cleaner, as the package system can then - keep track of installed software and cleanly delete them when not - being used. I recommend using the - <filename role="package">comms/conserver-com</filename> port. - Change into the - port directory and (as <username>root</username>) type:</para> - - <screen>&prompt.root; <userinput>make DEFAULTHOST=<replaceable>consolehost</replaceable> install</userinput></screen> - - <para>where <replaceable>consolehost</replaceable> is the name of the - machine running the console server. Specifying this when the binary - is compiled will avoid having to either specify it each time the - program is run on remote hosts or having to maintain a - <filename>conserver.cf</filename> file on every host. This command - will fetch, patch, configure, compile and install the - <application>conserver</application> application.</para> - - <para>You can then run <command>make package</command> to create a - binary package that can be installed on all the other &os; hosts - with &man.pkg.add.1;. For extra style points, you can make a two - versions of the package: one for the console server machine without - a <literal>DEFAULTHOST</literal> argument, and one for all the other - hosts with a <literal>DEFAULTHOST</literal> argument. This will - mean the console client program on the console server machine will - default to <hostid>localhost</hostid>, which will work in the - absence of name servers when the network is busted, and also allow - <quote>trusted</quote> (i.e. no password required) connections - via the localhost IP address for users logged into the console - server machine (either via the console screen or the emergency - backup modem). The version for the other machines with a - <literal>DEFAULTHOST</literal> argument means users can just use the - <application>console</application> client without specifying a - hostname every time, and without needing to configure the - <filename>conserver.cf</filename> file on every machine.</para> - </sect3> - - <sect3 id="from-tarball"> - <title>From the source tarball</title> - - <para>If you prefer, you can download <application>conserver</application> - and compile it yourself. - You might need to do this if you want to install the - console client on non-&os; systems. We run the client on our - &solaris; hosts and it inter-operates with the &os;-hosted server - with no problems. This allows anyone in the whole company (many of - whom have PCs and no &os; host access on their desk) to access - the console server.</para> - - <para>Download the file from the <ulink - url="ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz">conserver.com - FTP site</ulink>. Extract it into a handy directory then - configure it by running</para> - - <screen>&prompt.user; ./configure <option>--with-master=<replaceable>consoleserver</replaceable></option> <option>--with-port=<replaceable>782</replaceable></option></screen> - - <para>The <option>--with-master</option> argument avoids having to - specify the master server every time the client is run remotely (or - keeping up-to-date config files on all remote hosts). The - <option>--with-port</option> argument avoids having to update - <option>/etc/services</option> on every machine.</para> - - <para>Then type <command>make</command> and, as root, - <command>make install</command>.</para> - </sect3> - </sect2> - - <sect2 id="configuring-conserver"> - <title>Configuring conserver</title> - - <para>The <application>conserver</application> program is configured via a file called - <filename>conserver.cf</filename>. This file usually lives in - <filename>/usr/local/etc</filename> and is documented in the - &man.conserver.cf.5; manual page.</para> - - <para>Our config file looks like this:</para> - - <programlisting>LOGDIR=/var/log/consoles -gallows:/dev/cuaE0:9600p:&: -roo:/dev/cuaE1:9600p:&: -kanga:/dev/cuaE2:9600p:&: -%% -allow: itga.com.au -trusted: 127.0.0.1 buzz</programlisting> - - <para>The first line means all the console log files by default go into - the <filename>/var/log/consoles</filename> directory. The - <quote>&</quote> in each line says the log file for that machine - will be - <filename>/var/log/consoles/<replaceable>machine</replaceable></filename>.</para> - - <para>The next three lines show three machines to which we need to - connect. We use the - <devicename>cuaE<replaceable>x</replaceable></devicename> devices - rather than the - <devicename>ttyE<replaceable>x</replaceable></devicename> - devices because console ports typically do not show carrier. This - means that opening - <devicename>ttyE<replaceable>x</replaceable></devicename> would hang - and <application>conserver</application> would never connect. Using - the - <devicename>cuaE<replaceable>x</replaceable></devicename> - device avoids this problem. Another solution would be to use the - <devicename>ttyE<replaceable>x</replaceable></devicename> - devices and enable <quote>soft carrier</quote> on these ports, perhaps by - setting this using the - <devicename>ttyiE<replaceable>x</replaceable></devicename> - device in the <filename>/etc/rc.serial</filename> file. See the - comments in this file for more details. Also see &man.sio.4; - for information on the initial-state and locked-state devices. (The - Stallion driver also supports these conventions). And see the - &man.stty.1; for details on setting device modes.</para> - - <para>The last section shows that any user logged into the - server machine has passwordless access to all consoles. We do - this because there are no user accounts on this machine and it - is safely isolated from the wide world behind our firewall. - The allow line allows anyone on a machine inside our - organisation to access the console server if they provide - their password, which is recorded in the - <filename>conserver.passwd</filename> file (see next - section).</para> - </sect2> - - <sect2 id="setting-passwords"> - <title>Setting conserver passwords</title> - - <para>The <filename>conserver.passwd</filename> file contains the - encrypted version of the password that each user. The file is - documented in the <literal>conserver.cf(5)</literal> manual - page.</para> - - <para>The only tricky bit is loading the file with encoded passwords. - It appeared in &os; that was is no obvious way to generate an - encrypted password for inclusion in another file (but see below). So - I put together a quick hack perl script to do this:</para> - -<programlisting>@rands = (); -foreach (0..4) { - push(@rands, rand 64); -} - -$salt = join '', ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[@rands]; - -$salt = '$1$' . $salt . '$'; - -print 'Enter password: '; -`stty -echo`; -$cleartext = <>; -`stty echo`; -chop($cleartext); -print crypt($cleartext, $salt), "\n";</programlisting> - - <note> - <para>This uses the &os; <acronym>MD5</acronym>-style encrypted passwords. Running - this on other &unix; variants, or on &os; with DES passwords, will - likely need a different style of salt.</para> - </note> - - <para>&a.kris; has since pointed out you can get the same effect using - the <command>openssl passwd</command> command:</para> - - <screen>&prompt.user; openssl passwd -1 -Password: <userinput>password</userinput> -$1$VTd27V2G$eFu23iHpLvCBM5nQtNlKj/</screen> - </sect2> - - <sect2 id="starting-conserver"> - <title>Starting <application>conserver</application> at system boot time</title> - - <para>There are two ways this can be done. Firstly, you could start up - <application>conserver</application> from <application>init</application> - by including an entry in - <filename>/etc/ttys</filename> that is similar to this:</para> - - <programlisting>cuaE0 "/usr/local/sbin/conserver" unknown on insecure</programlisting> - - <para>This has two advantages: <application>init</application> will restart - the master console - server if it ever crashes for any reason (but we have not noticed any - crashes so far), and it arranges for standard output of the - <application>conserver</application> - process to be directed to the named tty (in this case - <devicename>cuaE0</devicename>). This is useful because you - can plug a terminal into this port, and the - <application>conserver</application> program - will show all console output not otherwise captured by a - client console connection. This is useful as a general - monitoring tool to see if anything is going on. We set this - terminal up in the computer room but visible from the main - office. It is a very handy feature. The downside of running - <application>conserver</application> - from the ttys file is that it cannot run in daemon - mode (else &man.init.8; would continually restart it). This means - <application>conserver</application> will not write a PID file, - which makes it hard to rotate the log files.</para> - - <para>So we start <application>conserver</application> from an rc.d script. - If you installed <application>conserver</application> via the port, - there will be a - <filename>conserver.sh.sample</filename> file installed in - <filename>/usr/local/etc/rc.d</filename>. Copy and/or rename this to - <filename>conserver.sh</filename> to enable <application>conserver</application> - to start at boot time.</para> - - <para>In fact we use a modified version of this script which also - connects <application>conserver</application> to a terminal via a tty device so we can monitor - unwatched console output. Our <filename>conserver.sh</filename> script looks like - this:</para> - - <programlisting>#!/bin/sh -# -# Startup for conserver -# - -PATH=/usr/bin:/usr/local/bin - -case "$1" in - 'start') - TTY=/dev/cuaE7 - conserver -d > $TTY - # get NL->CR+NL mapping so msgs look right - stty < /dev/cuaE7 opost onlcr - echo -n ' conserver' - ;; - - 'stop') - kill `cat /var/run/conserver.pid` && echo -n ' conserver' - ;; - - *) - echo "Usage: $0 { start | stop }" - ;; - -esac -exit 0</programlisting> - - <note> - <para>Note the use of <devicename>cuaE0</devicename> device - and the need to set tty modes for proper NL-<CR - handling).</para> - </note> - </sect2> - - <sect2 id="trimming-logs"> - <title>Keeping the log files trimmed</title> - - <para>&os; has a program called - <application>newsyslog</application> that will automatically - handle log file trimming. Just add some lines to the - configuration file <filename>/etc/newsyslog.conf</filename> - for the console logs:</para> - - <programlisting># -# The log files from conserver -/var/log/consoles/gallows 644 10 1000 * Z /var/run/conserver.pid -/var/log/consoles/kanga 644 10 1000 * Z /var/run/conserver.pid -/var/log/consoles/roo 644 10 1000 * Z /var/run/conserver.pid</programlisting> - - <para>This tells <application>newsyslog</application> (which is run from cron every hour on the - hour) that the console log files should be archived and compressed - once they reach 1Mb, that we should keep 10 of them, and that to - signal the server program you send a <literal>SIGHUP</literal> to the process whose PID - is in the <filename>conserver.pid</filename> file. This is the master server, and it will - arrange to signal all the child processes. Yes, this will send a <literal>HUP</literal> - to all clients whenever a single log file needs rotating, but that is - quite cheap. See &man.newsyslog.8; for details.</para> - </sect2> - </sect1> - - <sect1 id="cabling"> - <title>Cabling</title> - - <para>This is always the hardest part of this kind of problem. We had - only a dozen or so cables/headshells to build, and we already had a - collection of the appropriate crimping tools and hardware, so we did it - ourselves. But if you are not set up for this, or you have a large - number of cables to make, then you might consider getting some cables - custom made. Look in the yellow pages, there are a surprising number of - places that do this! Getting custom-made cabling is good, and you can - get much more professional results, but can be expensive. For example, - the RJ-45 to DB-25 adapter kits described below are about $10 each; - custom-made headshells are about twice that (and take a couple of weeks - to arrive). Similarly, crimping custom RJ-45 to RJ-45 leads is quite - cheap (say, $5 each) but it takes a fair amount of time. Custom made - RJ-45 socket to RJ-45 plug converters cost about $25 each.</para> - - <para>We have settled on RJ-45 Cat-V cabling for all our office and - computer room cabling needs. This included patching between racks in the - computer room. For serial connections, we use patchable headshells that - have RJ-45 sockets on the back. This allows us to patch whatever - RJ-45–DB-25 connections we need.</para> - - <para>Which is just as well, because there are many incompatible ways to - represent serial connections on the RJ-45 plug. So the cabling has to - be very careful to use the right mapping.</para> - - <sect2 id="rj45-colors"> - <title>RJ-45 colors</title> - - <para>RJ-45 cables and plugs have 8 pins/conductors. These are used as - 4 matched pairs. There are a couple of conventions about how the - pairs are mapped onto pins, but 100baseT uses the most common (known - as EIA 586B). There are three common color-coding conventions for the - individual conductors in RJ-45 cables. They are:</para> - - <table> - <title><!-- XXX: Add title for this table --></title> - <tgroup cols="5"> - <thead> - <row> - <entry>Pin</entry> - <entry>Scheme 1</entry> - <entry>Scheme 2 (EIA 568B)</entry> - <entry>Scheme 3 (EIA 568A)</entry> - <entry>Pair</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>Blue</entry> - <entry>White+Green</entry> - <entry>White+Orange</entry> - <entry>2+</entry> - </row> - - <row> - <entry>2</entry> - <entry>Orange</entry> - <entry>Green</entry> - <entry>Orange</entry> - <entry>2-</entry> - </row> - - <row> - <entry>3</entry> - <entry>Black</entry> - <entry>White+Orange</entry> - <entry>White+Green</entry> - <entry>3+</entry> - </row> - - <row> - <entry>4</entry> - <entry>Red</entry> - <entry>Blue</entry> - <entry>Blue</entry> - <entry>1+</entry> - </row> - - <row> - <entry>5</entry> - <entry>Green</entry> - <entry>White+Blue</entry> - <entry>White+Blue</entry> - <entry>1-</entry> - </row> - - <row> - <entry>6</entry> - <entry>Yellow</entry> - <entry>Orange</entry> - <entry>Green</entry> - <entry>3-</entry> - </row> - - <row> - <entry>7</entry> - <entry>Brown</entry> - <entry>White+Brown</entry> - <entry>White+Brown</entry> - <entry>4+</entry> - </row> - - <row> - <entry>8</entry> - <entry>White or Grey</entry> - <entry>Brown</entry> - <entry>Brown</entry> - <entry>4-</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Note EIA 468A and EIA 568B are very similar, simply swapping the - colors assigned to pair 2 and pair 3.</para> - - <para>See for example the <ulink - url="http://www.cabletron.com/support/techtips/tk0231-9.html">Cabletron - Tech Support Site</ulink> for more details.</para> - - <para>The pins in the RJ-45 plug are numbered from 1 to 8. Holding a - patch lead with the cable pointing down and the clip away from you, - pin 1 is at the left. Or, looking into an RJ-45 socket with the clip - to the top, pin 1 is on the right. The following illustration - (shamelessly lifted from the Cabletron web site above) shows it pretty - well:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="tk0231-9-1.png"> - </imageobject> - - <textobject> - <literallayout class="monospaced"><!-- XXX: add asci art --></literallayout> - </textobject> - - <textobject> - <phrase><!-- XXX: add RJ45 image description --></phrase> - </textobject> - </mediaobject> - - <para>We have four classes of equipment to deal with in our - setup:</para> - - <variablelist> - <varlistentry> - <term>Sun servers</term> - - <listitem> - <para>Sun servers operate as DTE (i.e. send data on TxD and read - RxD, and assert DTR) with a female DB-25 socket on board. So we - need to create a headshell for the Stallion that operates as DCE - and has a male DB-25 plug (i.e. acts as a <quote>null - modem</quote> cable as well as converts from RJ-45 to DB-25). - We use headshells that have an RJ-45 socket in them and 8 short - flyleads with DB-25 pins on the end. These pins can be inserted - into the DB-25 plug as required. This allows us to create a - custom RJ-45-DB-25 mapping. We used a couple of different - sorts, including the - <ulink url="http://www.molexpn.com.au/">MOD-TAP</ulink> - part no. <ulink - url="http://www.molexpn.com.au/products/index.nsx/1/7/0/0/id=340">06-9888-999-00</ulink> - and the <ulink - url="http://www.blackbox.com/faxbacks/12000/12654.PDF">FA730 - series</ulink> from - <ulink url="http://www.blackboxoz.com.au/">Black - Box</ulink>.</para> - - <para>On our version of the headshells, these flyleads had the - following colours (from Pin 1-8): Blue, Orange, Black, Red, - Green, Yellow, Brown, White. (Looking into an RJ-45 socket, - with the clip towards the top, pin 1 is on the right.) This is - how they are connected to the DB-25 socket:</para> - - <table> - <title><!-- XXX: Add a title here --></title> - <tgroup cols="5"> - <thead> - <row> - <entry>Stallion RJ-45 Pin</entry> - <entry>Colour</entry> - <entry>Signal</entry> - <entry>Sun DB-25 Male Pin</entry> - <entry>RS232 Signal</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>Blue</entry> - <entry>DCD</entry> - <entry>20</entry> - <entry>DTR</entry> - </row> - <row> - <entry>2</entry> - <entry>Orange</entry> - <entry>RTS</entry> - <entry>5</entry> - <entry>CTS</entry> - </row> - <row> - <entry>3</entry> - <entry>Black</entry> - <entry>Chassis Gnd</entry> - <entry>1</entry> - <entry>Chassis Gnd</entry> - </row> - <row> - <entry>4</entry> - <entry>Red</entry> - <entry>TxD</entry> - <entry>3</entry> - <entry>RxD</entry> - </row> - <row> - <entry>5</entry> - <entry>Green</entry> - <entry>RxD</entry> - <entry>2</entry> - <entry>TxD</entry> - </row> - <row> - <entry>6</entry> - <entry>Yellow</entry> - <entry>Signal Gnd</entry> - <entry>7</entry> - <entry>Signal Gnd</entry> - </row> - <row> - <entry>7</entry> - <entry>Brown</entry> - <entry>CTS</entry> - <entry>4</entry> - <entry>RTS</entry> - </row> - <row> - <entry>8</entry> - <entry>White</entry> - <entry>RTS</entry> - <entry>8</entry> - <entry>DCD</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Note that colours may be different for your - cables/headshells. In particular, pin 8 may be grey instead of - white.</para> - - <para>Remember to label the headshell - <emphasis>clearly</emphasis>, in a way that will not fade/fall - off/rub off with time!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Cisco 16xx/26xx/36xx Routers</term> - - <listitem> - <para>I think that all Cisco gear that has RJ-45 console ports and - runs &ios; will have the same cable requirements. But best to - check first. We have tried this on 1600s and 2600s only.</para> - - <para>Both the Stallion card and the 2600 have RJ-45 connections, - but of course they are not compatible. So you need to crimp up - a special RJ-45-RJ-45 cable. And this cable must be plugged in - the right way round! We use normal RJ-45 flyleads from the - router to the patch panel, then the special flylead from the - patch panel to the Stallion card.</para> - - <para>We built two special Stallion-Cisco leads by cutting in half - a 2m flylead and crimping an RJ-45 with the appropriate pinouts - to each free end. The original connector will be the Cisco end - of the cable, the new crimped connector will be the Stallion - end. Holding the RJ-45 connector on the flylead with the cable - pointing down and the clip pointing away, this is the order of - the colours of the cables in our flylead (pins 1-8, from L to - R): white/green, green, white/orange, blue, white/blue, orange, - white/brown, brown. For the Stallion end, trim and discard the - brown/white+brown and green/white+green pairs. Then holding the - RJ-45 plug in the same manner (cable down, clip away), the - connections should be (from L to R): None, None, Blue, Orange, - White/Orange, White/Blue, None, None, as shown:</para> - - <table> - <title><!-- XXX: add title for this table --></title> - - <tgroup cols="5"> - <thead> - <row> - <entry>Cisco RJ-45 Pin</entry> - <entry>Colour</entry> - <entry>Cisco Signal</entry> - <entry>Stallion RJ-45 Pin</entry> - <entry>Stallion Signal</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>White/Green</entry> - <entry>RTS</entry> - <entry>N/C</entry> - <entry> </entry> - </row> - - <row> - <entry>2</entry> - <entry>Green</entry> - <entry>DTR</entry> - <entry>N/C</entry> - <entry> </entry> - </row> - - <row> - <entry>3</entry> - <entry>White/Orange</entry> - <entry>TxD</entry> - <entry>5</entry> - <entry>RxD</entry> - </row> - - <row> - <entry>4</entry> - <entry>Blue</entry> - <entry>Gnd</entry> - <entry>3</entry> - <entry>Gnd</entry> - </row> - - <row> - <entry>5</entry> - <entry>White/Blue</entry> - <entry>Gnd</entry> - <entry>6</entry> - <entry>Gnd</entry> - </row> - - <row> - <entry>6</entry> - <entry>Orange</entry> - <entry>RxD</entry> - <entry>4</entry> - <entry>TxD</entry> - </row> - - <row> - <entry>7</entry> - <entry>White/Brown</entry> - <entry>DSR</entry> - <entry>N/C</entry> - <entry> </entry> - </row> - - <row> - <entry>8</entry> - <entry>Brown</entry> - <entry>CTS</entry> - <entry>N/C</entry> - <entry> </entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Note again that colours may be different for your - cables/headshells.</para> - - <para>Carefully label the cable, and each end of the cable, and - test it. If it does not work, testing is - <emphasis>really</emphasis> hard as they do not make RJ-45 - serial line testers!</para> - - <para>Let me state this more strongly: Be <emphasis>very</emphasis> - sure that you label this cable in a way that is easily, - instantly and permanently recognisable as a special cable and - not easily confused with normal drop cables. Some suggestions - (from Hugh Irvine):</para> - - <itemizedlist> - <listitem> - <para>Make them out of different coloured cable.</para> - </listitem> - - <listitem> - <para>For marking the ends, clear heat-shrink tubing slipped - over printed labels *before* putting on the connectors is - the best way I have seen for marking what they are.</para> - </listitem> - - <listitem> - <para>You can also use Panduit or similar tags that you put on - with nylon tie straps, but I find the ink wears off the - tags.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Cisco &catalyst; switches</term> - - <listitem> - <para>Astoundingly, the pinout on the console ports of the - &catalyst; switches is actually <emphasis>different</emphasis> to the - pinout used on the 26xx-series Cisco hardware. I think the way - to tell which is which is by considering the operating software. - If it uses &ios;, then the previous pinout is required. If it - uses the switch software, then this pinout is required.</para> - - <para>Fortunately, while the pinouts are different, the &catalyst; - pinout is simply a mirror image of the pinout for the 2600. - Even more fortunately, the Ciscos (both &catalyst; switches and 2600s) - seem to ship with a special <quote>rollover</quote> cable, which - is exactly what is required in this case. We use the rollover - cable from the &catalyst; switches to the patch panel, then the same cable - as above for the 2600s from the patch panel to the Stallion - card, and it all works just fine.</para> - - <para>This rollover cable is an RJ-45-RJ-45 cable and is intended - to be used with the shipped (hardwired) RJ-45 - DB-25 and - RJ-45–DB-9 headshells for console connections. Ours are - 2m long, either light blue or black, and are quite flat. - Attempts to use them for 100baseT Ethernet will fail miserably! - You can tell it is a rollover cable by holding both ends with - the cable pointing down and the clip pointing away from you. - Check the colour of the leads in each pin in the two connectors, - they should be mirror images. (In our case, one goes - grey-orange-black-red-green-yellow-blue-brown, the other - brown-blue-yellow-green-red-black-orange-grey). This is a - rollover cable.</para> - - <para>If you do not have a rollover cable present, then you can - use the same cable as for the 26xx except plug it in the other - way around (i.e. original 8-pin plug goes into the Stallion, the - new crimped plug with only 4 active wires goes into the - &catalyst; switch).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&os; servers (or any other &i386; PC systems using a serial - console)</term> - - <listitem> - <para>We run &os; 4 on a couple of &i386; PCs for various peripheral - uses. &os; usually uses a screen and keyboard for the - console, but can be configured to use a serial port (usually the - first serial port known as <devicename>COM1</devicename> in DOS/&windows; or - <devicename>ttyd0</devicename> in &unix;).</para> - - <para>The cabling for these servers depends on the PC harware. If - the PC has DB-25 female socket on board (as most older PCs do), - then the same headshell as works for the Sun server above will - work fine. If the PC has DB-9 male plug on board (as more - recent PCs tend to do), then there are two choices. Either use - a DB-9 to DB-25 converter (this is not recommended as it can - lead to unreliable connections over the long term as the adapter - is bumped/works loose), or build an RJ-45 to DB-9 cable as - follows:</para> - - <table> - <title><!-- XXX: add title for this table --></title> - - <tgroup cols="5"> - <thead> - <row> - <entry>Stallion RJ-45 Pin</entry> - <entry>Colour</entry> - <entry>Signal</entry> - <entry>PC DB-9 Female Pin</entry> - <entry>RS232 Signal</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>Blue</entry> - <entry>DCD</entry> - <entry>4</entry> - <entry>DTR</entry> - </row> - - <row> - <entry>2</entry> - <entry>Orange</entry> - <entry>RTS</entry> - <entry>8</entry> - <entry>CTS</entry> - </row> - - <row> - <entry>3</entry> - <entry>Black</entry> - <entry>Chassis Gnd</entry> - <entry>N/C</entry> - <entry> </entry> - </row> - - <row> - <entry>4</entry> - <entry>Red</entry> - <entry>TxD</entry> - <entry>2</entry> - <entry>RxD</entry> - </row> - - <row> - <entry>5</entry> - <entry>Green</entry> - <entry>RxD</entry> - <entry>3</entry> - <entry>TxD</entry> - </row> - - <row> - <entry>6</entry> - <entry>Yellow</entry> - <entry>Signal Gnd</entry> - <entry>5</entry> - <entry>Signal Gnd</entry> - </row> - - <row> - <entry>7</entry> - <entry>Brown</entry> - <entry>CTS</entry> - <entry>7</entry> - <entry>RTS</entry> - </row> - - <row> - <entry>8</entry> - <entry>White</entry> - <entry>RTS</entry> - <entry>1</entry> - <entry>DCD</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>See <xref linkend="freebsd"> for tips on configuring &os; - to use a serial console.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1 id="solaris"> - <title>On Sun Systems And Break</title> - - <para>Anyone who has turned off a terminal used as a console for a Sun - system will know what happens and why this is a problem. Sun hardware - recognises a serial <literal>BREAK</literal> as a command to halt the - OS and return to the ROM monitor prompt. A serial <literal>BREAK</literal> - is an out-of-band signal on an RS-232 serial port that involves making - the TX DATA line active (i.e. pulled down to less than -5v) for more than - two whole character times (or about 2ms on a 9600bps line). - Alas, this <literal>BREAK</literal> signal is all to - easily generated by serial hardware during power-on or power-off. And - the Stallion card does, in fact, generate breaks when the power to the - PC fails. Unless fixed, this problem would mean that every Sun box - connected to the console server would be halted whenever the power - failed (due to dead power supplies, or fat-fingered operators unplugging - it, or whatever). This is clearly not an acceptable situation.</para> - - <para>Fortunately, Sun have come up with a set of fixes for this. For - &solaris; 2.6 and later, the <command>kbd(1)</command> command can be used - to disable the <literal>ROM-on-BREAK</literal> behaviour. This is a good start, - but leaves you out of luck in the situation where a break is needed to get into a - broken machine.</para> - - <para>Starting with &solaris; 8, the <command>kbd</command> command can also - be used to enable an alternate break sequence using the - <command>kbd -a alternate</command> command. - When this is set, the key sequence - <keycap>Return</keycap><keycap>Tilde</keycap><keycombo><keycap>Ctrl</keycap><keycap>B</keycap></keycombo> - (within 5 seconds) will drop to the ROM. You can enable this - permanently by editing the <filename>/etc/default/kbd</filename> file; - see the <literal>kbd(1)</literal> man page. Note that this alternate - break sequence is only active once the kernel has started running - multiuser and processed the default file. While the ROM is active - (during power-on and during the boot process) and while running - single-user, you still need to use a <literal>BREAK</literal> to get to the ROM prompt. - The console client can cause the server to send a <literal>BREAK</literal> using the escape - sequence - <keycap>Esc</keycap><keycap>c</keycap><keycap>l</keycap><keycap>1</keycap>.</para> - - <para>If you have a Sun software support contract, there are patches - available for &solaris; 2.6 and 2.7 that add the <quote>alternate - break</quote> capability integrated into &solaris; 2.8. &solaris; 2.6 - requires patch 105924-10 or higher. &solaris; 2.7 requires patch 107589-02 - or higher.</para> - - <para>We have added this patch to all our &solaris; 2.6 servers, and added - it (and the entry in the /etc/default/kbd file) to our jumpstart - configuration so it will automatically be added to every new - install.</para> - - <para>We have confirmed by direct testing that neither the Cisco 16xx, - 26xx, or &catalyst; hardware suffers from the <literal>BREAK</literal> sent - when the Stallion card loses power. Contemporary Cisco software listens - for <literal>BREAK</literal> signal only for first 30 seconds after - power-on or reboot.</para> - </sect1> - - <sect1 id="freebsd"> - <title>Using a Serial Console on &os;</title> - - <para>The procedure for doing this is described in detail in the - <ulink url="&url.books.handbook;/serialconsole-setup.html">&os; - Handbook</ulink>. This is a quick summary.</para> - - <sect2 id="freebsd-kernconf"> - <title>Check the kernel configuration</title> - - <para>Check that the kernel configuration file has - <literal>flags 0x10</literal> in the config line for the - <devicename>sio0</devicename> device. This signals this device (known - as <devicename>COM1</devicename> in DOS/&windows; or - <devicename>/dev/ttyd0</devicename> in &os;) can be used as a - console. This flag is set on the <filename>GENERIC</filename> and - <filename>LINT</filename> sample configs, so is likely to be set in - your kernel.</para> - </sect2> - - <sect2 id="freebsd-bootconf"> - <title>Create the <filename>/boot.conf</filename> - file</title> - - <para>This file should be created containing a single line containing - just <quote><literal>-h</literal></quote> (minus the quotes). This - tells the &os; boot blocks to use the serial console.</para> - </sect2> - - <sect2 id="freebsd-ttys"> - <title>Edit <filename>/etc/ttys</filename></title> - - <para>Edit this file and make the following changes.</para> - - <para>If you are not going to have any keyboard/video screen on this - server at all, you should find all the lines for - <devicename>ttyv</devicename> devices like</para> - - <programlisting>ttyv1 "/usr/libexec/getty Pc" cons25 on secure</programlisting> - - <para>Change the <literal>on</literal> to <literal>off</literal>. This - will stop login screens being run on the useless video - consoles.</para> - - <para>Find the line containing <devicename>ttyd0</devicename>. Change - it from</para> - - <programlisting>ttyd0 "/usr/libexec/getty std.9600" dialup off secure</programlisting> - - <para>to</para> - - <programlisting>ttyd0 "/usr/libexec/getty std.9600" vt100 on secure</programlisting> - - <para>(replacing <literal>vt100</literal> with the term type of your - console. The <literal>xterms</literal> terminal type might be a good - choice). This allows you to log in to the console port once the - system is running multi-user.</para> - - <para>Reboot and off you go!</para> - </sect2> - </sect1> - - <sect1 id="security"> - <title>Security Implications</title> - - <para>The client-server protocol for <application>conserver</application> - requires the user of the <application>console</application> client to - enter a password. This password is passed across the net in - <emphasis>cleartext</emphasis>! This means - <application>conserver</application> is not really suitable for use - across untrusted networks (such as the Internet). Use of conserver-only - passwords (in the <filename>conserver.passwd</filename> file) slightly - mitigate this problem, but anyone sniffing a - <application>conserver</application> connection can - easily get console access, and from there prang your machine using the - console break sequence. For operating across the Internet, use - something secure like <application>SSH</application> to log into to the - server machine, and run the console client there.</para> - </sect1> - - <sect1 id="conserver-versions"> - <title>On Conserver Versions</title> - - <para>The <application>conserver</application> program has fractured into - a number of versions. The home page referenced below seems to be the - latest and most featureful version around, and for July 2004 carries a version number - of <quote>8.1.9</quote>. This is maintained by Bryan Stansell - <email>bryan@conserver.com</email>, who has brought together the work of - many people (listed on his webpage).</para> - - <para>The &os; ports collection contains a port for version 8.5 of - <application>conserver</application> at - <filename role="package">comms/conserver</filename>. - This seems to be older and less featureful than the 8.1.9 - version (in particular, it does not support consoles connected to - terminal server ports and does not support a - <filename>conserver.passwd</filename> file), and is written in a fairly - idiosyncratic manner (using a preprocessor to generate C code). Version - 8.5 is maintained by Kevin S. Braunsdorf - <email>ksb+conserver@sa.fedex.com</email> who did most of the original - work on <application>conserver</application>, - and whose work Bryan Stansell is building on. The - 8.5 version does support one feature not in the 8.1.9 version - (controlling power to remote machines via a specific serial-interfaced - power controller hardware).</para> - - <para>Beginning with December 2001, Brian's version (currently 8.1.9) is - also presented in ports collection at - <filename role="package">comms/conserver-com</filename>. We therefore - recommend you to use this version as it is much more appropriate for - console server building.</para> - - </sect1> - - <sect1 id="links"> - <title>Links</title> - - <variablelist> - <varlistentry> - <term><ulink url="http://www.conserver.com/"></ulink></term> - - <listitem> - <para>Homepage for the latest version of <application>conserver</application>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz">ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz</ulink></term> - - <listitem> - <para>The source tarball for version 8.1.9 of - <application>conserver</application>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.stallion.com/"></ulink></term> - - <listitem> - <para>Homepage of Stallion Technologies.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.conserver.com/consoles/msock.html"></ulink></term> - - <listitem> - <para>Davis Harris' <quote>Minor Scroll of Console Knowledge</quote> - contains a heap of useful information on serial consoles and - serial communications in general.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.conserver.com/consoles/"></ulink></term> - - <listitem> - <para>The <quote>Greater Scroll of Console Knowledge</quote> - contains even more specific information on connecting devices to - various other devices. Oh the joy of standards!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.eng.auburn.edu/users/doug/console.html"></ulink></term> - - <listitem> - <para>Doug Hughes has a similar console server, based on the - <application>screen</application> program and an old &sunos; host.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.realweasel.com/"></ulink></term> - - <listitem> - <para>The Real Weasel company makes a ISA or PCI video card that - looks like a PC video card but actually talks to a serial port. - This can be used to implement serial consoles on PC hardware for - operating systems that can not be forced to use serial console - ports early enough.</para> - </listitem> - </varlistentry> - - - </variablelist> - </sect1> - - <sect1 id="manpages"> - <title>Manual Pages</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.conserver.com/docs/console.man.html">console(8)</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.conserver.com/docs/conserver.man.html">conserver(8)</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.conserver.com/docs/conserver.cf.man.html">conserver.cf(5)</ulink></para> - </listitem> - </itemizedlist> - </sect1> - -</article> diff --git a/en_US.ISO8859-1/articles/contributing/Makefile b/en_US.ISO8859-1/articles/contributing/Makefile deleted file mode 100644 index 1f5b5eb47b..0000000000 --- a/en_US.ISO8859-1/articles/contributing/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Contributing to FreeBSD - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/contributing/article.sgml b/en_US.ISO8859-1/articles/contributing/article.sgml deleted file mode 100644 index a3af0f837e..0000000000 --- a/en_US.ISO8859-1/articles/contributing/article.sgml +++ /dev/null @@ -1,554 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -<!ENTITY % not.published "IGNORE"> -]> - -<article> - <articleinfo> - <title>Contributing to FreeBSD</title> - - <pubdate>$FreeBSD$</pubdate> - - <abstract> - <para>This article describes the different ways in which an - individual or organization may contribute to the FreeBSD - Project.</para> - </abstract> - - <authorgroup> - <author> - <firstname>Jordan</firstname> - <surname>Hubbard</surname> - <contrib>Contributed by </contrib> - </author> - </authorgroup> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.ieee; - &tm-attrib.general; - </legalnotice> - - </articleinfo> - - <indexterm><primary>contributing</primary></indexterm> - - <para>So you want to contribute to FreeBSD? That is great! FreeBSD - <emphasis>relies</emphasis> on the contributions of its user base - to survive. Your contributions are not only appreciated, they are - vital to FreeBSD's continued growth.</para> - - <para>Contrary to what some people might have you believe, you do - not need to be a hot-shot programmer or a close personal friend of - the FreeBSD core team to have your contributions accepted. A - large and growing number of international contributors, of greatly - varying ages and areas of technical expertise, develop FreeBSD. - There is always more work to be done than there are people - available to do it, and more help is always appreciated.</para> - - <para>The FreeBSD project is responsible for an entire operating - system environment, rather than just a kernel or a few scattered - utilities. As such, our <filename>TODO</filename> lists span a - very wide range of tasks: from documentation, beta testing and - presentation, to the system installer and highly specialized types - of kernel development. People of any skill level, in almost any - area, can almost certainly help the project.</para> - - <para>Commercial entities engaged in FreeBSD-related enterprises are - also encouraged to contact us. Do you need a special extension to - make your product work? You will find us receptive to your - requests, given that they are not too outlandish. Are you working - on a value-added product? Please let us know! We may be able to - work cooperatively on some aspect of it. The free software world - is challenging many existing assumptions about how software is - developed, sold, and maintained, and we urge you to at least give - it a second look.</para> - - <sect1 id="contrib-what"> - <title>What Is Needed</title> - - <para>The following list of tasks and sub-projects represents - something of an amalgam of various <filename>TODO</filename> - lists and user requests.</para> - - <sect2 id="non-programmer-tasks"> - <title>Ongoing Non-Programmer Tasks</title> - - <para>Many people who are involved in FreeBSD are not - programmers. The Project includes documentation writers, Web - designers, and support people. All that these people need to - contribute is an investment of time and a willingness to - learn.</para> - - <orderedlist> - <listitem> - <para>Read through the FAQ and Handbook periodically. If - anything is badly explained, out of date or even just - completely wrong, let us know. Even better, send us a fix - (SGML is not difficult to learn, but there is no objection - to ASCII submissions).</para> - </listitem> - - <listitem> - <para>Help translate FreeBSD documentation into your native - language. If documentation already exists for your - language, you can help translate additional documents or - verify that the translations are up-to-date. First take a - look at the <ulink - url="&url.books.fdp-primer;/translations.html">Translations - FAQ</ulink> in the FreeBSD Documentation Project Primer. - You are not committing yourself to translating every - single FreeBSD document by doing this — as a - volunteer, you can do as much or as little translation as - you desire. Once someone begins translating, others - almost always join the effort. If you only have the time - or energy to translate one part of the documentation, - please translate the installation instructions.</para> - </listitem> - - <listitem> - <para>Read the &a.questions; and &ng.misc; - occasionally (or even regularly). It can be very - satisfying to share your expertise and help people solve - their problems; sometimes you may even learn something new - yourself! These forums can also be a source of ideas for - things to work on.</para> - </listitem> - </orderedlist> - </sect2> - - <sect2 id="ongoing-programmer-tasks"> - <title>Ongoing Programmer Tasks</title> - <para>Most of the tasks listed here require either a considerable - investment of time, or an in-depth knowledge of the FreeBSD - kernel, or both. However, there are also many useful tasks - which are suitable for <quote>weekend hackers</quote>.</para> - - <orderedlist> - <listitem> - <para>If you run FreeBSD-CURRENT and have a good Internet - connection, there is a machine <hostid - role="fqdn">current.FreeBSD.org</hostid> which builds a - full release once a day—every now and again, try to - install the latest release from it and report any failures - in the process.</para> - </listitem> - - <listitem> - <para>Read the &a.bugs;. There might be a - problem you can comment constructively on or with patches - you can test. Or you could even try to fix one of the - problems yourself.</para> - </listitem> - - <listitem> - <para>If you know of any bug fixes which have been - successfully applied to -CURRENT but have not been merged - into -STABLE after a decent interval (normally a couple of - weeks), send the committer a polite reminder.</para> - </listitem> - - <listitem> - <para>Move contributed software to - <filename>src/contrib</filename> in the source - tree.</para> - </listitem> - - <listitem> - <para>Make sure code in <filename>src/contrib</filename> is - up to date.</para> - </listitem> - - <listitem> - <para>Build the source tree (or just part of it) with extra - warnings enabled and clean up the warnings.</para> - </listitem> - - <listitem> - <para>Fix warnings for ports which do deprecated things like - using <function>gets()</function> or including - <filename>malloc.h</filename>.</para> - </listitem> - - <listitem> - <para>If you have contributed any ports, send your patches - back to the original authors (this will make your life - easier when they bring out the next version).</para> - </listitem> - - <listitem> - <para>Get copies of formal standards like &posix;. You can - get some links about these standards at the <ulink - url="&url.base;/projects/c99/index.html">FreeBSD - C99 & POSIX Standards Conformance Project</ulink> web - site. Compare FreeBSD's behavior to that required by the - standard. If the behavior differs, particularly in subtle - or obscure corners of the specification, send in a PR - about it. If you are able, figure out how to fix it and - include a patch in the PR. If you think the standard is - wrong, ask the standards body to consider the - question.</para> - </listitem> - - <listitem> - <para>Suggest further tasks for this list!</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Work through the PR Database</title> - - <indexterm><primary>problem reports database</primary></indexterm> - - <para>The <ulink - url="&url.base;/cgi/query-pr-summary.cgi">FreeBSD - PR list</ulink> shows all the current active problem reports - and requests for enhancement that have been submitted by - FreeBSD users. The PR database includes both programmer and - non-programmer tasks. Look through the open PRs, and see if - anything there takes your interest. Some of these might be - very simple tasks that just need an extra pair of eyes to look - over them and confirm that the fix in the PR is a good one. - Others might be much more complex, or might not even have a - fix included at all.</para> - - <para>Start with the PRs that have not been assigned to anyone - else. If a PR is assigned to someone else, but it looks like - something you can handle, email the person it is assigned to - and ask if you can work on it—they might already have a - patch ready to be tested, or further ideas that you can - discuss with them.</para> - </sect2> - </sect1> - - <sect1 id="contrib-how"> - <title>How to Contribute</title> - - <para>Contributions to the system generally fall into one or more - of the following 5 categories:</para> - - <sect2 id="contrib-general"> - <title>Bug Reports and General Commentary</title> - - <para>An idea or suggestion of <emphasis>general</emphasis> - technical interest should be mailed to the &a.hackers;. - Likewise, people with an interest in such things (and a - tolerance for a <emphasis>high</emphasis> volume of mail!) may - subscribe to the &a.hackers;. - See <ulink - url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">The - FreeBSD Handbook</ulink> for more information about this and - other mailing lists.</para> - - <para>If you find a bug or are submitting a specific change, - please report it using the &man.send-pr.1; program or its - <ulink url="&url.base;/send-pr.html">WEB-based - equivalent</ulink>. Try to fill-in each field of the bug - report. Unless they exceed 65KB, include any patches directly - in the report. If the patch is suitable to be applied to the - source tree put <literal>[PATCH]</literal> in the synopsis of - the report. When including patches, <emphasis>do - not</emphasis> use cut-and-paste because cut-and-paste turns - tabs into spaces and makes them unusable. Consider - compressing patches and using &man.uuencode.1; if they exceed - 20KB.</para> - - <para>After filing a report, you should receive confirmation - along with a tracking number. Keep this tracking number so - that you can update us with details about the problem by - sending mail to <email>FreeBSD-gnats-submit@FreeBSD.org</email>. Use - the number as the message subject, e.g. <literal>"Re: - kern/3377"</literal>. Additional information for any bug - report should be submitted this way.</para> - - <para>If you do not receive confirmation in a timely fashion (3 - days to a week, depending on your email connection) or are, - for some reason, unable to use the &man.send-pr.1; command, - then you may ask someone to file it for you by sending mail to - the &a.bugs;.</para> - - <para>See also <ulink - url="&url.articles.problem-reports;/article.html">this - article</ulink> on how to write good problem reports.</para> - </sect2> - - <sect2> - <title>Changes to the Documentation</title> - - <indexterm><primary>documentation submissions</primary></indexterm> - - <para>Changes to the documentation are overseen by the &a.doc;. - Please look at the <ulink - url="&url.books.fdp-primer;/index.html">FreeBSD Documentation - Project Primer</ulink> for complete instructions. Send - submissions and changes (even small ones are welcome!) using - &man.send-pr.1; as described in <link - linkend="contrib-general">Bug Reports and General - Commentary</link>.</para> - </sect2> - - <sect2> - <title>Changes to Existing Source Code</title> - - <indexterm><primary>FreeBSD-CURRENT</primary></indexterm> - - <para>An addition or change to the existing source code is a - somewhat trickier affair and depends a lot on how far out of - date you are with the current state of FreeBSD - development. There is a special on-going release of FreeBSD - known as <quote>FreeBSD-CURRENT</quote> which is made - available in a variety of ways for the convenience of - developers working actively on the system. See <ulink url=" - &url.books.handbook;/current-stable.html">The FreeBSD - Handbook</ulink> for more information about getting and using - FreeBSD-CURRENT.</para> - - <para>Working from older sources unfortunately means that your - changes may sometimes be too obsolete or too divergent for - easy re-integration into FreeBSD. Chances of this can be - minimized somewhat by subscribing to the &a.announce; and the - &a.current; lists, where discussions on the current state of - the system take place.</para> - - <para>Assuming that you can manage to secure fairly up-to-date sources - to base your changes on, the next step is to produce a set of diffs to - send to the FreeBSD maintainers. This is done with the &man.diff.1; - command.</para> - - <para>The preferred &man.diff.1; format for submitting patches - is the unified output format generated by <command>diff - -u</command>. However, for patches that substantially change a - region of code, a context output format diff generated by - <command>diff -c</command> may be more readable and thus - preferable.</para> - - <indexterm> - <primary><command>diff</command></primary> - </indexterm> - - <para>For example:</para> - - <para> - <screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen> - - or - - <screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen> - - would generate such a set of context diffs for the given - source file or directory hierarchy.</para> - - <para>Likewise, - <screen>&prompt.user; <userinput>diff -u oldfile newfile</userinput></screen> - or - <screen>&prompt.user; <userinput>diff -u -r olddir newdir</userinput></screen> - - would do the same, except in the unified diff format.</para> - - <para>See the manual page for &man.diff.1; for more details.</para> - - <para>Once you have a set of diffs (which you may test with the - &man.patch.1; command), you should submit them for inclusion - with FreeBSD. Use the &man.send-pr.1; program as described in - <link linkend="contrib-general">Bug Reports and General - Commentary</link>. <emphasis>Do not</emphasis> just send the - diffs to the &a.hackers; or they will get lost! We greatly - appreciate your submission (this is a volunteer project!); - because we are busy, we may not be able to address it - immediately, but it will remain in the PR database until we - do. Indicate your submission by including - <literal>[PATCH]</literal> in the synopsis of the - report.</para> - - <indexterm> - <primary><command>uuencode</command></primary> - </indexterm> - - <para>If you feel it appropriate (e.g. you have added, deleted, - or renamed files), bundle your changes into a - <command>tar</command> file and run the &man.uuencode.1; - program on it. Archives created with &man.shar.1; are also welcome.</para> - - <para>If your change is of a potentially sensitive nature, - e.g. you are unsure of copyright issues governing its further - distribution or you are simply not ready to release it without - a tighter review first, then you should send it to &a.core; - directly rather than submitting it with &man.send-pr.1;. The - &a.core; reaches a much smaller group of people who - do much of the day-to-day work on FreeBSD. Note that this - group is also <emphasis>very busy</emphasis> and so you should - only send mail to them where it is truly necessary.</para> - - <para>Please refer to &man.intro.9; and &man.style.9; for - some information on coding style. We would appreciate it if - you were at least aware of this information before submitting - code.</para> - </sect2> - - <sect2> - <title>New Code or Major Value-Added Packages</title> - - <para>In the case of a significant contribution of a large body - work, or the addition of an important new feature to FreeBSD, - it becomes almost always necessary to either send changes as - uuencoded tar files or upload them to a web or FTP site for - other people to access. If you do not have access to a web or - FTP site, ask on an appropriate FreeBSD mailing list for - someone to host the changes for you.</para> - - <para>When working with large amounts of code, the touchy - subject of copyrights also invariably comes up. Acceptable - copyrights for code included in FreeBSD are:</para> - - <orderedlist> - <indexterm><primary>BSD copyright</primary></indexterm> - <listitem> - <para>The BSD copyright. This copyright is most preferred - due to its <quote>no strings attached</quote> nature and - general attractiveness to commercial enterprises. Far - from discouraging such commercial use, the FreeBSD Project - actively encourages such participation by commercial - interests who might eventually be inclined to invest - something of their own into FreeBSD.</para> - </listitem> - - <indexterm><primary>GPL</primary><see>GNU General Public License</see></indexterm> - <indexterm><primary>GNU General Public License</primary></indexterm> - <listitem> - <para>The GNU General Public License, or <quote>GPL</quote>. - This license is not quite as popular with us due to the - amount of extra effort demanded of anyone using the code - for commercial purposes, but given the sheer quantity of - GPL'd code we currently require (compiler, assembler, text - formatter, etc) it would be silly to refuse additional - contributions under this license. Code under the GPL also - goes into a different part of the tree, that being - <filename>/sys/gnu</filename> or - <filename>/usr/src/gnu</filename>, and is therefore easily - identifiable to anyone for whom the GPL presents a - problem.</para> - </listitem> - </orderedlist> - - <para>Contributions coming under any other type of copyright - must be carefully reviewed before their inclusion into FreeBSD - will be considered. Contributions for which particularly - restrictive commercial copyrights apply are generally - rejected, though the authors are always encouraged to make - such changes available through their own channels.</para> - - <para>To place a <quote>BSD-style</quote> copyright on your - work, include the following text at the very beginning of - every source code file you wish to protect, replacing the text - between the <literal>%%</literal> with the appropriate - information:</para> - - <programlisting>Copyright (c) %%proper_years_here%% - %%your_name_here%%, %%your_state%% %%your_zip%%. - All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer as - the first lines of this file unmodified. -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES -OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF -THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - $Id$</programlisting> - - <para>For your convenience, a copy of this text can be found in - <filename>/usr/share/examples/etc/bsd-style-copyright</filename>.</para> - </sect2> - - <sect2> - <title>Money, Hardware or Internet Access</title> - - <para>We are always very happy to accept donations to further - the cause of the FreeBSD Project and, in a volunteer effort - like ours, a little can go a long way! Donations of hardware - are also very important to expanding our list of supported - peripherals since we generally lack the funds to buy such - items ourselves.</para> - - <sect3> - <title><anchor id="donations">Donating Funds</title> - - <para>The FreeBSD Foundation is a non-profit, tax-exempt - foundation established to further the goals of the FreeBSD - Project. As a 501(c)3 entity, the Foundation is generally - exempt from US federal income tax as well as Colorado State - income tax. Donations to a tax-exempt entity are often - deductible from taxable federal income.</para> - - <para>Donations may be sent in check form to: - <address> - The FreeBSD Foundation - <street>7321 Brockway Dr.</street> - <city>Boulder</city>, <state>CO</state> <postcode>80303</postcode> - <country>USA</country> - </address> - </para> - - <para>The FreeBSD Foundation is now able to accept donations - through the web with PayPal. To place a donation, please - visit the Foundation <ulink - url="http://www.freebsdfoundation.org">web - site</ulink>.</para> - - <para>More information about the FreeBSD Foundation can be - found in <ulink - url="http://people.FreeBSD.org/~jdp/foundation/announcement.html">The - FreeBSD Foundation -- an Introduction</ulink>. To contact - the Foundation by email, write to - <email>bod@FreeBSDFoundation.org</email>.</para> - </sect3> - - <sect3> - <title>Donating Hardware</title> - <indexterm><primary>donations</primary></indexterm> - - <para>The FreeBSD Project happily accepts donations of - hardware that it can find good use for. If you are - interested in donating hardware, please contact the <ulink - url="&url.base;/donations/">Donations Liaison - Office</ulink>.</para> - </sect3> - - <sect3> - <title>Donating Internet Access</title> - - <para>We can always use new mirror sites for FTP, WWW or - <command>cvsup</command>. If you would like to be such a - mirror, please see the <ulink - url="&url.articles.hubs;/index.html">Mirroring FreeBSD</ulink> - article for more information.</para> - </sect3> - </sect2> - </sect1> - -</article> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO8859-1/articles/contributors/Makefile b/en_US.ISO8859-1/articles/contributors/Makefile deleted file mode 100644 index 23e6d0fff9..0000000000 --- a/en_US.ISO8859-1/articles/contributors/Makefile +++ /dev/null @@ -1,26 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Contributors to FreeBSD - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml -SRCS+= contrib.ent -SRCS+= contrib.386bsd.sgml -SRCS+= contrib.additional.sgml -SRCS+= contrib.committers.sgml -SRCS+= contrib.core.sgml -SRCS+= contrib.corealumni.sgml -SRCS+= contrib.develalumni.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/contributors/article.sgml b/en_US.ISO8859-1/articles/contributors/article.sgml deleted file mode 100644 index 969db3ffa4..0000000000 --- a/en_US.ISO8859-1/articles/contributors/article.sgml +++ /dev/null @@ -1,704 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -<!ENTITY % contrib.ent SYSTEM "contrib.ent"> -%contrib.ent; -<!ENTITY % not.published "IGNORE"> -]> - -<article> - <articleinfo> - <title>Contributors to FreeBSD</title> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.cvsup; - &tm-attrib.sun; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This article lists individuals and organizations who have - made a contribution to FreeBSD.</para> - </abstract> - </articleinfo> - - <sect1 id="donors"> - <title>Donors Gallery</title> - - <para>The FreeBSD Project is indebted to the following donors and would - like to publicly thank them here!</para> - - <itemizedlist> - <listitem> - <para><emphasis>Contributors to the central server - project:</emphasis></para> - - <para>The following individuals and businesses made it possible for - the FreeBSD Project to build a new central server machine, which - has replaced <hostid role="fqdn">freefall.FreeBSD.org</hostid> at - one point, by donating the following items:</para> - - <itemizedlist> - <listitem> - <para>&a.mbarkah; and his employer, <ulink - url="http://www.hemi.com/"> Hemisphere Online</ulink>, - donated a <emphasis>Pentium Pro (P6) 200MHz CPU</emphasis> - </para> - </listitem> - - <listitem> - <para><ulink url="http://www.asacomputers.com/">ASA - Computers</ulink> donated a <emphasis>Tyan 1662 - motherboard</emphasis>.</para> - </listitem> - - <listitem> - <para>Joe McGuckin <email>joe@via.net</email> of <ulink - url="http://www.via.net/">ViaNet Communications</ulink> donated - a <emphasis>Kingston ethernet controller.</emphasis></para> - </listitem> - - <listitem> - <para>Jack O'Neill <email>jack@diamond.xtalwind.net</email> - donated an <emphasis>NCR 53C875 SCSI controller - card</emphasis>.</para> - </listitem> - - <listitem> - <para>Ulf Zimmermann <email>ulf@Alameda.net</email> of <ulink - url="http://www.Alameda.net/">Alameda Networks</ulink> donated - <emphasis>128MB of memory</emphasis>, a <emphasis>4 Gb disk - drive and the case.</emphasis></para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Direct funding:</emphasis></para> - - <para>The following individuals and businesses have generously - contributed direct funding to the project:</para> - - <itemizedlist> - <listitem> - <para>Annelise Anderson - <email>ANDRSN@HOOVER.STANFORD.EDU</email></para> - </listitem> - - <listitem> - <para>&a.dillon;</para> - </listitem> - - <listitem> - <para><ulink url="http://www.bluemountain.com/">Blue Mountain - Arts</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.epilogue.com/">Epilogue Technology - Corporation</ulink></para> - </listitem> - - <listitem> - <para>&a.sef;</para> - </listitem> - - <listitem> - <para><ulink url="http://www.gta.com/">Global Technology - Associates, Inc</ulink></para> - </listitem> - - <listitem> - <para>Don Scott Wilde</para> - </listitem> - - <listitem> - <para>Gianmarco Giovannelli - <email>gmarco@masternet.it</email></para> - </listitem> - - <listitem> - <para>Josef C. Grosch <email>joeg@truenorth.org</email></para> - </listitem> - - <listitem> - <para>Robert T. Morris</para> - </listitem> - - <listitem> - <para>&a.chuckr;</para> - </listitem> - - <listitem> - <para>Kenneth P. Stox <email>ken@stox.sa.enteract.com</email> of - <ulink url="http://www.imagescape.com/">Imaginary Landscape, - LLC.</ulink></para> - </listitem> - - <listitem> - <para>Dmitry S. Kohmanyuk <email>dk@dog.farm.org</email></para> - </listitem> - - <listitem> - <para><ulink url="http://www.cdrom.co.jp/">Laser5</ulink> of Japan - (a portion of the profits from sales of their various FreeBSD - CDROMs).</para> - </listitem> - - <listitem> - <para><ulink url="http://www.mmjp.or.jp/fuki/">Fuki Shuppan - Publishing Co.</ulink> donated a portion of their profits from - <emphasis>Hajimete no FreeBSD</emphasis> (FreeBSD, Getting - started) to the FreeBSD and XFree86 projects.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.ascii.co.jp/">ASCII Corp.</ulink> - donated a portion of their profits from several FreeBSD-related - books to the FreeBSD project.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.yokogawa.co.jp/">Yokogawa Electric - Corp</ulink> has generously donated significant funding to the - FreeBSD project.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.buffnet.net/">BuffNET</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.pacificsolutions.com/">Pacific - Solutions</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.siemens.de/">Siemens AG</ulink> - via Andre Albsmeier - <email>andre.albsmeier@mchp.siemens.de</email></para> - </listitem> - - <listitem> - <para>Chris Silva <email>ras@interaccess.com</email></para> - </listitem> - - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Hardware contributors:</emphasis></para> - - <para>The following individuals and businesses have generously - contributed hardware for testing and device driver - development/support:</para> - - <itemizedlist> - <listitem> - <para>BSDi for providing the Pentium P5-90 and - 486/DX2-66 EISA/VL systems that are being used for our - development work, to say nothing of the network access and other - donations of hardware resources.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.compaq.com">Compaq</ulink> - has donated a variety of Alpha systems to the FreeBSD - Project. Among the many generous donations are 4 - AlphaStation DS10s, an AlphaServer DS20, - AlphaServer 2100s, an AlphaServer 4100, 8 500Mhz - Personal Workstations, 4 433Mhz Personal Workstations, - and more! These machines are used for release - engineering, package building, SMP development, and general - development on the Alpha architecture.</para> - </listitem> - - <listitem> - <para>TRW Financial Systems, Inc. provided 130 PCs, three 68 GB - file servers, twelve Ethernets, two routers and an ATM switch for - debugging the diskless code.</para> - </listitem> - - <listitem> - <para>Dermot McDonnell donated the Toshiba XM3401B CDROM drive - currently used in freefall.</para> - </listitem> - - <listitem> - <para>Chuck Robey <email>chuckr@glue.umd.edu</email> contributed - his floppy tape streamer for experimental work.</para> - </listitem> - - <listitem> - <para>Larry Altneu <email>larry@ALR.COM</email>, and &a.wilko;, - provided Wangtek and Archive QIC-02 tape drives in order to - improve the <devicename>wt</devicename> driver.</para> - </listitem> - - <listitem> - <para>Ernst Winter <email>ewinter@lobo.muc.de</email> contributed - a 2.88 MB floppy drive to the project. This will hopefully - increase the pressure for rewriting the floppy disk driver. - </para> - </listitem> - - <listitem> - <para><ulink url="http://www.tekram.com/">Tekram - Technologies</ulink> sent one each of their DC-390, DC-390U - and DC-390F FAST and ULTRA SCSI host adapter cards for - regression testing of the NCR and AMD drivers with their cards. - They are also to be applauded for making driver sources for free - operating systems available from their FTP server <ulink - url="ftp://ftp.tekram.com/scsi/FreeBSD/"></ulink>.</para> - </listitem> - - <listitem> - <para>Larry M. Augustin contributed not only a - Symbios Sym8751S SCSI card, but also a set of data books, - including one about the forthcoming Sym53c895 chip with Ultra-2 - and LVD support, and the latest programming manual with - information on how to safely use the advanced features of the - latest Symbios SCSI chips. Thanks a lot!</para> - </listitem> - - <listitem> - <para>Christoph Kukulies <email>kuku@FreeBSD.org</email> donated - an FX120 12 speed Mitsumi CDROM drive for IDE CDROM driver - development.</para> - </listitem> - - <listitem> - <para>Mike Tancsa <email>mike@sentex.ca</email> donated four various - ATM PCI cards in order to help increase support of these cards as - well as help support the development effort of the netatm ATM - stack. - </para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Special contributors:</emphasis></para> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.osd.bsdi.com/">BSDi</ulink> (formerly Walnut Creek CDROM) - has donated almost more than we can say (see the 'About the FreeBSD Project' - section of the <ulink url="&url.books.handbook;/index.html">FreeBSD Handbook</ulink> for more details). - In particular, we would like to thank them for the original - hardware used for <hostid - role="fqdn">freefall.FreeBSD.org</hostid>, our primary - development machine, and for <hostid - role="fqdn">thud.FreeBSD.org</hostid>, a testing and build - box. We are also indebted to them for funding various - contributors over the years and providing us with unrestricted - use of their T1 connection to the Internet.</para> - </listitem> - - <listitem> - <para>The <ulink url="http://www.interface-business.de/">interface - business GmbH, Dresden</ulink> has been patiently supporting - &a.joerg; who has often preferred FreeBSD work over paid work, and - used to fall back to their (quite expensive) EUnet Internet - connection whenever his private connection became too slow or - flaky to work with it...</para> - </listitem> - - <listitem> - <para><ulink url="http://www.bsdi.com/">Berkeley Software Design, - Inc.</ulink> has contributed their DOS emulator code to the - remaining BSD world, which is used in the - <emphasis>doscmd</emphasis> command.</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </sect1> - -<!--- XXX top level "staff" group vs additional contributors - <title>FreeBSD Project Staff</title> - - <para>The FreeBSD Project is managed and operated by the following groups of - people:</para> ---> - - <sect1 id="staff-core"> - <title>The FreeBSD Core Team</title> - - <para>The FreeBSD core team constitutes the project's <quote>Board of - Directors</quote>, responsible for deciding the project's overall goals - and direction as well as managing <link linkend="staff-who">specific - areas</link> of the FreeBSD project landscape.</para> - - <para>(in alphabetical order by last name):</para> - - &contrib.core; - </sect1> - -<!-- The following is the staff listing. --> - - <sect1 id="staff-listing"> - <title>Other &os; Teams</title> - - <para>The &os; project delegates certain individuals to work - on various teams according to project needs. The following - list contains the current information on those individuals and - their designated areas:</para> - - &contrib.staff; - </sect1> - -<!-- - This list is sorted by last name, not by entity or tenure. ---> - - <sect1 id="staff-committers"> - <title>The FreeBSD Developers</title> - - <para>These are the people who have commit privileges and do the - engineering work on the FreeBSD source tree. All core team members are - also developers.</para> - - <para>(in alphabetical order by last name):</para> - - &contrib.committers; - </sect1> - - <sect1 id="staff-doc"> - <title>The FreeBSD Documentation Project</title> - - <para>The <ulink url="&url.base;/docproj/index.html">FreeBSD - Documentation Project</ulink> is responsible for a number of different - services, each service being run by an individual and his - <emphasis>deputies</emphasis> (if any):</para> - - <variablelist> - <varlistentry> - <term>Documentation Project Architect</term> - - <listitem> - <para>&a.doceng;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Handbook Editor</term> - - <listitem> - <para>&a.doc;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FAQ Editor</term> - - <listitem> - <para>&a.doc;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>News Editor</term> - - <listitem> - <para>&a.www;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>In the Press Editor</term> - - <listitem> - <para>&a.jkoshy;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FreeBSD Really-Quick NewsLetter Editor</term> - - <listitem> - <para>Chris Coleman <email>chrisc@vmunix.com</email></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Gallery Editor</term> - - <listitem> - <para>&a.phantom;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Commercial Gallery Editor</term> - - <listitem> - <para>&a.josef;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>User Groups Editor</term> - - <listitem> - <para>&a.grog;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FreeBSD &java; Project</term> - - <listitem> - <para>&a.patrick;</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="staff-who"> - <title>Who is Responsible for What</title> - - <variablelist> - <varlistentry> - <term><ulink - url="&url.base;/docproj/index.html">Documentation - Project Manager</ulink></term> - - <listitem> - <para>&a.doceng;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>CVSup Mirror Site Coordinator</term> - - <listitem> - <para>&a.cvsup-master;</para> - - <para>which includes:</para> - - <para>&a.kuriyama; (responsible),</para> - <para>&a.jdp; (advisor)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FTP/WWW Mirror Site Coordinator</term> - - <listitem> - <para>&a.mirror-admin;</para> - - <para>which includes:</para> - - <para>&a.kuriyama;,</para> - <para>&a.kensmith;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Localization</term> - - <listitem> - <para>&a.ache;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Postmaster</term> - - <listitem> - <para>&a.dhw;,</para> - <para>&a.jmb;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="&url.articles.releng;/index.html">Release - Coordination</ulink></term> - - <listitem> - <para>&a.re; headed by &a.murray;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Public Relations & Corporate Liaison</term> - - <listitem> - <para>Seat open</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="&url.base;/security/index.html">Security - Officers</ulink></term> - - <listitem> - <para>&a.security-officer; headed by &a.nectar;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="&url.base;/support.html#cvs">Source - Repository Managers</ulink></term> - - <listitem> - <para>Principal: &a.peter;</para> - - <para>Assistants: &a.markm;, &a.joe;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Website Management</term> - - <listitem> - <para>&a.www;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="&url.base;/ports/index.html">Ports - Manager</ulink></term> - - <listitem> - <para>&a.portmgr;</para> - - <para>which includes:</para> - - <para>&a.kris;,</para> - <para>&a.marcus;,</para> - <para>&a.will;,</para> - <para>&a.linimon;,</para> - <para>&a.eik;,</para> - <para>&a.krion;,</para> - <para>&a.erwin; (secretary)</para> - - </listitem> - </varlistentry> - - <varlistentry> - <term>Standards</term> - - <listitem> - <para>&a.wollman;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>XFree86 Project, Inc. Liaison</term> - - <listitem> - <para>&a.rich;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="&url.base;/support.html#gnats">GNATS - Administrators</ulink></term> - - <listitem> - <para>&a.ceri;</para> - <para>&a.keramida;</para> - <para>&a.linimon;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Bugmeisters</term> - - <listitem> - <para>&a.ceri;</para> - <para>&a.keramida;</para> - <para>&a.linimon;</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="&url.base;/donations/index.html">Donations Liaison Office</ulink></term> - - <listitem> - <para>&a.donations;</para> - - <para>which includes:</para> - - <para>&a.mwlucas</para> - <para>&a.nsayer</para> - <para>&a.obrien</para> - <para>&a.rwatson</para> - <para>&a.trhodes</para> - </listitem> - </varlistentry> - - </variablelist> - </sect1> - - <sect1 id="contrib-corealumni"> - <title>Core Team Alumni</title> - - <indexterm><primary>core team</primary></indexterm> - <para>The following people were members of the FreeBSD core team during - the periods indicated. We thank them for their past efforts in the - service of the FreeBSD project.</para> - - <para><emphasis>In rough chronological order:</emphasis></para> - - &contrib.corealumni; - </sect1> - - <sect1 id="contrib-develalumni"> - <title>Development Team Alumni</title> - - <indexterm><primary>development team</primary></indexterm> - <para>The following people were members of the FreeBSD development team - during the periods indicated. We thank them for their past efforts - in the service of the FreeBSD project.</para> - - <para><emphasis>In rough chronological order:</emphasis></para> - - &contrib.develalumni; - </sect1> - - <sect1 id="contrib-derived"> - <title>Derived Software Contributors</title> - - <para>This software was originally derived from William F. Jolitz's 386BSD - release 0.1, though almost none of the original 386BSD specific code - remains. This software has been essentially re-implemented from the - 4.4BSD-Lite release provided by the Computer Science Research Group - (CSRG) at the University of California, Berkeley and associated academic - contributors.</para> - - <para>There are also portions of NetBSD and OpenBSD that have been - integrated into FreeBSD as well, and we would therefore like to thank - all the contributors to NetBSD and OpenBSD for their work.</para> - </sect1> - - <sect1 id="contrib-additional"> - <title>Additional FreeBSD Contributors</title> - - <para>(in alphabetical order by first name):</para> - - &contrib.additional; - </sect1> - - <sect1 id="contrib-386bsd"> - <title>386BSD Patch Kit Patch Contributors</title> - - <para>(in alphabetical order by first name):</para> - - &contrib.386bsd; - </sect1> -</article> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO8859-1/articles/contributors/chapter.decl b/en_US.ISO8859-1/articles/contributors/chapter.decl deleted file mode 100644 index 3aac7b965b..0000000000 --- a/en_US.ISO8859-1/articles/contributors/chapter.decl +++ /dev/null @@ -1,2 +0,0 @@ -<!-- $FreeBSD$ --> -<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.386bsd.sgml b/en_US.ISO8859-1/articles/contributors/contrib.386bsd.sgml deleted file mode 100644 index 697f409a8c..0000000000 --- a/en_US.ISO8859-1/articles/contributors/contrib.386bsd.sgml +++ /dev/null @@ -1,488 +0,0 @@ -<!-- $FreeBSD$ --> - - <itemizedlist> - <listitem> - <para>Adam Glass - <email>glass@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Adrian Hall - <email>ahall@mirapoint.com</email></para> - </listitem> - - <listitem> - <para>Andrey A. Chernov - <email>ache@astral.msk.su</email></para> - </listitem> - - <listitem> - <para>Andrew Gerweck - <email>andy@gerweck.dynup.net</email></para> - </listitem> - - <listitem> - <para>Andrew Herbert - <email>andrew@werple.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Andrew Moore - <email>alm@netcom.com</email></para> - </listitem> - - <listitem> - <para>Andy Valencia <email>ajv@csd.mot.com</email> - <email>jtk@netcom.com</email></para> - </listitem> - - <listitem> - <para>Arne Henrik Juul - <email>arnej@Lise.Unit.NO</email></para> - </listitem> - - <listitem> - <para>Bakul Shah - <email>bvs@bitblocks.com</email></para> - </listitem> - - <listitem> - <para>Barry Irwin - <email>bvi@moria.org</email></para> - </listitem> - - <listitem> - <para>Barry Lustig - <email>barry@ictv.com</email></para> - </listitem> - - <listitem> - <para>Bob Wilcox - <email>bob@obiwan.uucp</email></para> - </listitem> - - <listitem> - <para>Branko Lankester</para> - </listitem> - - <listitem> - <para>Brett Lymn - <email>blymn@mulga.awadi.com.AU</email></para> - </listitem> - - <listitem> - <para>Charles Hannum - <email>mycroft@ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Chris G. Demetriou - <email>cgd@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Chris Torek - <email>torek@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Christoph Robitschko - <email>chmr@edvz.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Daniel Poirot - <email>poirot@aio.jsc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Dave Burgess - <email>burgess@hrd769.brooks.af.mil</email></para> - </listitem> - - <listitem> - <para>Dave Rivers - <email>rivers@ponds.uucp</email></para> - </listitem> - - <listitem> - <para>David Dawes - <email>dawes@physics.su.OZ.AU</email></para> - </listitem> - - <listitem> - <para>David Greenman - <email>dg@Root.COM</email></para> - </listitem> - - <listitem> - <para>Eric J. Haug - <email>ejh@slustl.slu.edu</email></para> - </listitem> - - <listitem> - <para>Felix Gaehtgens - <email>felix@escape.vsse.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Frank Maclachlan - <email>fpm@crash.cts.com</email></para> - </listitem> - - <listitem> - <para>Gary A. Browning - <email>gab10@griffcd.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Gary Howland - <email>gary@hotlava.com</email></para> - </listitem> - - <listitem> - <para>Geoff Rehmet - <email>csgr@alpha.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Goran Hammarback - <email>goran@astro.uu.se</email></para> - </listitem> - - <listitem> - <para>Guido van Rooij - <email>guido@gvr.org</email></para> - </listitem> - - <listitem> - <para>Guy Antony Halse - <email>guy@rucus.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Guy Harris - <email>guy@auspex.com</email></para> - </listitem> - - <listitem> - <para>Havard Eidnes - <email>Havard.Eidnes@runit.sintef.no</email></para> - </listitem> - - <listitem> - <para>Herb Peyerl - <email>hpeyerl@novatel.cuc.ab.ca</email></para> - </listitem> - - <listitem> - <para>Holger Veit - <email>Holger.Veit@gmd.de</email></para> - </listitem> - - <listitem> - <para>Ishii Masahiro, R. Kym Horsell</para> - </listitem> - - <listitem> - <para>J.T. Conklin - <email>jtc@cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jagane D Sundar - <email>jagane@netcom.com</email></para> - </listitem> - - <listitem> - <para>James Clark - <email>jjc@jclark.com</email></para> - </listitem> - - <listitem> - <para>James Jegers - <email>jimj@miller.cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>James W. Dolter</para> - </listitem> - - <listitem> - <para>James da Silva - <email>jds@cs.umd.edu</email> et al</para> - </listitem> - - <listitem> - <para>Jay Fenlason - <email>hack@datacube.com</email></para> - </listitem> - - <listitem> - <para>Jim Wilson - <email>wilson@moria.cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jörg Lohse - <email>lohse@tech7.informatik.uni-hamburg.de</email></para> - </listitem> - - <listitem> - <para>Jörg Wunsch - <email>joerg_wunsch@uriah.heep.sax.de</email></para> - </listitem> - - <listitem> - <para>John Dyson</para> - </listitem> - - <listitem> - <para>John Woods - <email>jfw@eddie.mit.edu</email></para> - </listitem> - - <listitem> - <para>Jordan K. Hubbard - <email>jkh@whisker.hubbard.ie</email></para> - </listitem> - - <listitem> - <para>Julian Elischer - <email>julian@dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Karl Dietz - <email>Karl.Dietz@triplan.com</email></para> - </listitem> - - <listitem> - <para>Karl Lehenbauer - <email>karl@NeoSoft.com</email> - <email>karl@one.neosoft.com</email></para> - </listitem> - - <listitem> - <para>Keith Bostic - <email>bostic@toe.CS.Berkeley.EDU</email></para> - </listitem> - - <listitem> - <para>Ken Hughes</para> - </listitem> - - <listitem> - <para>Kent Talarico - <email>kent@shipwreck.tsoft.net</email></para> - </listitem> - - <listitem> - <para>Kevin Lahey - <email>kml%rokkaku.UUCP@mathcs.emory.edu</email> - <email>kml@mosquito.cis.ufl.edu</email></para> - </listitem> - - <listitem> - <para>Konstantinos Konstantinidis - <email>kkonstan@duth.gr</email></para> - </listitem> - - <listitem> - <para>Marc Frajola - <email>marc@dev.com</email></para> - </listitem> - - <listitem> - <para>Mark Tinguely - <email>tinguely@plains.nodak.edu</email> - <email>tinguely@hookie.cs.ndsu.NoDak.edu</email></para> - </listitem> - - <listitem> - <para>Martin Renters - <email>martin@tdc.on.ca</email></para> - </listitem> - - <listitem> - <para>Michael Clay - <email>mclay@weareb.org</email></para> - </listitem> - - <listitem> - <para>Michael Galassi - <email>nerd@percival.rain.com</email></para> - </listitem> - - <listitem> - <para>Mike Durkin - <email>mdurkin@tsoft.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Naoki Hamada - <email>nao@tom-yam.or.jp</email></para> - </listitem> - - <listitem> - <para>Nate Williams - <email>nate@bsd.coe.montana.edu</email></para> - </listitem> - - <listitem> - <para>Nick Handel - <email>nhandel@NeoSoft.com</email> - <email>nick@madhouse.neosoft.com</email></para> - </listitem> - - <listitem> - <para>Pace Willisson - <email>pace@blitz.com</email></para> - </listitem> - - <listitem> - <para>Paul Kranenburg - <email>pk@cs.few.eur.nl</email></para> - </listitem> - - <listitem> - <para>Paul Mackerras - <email>paulus@cs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Paul Popelka - <email>paulp@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Peter da Silva - <email>peter@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>Phil Sutherland - <email>philsuth@mycroft.dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Poul-Henning Kamp - <email>phk@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Ralf Friedl - <email>friedl@informatik.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Rick Macklem - <email>root@snowhite.cis.uoguelph.ca</email></para> - </listitem> - - <listitem> - <para>Robert D. Thrush - <email>rd@phoenix.aii.com</email></para> - </listitem> - - <listitem> - <para>Rodney W. Grimes - <email>rgrimes@cdrom.com</email></para> - </listitem> - - <listitem> - <para>Sascha Wildner - <email>swildner@channelz.GUN.de</email></para> - </listitem> - - <listitem> - <para>Scott Burris - <email>scott@pita.cns.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Reynolds - <email>scott@clmqt.marquette.mi.us</email></para> - </listitem> - - <listitem> - <para>Seamus Venasse - <email>svenasse@polaris.ca</email></para> - </listitem> - - <listitem> - <para>Sean Eric Fagan - <email>sef@kithrup.com</email></para> - </listitem> - - <listitem> - <para>Sean McGovern - <email>sean@sfarc.net</email></para> - </listitem> - - <listitem> - <para>Simon J Gerraty <email>sjg@melb.bull.oz.au</email> - <email>sjg@zen.void.oz.au</email></para> - </listitem> - - <listitem> - <para>Stephen McKay - <email>syssgm@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Terry Lambert - <email>terry@icarus.weber.edu</email></para> - </listitem> - - <listitem> - <para>Terry Lee - <email>terry@uivlsi.csl.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>Tor Egge - <email>Tor.Egge@idi.ntnu.no</email></para> - </listitem> - - <listitem> - <para>Warren Toomey - <email>wkt@csadfa.cs.adfa.oz.au</email></para> - </listitem> - - <listitem> - <para>Wiljo Heinen - <email>wiljo@freeside.ki.open.de</email></para> - </listitem> - - <listitem> - <para>William Jolitz - <email>withheld</email></para> - </listitem> - - <listitem> - <para>Wolfgang Solfrank - <email>ws@tools.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Stanglmeier - <email>wolf@dentaro.GUN.de</email></para> - </listitem> - - <listitem> - <para>Yuval Yarom - <email>yval@cs.huji.ac.il</email></para> - </listitem> - </itemizedlist> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("article.sgml" "part" "sect1") - End: ---> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml b/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml deleted file mode 100644 index 05be567fe3..0000000000 --- a/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml +++ /dev/null @@ -1,7601 +0,0 @@ -<!-- $FreeBSD$ --> -<!-- - NOTE TO COMMITTERS: Contributors lists are sorted in alphabetical - order by first name. ---> - - <itemizedlist> - <listitem> - <para>ABURAYA Ryushirou - <email>rewsirow@ff.iij4u.or.jp</email></para> - </listitem> - - <listitem> - <para>AMAGAI Yoshiji - <email>amagai@nue.org</email></para> - </listitem> - - <listitem> - <para>Aaron Bornstein - <email>aaronb@j51.com</email></para> - </listitem> - - <listitem> - <para>Aaron Dalton - <email>aaron@daltons.ca</email></para> - </listitem> - - <listitem> - <para>Aaron Myles Landwehr - <email>aaron@snaphat.com</email></para> - </listitem> - - <listitem> - <para>Aaron Smith - <email>aaron@mutex.org</email></para> - </listitem> - - <listitem> - <para>Aaron Zauner - <email>az_mail@gmx.at</email></para> - </listitem> - - <listitem> - <para>Achim Patzner - <email>ap@noses.com</email></para> - </listitem> - - <listitem> - <para>Ada T Lim - <email>ada@bsd.org</email></para> - </listitem> - - <listitem> - <para>Adam Baran - <email>badam@mw.mil.pl</email></para> - </listitem> - - <listitem> - <para>Adam Glass - <email>glass@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Adam Herzog - <email>adam@herzogdesigns.com</email></para> - </listitem> - - <listitem> - <para>Adam Kranzel - <email>adam@alameda.edu</email></para> - </listitem> - - <listitem> - <para>Adam McDougall - <email>mcdouga9@egr.msu.edu</email></para> - </listitem> - - <listitem> - <para>Adam Strohl - <email>troll@digitalspark.net</email></para> - </listitem> - - <listitem> - <para>Adoal Xu - <email>adoal@iname.com</email></para> - </listitem> - - <listitem> - <para>Adrian Colley - <email>aecolley@ois.ie</email></para> - </listitem> - - <listitem> - <para>Adrian Hall - <email>ahall@mirapoint.com</email></para> - </listitem> - - <listitem> - <para>Adrian Mariano - <email>adrian@cam.cornell.edu</email></para> - </listitem> - - <listitem> - <para>Adrian Steinmann - <email>ast@marabu.ch</email></para> - </listitem> - - <listitem> - <para>Adrian T. Filipi-Martin - <email>atf3r@agate.cs.virginia.edu</email></para> - </listitem> - - <listitem> - <para>Ajit Thyagarajan - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Akira SAWADA - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Akira Watanabe - <email>akira@myaw.ei.meisei-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Akito Fujita - <email>fujita@zoo.ncl.omron.co.jp</email></para> - </listitem> - - <listitem> - <para>Alain Kalker - <email>A.C.P.M.Kalker@student.utwente.nl</email></para> - </listitem> - - <listitem> - <para>Alan Bawden - <email>alan@curry.epilogue.com</email></para> - </listitem> - - <listitem> - <para>Albert Graef - <email>Dr.Graef@t-online.de</email></para> - </listitem> - - <listitem> - <para>Alec Wolman - <email>wolman@cs.washington.edu</email></para> - </listitem> - - <listitem> - <para>Aled Morris - <email>aledm@routers.co.uk</email></para> - </listitem> - - <listitem> - <para>Aleksander Fafula - <email>alex@fafula.com</email></para> - </listitem> - - <listitem> - <para>Aleksandr A Babaylov - <email>.@babolo.ru</email></para> - </listitem> - - <listitem> - <para>Alex D. Chen - <email>dhchen@elearning.nsysu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Alex G. Bulushev - <email>bag@demos.su</email></para> - </listitem> - - <listitem> - <para>Alex Kapranoff - <email>kappa@zombie.antar.bryansk.ru</email></para> - </listitem> - - <listitem> - <para>Alex Kiesel - <email>kiesel@schlund.de</email></para> - </listitem> - - <listitem> - <para>Alex Le Heux - <email>alexlh@funk.org</email></para> - </listitem> - - <listitem> - <para>Alex Perel - <email>veers@disturbed.net</email></para> - </listitem> - - <listitem> - <para>Alex Rodioukov - <email>simuran@shaw.ca</email></para> - </listitem> - - <listitem> - <para>Alex Rousskov - <email>rousskov@measurement-factory.com</email></para> - </listitem> - - <listitem> - <para>Alex Semenyaka - <email>alex@rinet.ru</email></para> - </listitem> - - <listitem> - <para>Alex Trull - <email>alexander@trull.com</email></para> - </listitem> - - <listitem> - <para>Alex Varju - <email>varju@webct.com</email></para> - </listitem> - - <listitem> - <para>Alex Zepeda - <email>garbanzo@hooked.net</email></para> - </listitem> - - <listitem> - <para>Alexander B. Povolotsky - <email>tarkhil@mgt.msk.ru</email></para> - </listitem> - - <listitem> - <para>Alexander Gelfenbain - <email>mail@gelf.com</email></para> - </listitem> - - <listitem> - <para>Alexander Kovalenko - <email>never@nevermind.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Alexander Novitsky - <email>alecn2002@yandex.ru</email></para> - </listitem> - - <listitem> - <para>Alexander Timoshenko - <email>gonzo@univ.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Alexandre Peixoto - <email>alexandref@tcoip.com.br</email></para> - </listitem> - - <listitem> - <para>Alexandre Snarskii - <email>snar@paranoia.ru</email></para> - </listitem> - - <listitem> - <para>Alexey V. Antipovsky - <email>kemm@in-line.ru</email></para> - </listitem> - - <listitem> - <para>Alexey Y. Mikhailov - <email>karma@ez.pereslavl.ru</email></para> - </listitem> - - <listitem> - <para>Alexey V. Neyman - <email>alex.neyman@auriga.ru</email></para> - </listitem> - - <listitem> - <para>Alexey Zaytsev - <email>mangoost@inetcomm.ru</email></para> - </listitem> - - <listitem> - <para>Alexis Yushin - <email>alexis@forest.NLnetLabs.nl</email></para> - </listitem> - - <listitem> - <para>Alistair G. Crooks - <email>agc@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Allan Bowhill - <email>bowhill@bowhill.vservers.com</email></para> - </listitem> - - <listitem> - <para>Allan Saddi - <email>asaddi@philosophysw.com</email></para> - </listitem> - - <listitem> - <para>Allen Campbell - <email>allenc@verinet.com</email></para> - </listitem> - - <listitem> - <para>Amakawa Shuhei - <email>amakawa@hoh.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Amar Takhar - <email>verm@drunkmonk.net</email></para> - </listitem> - - <listitem> - <para>Amir Farah - <email>amir@comtrol.com</email></para> - </listitem> - - <listitem> - <para>Amir Shalem - <email>amir@boom.org.il</email></para> - </listitem> - - <listitem> - <para>Amy Baron - <email>amee@beer.org</email></para> - </listitem> - - <listitem> - <para>Anatoliy Dmytriyev - <email>tolid@plab.ku.dk</email></para> - </listitem> - - <listitem> - <para>Anatoly A. Orehovsky - <email>tolik@mpeks.tomsk.su</email></para> - </listitem> - - <listitem> - <para>Anatoly Vorobey - <email>mellon@pobox.com</email></para> - </listitem> - - <listitem> - <para>Anders Andersson - <email>anders@codefactory.se</email></para> - </listitem> - - <listitem> - <para>Anders Thulin - <email>Anders.X.Thulin@telia.se</email></para> - </listitem> - - <listitem> - <para>Anderson S. Ferreira - <email>anderson@cnpm.embrapa.br</email></para> - </listitem> - - <listitem> - <para>Andi Payn - <email>andi_payn@speedymail.org</email></para> - </listitem> - - <listitem> - <para>Andre Albsmeier - <email>Andre.Albsmeier@mchp.siemens.de</email></para> - </listitem> - - <listitem> - <para>Andre Goeree - <email>abgoeree@uwnet.nl</email></para> - </listitem> - - <listitem> - <para>Andrea Venturoli - <email>a.ventu@flashnet.it</email></para> - </listitem> - - <listitem> - <para>Andreas Berg - <email>aberg@doomnet.de</email></para> - </listitem> - - <listitem> - <para>Andreas Fehlner - <email>fehlner@gmx.de</email></para> - </listitem> - - <listitem> - <para>Andreas Haakh - <email>ah@alman.robin.de</email></para> - </listitem> - - <listitem> - <para>Andreas Heil - <email>ah@linux-hq.de</email></para> - </listitem> - - <listitem> - <para>Andreas Kohout - <email>shanee@rabbit.augusta.de</email></para> - </listitem> - - <listitem> - <para>Andreas Lohr - <email>andreas@marvin.RoBIN.de</email></para> - </listitem> - - <listitem> - <para>Andreas Wetzel - <email>mickey@deadline.snafu.de</email></para> - </listitem> - - <listitem> - <para>Andreas Wrede - <email>andreas@planix.com</email></para> - </listitem> - - <listitem> - <para>Andrei V. Shetuhin - <email>shetuhin@corp.mail.ru</email></para> - </listitem> - - <listitem> - <para>Andrej Zverev - <email>az@inec.ru</email></para> - </listitem> - - <listitem> - <para>Andres Vega Garcia - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Andrew Atrens - <email>atreand@statcan.ca</email></para> - </listitem> - - <listitem> - <para>Andrew Boothman - <email>andrew@cream.org</email></para> - </listitem> - - <listitem> - <para>Andrew Gillham - <email>gillham@andrews.edu</email></para> - </listitem> - - <listitem> - <para>Andrew Gordon - <email>andrew.gordon@net-tel.co.uk</email></para> - </listitem> - - <listitem> - <para>Andrew Herbert - <email>andrew@werple.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Andrew J. Caines - <email>A.J.Caines@halplant.com</email></para> - </listitem> - - <listitem> - <para>Andrew J. Korty - <email>ajk@purdue.edu</email></para> - </listitem> - - <listitem> - <para>Andrew L. Neporada - <email>andrew@chg.ru</email></para> - </listitem> - - <listitem> - <para>Andrew McNaughton - <email>andrew@scoop.co.nz</email></para> - </listitem> - - <listitem> - <para>Andrew McRae - <email>amcrae@cisco.com</email></para> - </listitem> - - <listitem> - <para>Andrew P. Lentvorski - <email>bsder@allcaps.org</email></para> - </listitem> - - <listitem> - <para>Andrew S. Midthune - <email>amidthune@cableone.net</email></para> - </listitem> - - <listitem> - <para>Andrew Shevtsov - <email>nyxo@dnuc.polyn.kiae.su</email></para> - </listitem> - - <listitem> - <para>Andrew Stevenson - <email>andrew@ugh.net.au</email></para> - </listitem> - - <listitem> - <para>Andrew Thompson - <email>andy@fud.org.nz</email></para> - </listitem> - - <listitem> - <para>Andrew Timonin - <email>tim@pool1.convey.ru</email></para> - </listitem> - - <listitem> - <para>Andrew V. Stesin - <email>stesin@elvisti.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Andrew Webster - <email>awebster@dataradio.com</email></para> - </listitem> - - <listitem> - <para>Andrey Novikov - <email>andrey@novikov.com</email></para> - </listitem> - - <listitem> - <para>Andrey Simonenko - <email>simon@comsys.ntu-kpi.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Andrey Slusar - <email>vasallia@ukr.net</email></para> - </listitem> - - <listitem> - <para>Andrey Sverdlichenko - <email>rblaze@users.sourceforge.net</email></para> - </listitem> - - <listitem> - <para>Andrey Tchoritch - <email>andy@venus.sympad.net</email></para> - </listitem> - - <listitem> - <para>Andy Farkas - <email>andyf@speednet.com.au</email></para> - </listitem> - - <listitem> - <para>Andy Gilligan - <email>andy@evo6.org</email></para> - </listitem> - - <listitem> - <para>Andy Miller - <email>andy@trit.org</email></para> - </listitem> - - <listitem> - <para>Andy Pavlo - <email>amp0928@rit.edu</email></para> - </listitem> - - <listitem> - <para>Andy Sparrow - <email>spadger@best.com</email></para> - </listitem> - - <listitem> - <para>Andy Valencia - <email>ajv@csd.mot.com</email></para> - </listitem> - - <listitem> - <para>Andy Whitcroft - <email>andy@sarc.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Angel Todorov - <email>todorov_bg@gmx.net</email></para> - </listitem> - - <listitem> - <para>Angelo Turetta - <email>ATuretta@stylo.it</email></para> - </listitem> - - <listitem> - <para>Anish Mistry - <email>amistry@am-productions.biz</email></para> - </listitem> - - <listitem> - <para>Anthony C. Chavez - <email>acc@anthonychavez.org</email></para> - </listitem> - - <listitem> - <para>Anthony Yee-Hang Chan - <email>yeehang@netcom.com</email></para> - </listitem> - - <listitem> - <para>Antoine Beaupre - <email>anarcat@anarcat.ath.cx</email></para> - </listitem> - - <listitem> - <para>Anton N. Bruesov - <email>antonz@library.ntu-kpi.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Anton Voronin - <email>anton@urc.ac.ru</email></para> - </listitem> - - <listitem> - <para>Antonio Carlos Venancio Junior - <email>antonio@php.net</email></para> - </listitem> - - <listitem> - <para>Antti Kaipila - <email>anttik@iki.fi</email></para> - </listitem> - - <listitem> - <para>Are Bryne - <email>are.bryne@communique.no</email></para> - </listitem> - - <listitem> - <para>Ari Suutari - <email>ari@suutari.iki.fi</email></para> - </listitem> - - <listitem> - <para>Arindum Mukerji - <email>raja@moselle.com</email></para> - </listitem> - - <listitem> - <para>Arjan de Vet - <email>devet@devet.nl</email></para> - </listitem> - - <listitem> - <para>Arnaud S. Launay - <email>asl@launay.org</email></para> - </listitem> - - <listitem> - <para>Arne Henrik Juul - <email>arnej@Lise.Unit.NO</email></para> - </listitem> - - <listitem> - <para>Artem Nosov - <email>chip-set@mail.ru</email></para> - </listitem> - - <listitem> - <para>Ashley Penney - <email>ashp@unloved.org</email></para> - </listitem> - - <listitem> - <para>Ask Bjoern Hansen - <email>ask@valueclick.com</email></para> - </listitem> - - <listitem> - <para>Atsushi Furuta - <email>furuta@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>Atushi Sakauchi - <email>sakauchi@yamame.to</email></para> - </listitem> - - <listitem> - <para>Autrijus Tang - <email>autrijus@autrijus.org</email></para> - </listitem> - - <listitem> - <para>Bakul Shah - <email>bvs@bitblocks.com</email></para> - </listitem> - - <listitem> - <para>Barry Bierbauch - <email>pivrnec@vszbr.cz</email></para> - </listitem> - - <listitem> - <para>Barry Lustig - <email>barry@ictv.com</email></para> - </listitem> - - <listitem> - <para>Ben Hutchinson - <email>benhutch@xfiles.org.uk</email></para> - </listitem> - - <listitem> - <para>Ben Jackson - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ben Walter - <email>bwalter@itachi.swcp.com</email></para> - </listitem> - - <listitem> - <para>Benedikt Köhler - <email>benedikt@furukama.de</email></para> - </listitem> - - <listitem> - <para>Benjamin Lewis - <email>bhlewis@gte.net</email></para> - </listitem> - - <listitem> - <para>Berend de Boer - <email>berend@pobox.com</email></para> - </listitem> - - <listitem> - <para>Bernd Rosauer - <email>br@schiele-ct.de</email></para> - </listitem> - - <listitem> - <para>Bill Kish - <email>kish@osf.org</email></para> - </listitem> - - <listitem> - <para>Bill Trost - <email>trost@cloud.rain.com</email></para> - </listitem> - - <listitem> - <para>Björn Lindström - <email>bkhl@elektrubadur.se</email></para> - </listitem> - - <listitem> - <para>Blaz Zupan - <email>blaz@amis.net</email></para> - </listitem> - - <listitem> - <para>Bob Van Valzah - <email>Bob@whitebarn.com</email></para> - </listitem> - - <listitem> - <para>Bob Willcox - <email>bob@luke.pmr.com</email></para> - </listitem> - - <listitem> - <para>Boris Staeblow - <email>balu@dva.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Boyd R. Faulkner - <email>faulkner@asgard.bga.com</email></para> - </listitem> - - <listitem> - <para>Brad Chapman - <email>chapmanb@arches.uga.edu</email></para> - </listitem> - - <listitem> - <para>Brad Davis - <email>so14k@so14k.com</email></para> - </listitem> - - <listitem> - <para>Brad Hendrickse - <email>bradh@uunet.co.za</email></para> - </listitem> - - <listitem> - <para>Brad Jones - <email>brad@kazrak.com</email></para> - </listitem> - - <listitem> - <para>Brad Karp - <email>karp@eecs.harvard.edu</email></para> - </listitem> - - <listitem> - <para>Brad Lanam - <email>bll@gentoo.com</email></para> - </listitem> - - <listitem> - <para>Bill Lloyd - <email>wlloyd@mpd.ca</email></para> - </listitem> - - <listitem> - <para>Bradley Dunn - <email>bradley@dunn.org</email></para> - </listitem> - - <listitem> - <para>Bram Moolenaar - <email>bram@moolenaar.net</email></para> - </listitem> - - <listitem> - <para>Brandon Fosdick - <email>bfoz@glue.umd.edu</email></para> - </listitem> - - <listitem> - <para>Brandon Gillespie - <email>brandon@roguetrader.com</email></para> - </listitem> - - <listitem> - <para>Brent J. Nordquist - <email>bjn@visi.com</email></para> - </listitem> - - <listitem> - <para>Brett Lymn - <email>blymn@mulga.awadi.com.AU</email></para> - </listitem> - - <listitem> - <para>Brett Taylor - <email>brett@peloton.runet.edu</email></para> - </listitem> - - <listitem> - <para>Brian Campbell - <email>brianc@pobox.com</email></para> - </listitem> - - <listitem> - <para>Brian Clapper - <email>bmc@willscreek.com</email></para> - </listitem> - - <listitem> - <para>Brian Cully - <email>shmit@kublai.com</email></para> - </listitem> - - <listitem> - <para>Brian Handy - <email>handy@lambic.space.lockheed.com</email></para> - </listitem> - - <listitem> - <para>Brian Litzinger - <email>brian@MediaCity.com</email></para> - </listitem> - - <listitem> - <para>Brian McGovern - <email>bmcgover@cisco.com</email></para> - </listitem> - - <listitem> - <para>Brian Moore - <email>ziff@houdini.eecs.umich.edu</email></para> - </listitem> - - <listitem> - <para>Brian R. Haug - <email>haug@conterra.com</email></para> - </listitem> - - <listitem> - <para>Brian Skrab - <email>brian@quynh-and-brian.org</email></para> - </listitem> - - <listitem> - <para>Brian Tao - <email>taob@risc.org</email></para> - </listitem> - - <listitem> - <para>Brion Moss - <email>brion@queeg.com</email></para> - </listitem> - - <listitem> - <para>Bruce Albrecht - <email>bruce@zuhause.mn.org</email></para> - </listitem> - - <listitem> - <para>Bruce Cran - <email>bruce@cran.org.uk</email></para> - </listitem> - - <listitem> - <para>Bruce Gingery - <email>bgingery@gtcs.com</email></para> - </listitem> - - <listitem> - <para>Bruce J. Keeler - <email>loodvrij@gridpoint.com</email></para> - </listitem> - - <listitem> - <para>Bruce Murphy - <email>packrat@iinet.net.au</email></para> - </listitem> - - <listitem> - <para>Bruce Walter - <email>walter@fortean.com</email></para> - </listitem> - - <listitem> - <para>Camson Huynh - <email>chuynh@biolateral.com.au</email></para> - </listitem> - - <listitem> - <para>Carey Jones - <email>mcj@acquiesce.org</email></para> - </listitem> - - <listitem> - <para>Carl Fongheiser - <email>kf0yn@mchsi.com</email></para> - </listitem> - - <listitem> - <para>Carl Makin - <email>carl@stagecraft.cx</email></para> - </listitem> - - <listitem> - <para>Carl Mascott - <email>cmascott@world.std.com</email></para> - </listitem> - - <listitem> - <para>Carl Schmidt - <email>carl@perlpimp.codersluts.net</email></para> - </listitem> - - <listitem> - <para>Casper - <email>casper@acc.am</email></para> - </listitem> - - <listitem> - <para>Castor Fu - <email>castor@geocast.com</email></para> - </listitem> - - <listitem> - <para>Chain Lee - <email>chain@110.net</email></para> - </listitem> - - <listitem> - <para>Charles Hannum - <email>mycroft@ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Charles Henrich - <email>henrich@msu.edu</email></para> - </listitem> - - <listitem> - <para>Charles Mott - <email>cmott@scientech.com</email></para> - </listitem> - - <listitem> - <para>Charles Owens - <email>owensc@enc.edu</email></para> - </listitem> - - <listitem> - <para>Chet Ramey - <email>chet@odin.INS.CWRU.Edu</email></para> - </listitem> - - <listitem> - <para>Chia-liang Kao - <email>clkao@CirX.ORG</email></para> - </listitem> - - <listitem> - <para>Chiharu Shibata - <email>chi@bd.mbn.or.jp</email></para> - </listitem> - - <listitem> - <para>Chip Norkus - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Choe, Cheng-Dae - <email>whitekid@netian.com</email></para> - </listitem> - - <listitem> - <para>Chris Burkert - <email>chris@chrisburkert.de</email></para> - </listitem> - - <listitem> - <para>Chris Csanady - <email>cc@tarsier.ca.sandia.gov</email></para> - </listitem> - - <listitem> - <para>Chris Dabrowski - <email>chris@vader.org</email></para> - </listitem> - - <listitem> - <para>Chris Dillon - <email>cdillon@wolves.k12.mo.us</email></para> - </listitem> - - <listitem> - <para>Chris Howells - <email>howells@kde.org</email></para> - </listitem> - - <listitem> - <para>Chris Knight - <email>chris@e-easy.com.au</email></para> - </listitem> - - <listitem> - <para>Chris Larsen - <email>darth@vader.dk</email></para> - </listitem> - - <listitem> - <para>Chris Pepper - <email>pepper@mail.rockefeller.edu</email></para> - </listitem> - - <listitem> - <para>Chris Pressey - <email>chris_pressey@yahoo.ca</email></para> - </listitem> - - <listitem> - <para>Chris Shenton - <email>cshenton@angst.it.hq.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Chris Stenton - <email>jacs@gnome.co.uk</email></para> - </listitem> - - <listitem> - <para>Chris Torek - <email>torek@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Christian Gusenbauer - <email>c47g@gmx.at</email></para> - </listitem> - - <listitem> - <para>Christian Haury - <email>Christian.Haury@sagem.fr</email></para> - </listitem> - - <listitem> - <para>Christian Lackas - <email>delta@lackas.net</email></para> - </listitem> - - <listitem> - <para>Christian Laursen - <email>xi@borderworlds.dk</email></para> - </listitem> - - <listitem> - <para>Christian Schade - <email>christian.schade@interface-projects.de</email></para> - </listitem> - - <listitem> - <para>Christian Zander - <email>zander@minion.de</email></para> - </listitem> - - <listitem> - <para>Christoph P. Kukulies - <email>kuku@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Christoph Robitschko - <email>chmr@edvz.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Christophe Juniet - <email>cjuniet@entreview.com</email></para> - </listitem> - - <listitem> - <para>Christoph Weber-Fahr - <email>wefa@callcenter.systemhaus.net</email></para> - </listitem> - - <listitem> - <para>Christophe Juniet - <email>cjuniet@entreview.com</email></para> - </listitem> - - <listitem> - <para>Christopher G. Demetriou - <email>cgd@postgres.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Christopher K. Davis - <email>ckd-freebsd@ckdhr.com</email></para> - </listitem> - - <listitem> - <para>Christopher N. Harrell - <email>cnh@ivmg.net</email></para> - </listitem> - - <listitem> - <para>Christopher Preston - <email>rbg@gayteenresource.org</email></para> - </listitem> - - <listitem> - <para>Christopher T. Johnson - <email>cjohnson@neunacht.netgsi.com</email></para> - </listitem> - - <listitem> - <para>Christopher Vance - <email>vance@aurema.com</email></para> - </listitem> - - <listitem> - <para>Chrisy Luke - <email>chrisy@flix.net</email></para> - </listitem> - - <listitem> - <para>Chuck Hein - <email>chein@cisco.com</email></para> - </listitem> - - <listitem> - <para>Clement MOULIN - <email>moeti-freebsd@ouestil.com</email></para> - </listitem> - - <listitem> - <para>Cliff Rowley - <email>dozprompt@onsea.com</email></para> - </listitem> - - <listitem> - <para>Colman Reilly - <email>careilly@tcd.ie</email></para> - </listitem> - - <listitem> - <para>Conrad Sabatier - <email>conrads@cox.net</email></para> - </listitem> - - <listitem> - <para>Constantin S. Svintsoff - <email>kostik@iclub.nsu.ru</email></para> - </listitem> - - <listitem> - <para>Coranth Gryphon - <email>gryphon@healer.com</email></para> - </listitem> - - <listitem> - <para>Cornelis van der Laan - <email>nils@guru.ims.uni-stuttgart.de</email></para> - </listitem> - - <listitem> - <para>Cosmin Stroe - <email>cstroe1@uic.edu</email></para> - </listitem> - - <listitem> - <para>Cove Schneider - <email>cove@brazil.nbn.com</email></para> - </listitem> - - <listitem> - <para>Craig Leres - <email>leres@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Craig Loomis - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Craig Metz - <email>cmetz@inner.net</email></para> - </listitem> - - <listitem> - <para>Craig Spannring - <email>cts@internetcds.com</email></para> - </listitem> - - <listitem> - <para>Craig Struble - <email>cstruble@vt.edu</email></para> - </listitem> - - <listitem> - <para>Cristian Ferretti - <email>cfs@riemann.mat.puc.cl</email></para> - </listitem> - - <listitem> - <para>Curt Mayer - <email>curt@toad.com</email></para> - </listitem> - - <listitem> - <para>Cyrille Lefevre - <email>clefevre@citeweb.net</email></para> - </listitem> - - <listitem> - <para>Cyrus Rahman - <email>cr@jcmax.com</email></para> - </listitem> - - <listitem> - <para>Dai Ishijima - <email>ishijima@tri.pref.osaka.jp</email></para> - </listitem> - - <listitem> - <para>Daisuke Watanabe - <email>NU7D-WTNB@asahi-net.or.jp</email></para> - </listitem> - - <listitem> - <para>Damian Hamill - <email>damian@cablenet.net</email></para> - </listitem> - - <listitem> - <para>Damien Tougas - <email>damien@tougas.net</email></para> - </listitem> - - <listitem> - <para>Dan Caescu - <email>daniel@freebsd.ro</email></para> - </listitem> - - <listitem> - <para>Dan Cross - <email>tenser@spitfire.ecsel.psu.edu</email></para> - </listitem> - - <listitem> - <para>Dan Langille - <email>dan@freebsddiary.org</email></para> - </listitem> - - <listitem> - <para>Dan Lukes - <email>dan@obluda.cz</email></para> - </listitem> - - <listitem> - <para>Dan Nelson - <email>dnelson@emsphone.com</email></para> - </listitem> - - <listitem> - <para>Dan Papasian - <email>bugg@bugg.strangled.net</email></para> - </listitem> - - <listitem> - <para>Dan Pelleg - <email>dpelleg+unison@cs.cmu.edu</email></para> - </listitem> - - <listitem> - <para>Dan Piponi - <email>wmtop@tanelorn.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Dan Walters - <email>hannibal@cyberstation.net</email></para> - </listitem> - - <listitem> - <para>Daniel B. Hemmerich - <email>dan@spot.org</email></para> - </listitem> - - <listitem> - <para>Daniel Blankensteiner - <email>db@TruNet.dk</email></para> - </listitem> - - <listitem> - <para>Daniel Hagan - <email>dhagan@acm.vt.edu</email></para> - </listitem> - - <listitem> - <para>Daniel O'Connor - <email>doconnor@gsoft.com.au</email></para> - </listitem> - - <listitem> - <para>Daniel Poirot - <email>poirot@aio.jsc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Daniel Rock - <email>rock@cs.uni-sb.de</email></para> - </listitem> - - <listitem> - <para>Daniel Roethlisberger - <email>daniel@roe.ch</email></para> - </listitem> - - <listitem> - <para>Daniel W. McRobb - <email>dwm@caimis.com</email></para> - </listitem> - - <listitem> - <para>Danny Egen - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Danny Howard - <email>dannyman@toldme.com</email></para> - </listitem> - - <listitem> - <para>Danny J. Zerkel - <email>dzerkel@phofarm.com</email></para> - </listitem> - - <listitem> - <para>Danny Pansters - <email>danny@ricin.com</email></para> - </listitem> - - <listitem> - <para>Dave Adkins - <email>adkin003@tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>Dave Andersen - <email>angio@aros.net</email></para> - </listitem> - - <listitem> - <para>Dave Blizzard - <email>dblizzar@sprynet.com</email></para> - </listitem> - - <listitem> - <para>Dave Bodenstab - <email>imdave@synet.net</email></para> - </listitem> - - <listitem> - <para>Dave Burgess - <email>burgess@hrd769.brooks.af.mil</email></para> - </listitem> - - <listitem> - <para>Dave Chapeskie - <email>dchapes@ddm.on.ca</email></para> - </listitem> - - <listitem> - <para>Dave Cornejo - <email>dave@dogwood.com</email></para> - </listitem> - - <listitem> - <para>Dave Edmondson - <email>davided@sco.com</email></para> - </listitem> - - <listitem> - <para>Dave Glowacki - <email>dglo@ssec.wisc.edu</email></para> - </listitem> - - <listitem> - <para>Dave Marquardt - <email>marquard@austin.ibm.com</email></para> - </listitem> - - <listitem> - <para>Dave Tweten - <email>tweten@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>David A. Adkins - <email>adkin003@tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>David A. Bader - <email>dbader@eece.unm.edu</email></para> - </listitem> - - <listitem> - <para>David Borman - <email>dab@bsdi.com</email></para> - </listitem> - - <listitem> - <para>David Bremner - <email>bremner@unb.ca</email></para> - </listitem> - - <listitem> - <para>David Bushong - <email>david+ports@bushong.net</email></para> - </listitem> - - <listitem> - <para>David Dawes - <email>dawes@XFree86.org</email></para> - </listitem> - - <listitem> - <para>David Filo - <email>unknown</email></para> - </listitem> - - <listitem> - <para>David Magda - <email>dmagda@magda.ca</email></para> - </listitem> - - <listitem> - <para>David H. Munro - <email>munro1@llnl.gov</email></para> - </listitem> - - <listitem> - <para>David Holland - <email>dholland@eecs.harvard.edu</email></para> - </listitem> - - <listitem> - <para>David Holloway - <email>daveh@gwythaint.tamis.com</email></para> - </listitem> - - <listitem> - <para>David Horwitt - <email>dhorwitt@ucsd.edu</email></para> - </listitem> - - <listitem> - <para>David Hovemeyer - <email>daveho@infocom.com</email></para> - </listitem> - - <listitem> - <para>David Jones - <email>dej@qpoint.torfree.net</email></para> - </listitem> - - <listitem> - <para>David Kelly - <email>dkelly@tomcat1.tbe.com</email></para> - </listitem> - - <listitem> - <para>David Kulp - <email>dkulp@neomorphic.com</email></para> - </listitem> - - <listitem> - <para>David L. Nugent - <email>davidn@blaze.net.au</email></para> - </listitem> - - <listitem> - <para>David Le Brun - <email>david@dyn-ns.net</email></para> - </listitem> - - <listitem> - <para>David Leonard - <email>d@scry.dstc.edu.au</email></para> - </listitem> - - <listitem> - <para>David Muir Sharnoff - <email>muir@idiom.com</email></para> - </listitem> - - <listitem> - <para>David S. Miller - <email>davem@jenolan.rutgers.edu</email></para> - </listitem> - - <listitem> - <para>David Sugar - <email>dyfet@gnu.org</email></para> - </listitem> - - <listitem> - <para>David Sze - <email>dsze@alumni.uwaterloo.ca</email></para> - </listitem> - - <listitem> - <para>David Thiel - <email>lx@redundancy.redundancy.org</email></para> - </listitem> - - <listitem> - <para>David Wolfskill - <email>david@catwhisker.org</email></para> - </listitem> - - <listitem> - <para>David Yeske - <email>dyeske@yahoo.com</email></para> - </listitem> - - <listitem> - <para>Dean Gaudet - <email>dgaudet@arctic.org</email></para> - </listitem> - - <listitem> - <para>Dean Huxley - <email>dean@fsa.ca</email></para> - </listitem> - - <listitem> - <para>Denis Fortin - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Dean Hollister - <email>dean@odyssey.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Denis Philippov - <email>for_spam@mezon.ru</email></para> - </listitem> - - <listitem> - <para>Denis Shaposhnikov - <email>dsh@vlink.ru</email></para> - </listitem> - - <listitem> - <para>Dennis Glatting - <email>dennis.glatting@software-munitions.com</email></para> - </listitem> - - <listitem> - <para>Denton Gentry - <email>denny1@home.com</email></para> - </listitem> - - <listitem> - <para>Derek Inksetter - <email>derek@saidev.com</email></para> - </listitem> - - <listitem> - <para>Dermot Tynan - <email>dtynan@kalopa.com</email></para> - </listitem> - - <listitem> - <para>Diane Bruce - <email>db@db.net</email></para> - </listitem> - - <listitem> - <para>Dirk Gouders - <email>gouders@et.bocholt.fh-gelsenkirchen.de</email></para> - </listitem> - - <listitem> - <para>Dirk Keunecke - <email>dk@panda.rhein-main.de</email></para> - </listitem> - - <listitem> - <para>Dirk Nehrling - <email>nerle@pdv.de</email></para> - </listitem> - - <listitem> - <para>Dirk-Willem van Gulik - <email>dirkx@skutsje.san.webweaving.org</email></para> - </listitem> - - <listitem> - <para>Dishanker Rajakulendren - <email>draj@oceanfree.net</email></para> - </listitem> - - <listitem> - <para>Dmitri Nikulin - <email>setagllib@optusnet.com.au</email></para> - </listitem> - - <listitem> - <para>Dmitry A. Yanko - <email>fm@astral.ntu-kpi.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Dmitry Afanasiev - <email>KOT@MATPOCKuH.Ru</email></para> - </listitem> - - <listitem> - <para>Dmitry Dyomin - <email>old@old.com.ua</email></para> - </listitem> - - <listitem> - <para>Dmitry Karasik - <email>dmitry@karasik.eu.org</email></para> - </listitem> - - <listitem> - <para>Dmitry Khrustalev - <email>dima@xyzzy.machaon.ru</email></para> - </listitem> - - <listitem> - <para>Dmitry Kohmanyuk - <email>dk@farm.org</email></para> - </listitem> - - <listitem> - <para>Dmitry Semkin - <email>ds@tic-tac.ru</email></para> - </listitem> - - <listitem> - <para>Dmytro Rud - <email>unixoid@yahoo.com</email></para> - </listitem> - - <listitem> - <para>Dom Mitchell - <email>dom@myrddin.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Domas Mituzas - <email>midom@dammit.lt</email></para> - </listitem> - - <listitem> - <para>Dominic Marks - <email>dominic_marks@btinternet.com</email></para> - </listitem> - - <listitem> - <para>Dominik Brettnacher - <email>domi@saargate.de</email></para> - </listitem> - - <listitem> - <para>Dominik Rothert - <email>dr@domix.de</email></para> - </listitem> - - <listitem> - <para>Don Croyle - <email>croyle@gelemna.ft-wayne.in.us</email></para> - </listitem> - - <listitem> - <para>Don Morrison - <email>dmorrisn@u.washington.edu</email></para> - </listitem> - - <listitem> - <para>&a.whiteside;</para> - </listitem> - - <listitem> - <para>Don Yuniskis - <email>dgy@rtd.com</email></para> - </listitem> - - <listitem> - <para>Donald Maddox - <email>dmaddox@conterra.com</email></para> - </listitem> - - <listitem> - <para>Donn Miller - <email>dmmiller@cvzoom.net</email></para> - </listitem> - - <listitem> - <para>Douglas A. Maske - <email>maske@rungepaper.com</email></para> - </listitem> - - <listitem> - <para>Douglas Carmichael - <email>dcarmich@mcs.com</email></para> - </listitem> - - <listitem> - <para>Douglas Crosher - <email>dtc@scrooge.ee.swin.oz.au</email></para> - </listitem> - - <listitem> - <para>Douglas K. Rand - <email>rand@meridian-enviro.com</email></para> - </listitem> - - <listitem> - <para>Drew Derbyshire - <email>ahd@kew.com</email></para> - </listitem> - - <listitem> - <para>Dryice Liu - <email>dryice@liu.com.cn</email></para> - </listitem> - - <listitem> - <para>Dustin Sallings - <email>dustin@spy.net</email></para> - </listitem> - - <listitem> - <para>Dylan Simon - <email>dylan@dylex.net</email></para> - </listitem> - - <listitem> - <para>ELISA Font Project</para> - </listitem> - - <listitem> - <para>Eckart "Isegrim" Hofmann - <email>Isegrim@Wunder-Nett.org</email></para> - </listitem> - - <listitem> - <para>Ed Gold - <email>vegold01@starbase.spd.louisville.edu</email></para> - </listitem> - - <listitem> - <para>Ed Hudson - <email>elh@p5.spnet.com</email></para> - </listitem> - - <listitem> - <para>Edgardo Garcia Hoeffler - <email>edybsd@yahoo.com.ar</email></para> - </listitem> - - <listitem> - <para>Edson Brandi - <email>ebrandi.home@uol.com.br</email></para> - </listitem> - - <listitem> - <para>Eduard Martinescu - <email>martines@rochester.rr.com</email></para> - </listitem> - - <listitem> - <para>Edward Chuang - <email>edwardc@firebird.org.tw</email></para> - </listitem> - - <listitem> - <para>Edward Wang - <email>edward@edcom.com</email></para> - </listitem> - - <listitem> - <para>Edwin Mons - <email>e@ik.nu</email></para> - </listitem> - - <listitem> - <para>Ege Rekk - <email>aagero@aage.priv.no</email></para> - </listitem> - - <listitem> - <para>Eiji-usagi-MATSUmoto - <email>usagi@clave.gr.jp</email></para> - </listitem> - - <listitem> - <para>Eike Bernhardt - <email>eike.bernhardt@gmx.de</email></para> - </listitem> - - <listitem> - <para>Elmar Bartel - <email>bartel@informatik.tu-muenchen.de</email></para> - </listitem> - - <listitem> - <para>Emanuel Haupt - <email>ehaupt@critical.ch</email></para> - </listitem> - - <listitem> - <para>Eoin Lawless - <email>eoin@maths.tcd.ie</email></para> - </listitem> - - <listitem> - <para>Eric A. Griff - <email>eric@talesfromthereal.com</email></para> - </listitem> - - <listitem> - <para>Eric Anderson - <email>anderson@centtech.com</email></para> - </listitem> - - <listitem> - <para>Eric Blood - <email>eblood@cs.unr.edu</email></para> - </listitem> - - <listitem> - <para>Eric D. Futch - <email>efutch@nyct.net</email></para> - </listitem> - - <listitem> - <para>Eric J. Haug - <email>ejh@slustl.slu.edu</email></para> - </listitem> - - <listitem> - <para>Eric J. Schwertfeger - <email>eric@cybernut.com</email></para> - </listitem> - - <listitem> - <para>Eric L. Hernes - <email>erich@lodgenet.com</email></para> - </listitem> - - <listitem> - <para>Eric P. Scott - <email>eps@sirius.com</email></para> - </listitem> - - <listitem> - <para>Eric Shao-yu Cheng - <email>eric@fractal.csie.org</email></para> - </listitem> - - <listitem> - <para>Eric Sprinkle - <email>eric@ennovatenetworks.com</email></para> - </listitem> - - <listitem> - <para>Erich Stefan Boleyn - <email>erich@uruk.org</email></para> - </listitem> - - <listitem> - <para>Erich Zigler - <email>erich@tacni.net</email></para> - </listitem> - - <listitem> - <para>Erik E. Rantapaa - <email>rantapaa@math.umn.edu</email></para> - </listitem> - - <listitem> - <para>Erik H. Bakke - <email>erikhb@bgnett.no</email></para> - </listitem> - - <listitem> - <para>Erik Greenwald - <email>erik@smluc.org</email></para> - </listitem> - - <listitem> - <para>Erik H. Moe - <email>ehm@cris.com</email></para> - </listitem> - - <listitem> - <para>Ernst Winter - <email>ewinter@lobo.muc.de</email></para> - </listitem> - - <listitem> - <para>Espen Skoglund - <email>esk@ira.uka.de</email></para> - </listitem> - - <listitem> - <para>Eugene Grosbein - <email>eugen@grosbein.pp.ru</email></para> - </listitem> - - <listitem> - <para>Eugene M. Kim - <email>astralblue@usa.net</email></para> - </listitem> - - <listitem> - <para> Eugene Ossintsev - <email>eugos@gmx.net</email></para> - </listitem> - - <listitem> - <para>Eugene Radchenko - <email>genie@qsar.chem.msu.su</email></para> - </listitem> - - <listitem> - <para>Eugene Ray - <email>pal@paladin7.net</email></para> - </listitem> - - <listitem> - <para>Eugeney Ryzhyk - <email>rzheka@users.sourceforge.net</email></para> - </listitem> - - <listitem> - <para>Eugeny Kuzakov - <email>CoreDumped@coredumped.null.ru</email></para> - </listitem> - - <listitem> - <para>Evan Champion - <email>evanc@synapse.net</email></para> - </listitem> - - <listitem> - <para>Evgueni V. Gavrilov - <email>aquatique@rusunix.org</email></para> - </listitem> - - <listitem> - <para>FUJIMOTO Kensaku - <email>fujimoto@oscar.elec.waseda.ac.jp</email></para> - </listitem> - - <listitem> - <para>FURUSAWA Kazuhisa - <email>furusawa@com.cs.osakafu-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Fanying Jen - <email>fanying@fynet.com</email></para> - </listitem> - - <listitem> - <para>Faried Nawaz - <email>fn@Hungry.COM</email></para> - </listitem> - - <listitem> - <para>Fernan Aguero - <email>fernan@iib.unsam.edu.ar</email></para> - </listitem> - - <listitem> - <para>Ferruccio Vitale - <email>vitale@cs.tin.it</email></para> - </listitem> - - <listitem> - <para>Filippo Natali - <email>filippo@widestore.net</email></para> - </listitem> - - <listitem> - <para>Flemming Jacobsen - <email>fj@batmule.dk</email></para> - </listitem> - - <listitem> - <para>Florent Thoumie - <email>flz@xbsd.org</email></para> - </listitem> - - <listitem> - <para>Fong-Ching Liaw - <email>fong@juniper.net</email></para> - </listitem> - - <listitem> - <para>Francis M J Hsieh - <email>mjshieh@life.nthu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Francisco Gomez - <email>francisco@gomezmarin.com</email></para> - </listitem> - - <listitem> - <para>Francisco Reyes - <email>fjrm@yahoo.com</email></para> - </listitem> - - <listitem> - <para>François Tamone - <email>tamone@eig.unige.ch</email></para> - </listitem> - - <listitem> - <para>Frank Bartels - <email>knarf@camelot.de</email></para> - </listitem> - - <listitem> - <para>Frank Chen Hsiung Chan - <email>frankch@waru.life.nthu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Frank Gründer - <email>elwood@mc5sys.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Frank J. Lazlo - <email>laszlof@freebsdmatrix.net</email></para> - </listitem> - - <listitem> - <para>Frank MacLachlan - <email>fpm@n2.net</email></para> - </listitem> - - <listitem> - <para>Frank Nobis - <email>fn@Radio-do.de</email></para> - </listitem> - - <listitem> - <para>Frank Ruell - <email>stoerte@dreamwarrior.net</email></para> - </listitem> - - <listitem> - <para>Frank Volf - <email>volf@oasis.IAEhv.nl</email></para> - </listitem> - - <listitem> - <para>Frank ten Wolde - <email>franky@pinewood.nl</email></para> - </listitem> - - <listitem> - <para>Frank van der Linden - <email>frank@fwi.uva.nl</email></para> - </listitem> - - <listitem> - <para>Franz Klammer - <email>klammer@webonaut.com</email></para> - </listitem> - - <listitem> - <para>Fred Cawthorne - <email>fcawth@jjarray.umn.edu</email></para> - </listitem> - - <listitem> - <para>Fred Gilham - <email>gilham@csl.sri.com</email></para> - </listitem> - - <listitem> - <para>Fred Templin - <email>templin@erg.sri.com</email></para> - </listitem> - - <listitem> - <para>Freddie Cash - <email>fcash@bigfoot.com</email></para> - </listitem> - - <listitem> - <para>Frederic Dubuy - <email>fdubuy@free.fr</email></para> - </listitem> - - <listitem> - <para>Frederick Earl Gray - <email>fgray@rice.edu</email></para> - </listitem> - - <listitem> - <para>Frerich Raabe - <email>frerich.raabe@gmx.de</email></para> - </listitem> - - <listitem> - <para>Fuyuhiko Maruyama - <email>fuyuhik8@is.titech.ac.jp</email></para> - </listitem> - - <listitem> - <para>&a.stanislav;</para> - </listitem> - - <listitem> - <para>Gabor Kincses - <email>gabor@acm.org</email></para> - </listitem> - - <listitem> - <para>Gabor Zahemszky - <email>zgabor@CoDe.hu</email></para> - </listitem> - - <listitem> - <para>Gareth McCaughan - <email>gjm11@dpmms.cam.ac.uk</email></para> - </listitem> - - <listitem> - <para>Garrett Rooney - <email>rooneg@electricjellyfish.net</email></para> - </listitem> - - <listitem> - <para>Gary A. Browning - <email>gab10@griffcd.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Gary Howland - <email>gary@hotlava.com</email></para> - </listitem> - - <listitem> - <para>Gary J. - <email>garyj@rks32.pcs.dec.com</email></para> - </listitem> - - <listitem> - <para>Gary Kline - <email>kline@thought.org</email></para> - </listitem> - - <listitem> - <para>Gary W. Swearingen - <email>swear@aa.net</email></para> - </listitem> - - <listitem> - <para>Gaspar Chilingarov - <email>nightmar@lemming.acc.am</email></para> - </listitem> - - <listitem> - <para>Gavin Atkinson - <email>gavin@ury.york.ac.uk</email></para> - </listitem> - - <listitem> - <para>Gea-Suan Lin - <email>gslin@ccca.nctu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Gerasimos Dimitriadis - <email>gedimitr@auth.gr</email></para> - </listitem> - - <listitem> - <para>Gerhard Gonter - <email>g.gonter@ieee.org</email></para> - </listitem> - - <listitem> - <para>Geoff Rehmet - <email>csgr@alpha.ru.ac.za</email></para> - </listitem> - - <listitem> - <para>Georg Wagner - <email>georg.wagner@ubs.com</email></para> - </listitem> - - <listitem> - <para>Gerrit Beine - <email>gerrit@beine-computer.de</email></para> - </listitem> - - <listitem> - <para>Gianlorenzo Masini - <email>masini@uniroma3.it</email></para> - </listitem> - - <listitem> - <para>Gianmarco Giovannelli - <email>gmarco@giovannelli.it</email></para> - </listitem> - - <listitem> - <para>Gil Kloepfer Jr. - <email>gil@limbic.ssdl.com</email></para> - </listitem> - - <listitem> - <para>Gilad Rom - <email>rom_glsa@ein-hashofet.co.il</email></para> - </listitem> - - <listitem> - <para>Giles Lean - <email>giles@nemeton.com.au</email></para> - </listitem> - - <listitem> - <para>Ginga Kawaguti - <email>ginga@amalthea.phys.s.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Glen Foster - <email>gfoster@gfoster.com</email></para> - </listitem> - - <listitem> - <para>Glenn Johnson - <email>gljohns@bellsouth.net</email></para> - </listitem> - - <listitem> - <para>Godmar Back - <email>gback@facility.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Goran Hammarback - <email>goran@astro.uu.se</email></para> - </listitem> - - <listitem> - <para>Gord Matzigkeit - <email>gord@enci.ucalgary.ca</email></para> - </listitem> - - <listitem> - <para>Gordon Greeff - <email>gvg@uunet.co.za</email></para> - </listitem> - - <listitem> - <para>Graham Wheeler - <email>gram@cdsec.com</email></para> - </listitem> - - <listitem> - <para>Greg A. Woods - <email>woods@zeus.leitch.com</email></para> - </listitem> - - <listitem> - <para>Greg Ansley - <email>gja@ansley.com</email></para> - </listitem> - - <listitem> - <para>Greg J. - <email>xcas@cox.net</email></para> - </listitem> - - <listitem> - <para>Greg Robinson - <email>greg@rosevale.com.au</email></para> - </listitem> - - <listitem> - <para>Greg Troxel - <email>gdt@ir.bbn.com</email></para> - </listitem> - - <listitem> - <para>Greg Ungerer - <email>gerg@stallion.oz.au</email></para> - </listitem> - - <listitem> - <para>Gregory Bond - <email>gnb@itga.com.au</email></para> - </listitem> - - <listitem> - <para>Gregory D. Moncreaff - <email>moncrg@bt340707.res.ray.com</email></para> - </listitem> - - <listitem> - <para>Gurkan Sengun - <email>gurkan@linuks.mine.nu</email></para> - </listitem> - - <listitem> - <para>Guy Harris - <email>guy@netapp.com</email></para> - </listitem> - - <listitem> - <para>HAMADA Naoki - <email>hamada@astec.co.jp</email></para> - </listitem> - - <listitem> - <para>HIYAMA Takeshi - <email>gibbon@cocoa.freemail.ne.jp</email></para> - </listitem> - - <listitem> - <para>HONDA Yasuhiro - <email>honda@kashio.info.mie-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>HOSOBUCHI Noriyuki - <email>hoso@buchi.tama.or.jp</email></para> - </listitem> - - <listitem> - <para>HOTARU-YA - <email>hotaru@tail.net</email></para> - </listitem> - - <listitem> - <para>Haesu Jeon - <email>haesu@towardex.com</email></para> - </listitem> - - <listitem> - <para>Hammurabi Mendes - <email>hmendes_br@yahoo.com</email></para> - </listitem> - - <listitem> - <para>Hannes Sowa - <email>satbran@web.de</email></para> - </listitem> - - <listitem> - <para>Hannu Savolainen - <email>hannu@voxware.pp.fi</email></para> - </listitem> - - <listitem> - <para>Hans Huebner - <email>hans@artcom.de</email></para> - </listitem> - - <listitem> - <para>Hans Petter Bieker - <email>zerium@webindex.no</email></para> - </listitem> - - <listitem> - <para>Hans Zuidam - <email>hans@brandinnovators.com</email></para> - </listitem> - - <listitem> - <para>Hans-Christian Ebke - <email>hans-christian_ebke@gmx.de</email></para> - </listitem> - - <listitem> - <para>Hansjoerg Pehofer - <email>hansjoerg.pehofer@uibk.ac.at</email></para> - </listitem> - - <listitem> - <para>Harald Wille - <email>harald.wille@students.jku.at</email></para> - </listitem> - - <listitem> - <para>Harlan Stenn - <email>Harlan.Stenn@pfcs.com</email></para> - </listitem> - - <listitem> - <para>Harold Barker - <email>hbarker@dsms.com</email></para> - </listitem> - - <listitem> - <para>Harry Newton - <email>harry_newton@telinco.co.uk</email></para> - </listitem> - - <listitem> - <para>Havard Eidnes - <email>Havard.Eidnes@runit.sintef.no</email></para> - </listitem> - - <listitem> - <para>Heath Nielson - <email>heath@cs.byu.edu</email></para> - </listitem> - - <listitem> - <para>Heikki Suonsivu - <email>hsu@cs.hut.fi</email></para> - </listitem> - - <listitem> - <para>Heiko W. Rupp - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Heiner Eichmann - <email>h.eichmann@gmx.de</email></para> - </listitem> - - <listitem> - <para>Heiner Strauss - <email>heiner@bilch.com</email></para> - </listitem> - - <listitem> - <para>Helmut F. Wirth - <email>hfwirth@ping.at</email></para> - </listitem> - - <listitem> - <para>Hendrik Scholz - <email>hendrik@scholz.net</email></para> - </listitem> - - <listitem> - <para>Henrik Motakef - <email>henrik.motakef@web.de</email></para> - </listitem> - - <listitem> - <para>Henrik Vestergaard Draboel - <email>hvd@terry.ping.dk</email></para> - </listitem> - - <listitem> - <para>Henry Whincup - <email>henry@techiebod.com</email></para> - </listitem> - - <listitem> - <para>Herb Peyerl - <email>hpeyerl@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Hideaki Ohmon - <email>ohmon@tom.sfc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hidekazu Kuroki - <email>hidekazu@cs.titech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hideki Machida - <email>hido@neojapangz.com</email></para> - </listitem> - - <listitem> - <para>Hideki Yamamoto - <email>hyama@acm.org</email></para> - </listitem> - - <listitem> - <para>Hideyuki Suzuki - <email>hideyuki@sat.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hirayama Issei - <email>iss@mail.wbs.ne.jp</email></para> - </listitem> - - <listitem> - <para>Hiroaki Sakai - <email>sakai@miya.ee.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hiroharu Tamaru - <email>tamaru@ap.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Hironori Ikura - <email>hikura@kaisei.org</email></para> - </listitem> - - <listitem> - <para>Hiroshi Nishikawa - <email>nis@pluto.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>Hiroya Tsubakimoto - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Holger Lamm - <email>holger@eit.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Holger Veit - <email>Holger.Veit@gmd.de</email></para> - </listitem> - - <listitem> - <para>Holm Tiffe - <email>holm@geophysik.tu-freiberg.de</email></para> - </listitem> - - <listitem> - <para>Horance Chou - <email>horance@freedom.ie.cycu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Horihiro Kumagai - <email>kuma@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Hr.Ladavac - <email>lada@ws2301.gud.siemens.co.at</email></para> - </listitem> - - <listitem> - <para>Hsin-Hsiung Chang - <email>sexbear@tmu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Hubert Feyrer - <email>hubertf@NetBSD.ORG</email></para> - </listitem> - - <listitem> - <para>Hubert Tournier - <email>hubert@tournier.org</email></para> - </listitem> - - <listitem> - <para>Hugh Mahon - <email>h_mahon@fc.hp.com</email></para> - </listitem> - - <listitem> - <para>Hung-Chi Chu - <email>hcchu@r350.ee.ntu.edu.tw</email></para> - </listitem> - - <listitem> - <para>IMAI Takeshi - <email>take-i@ceres.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>IMAMURA Tomoaki - <email>tomoak-i@is.aist-nara.ac.jp</email></para> - </listitem> - - <listitem> - <para>IWASHITA Yoji - <email>shuna@pop16.odn.ne.jp</email></para> - </listitem> - - <listitem> - <para>Ian Holland - <email>ianh@tortuga.com.au</email></para> - </listitem> - - <listitem> - <para>Ian Struble - <email>ian@broken.net</email></para> - </listitem> - - <listitem> - <para>Ian Vaudrey - <email>i.vaudrey@bigfoot.com</email></para> - </listitem> - - <listitem> - <para>Igor Khasilev - <email>igor@jabber.paco.odessa.ua</email></para> - </listitem> - - <listitem> - <para>Igor Pokrovsky - <email>tiamat@telegraph.spb.ru</email></para> - </listitem> - - <listitem> - <para>Igor Roshchin - <email>str@giganda.komkon.org</email></para> - </listitem> - - <listitem> - <para>Igor Serikov - <email>bt@turtle.pangeatech.com</email></para> - </listitem> - - <listitem> - <para>Igor Sviridov - <email>siac@ua.net</email></para> - </listitem> - - <listitem> - <para>Igor Vinokurov - <email>igor@zynaps.ru</email></para> - </listitem> - - <listitem> - <para>Ikuo Nakagawa - <email>ikuo@isl.intec.co.jp</email></para> - </listitem> - - <listitem> - <para>Ilia Chipitsine - <email>ilia@jane.cgu.chel.su</email></para> - </listitem> - - <listitem> - <para>Ilya V. Komarov - <email>mur@lynx.ru</email></para> - </listitem> - - <listitem> - <para>Ivan Sharov - <email>ivan.sharov@iname.com</email></para> - </listitem> - - <listitem> - <para>Ismail Yenigul - <email>ismail@enderunix.org</email></para> - </listitem> - - <listitem> - <para>Itsuro Saito - <email>saito@miv.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>J. Bryant - <email>jbryant@argus.flash.net</email></para> - </listitem> - - <listitem> - <para>J. David Lowe - <email>lowe@saturn5.com</email></para> - </listitem> - - <listitem> - <para>J. Han - <email>hjh@photino.com</email></para> - </listitem> - - <listitem> - <para>J. Hawk - <email>jhawk@MIT.EDU</email></para> - </listitem> - - <listitem> - <para>J Shoemaker - <email>shoemaker@softhome.net</email></para> - </listitem> - - <listitem> - <para>J.T. Conklin - <email>jtc@cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jacek Pelka - <email>jacek@combit.com.pl</email></para> - </listitem> - - <listitem> - <para>Jack - <email>jack@zeus.xtalwind.net</email></para> - </listitem> - - <listitem> - <para>Jacob Bohn Lorensen - <email>jacob@jblhome.ping.mk</email></para> - </listitem> - - <listitem> - <para>Jagane D Sundar - <email>jagane@netcom.com</email></para> - </listitem> - - <listitem> - <para>Jake Hamby - <email>jehamby@anobject.com</email></para> - </listitem> - - <listitem> - <para>Jakub Klausa - <email>jacke@bofh.pl</email></para> - </listitem> - - <listitem> - <para>James Clark - <email>jjc@jclark.com</email></para> - </listitem> - - <listitem> - <para>James D. Stewart - <email>jds@c4systm.com</email></para> - </listitem> - - <listitem> - <para>James Jegers - <email>jimj@miller.cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>James Raftery - <email>james@now.ie</email></para> - </listitem> - - <listitem> - <para>James Raynard - <email>fhackers@jraynard.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>James T. Liu - <email>jtliu@phlebas.rockefeller.edu</email></para> - </listitem> - - <listitem> - <para>James da Silva - <email>jds@cs.umd.edu</email></para> - </listitem> - - <listitem> - <para>Jamie Heckford - <email>jamie@jamiesdomain.co.uk</email></para> - </listitem> - - <listitem> - <para>Jan Conard - <email>charly@fachschaften.tu-muenchen.de</email></para> - </listitem> - - <listitem> - <para>Jan Jungnickel - <email>Jan@Jungnickel.com</email></para> - </listitem> - - <listitem> - <para>Jan Koum - <email>jkb@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Jan L. Peterson - <email>jlp@flipdog.com</email></para> - </listitem> - - <listitem> - <para>Jan Rochel - <email>jan.rochel@epost.de</email></para> - </listitem> - - <listitem> - <para>Jan Stocker - <email>jan.stocker@t-online.de</email></para> - </listitem> - - <listitem> - <para>Jan-Peter Koopmann - <email>j.koopmann@seceidos.de</email></para> - </listitem> - - <listitem> - <para>Janick Taillandier - <email>Janick.Taillandier@ratp.fr</email></para> - </listitem> - - <listitem> - <para>Janos Mohacsi - <email>janos.mohacsi@bsd.hu</email></para> - </listitem> - - <listitem> - <para>Janusz Kokot - <email>janek@gaja.ipan.lublin.pl</email></para> - </listitem> - - <listitem> - <para>Jarle Greipsland - <email>jarle@idt.unit.no</email></para> - </listitem> - - <listitem> - <para>Jason DiCioccio - <email>geniusj@ods.org</email></para> - </listitem> - - <listitem> - <para>Jason Garman - <email>init@risen.org</email></para> - </listitem> - - <listitem> - <para>Jason Harris - <email>jharris@widomaker.com</email></para> - </listitem> - - <listitem> - <para>Jason R. Mastaler - <email>jason-freebsd@mastaler.com</email></para> - </listitem> - - <listitem> - <para>Jason Stone - <email>jason-fbsd-ports@shalott.net</email></para> - </listitem> - - <listitem> - <para>Jason Thorpe - <email>thorpej@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Jason Wright - <email>jason@OpenBSD.org</email></para> - </listitem> - - <listitem> - <para>Jason Young - <email>doogie@forbidden-donut.anet-stl.com</email></para> - </listitem> - - <listitem> - <para>Javier Martin Rueda - <email>jmrueda@diatel.upm.es</email></para> - </listitem> - - <listitem> - <para>Jay Fenlason - <email>hack@datacube.com</email></para> - </listitem> - - <listitem> - <para>Jay Krell - <email>jay.krell@cornell.edu</email></para> - </listitem> - - <listitem> - <para>Jaye Mathisen - <email>mrcpu@cdsnet.net</email></para> - </listitem> - - <listitem> - <para>Jean-Sebastien Roy - <email>js@jeannot.org</email></para> - </listitem> - - <listitem> - <para>Jean-Yves Lefort - <email>jylefort@brutele.be</email></para> - </listitem> - - <listitem> - <para>Jean Milanez Melo - <email>jmelo@freebsdbrasil.com.br</email></para> - </listitem> - - <listitem> - <para>Jeff Bartig - <email>jeffb@doit.wisc.edu</email></para> - </listitem> - - <listitem> - <para>Jeff Brown - <email>jabrown@caida.org</email></para> - </listitem> - - <listitem> - <para>Jeff Forys - <email>jeff@forys.cranbury.nj.us</email></para> - </listitem> - - <listitem> - <para>Jeff Kletsky - <email>Jeff@Wagsky.com</email></para> - </listitem> - - <listitem> - <para>Jeff Palmer - <email>scorpio@drkshdw.org</email></para> - </listitem> - - <listitem> - <para>Jeffrey Evans - <email>evans@scnc.k12.mi.us</email></para> - </listitem> - - <listitem> - <para>Jeffrey Wheat - <email>jeff@cetlink.net</email></para> - </listitem> - - <listitem> - <para>Jens Rehsack - <email>rehsack@liwing.de</email></para> - </listitem> - - <listitem> - <para>Jeremy Allison - <email>jallison@whistle.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Chadwick - <email>yoshi@parodius.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Chatfield - <email>jdc@xinside.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Karlson - <email>karlj000@unbc.ca</email></para> - </listitem> - - <listitem> - <para>Jeremy Prior - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Jeremy C. Reed - <email>reed@pugetsoundtechnology.com</email></para> - </listitem> - - <listitem> - <para>Jeremy Shaffner - <email>jeremy@external.org</email></para> - </listitem> - - <listitem> - <para>Jesper Dalberg - <email>jesper@jdn.dk</email></para> - </listitem> - - <listitem> - <para>Jesper Noehr - <email>jesper@noehr.org</email></para> - </listitem> - - <listitem> - <para>Jesse McConnell - <email>jesse@cylant.com</email></para> - </listitem> - - <listitem> - <para>Jesse Rosenstock - <email>jmr@ugcs.caltech.edu</email></para> - </listitem> - - <listitem> - <para>Jian-Da Li - <email>jdli@csie.nctu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Jim Babb - <email>babb@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Jim Binkley - <email>jrb@cs.pdx.edu</email></para> - </listitem> - - <listitem> - <para>Jim Bloom - <email>bloom@acm.org</email></para> - </listitem> - - <listitem> - <para>Jim Carroll - <email>jim@carroll.com</email></para> - </listitem> - - <listitem> - <para>Jim Flowers - <email>jflowers@ezo.net</email></para> - </listitem> - - <listitem> - <para>Jim Geovedi - <email>negative@toxic.magnesium.net</email></para> - </listitem> - - <listitem> - <para>Jim Leppek - <email>jleppek@harris.com</email></para> - </listitem> - - <listitem> - <para>Jim Lowe - <email>james@cs.uwm.edu</email></para> - </listitem> - - <listitem> - <para>Jim Mattson - <email>jmattson@sonic.net</email></para> - </listitem> - - <listitem> - <para>Jim Mercer - <email>jim@komodo.reptiles.org</email></para> - </listitem> - - <listitem> - <para>Jim Pirzyk - <email>pirzyk@uiuc.edu</email></para> - </listitem> - - <listitem> - <para>Jim Shewmaker - <email>jim@bluenotch.com</email></para> - </listitem> - - <listitem> - <para>Jim Sloan - <email>odinn@atlantabiker.net</email></para> - </listitem> - - <listitem> - <para>Jim Wilson - <email>wilson@moria.cygnus.com</email></para> - </listitem> - - <listitem> - <para>Jimbo Bahooli - <email>griffin@blackhole.iceworld.org</email></para> - </listitem> - - <listitem> - <para>Jin Guojun - <email>jin@george.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Joachim Kuebart - <email>kuebart@mathematik.uni-ulm.de</email></para> - </listitem> - - <listitem> - <para>Joachim Strombergson - <email>Watchman@ludd.luth.se</email></para> - </listitem> - - <listitem> - <para>Joao Carlos Mendes Luis - <email>jonny@jonny.eng.br</email></para> - </listitem> - - <listitem> - <para>Jochen Pohl - <email>jpo.drs@sni.de</email></para> - </listitem> - - <listitem> - <para>Joe Abley - <email>jabley@automagic.org</email></para> - </listitem> - - <listitem> - <para>Joe Halpin - <email>joe.halpin@attbi.com</email></para> - </listitem> - - <listitem> - <para>Joe Jih-Shian Lu - <email>jslu@dns.ntu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Joe Kelsey - <email>joek@flyingcroc.net</email></para> - </listitem> - - <listitem> - <para>Joe Orthoefer - <email>j_orthoefer@tia.net</email></para> - </listitem> - - <listitem> - <para>Joe Traister - <email>traister@mojozone.org</email></para> - </listitem> - - <listitem> - <para>Joel Diaz - <email>joeldiaz@bellsouth.net</email></para> - </listitem> - - <listitem> - <para>Joel Faedi - <email>Joel.Faedi@esial.u-nancy.fr</email></para> - </listitem> - - <listitem> - <para>Joel Ray Holveck - <email>joelh@gnu.org</email></para> - </listitem> - - <listitem> - <para>Joel Sutton - <email>jsutton@bbcon.com.au</email></para> - </listitem> - - <listitem> - <para>Johan Granlund - <email>johan@granlund.nu</email></para> - </listitem> - - <listitem> - <para>Johan Larsson - <email>johan@moon.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Johann Kois - <email>J.Kois@web.de</email></para> - </listitem> - - <listitem> - <para>Johann Tonsing - <email>jtonsing@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>Johann van Selst - <email>johans@stack.nl</email></para> - </listitem> - - <listitem> - <para>Johannes 5 Joemann - <email>joemann@beefree.free.de</email></para> - </listitem> - - <listitem> - <para>Johannes Helander - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Johannes Stille - <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Beckett - <email>jbeckett@southern.edu</email></para> - </listitem> - - <listitem> - <para>John Beukema - <email>jbeukema@hk.super.net</email></para> - </listitem> - - <listitem> - <para>John Brezak - <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Capo - <email>jc@irbs.com</email></para> - </listitem> - - <listitem> - <para>John F. Woods - <email>jfw@jfwhome.funhouse.com</email></para> - </listitem> - - <listitem> - <para>John Goerzen - <email>jgoerzen@alexanderwohl.complete.org</email></para> - </listitem> - - <listitem> - <para>John Heidemann - <email>johnh@isi.edu</email></para> - </listitem> - - <listitem> - <para>John Hood - <email>cgull@owl.org</email></para> - </listitem> - - <listitem> - <para>John Kohl - <email>unknown</email></para> - </listitem> - - <listitem> - <para>John Lind - <email>john@starfire.mn.org</email></para> - </listitem> - - <listitem> - <para>John Mackin - <email>john@physiol.su.oz.au</email></para> - </listitem> - - <listitem> - <para>John Merryweather Cooper - <email>jmcoopr@webmail.bmi.net</email></para> - </listitem> - - <listitem> - <para>John Nielsen - <email>john@jnielsen.net</email></para> - </listitem> - - <listitem> - <para>John P - <email>johnp@lodgenet.com</email></para> - </listitem> - - <listitem> - <para>John Perry - <email>perry@vishnu.alias.net</email></para> - </listitem> - - <listitem> - <para>John Preisler - <email>john@vapornet.com</email></para> - </listitem> - - <listitem> - <para>John Reynolds - <email>jjreynold@home.com</email></para> - </listitem> - - <listitem> - <para>John Rochester - <email>jr@cs.mun.ca</email></para> - </listitem> - - <listitem> - <para>John Sadler - <email>john_sadler@alum.mit.edu</email></para> - </listitem> - - <listitem> - <para>John Saunders - <email>john@pacer.nlc.net.au</email></para> - </listitem> - - <listitem> - <para>John Wehle - <email>john@feith.com</email></para> - </listitem> - - <listitem> - <para>John Woods - <email>jfw@eddie.mit.edu</email></para> - </listitem> - - <listitem> - <para>Johny Mattsson - <email>lonewolf@flame.org</email></para> - </listitem> - - <listitem> - <para>Jon Morgan - <email>morgan@terminus.trailblazer.com</email></para> - </listitem> - - <listitem> - <para>Jon Nistor - <email>nistor@snickers.org</email></para> - </listitem> - - <listitem> - <para>Jon Wilson - <email>jon@phuq.co.uk</email></para> - </listitem> - - <listitem> - <para>Jonathan Belson - <email>jon@witchspace.com</email></para> - </listitem> - - <listitem> - <para>Jonathan Drews - <email>j.e.drews@att.net</email></para> - </listitem> - - <listitem> - <para>Jonathan H N Chin - <email>jc254@newton.cam.ac.uk</email></para> - </listitem> - - <listitem> - <para>Jonathan Hanna - <email>jh@pc-21490.bc.rogers.wave.ca</email></para> - </listitem> - - <listitem> - <para>Jonathan Lennox - <email>lennox@cs.columbia.edu</email></para> - </listitem> - - <listitem> - <para>Jonathan Pennington - <email>john@coastalgeology.org</email></para> - </listitem> - - <listitem> - <para>Jordan DeLong - <email>fracture@allusion.net</email></para> - </listitem> - - <listitem> - <para>Jorge Goncalves - <email>j@bug.fe.up.pt</email></para> - </listitem> - - <listitem> - <para>Jorge M. Goncalves - <email>ee96199@tom.fe.up.pt</email></para> - </listitem> - - <listitem> - <para>Jos Backus - <email>jos@catnook.com</email></para> - </listitem> - - <listitem> - <para>Jose Abelardo Martinez - <email>jamartinez@altern.org</email></para> - </listitem> - - <listitem> - <para>Jose Marques - <email>jose@nobody.org</email></para> - </listitem> - - <listitem> - <para>Josef Grosch - <email>jgrosch@superior.mooseriver.com</email></para> - </listitem> - - <listitem> - <para>Joseph Haga - <email>tuximus@tcsn.net</email></para> - </listitem> - - <listitem> - <para>Joseph Scott - <email>joseph@randomnetworks.com</email></para> - </listitem> - - <listitem> - <para>Joseph Stein - <email>joes@wstein.com</email></para> - </listitem> - - <listitem> - <para>Josh Elsasser - <email>jre@vineyard.net</email></para> - </listitem> - - <listitem> - <para>Josh Gilliam - <email>josh@quick.net</email></para> - </listitem> - - <listitem> - <para>Josh Tiefenbach - <email>josh@ican.net</email></para> - </listitem> - - <listitem> - <para>Joshua Goodall - <email>joshua@roughtrade.net</email></para> - </listitem> - - <listitem> - <para>Jostein Trondal - <email>jostein.trondal@sikkerhet.no</email></para> - </listitem> - - <listitem> - <para>Juan Salaverria - <email>rael@vectorstar.net</email></para> - </listitem> - - <listitem> - <para>Juergen Lock - <email>nox@jelal.hb.north.de</email></para> - </listitem> - - <listitem> - <para>Juha Inkari - <email>inkari@cc.hut.fi</email></para> - </listitem> - - <listitem> - <para>Juha Nygard - <email>juha.nygard1@netikka.fi</email></para> - </listitem> - - <listitem> - <para>Juha Ylitalo - <email>juha.ylitalo@iki.fi</email></para> - </listitem> - - <listitem> - <para>Jukka A. Ukkonen - <email>jau@iki.fi</email></para> - </listitem> - - <listitem> - <para>Julian Assange - <email>proff@suburbia.net</email></para> - </listitem> - - <listitem> - <para>Julian Coleman - <email>j.d.coleman@ncl.ac.uk</email></para> - </listitem> - - <listitem> - <para>&a.jhs;</para> - </listitem> - - <listitem> - <para>Julian Jenkins - <email>kaveman@magna.com.au</email></para> - </listitem> - - <listitem> - <para>Julian Stecklina - <email>der_julian@web.de</email></para> - </listitem> - - <listitem> - <para>Jung-uk Kim - <email>jkim@niksun.com</email></para> - </listitem> - - <listitem> - <para>Junichi Satoh - <email>junichi@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Junji SAKAI - <email>sakai@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Junya WATANABE - <email>junya-w@remus.dti.ne.jp</email></para> - </listitem> - - <listitem> - <para>Justas - <email>justas@mbank.lv</email></para> - </listitem> - - <listitem> - <para>Justin Stanford - <email>jus@security.za.net</email></para> - </listitem> - - <listitem> - <para>KANOU Hiroki - <email>kanou@khdd.net</email></para> - </listitem> - - <listitem> - <para>KATO Tsuguru - <email>tkato@prontomail.ne.jp</email></para> - </listitem> - - <listitem> - <para>KIMURA Shigekazu - <email>zau50357@lion.zero.ad.jp</email></para> - </listitem> - - <listitem> - <para>KUNISHIMA Takeo - <email>kunishi@c.oka-pu.ac.jp</email></para> - </listitem> - - <listitem> - <para>K.Higashino - <email>a00303@cc.hc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Kai Vorma - <email>vode@snakemail.hut.fi</email></para> - </listitem> - - <listitem> - <para>Kaleb S. Keithley - <email>kaleb@ics.com</email></para> - </listitem> - - <listitem> - <para>Kaneda Hiloshi - <email>vanitas@ma3.seikyou.ne.jp</email></para> - </listitem> - - <listitem> - <para>Kang-ming Liu - <email>gugod@gugod.org</email></para> - </listitem> - - <listitem> - <para>Kapil Chowksey - <email>kchowksey@hss.hns.com</email></para> - </listitem> - - <listitem> - <para>Karl Denninger - <email>karl@mcs.com</email></para> - </listitem> - - <listitem> - <para>Karl Dietz - <email>Karl.Dietz@triplan.com</email></para> - </listitem> - - <listitem> - <para>Karl Lehenbauer - <email>karl@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>Karsten W. Rohrbach - <email>karsten@rohrbach.de</email></para> - </listitem> - - <listitem> - <para>Kawanobe Koh - <email>kawanobe@st.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Kay Lehmann - <email>kay_lehmann@web.de</email></para> - </listitem> - - <listitem> - <para>Kees Jan Koster - <email>kjkoster@kjkoster.org</email></para> - </listitem> - - <listitem> - <para>Keith Bostic - <email>bostic@bostic.com</email></para> - </listitem> - - <listitem> - <para>Keith E. Walker - <email>kew@icehouse.net</email></para> - </listitem> - - <listitem> - <para>Keith Moore - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Keith Sklower - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ken Hornstein - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Ken Key - <email>key@cs.utk.edu</email></para> - </listitem> - - <listitem> - <para>Ken Mayer - <email>kmayer@freegate.com</email></para> - </listitem> - - <listitem> - <para>Ken McGlothlen - <email>mcglk@artlogix.com</email></para> - </listitem> - - <listitem> - <para>Ken Tom - <email>subd@mui.net</email></para> - </listitem> - - <listitem> - <para>Kenji Saito - <email>marukun@mx2.nisiq.net</email></para> - </listitem> - - <listitem> - <para>Kenji Tomita - <email>tommyk@da2.so-net.or.jp</email></para> - </listitem> - - <listitem> - <para>Kenneth Furge - <email>kenneth.furge@us.endress.com</email></para> - </listitem> - - <listitem> - <para>Kenneth Monville - <email>desmo@bandwidth.org</email></para> - </listitem> - - <listitem> - <para>Kenneth R. Westerback - <email>krw@tcn.net</email></para> - </listitem> - - <listitem> - <para>Kenneth Stailey - <email>kstailey@gnu.ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Kent Talarico - <email>kent@shipwreck.tsoft.net</email></para> - </listitem> - - <listitem> - <para>Kent Vander Velden - <email>graphix@iastate.edu</email></para> - </listitem> - - <listitem> - <para>Kentaro Inagaki - <email>JBD01226@niftyserve.ne.jp</email></para> - </listitem> - - <listitem> - <para>Kevin Bracey - <email>kbracey@art.acorn.co.uk</email></para> - </listitem> - - <listitem> - <para>Kevin Day - <email>toasty@dragondata.com</email></para> - </listitem> - - <listitem> - <para>Kevin Lahey - <email>kml@nas.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Kevin Meltzer - <email>perlguy@perlguy.com</email></para> - </listitem> - - <listitem> - <para>Kevin Street - <email>street@iname.com</email></para> - </listitem> - - <listitem> - <para>Kevin Van Maren - <email>vanmaren@fast.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Khairil Yusof - <email>kaeru@inigo-tech.com</email></para> - </listitem> - - <listitem> - <para>Killer - <email>killer@prosalg.no</email></para> - </listitem> - - <listitem> - <para>Kim Scarborough - <email>sluggo@unknown.nu</email></para> - </listitem> - - <listitem> - <para>Fumihiko Kimura - <email>jfkimura@yahoo.co.jp</email></para> - </listitem> - - <listitem> - <para>Kimura Fuyuki - <email>fuyuki@hadaly.org</email></para> - </listitem> - - <listitem> - <para>Kiril Mitev - <email>kiril@ideaglobal.com</email></para> - </listitem> - - <listitem> - <para>Kirill Bezzubets - <email>kirill@solaris.ru</email></para> - </listitem> - - <listitem> - <para>Kiroh HARADA - <email>kiroh@kh.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Klaus Goger - <email>klaus.goger@reflex.at</email></para> - </listitem> - - <listitem> - <para>Klaus Herrmann - <email>klaus.herrmann@gmx.net</email></para> - </listitem> - - <listitem> - <para>Klaus Klein - <email>kleink@layla.inka.de</email></para> - </listitem> - - <listitem> - <para>Klaus-J. Wolf - <email>Yanestra@t-online.de</email></para> - </listitem> - - <listitem> - <para>Koichi Sato - <email>copan@ppp.fastnet.or.jp</email></para> - </listitem> - - <listitem> - <para>Konrad Heuer - <email>kheuer@gwdu60.gwdg.de</email></para> - </listitem> - - <listitem> - <para>Konstantin Chuguev - <email>Konstantin.Chuguev@dante.org.uk</email></para> - </listitem> - - <listitem> - <para>Konstantin Reznichenko - <email>kot@premierbank.dp.ua</email></para> - </listitem> - - <listitem> - <para>Koop Mast - <email>einekoai@chello.nl</email></para> - </listitem> - - <listitem> - <para>Kostya Lukin - <email>lukin@okbmei.msk.su</email></para> - </listitem> - - <listitem> - <para>Kouichi Hirabayashi - <email>kh@mogami-wire.co.jp</email></para> - </listitem> - - <listitem> - <para>Kris Dow - <email>kris@vilnya.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Kurt D. Zeilenga - <email>Kurt@Boolean.NET</email></para> - </listitem> - - <listitem> - <para>Kurt Olsen - <email>kurto@tiny.mcs.usu.edu</email></para> - </listitem> - - <listitem> - <para>Kyle Martin - <email>mkm@ieee.org</email></para> - </listitem> - - <listitem> - <para>L. Jonas Olsson - <email>ljo@ljo-slip.DIALIN.CWRU.Edu</email></para> - </listitem> - - <listitem> - <para>Landon Fuller - <email>landonf@opendarwin.org</email></para> - </listitem> - - <listitem> - <para>Lapo Luchini - <email>lapo@lapo.it</email></para> - </listitem> - - <listitem> - <para>Larry Altneu - <email>larry@ALR.COM</email></para> - </listitem> - - <listitem> - <para>Larry Rosenman - <email>ler@lerctr.org</email></para> - </listitem> - - <listitem> - <para>Lars Bernhardsson - <email>lab@fnurt.net</email></para> - </listitem> - - <listitem> - <para>Lars Eggert - <email>lars.eggert@gmx.net</email></para> - </listitem> - - <listitem> - <para>Lars Erik Gullerud - <email>lerik@nolink.net</email></para> - </listitem> - - <listitem> - <para>Lasse L. Johnsen - <email>lasse@freebsdcluster.org</email></para> - </listitem> - - <listitem> - <para>Laurence Lopez - <email>lopez@mv.mv.com</email></para> - </listitem> - - <listitem> - <para>Lauri Watts - <email>lauri@kde.org</email></para> - </listitem> - - <listitem> - <para>Laust S. Jespersen - <email>L@ust.dk</email></para> - </listitem> - - <listitem> - <para>Lee Cremeans - <email>lcremean@tidalwave.net</email></para> - </listitem> - - <listitem> - <para>Lefteris Chatzibarbas - <email>lefcha@hellug.gr</email></para> - </listitem> - - <listitem> - <para>Leo Kim - <email>leo@florida.sarang.net</email></para> - </listitem> - - <listitem> - <para>Len Sassaman - <email>rabbi@abditum.com</email></para> - </listitem> - - <listitem> - <para>Lewis Thompson - <email>purple@lewiz.net</email></para> - </listitem> - - <listitem> - <para>Li-lun Wang - <email>llwang@infor.org</email></para> - </listitem> - - <listitem> - <para>Liam Foy - <email>liamfoy@sepulcrum.org</email></para> - </listitem> - - <listitem> - <para>Liang Tai-hwa - <email>avatar@www.mmlab.cse.yzu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Lon Willett - <email>lon%softt.uucp@math.utah.edu</email></para> - </listitem> - - <listitem> - <para>Louis A. Mamakos - <email>loiue@TransSys.com</email></para> - </listitem> - - <listitem> - <para>Lowell Gilbert - <email>lowell@world.std.com</email></para> - </listitem> - - <listitem> - <para>Lucas James - <email>Lucas.James@ldjpc.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Lyndon Nerenberg - <email>lyndon@orthanc.ab.ca</email></para> - </listitem> - - <listitem> - <para>M. L. Dodson - <email>bdodson@scms.utmb.EDU</email></para> - </listitem> - - <listitem> - <para>M.C. Wong - <email>unknown</email></para> - </listitem> - - <listitem> - <para>MOROHOSHI Akihiko - <email>moro@race.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Machiel Mastenbroek - <email>machiel_mastenbroek@hotmail.com</email></para> - </listitem> - - <listitem> - <para>Magnus Enbom - <email>dot@tinto.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Mahesh Neelakanta - <email>mahesh@gcomm.com</email></para> - </listitem> - - <listitem> - <para>Makoto WATANABE - <email>watanabe@zlab.phys.nagoya-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Makoto YAMAKURA - <email>makoto@pinpott.spnet.ne.jp</email></para> - </listitem> - - <listitem> - <para>Malte Lance - <email>malte.lance@gmx.net</email></para> - </listitem> - - <listitem> - <para>Manu Iyengar - <email>iyengar@grunthos.pscwa.psca.com</email></para> - </listitem> - - <listitem> - <para>Marc Frajola - <email>marc@dev.com</email></para> - </listitem> - - <listitem> - <para>Marc Ramirez - <email>mrami@mramirez.sy.yale.edu</email></para> - </listitem> - - <listitem> - <para>Marc Recht - <email>marc@informatik.uni-bremen.de</email></para> - </listitem> - - <listitem> - <para>Marc Silver - <email>marcs@draenor.org</email></para> - </listitem> - - <listitem> - <para>Marc Slemko - <email>marcs@znep.com</email></para> - </listitem> - - <listitem> - <para>Marc van Kempen - <email>wmbfmk@urc.tue.nl</email></para> - </listitem> - - <listitem> - <para>Marc van Woerkom - <email>van.woerkom@netcologne.de</email></para> - </listitem> - - <listitem> - <para>Marcin Cieslak - <email>saper@system.pl</email></para> - </listitem> - - <listitem> - <para>Marco Molteni - <email>molter@tin.it</email></para> - </listitem> - - <listitem> - <para>Marcus vA - <email>mva121@gmx.net</email></para> - </listitem> - - <listitem> - <para>Mark Andrews - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mark Cammidge - <email>mark@gmtunx.ee.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Mark Diekhans - <email>markd@grizzly.com</email></para> - </listitem> - - <listitem> - <para>Mark Huizer - <email>xaa@stack.nl</email></para> - </listitem> - - <listitem> - <para>Mark J. Taylor - <email>mtaylor@cybernet.com</email></para> - </listitem> - - <listitem> - <para>Mark Knight - <email>markk@knigma.org</email></para> - </listitem> - - <listitem> - <para>Mark Krentel - <email>krentel@rice.edu</email></para> - </listitem> - - <listitem> - <para>Mark Mayo - <email>markm@vmunix.com</email></para> - </listitem> - - <listitem> - <para>Mark Thompson - <email>thompson@tgsoft.com</email></para> - </listitem> - - <listitem> - <para>Mark Tinguely - <email>tinguely@plains.nodak.edu</email></para> - </listitem> - - <listitem> - <para>Mark Treacy - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mark Valentine - <email>mark@thuvia.org</email></para> - </listitem> - - <listitem> - <para>Mark A. Wicks - <email>mwicks@kettering.edu</email></para> - </listitem> - - <listitem> - <para>Markus Holmberg - <email>saska@acc.umu.se</email></para> - </listitem> - - <listitem> - <para>Martin Birgmeier - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Martin Hinner - <email>mhi@linux.gyarab.cz</email></para> - </listitem> - - <listitem> - <para>Martin Ibert - <email>mib@ppe.bb-data.de</email></para> - </listitem> - - <listitem> - <para>Martin Kammerhofer - <email>dada@sbox.tu-graz.ac.at</email></para> - </listitem> - - <listitem> - <para>Martin Karlsson - <email>martin.karlsson@visit.se</email></para> - </listitem> - - <listitem> - <para>Martin Klaffenboeck - <email>martin.klaffenboeck@gmx.at</email></para> - </listitem> - - <listitem> - <para>Martin Kraft - <email>martin.kraft@fal.de</email></para> - </listitem> - - <listitem> - <para>Martin Matuska - <email>martin@tradex.sk</email></para> - </listitem> - - <listitem> - <para>Martin Minkus - <email>diskiller@cnbinc.com</email></para> - </listitem> - - <listitem> - <para>Martin Preuss - <email>martin@libchipcard.de</email></para> - </listitem> - - <listitem> - <para>Martti Kuparinen - <email>martti.kuparinen@ericsson.com</email></para> - </listitem> - - <listitem> - <para>Marwan Burelle - <email>marwan.burelle@lri.fr</email></para> - </listitem> - - <listitem> - <para>Masachika ISHIZUKA - <email>ishizuka@isis.min.ntt.jp</email></para> - </listitem> - - <listitem> - <para>Masahiro Sekiguchi - <email>seki@sysrap.cs.fujitsu.co.jp</email></para> - </listitem> - - <listitem> - <para>Masahiro TAKEMURA - <email>mastake@msel.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Masakazu HIGAKI - <email>higamasa@dream.com</email></para> - </listitem> - - <listitem> - <para>Masanobu Saitoh - <email>msaitoh@spa.is.uec.ac.jp</email></para> - </listitem> - - <listitem> - <para>Masanori Kanaoka - <email>kana@saijo.mke.mei.co.jp</email></para> - </listitem> - - <listitem> - <para>Masanori Kiriake - <email>seiken@ARGV.AC</email></para> - </listitem> - - <listitem> - <para>Masatoshi TAMURA - <email>tamrin@shinzan.kuee.kyoto-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Mats Lofkvist - <email>mal@algonet.se</email></para> - </listitem> - - <listitem> - <para>Matt Bartley - <email>mbartley@lear35.cytex.com</email></para> - </listitem> - - <listitem> - <para>Matt Dawson - <email>matt@mattsnetwork.co.uk</email></para> - </listitem> - - <listitem> - <para>Matt Douhan - <email>matt@athame.co.uk</email></para> - </listitem> - - <listitem> - <para>Matt Heckaman - <email>matt@LUCIDA.QC.CA</email></para> - </listitem> - - <listitem> - <para>Matt Jibson - <email>dolmant@dolmant.net</email></para> - </listitem> - - <listitem> - <para>Matt Lancereau - <email>matt@rimasec.net</email></para> - </listitem> - - <listitem> - <para>Matt Loschert - <email>loschert@servint.com</email></para> - </listitem> - - <listitem> - <para>Matt Peterson - <email>matt@peterson.org</email></para> - </listitem> - - <listitem> - <para>Matt Thomas - <email>matt@3am-software.com</email></para> - </listitem> - - <listitem> - <para>Matt White - <email>mwhite+@CMU.EDU</email></para> - </listitem> - - <listitem> - <para>Matthew Braithwaite - <email>mab@red-bean.com</email></para> - </listitem> - - <listitem> - <para>Matthew C. Mead - <email>mmead@Glock.COM</email></para> - </listitem> - - <listitem> - <para>Matthew Cashdollar - <email>mattc@rfcnet.com</email></para> - </listitem> - - <listitem> - <para>Matthew Emmerton - <email>root@gabby.gsicomp.on.ca</email></para> - </listitem> - - <listitem> - <para>Matthew Flatt - <email>mflatt@cs.rice.edu</email></para> - </listitem> - - <listitem> - <para>Matthew Fuller - <email>fullermd@over-yonder.net</email></para> - </listitem> - - <listitem> - <para>Matthew George - <email>mdg@secureworks.net</email></para> - </listitem> - - <listitem> - <para>Matthew Seaman - <email>m.seaman@infracaninophile.co.uk</email></para> - </listitem> - - <listitem> - <para>Matthew Stein - <email>matt@bdd.net</email></para> - </listitem> - - <listitem> - <para>Matthew West - <email>mwest@uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Matthias Andree - <email>matthias.andree@gmx.de</email></para> - </listitem> - - <listitem> - <para>Matthias Pfaller - <email>leo@dachau.marco.de</email></para> - </listitem> - - <listitem> - <para>Matthias Scheler - <email>tron@netbsd.org</email></para> - </listitem> - - <listitem> - <para>Matthias Schündehütte - <email>msch@snafu.de</email></para> - </listitem> - - <listitem> - <para>Matthias Teege - <email>mteege.de</email></para> - </listitem> - - <listitem> - <para>Mattias Gronlund - <email>Mattias.Gronlund@sa.erisoft.se</email></para> - </listitem> - - <listitem> - <para>Mattias Pantzare - <email>pantzer@ludd.luth.se</email></para> - </listitem> - - <listitem> - <para>Maurice Castro - <email>maurice@planet.serc.rmit.edu.au</email></para> - </listitem> - - <listitem> - <para>Max Euston - <email>meuston@jmrodgers.com</email></para> - </listitem> - - <listitem> - <para>Maxim Bolotin - <email>max@rsu.ru</email></para> - </listitem> - - <listitem> - <para>Maxim Tuliuk - <email>mt@primats.org.ua</email></para> - </listitem> - - <listitem> - <para>Maxime Romano - <email>verbophobe@hotmail.com</email></para> - </listitem> - - <listitem> - <para>Meikel Brandmeyer - <email>Brandels_Mikesh@web.de</email></para> - </listitem> - - <listitem> - <para>Meyer Wolfsheim - <email>wolf@priori.net</email></para> - </listitem> - - <listitem> - <para>Micha Class - <email>michael_class@hpbbse.bbn.hp.com</email></para> - </listitem> - - <listitem> - <para>Michael A. Kohn - <email>naken@naken.cc</email></para> - </listitem> - - <listitem> - <para>Michael Alyn Miller - <email>malyn@strangeGizmo.com</email></para> - </listitem> - - <listitem> - <para>Michael Bushkov - <email>bushman@rsu.ru</email></para> - </listitem> - - <listitem> - <para>Michael Butler - <email>imb@scgt.oz.au</email></para> - </listitem> - - <listitem> - <para>Michael Butschky - <email>butsch@computi.erols.com</email></para> - </listitem> - - <listitem> - <para>Michael C. Shultz - <email>ringworm@inbox.lv</email></para> - </listitem> - - <listitem> - <para>Michael Clay - <email>mclay@weareb.org</email></para> - </listitem> - - <listitem> - <para>Michael Collette - <email>metrol@metrol.net</email></para> - </listitem> - - <listitem> - <para>Michael Ebert - <email>ebert@informatik.unibw-muenchen.de</email></para> - </listitem> - - <listitem> - <para>Michael Edenfield - <email>kutulu@kutulu.org</email></para> - </listitem> - - <listitem> - <para>Michael Galassi - <email>nerd@percival.rain.com</email></para> - </listitem> - - <listitem> - <para>Michael Hancock - <email>michaelh@cet.co.jp</email></para> - </listitem> - - <listitem> - <para>Michael Handler - <email>handler@grendel.net</email></para> - </listitem> - - <listitem> - <para>Michael Hohmuth - <email>hohmuth@inf.tu-dresden.de</email></para> - </listitem> - - <listitem> - <para>Michael Iatrou - <email>m_iatrou@freemail.gr</email></para> - </listitem> - - <listitem> - <para>Michael Johnson - <email>ahze@ahze.net</email></para> - </listitem> - - <listitem> - <para>Michael Lyngbøl - <email>michael@lyngbol.dk</email></para> - </listitem> - - <listitem> - <para>Michael Neumann - <email>mneumann@ntecs.de</email></para> - </listitem> - - <listitem> - <para>Michael Perlman - <email>canuck@caam.rice.edu</email></para> - </listitem> - - <listitem> - <para>Michael Petry - <email>petry@netwolf.NetMasters.com</email></para> - </listitem> - - <listitem> - <para>Michael Ranner - <email>mranner@inode.at</email></para> - </listitem> - - <listitem> - <para>Michael Sardo - <email>jaeger16@yahoo.com</email></para> - </listitem> - - <listitem> - <para>Michael Schout - <email>mschout@gkg.net</email></para> - </listitem> - - <listitem> - <para>Michael Searle - <email>searle@longacre.demon.co.uk</email></para> - </listitem> - - <listitem> - <para>Michael Urban - <email>murban@tznet.com</email></para> - </listitem> - - <listitem> - <para>Michael Vasilenko - <email>acid@stu.cn.ua</email></para> - </listitem> - - <listitem> - <para>Michal Listos - <email>mcl@Amnesiac.123.org</email></para> - </listitem> - - <listitem> - <para>Michal Pasternak - <email>dotz@irc.pl</email></para> - </listitem> - - <listitem> - <para>Michele Possamai - <email>possamai@xs4all.nl</email></para> - </listitem> - - <listitem> - <para>Michio Karl Jinbo - <email>karl@marcer.nagaokaut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Miguel Angel Sagreras - <email>msagre@cactus.fi.uba.ar</email></para> - </listitem> - - <listitem> - <para>Miguel Mendez - <email>flynn@energyhq.homeip.net</email></para> - </listitem> - - <listitem> - <para>Mihoko Tanaka - <email>m_tonaka@pa.yokogawa.co.jp</email></para> - </listitem> - - <listitem> - <para>Mij - <email>mij@bitchx.it</email></para> - </listitem> - - <listitem> - <para>Mika Nystrom - <email>mika@cs.caltech.edu</email></para> - </listitem> - - <listitem> - <para>Mikael Hybsch - <email>micke@dynas.se</email></para> - </listitem> - - <listitem> - <para>Mikael Karpberg - <email>karpen@ocean.campus.luth.se</email></para> - </listitem> - - <listitem> - <para>Mike Bristow - <email>mike@urgle.com</email></para> - </listitem> - - <listitem> - <para>Mike Del - <email>repenting@hotmail.com</email></para> - </listitem> - - <listitem> - <para>Mike Durian - <email>durian@plutotech.com</email></para> - </listitem> - - <listitem> - <para>Mike Durkin - <email>mdurkin@tsoft.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Mike E. Matsnev - <email>mike@azog.cs.msu.su</email></para> - </listitem> - - <listitem> - <para>Mike Evans - <email>mevans@candle.com</email></para> - </listitem> - - <listitem> - <para>Mike Futerko - <email>mike@LITech.lviv.ua</email></para> - </listitem> - - <listitem> - <para>Mike Grupenhoff - <email>kashmir@umiacs.umd.edu</email></para> - </listitem> - - <listitem> - <para>Mike Harding - <email>mvh@ix.netcom.com</email></para> - </listitem> - - <listitem> - <para>Mike Hibler - <email>mike@marker.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Mike Karels - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Mike McGaughey - <email>mmcg@cs.monash.edu.au</email></para> - </listitem> - - <listitem> - <para>Mike Meyer - <email>mwm@mired.org</email></para> - </listitem> - - <listitem> - <para>Mike Mitchell - <email>mitchell@ref.tfs.com</email></para> - </listitem> - - <listitem> - <para>Mike Murphy - <email>mrm@alpharel.com</email></para> - </listitem> - - <listitem> - <para>Mike Peck - <email>mike@binghamton.edu</email></para> - </listitem> - - <listitem> - <para>Mike Sherwood - <email>mike@fate.com</email></para> - </listitem> - - <listitem> - <para>Mike Spengler - <email>mks@msc.edu</email></para> - </listitem> - - <listitem> - <para>Mikhail A. Sokolov - <email>mishania@demos.su</email></para> - </listitem> - - <listitem> - <para>Ming-I Hseh - <email>PA@FreeBSD.ee.Ntu.edu.TW</email></para> - </listitem> - - <listitem> - <para>Mitsuru Yoshida - <email>mitsuru@riken.go.jp</email></para> - </listitem> - - <listitem> - <para>Monte Mitzelfelt - <email>monte@gonefishing.org</email></para> - </listitem> - - <listitem> - <para>Morgan Davis - <email>root@io.cts.com</email></para> - </listitem> - - <listitem> - <para>Mostyn Lewis - <email>mostyn@mrl.com</email></para> - </listitem> - - <listitem> - <para>Motomichi Matsuzaki - <email>mzaki@e-mail.ne.jp</email></para> - </listitem> - - <listitem> - <para>Motoyuki Kasahara - <email>m-kasahr@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>Munish Chopra - <email>munish@engmail.uwaterloo.ca</email></para> - </listitem> - - <listitem> - <para>Mykola Khotyaintsev - <email>ko@irfu.se</email></para> - </listitem> - - <listitem> - <para>N.G.Smith - <email>ngs@sesame.hensa.ac.uk</email></para> - </listitem> - - <listitem> - <para>NAGAO Tadaaki - <email>nagao@cs.titech.ac.jp</email></para> - </listitem> - - <listitem> - <para>NAKAJI Hiroyuki - <email>nakaji@tutrp.tut.ac.jp</email></para> - </listitem> - - <listitem> - <para>NAKAMURA Kazushi - <email>nkazushi@highway.or.jp</email></para> - </listitem> - - <listitem> - <para>NAKAMURA Motonori - <email>motonori@econ.kyoto-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>NIIMI Satoshi - <email>sa2c@and.or.jp</email></para> - </listitem> - - <listitem> - <para>NOKUBI Hirotaka - <email>h-nokubi@yyy.or.jp</email></para> - </listitem> - - <listitem> - <para>Nadav Eiron - <email>nadav@barcode.co.il</email></para> - </listitem> - - <listitem> - <para>Nanbor Wang - <email>nw1@cs.wustl.edu</email></para> - </listitem> - - <listitem> - <para>Naofumi Honda - <email>honda@Kururu.math.sci.hokudai.ac.jp</email></para> - </listitem> - - <listitem> - <para>Naoki Hamada - <email>nao@tom-yam.or.jp</email></para> - </listitem> - - <listitem> - <para>Narvi - <email>narvi@haldjas.folklore.ee</email></para> - </listitem> - - <listitem> - <para>Nathan Dorfman - <email>nathan@rtfm.net</email></para> - </listitem> - - <listitem> - <para>Neal Fachan - <email>kneel@ishiboo.com</email></para> - </listitem> - - <listitem> - <para>Ned Wolpert - <email>wolpert@codeheadsystems.com</email></para> - </listitem> - - <listitem> - <para>Niall Smart - <email>rotel@indigo.ie</email></para> - </listitem> - - <listitem> - <para>Nicholas Esborn - <email>nick@netdot.net</email></para> - </listitem> - - <listitem> - <para>Nick Barnes - <email>Nick.Barnes@pobox.com</email></para> - </listitem> - - <listitem> - <para>Nick Handel - <email>nhandel@NeoSoft.com</email></para> - </listitem> - - <listitem> - <para>Nick Hilliard - <email>nick@foobar.org</email></para> - </listitem> - - <listitem> - <para>Nick Johnson - <email>freebsd@spatula.net</email></para> - </listitem> - - <listitem> - <para>Nick Leuta - <email>skynick@stu.lipetsk.ru</email></para> - </listitem> - - <listitem> - <para>Nick Williams - <email>njw@cs.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Nickolay N. Dudorov - <email>nnd@itfs.nsk.su</email></para> - </listitem> - - <listitem> - <para>Nicola Vitale - <email>nivit@users.sourceforge.net</email></para> - </listitem> - - <listitem> - <para>Nicolas Jombart - <email>ecu@ipv42.net</email></para> - </listitem> - - <listitem> - <para>Niklas Hallqvist - <email>niklas@filippa.appli.se</email></para> - </listitem> - - <listitem> - <para>Nils M. Holm - <email>nmh@t3x.org</email></para> - </listitem> - - <listitem> - <para>Nisha Talagala - <email>nisha@cs.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>No Name - <email>ZW6T-KND@j.asahi-net.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>adrian@virginia.edu</email></para> - </listitem> - - <listitem> - <para>No Name - <email>alex@elvisti.kiev.ua</email></para> - </listitem> - - <listitem> - <para>No Name - <email>anto@netscape.net</email></para> - </listitem> - - <listitem> - <para>No Name - <email>bobson@egg.ics.nitch.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>bovynf@awe.be</email></para> - </listitem> - - <listitem> - <para>No Name - <email>burg@is.ge.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>chris@gnome.co.uk</email></para> - </listitem> - - <listitem> - <para>No Name - <email>colsen@usa.net</email></para> - </listitem> - - <listitem> - <para>No Name - <email>coredump@nervosa.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>dannyman@arh0300.urh.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>No Name - <email>davids@SECNET.COM</email></para> - </listitem> - - <listitem> - <para>No Name - <email>derek@free.org</email></para> - </listitem> - - <listitem> - <para>No Name - <email>dvv@sprint.net</email></para> - </listitem> - - <listitem> - <para>No Name - <email>enami@ba2.so-net.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>flash@eru.tubank.msk.su</email></para> - </listitem> - - <listitem> - <para>No Name - <email>flash@hway.ru</email></para> - </listitem> - - <listitem> - <para>No Name - <email>fn@pain.csrv.uidaho.edu</email></para> - </listitem> - - <listitem> - <para>No Name - <email>frf@xocolatl.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>gclarkii@netport.neosoft.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>gordon@sheaky.lonestar.org</email></para> - </listitem> - - <listitem> - <para>No Name - <email>graaf@iae.nl</email></para> - </listitem> - - <listitem> - <para>No Name - <email>greg@greg.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>grossman@cygnus.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>gusw@fub46.zedat.fu-berlin.de</email></para> - </listitem> - - <listitem> - <para>No Name - <email>hfir@math.rochester.edu</email></para> - </listitem> - - <listitem> - <para>No Name - <email>hnokubi@yyy.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>iaint@css.tuu.utas.edu.au</email></para> - </listitem> - - <listitem> - <para>No Name - <email>invis@visi.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>ishisone@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>iverson@lionheart.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>jpt@magic.net</email></para> - </listitem> - - <listitem> - <para>No Name - <email>junker@jazz.snu.ac.kr</email></para> - </listitem> - - <listitem> - <para>No Name - <email>k-sugyou@ccs.mt.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>kenji@reseau.toyonaka.osaka.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>kfurge@worldnet.att.net</email></para> - </listitem> - - <listitem> - <para>No Name - <email>lh@aus.org</email></para> - </listitem> - - <listitem> - <para>No Name - <email>lhecking@nmrc.ucc.ie</email></para> - </listitem> - - <listitem> - <para>No Name - <email>mrgreen@mame.mu.oz.au</email></para> - </listitem> - - <listitem> - <para>No Name - <email>nakagawa@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>No Name - <email>ohki@gssm.otsuka.tsukuba.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>owaki@st.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>pechter@shell.monmouth.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>pete@pelican.pelican.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>pritc003@maroon.tc.umn.edu</email></para> - </listitem> - - <listitem> - <para>No Name - <email>risner@stdio.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>root@ns2.redline.ru</email></para> - </listitem> - - <listitem> - <para>No Name - <email>root@uglabgw.ug.cs.sunysb.edu</email></para> - </listitem> - - <listitem> - <para>No Name - <email>stephen.ma@jtec.com.au</email></para> - </listitem> - - <listitem> - <para>No Name - <email>sumii@is.s.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>takas-su@is.aist-nara.ac.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>tjevans@raleigh.ibm.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>tony-o@iij.ad.jp amurai@spec.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>torii@tcd.hitachi.co.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>uenami@imasy.or.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>uhlar@netlab.sk</email></para> - </listitem> - - <listitem> - <para>No Name - <email>vode@hut.fi</email></para> - </listitem> - - <listitem> - <para>No Name - <email>wlloyd@mpd.ca</email></para> - </listitem> - - <listitem> - <para>No Name - <email>wlr@furball.wellsfargo.com</email></para> - </listitem> - - <listitem> - <para>No Name - <email>wmbfmk@urc.tue.nl</email></para> - </listitem> - - <listitem> - <para>No Name - <email>yamagata@nwgpc.kek.jp</email></para> - </listitem> - - <listitem> - <para>No Name - <email>ziggy@ryan.org</email></para> - </listitem> - - <listitem> - <para>Nobuhiro Yasutomi - <email>nobu@psrc.isac.co.jp</email></para> - </listitem> - - <listitem> - <para>Nobuyuki Koganemaru - <email>kogane@koganemaru.co.jp</email></para> - </listitem> - - <listitem> - <para>Norio Suzuki - <email>nosuzuki@e-mail.ne.jp</email></para> - </listitem> - - <listitem> - <para>Noritaka Ishizumi - <email>graphite@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Noriyuki Soda - <email>soda@sra.co.jp</email></para> - </listitem> - - <listitem> - <para>Oddbjorn Steffensen - <email>oddbjorn@tricknology.org</email></para> - </listitem> - - <listitem> - <para>Oh Junseon - <email>hollywar@mail.holywar.net</email></para> - </listitem> - - <listitem> - <para>Olaf Wagner - <email>wagner@luthien.in-berlin.de</email></para> - </listitem> - - <listitem> - <para>Oleg Semyonov - <email>os@altavista.net</email></para> - </listitem> - - <listitem> - <para>Oleg Sharoiko - <email>os@rsu.ru</email></para> - </listitem> - - <listitem> - <para>Oleg V. Volkov - <email>rover@lglobus.ru</email></para> - </listitem> - - <listitem> - <para>Olexander Kunytsa - <email>kunia@wolf.istc.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Oliver Breuninger - <email>ob@seicom.NET</email></para> - </listitem> - - <listitem> - <para>Oliver Fischer - <email>plexus@snafu.de</email></para> - </listitem> - - <listitem> - <para>Oliver Friedrichs - <email>oliver@secnet.com</email></para> - </listitem> - - <listitem> - <para>Oliver Fromme - <email>oliver.fromme@heim3.tu-clausthal.de</email></para> - </listitem> - - <listitem> - <para>Oliver Helmling - <email>oliver.helmling@stud.uni-bayreuth.de</email></para> - </listitem> - - <listitem> - <para>Oliver Laumann - <email>net@informatik.uni-bremen.de</email></para> - </listitem> - - <listitem> - <para>Oliver Oberdorf - <email>oly@world.std.com</email></para> - </listitem> - - <listitem> - <para>Olivier Tharan - <email>olive@oban.frmug.org</email></para> - </listitem> - - <listitem> - <para>Olof Johansson - <email>offe@ludd.luth.se</email></para> - </listitem> - - <listitem> - <para>Omer Faruk Sen - <email>ofsen@enderunix.org</email></para> - </listitem> - - <listitem> - <para>Ozkan KIRIK - <email>ozkan@enderunix.org</email></para> - </listitem> - - <listitem> - <para>Pace Willisson - <email>pace@blitz.com</email></para> - </listitem> - - <listitem> - <para>Paco Rosich - <email>rosich@modico.eleinf.uv.es</email></para> - </listitem> - - <listitem> - <para>Palle Girgensohn - <email>girgen@partitur.se</email></para> - </listitem> - - <listitem> - <para>Panagiotis Astithas - <email>past@noc.ntua.gr</email></para> - </listitem> - - <listitem> - <para>Paolo Flag - <email>flag@gufi.org</email></para> - </listitem> - - <listitem> - <para>Parag Patel - <email>parag@cgt.com</email></para> - </listitem> - - <listitem> - <para>Pascal Pederiva - <email>pascal@zuo.dec.com</email></para> - </listitem> - - <listitem> - <para>Pasvorn Boonmark - <email>boonmark@juniper.net</email></para> - </listitem> - - <listitem> - <para>Patrick Alken - <email>cosine@ellipse.mcs.drexel.edu</email></para> - </listitem> - - <listitem> - <para>Patrick Atamaniuk - <email>atamaniuk-ports@frobs.net</email></para> - </listitem> - - <listitem> - <para>Patrick Bihan-Faou - <email>patrick@mindstep.com</email></para> - </listitem> - - <listitem> - <para>Patrick Hausen - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Patrick MARIE - <email>mycroft@virgaria.org</email></para> - </listitem> - - <listitem> - <para>Patrick Powell - <email>papowell@astart.com</email></para> - </listitem> - - <listitem> - <para>Patrick Rinke - <email>patrick@rinke-bochum.de</email></para> - </listitem> - - <listitem> - <para>Patrick Seal - <email>patseal@hyperhost.net</email></para> - </listitem> - - <listitem> - <para>Paul Antonov - <email>apg@demos.su</email></para> - </listitem> - - <listitem> - <para>Paul Chvostek - <email>paul@it.ca</email></para> - </listitem> - - <listitem> - <para>Paul Dlug - <email>paul@aps.org</email></para> - </listitem> - - <listitem> - <para>Paul F. Werkowski - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Paul Fox - <email>pgf@foxharp.boston.ma.us</email></para> - </listitem> - - <listitem> - <para>Paul Koch - <email>koch@thehub.com.au</email></para> - </listitem> - - <listitem> - <para>Paul Kranenburg - <email>pk@NetBSD.org</email></para> - </listitem> - - <listitem> - <para>Paul M. Lambert - <email>plambert@plambert.net</email></para> - </listitem> - - <listitem> - <para>Paul Mackerras - <email>paulus@cs.anu.edu.au</email></para> - </listitem> - - <listitem> - <para>Paul Popelka - <email>paulp@uts.amdahl.com</email></para> - </listitem> - - <listitem> - <para>Paul S. LaFollette, Jr. - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Paul Sandys - <email>myj@nyct.net</email></para> - </listitem> - - <listitem> - <para>Paul T. Root - <email>proot@horton.iaces.com</email></para> - </listitem> - - <listitem> - <para>Paul Vixie - <email>paul@vix.com</email></para> - </listitem> - - <listitem> - <para>Paulo Menezes - <email>paulo@isr.uc.pt</email></para> - </listitem> - - <listitem> - <para>Paulo Menezes - <email>pm@dee.uc.pt</email></para> - </listitem> - - <listitem> - <para>Pavel Janik - <email>Pavel@Janik.cz</email></para> - </listitem> - - <listitem> - <para>Pavel Novikov - <email>pavel@ext.by</email></para> - </listitem> - - <listitem> - <para>Pavel Veretennikov - <email>vermut@kid.lv</email></para> - </listitem> - - <listitem> - <para>Pedro A M Vazquez - <email>vazquez@IQM.Unicamp.BR</email></para> - </listitem> - - <listitem> - <para>Pedro Giffuni - <email>giffunip@asme.org</email></para> - </listitem> - - <listitem> - <para>Per Wigren - <email>wigren@home.se</email></para> - </listitem> - - <listitem> - <para>Pete Bentley - <email>pete@demon.net</email></para> - </listitem> - - <listitem> - <para>Peter Avalos - <email>pavalos@theshell.com</email></para> - </listitem> - - <listitem> - <para>Peter Childs - <email>pjchilds@imforei.apana.org.au</email></para> - </listitem> - - <listitem> - <para>Peter Cornelius - <email>pc@inr.fzk.de</email></para> - </listitem> - - <listitem> - <para>Peter Haight - <email>peterh@prognet.com</email></para> - </listitem> - - <listitem> - <para>Peter Jeremy - <email>peter.jeremy@alcatel.com.au</email></para> - </listitem> - - <listitem> - <para>Peter Kolmisoppi - <email>growspd@brokep.com</email></para> - </listitem> - - <listitem> - <para>Peter M. Chen - <email>pmchen@eecs.umich.edu</email></para> - </listitem> - - <listitem> - <para>Peter Much - <email>peter@citylink.dinoex.sub.org</email></para> - </listitem> - - <listitem> - <para>Peter Olsson - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Peter Philipp - <email>pjp@bsd-daemon.net</email></para> - </listitem> - - <listitem> - <para>Peter Stubbs - <email>PETERS@staidan.qld.edu.au</email></para> - </listitem> - - <listitem> - <para>Peter W. Schmiedeskamp - <email>pschmied@qwest.net</email></para> - </listitem> - - <listitem> - <para>Peter van Heusden - <email>pvh@wfeet.za.net</email></para> - </listitem> - - <listitem> - <para>Phil Maker - <email>pjm@cs.ntu.edu.au</email></para> - </listitem> - - <listitem> - <para>Phil Oleson - <email>oz@nixil.net</email></para> - </listitem> - - <listitem> - <para>Phil Sutherland - <email>philsuth@mycroft.dialix.oz.au</email></para> - </listitem> - - <listitem> - <para>Phil Taylor - <email>phil@zipmail.co.uk</email></para> - </listitem> - - <listitem> - <para>Philip Musumeci - <email>philip@rmit.edu.au</email></para> - </listitem> - - <listitem> - <para>Philippe Lefebvre - <email>nemesis@balistik.net</email></para> - </listitem> - - <listitem> - <para>Pierre-Paul Lavoie - <email>ppl@nbnet.nb.ca</email></para> - </listitem> - - <listitem> - <para>Pierre Y. Dampure - <email>pierre.dampure@k2c.co.uk</email></para> - </listitem> - - <listitem> - <para>Piotr Smyrak - <email>piotr.smyrak@heron.pl</email></para> - </listitem> - - <listitem> - <para>Pius Fischer - <email>pius@ienet.com</email></para> - </listitem> - - <listitem> - <para>Pomegranate - <email>daver@flag.blackened.net</email></para> - </listitem> - - <listitem> - <para>Powerdog Industries - <email>kevin.ruddy@powerdog.com</email></para> - </listitem> - - <listitem> - <para>Priit Järv - <email>priit@cc.ttu.ee</email></para> - </listitem> - - <listitem> - <para>Quinton Dolan - <email>q@onthenet.com.au</email></para> - </listitem> - - <listitem> - <para>R Joseph Wright - <email>rjoseph@mammalia.org</email></para> - </listitem> - - <listitem> - <para>R. Kym Horsell</para> - </listitem> - - <listitem> - <para>Radim Kolar - <email>hsn@netmag.cz</email></para> - </listitem> - - <listitem> - <para>Radoslav Vasilev - <email>rvasilev@uni-svishtov.bg</email></para> - </listitem> - - <listitem> - <para>Ralf Friedl - <email>friedl@informatik.uni-kl.de</email></para> - </listitem> - - <listitem> - <para>Ralf van Dooren - <email>r.vdooren@snow.nl</email></para> - </listitem> - - <listitem> - <para>Randal S. Masutani - <email>randal@comtest.com</email></para> - </listitem> - - <listitem> - <para>Randall Hopper - <email>rhh@ct.picker.com</email></para> - </listitem> - - <listitem> - <para>Randall W. Dean - <email>rwd@osf.org</email></para> - </listitem> - - <listitem> - <para>Randy Bush - <email>rbush@bainbridge.verio.net</email></para> - </listitem> - - <listitem> - <para>Rashid N. Achilov - <email>shelton@sentry.granch.ru</email></para> - </listitem> - - <listitem> - <para>Rasmus Kaj - <email>kaj@Raditex.se</email></para> - </listitem> - - <listitem> - <para>Reinier Bezuidenhout - <email>rbezuide@mikom.csir.co.za</email></para> - </listitem> - - <listitem> - <para>Remington Lang - <email>MrL0L@charter.net</email></para> - </listitem> - - <listitem> - <para>Remy Card - <email>Remy.Card@masi.ibp.fr</email></para> - </listitem> - - <listitem> - <para>Renato Botelho - <email>renato@galle.com.br</email></para> - </listitem> - - <listitem> - <para>Ricardas Cepas - <email>rch@richard.eu.org</email></para> - </listitem> - - <listitem> - <para>Riccardo Veraldi - <email>veraldi@cs.unibo.it</email></para> - </listitem> - - <listitem> - <para>Rich Wood - <email>rich@FreeBSD.org.uk</email></para> - </listitem> - - <listitem> - <para>Richard Arends - <email>richard@unixguru.nl</email></para> - </listitem> - - <listitem> - <para>Richard Henderson - <email>richard@atheist.tamu.edu</email></para> - </listitem> - - <listitem> - <para>Richard Hwang - <email>rhwang@bigpanda.com</email></para> - </listitem> - - <listitem> - <para>Richard J Kuhns - <email>rjk@watson.grauel.com</email></para> - </listitem> - - <listitem> - <para>Richard Kiss - <email>richard@homemail.com</email></para> - </listitem> - - <listitem> - <para>Richard M. Neswold - <email>rneswold@enteract.com</email></para> - </listitem> - - <listitem> - <para>Richard Stallman - <email>rms@gnu.ai.mit.edu</email></para> - </listitem> - - <listitem> - <para>Richard Straka - <email>straka@user1.inficad.com</email></para> - </listitem> - - <listitem> - <para>Richard Tobin - <email>richard@cogsci.ed.ac.uk</email></para> - </listitem> - - <listitem> - <para>Richard Wackerbarth - <email>rkw@Dataplex.NET</email></para> - </listitem> - - <listitem> - <para>Richard Winkel - <email>rich@math.missouri.edu</email></para> - </listitem> - - <listitem> - <para>Richard Wiwatowski - <email>rjwiwat@adelaide.on.net</email></para> - </listitem> - - <listitem> - <para>Rick Fournier - <email>rick@help-desk.ca</email></para> - </listitem> - - <listitem> - <para>Rick Macklem - <email>rick@snowhite.cis.uoguelph.ca</email></para> - </listitem> - - <listitem> - <para>Rick Macklin - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Rob Austein - <email>sra@epilogue.com</email></para> - </listitem> - - <listitem> - <para>Rob Evers - <email>rob@debank.tv</email></para> - </listitem> - - <listitem> - <para>Rob Mallory - <email>rmallory@qualcomm.com</email></para> - </listitem> - - <listitem> - <para>Rob Snow - <email>rsnow@txdirect.net</email></para> - </listitem> - - <listitem> - <para>Robert Crowe - <email>bob@speakez.com</email></para> - </listitem> - - <listitem> - <para>Robert D. Thrush - <email>rd@phoenix.aii.com</email></para> - </listitem> - - <listitem> - <para>Robert Eckardt - <email>roberte@MEP.Ruhr-Uni-Bochum.de</email></para> - </listitem> - - <listitem> - <para>Robert P Ricci - <email>ricci@cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Robert Sanders - <email>rsanders@mindspring.com</email></para> - </listitem> - - <listitem> - <para>Robert Sexton - <email>robert@kudra.com</email></para> - </listitem> - - <listitem> - <para>Robert Shady - <email>rls@id.net</email></para> - </listitem> - - <listitem> - <para>Robert Swindells - <email>swindellsr@genrad.co.uk</email></para> - </listitem> - - <listitem> - <para>Robert Withrow - <email>witr@rwwa.com</email></para> - </listitem> - - <listitem> - <para>Robert Yoder - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Robin Carey - <email>robin@mailgate.dtc.rankxerox.co.uk</email></para> - </listitem> - - <listitem> - <para>Robin Schoonover - <email>end@endif.cjb.net</email></para> - </listitem> - - <listitem> - <para>Rod Taylor - <email>rod@idiotswitch.org</email></para> - </listitem> - - <listitem> - <para>Roger Hardiman - <email>roger@cs.strath.ac.uk</email></para> - </listitem> - - <listitem> - <para>Roland Jesse - <email>jesse@cs.uni-magdeburg.de</email></para> - </listitem> - - <listitem> - <para>Roman Y. Bogdanov - <email>sam@brj.pp.ru</email></para> - </listitem> - - <listitem> - <para>Roman Bogorodskiy - <email>bogorodskiy@inbox.ru</email></para> - </listitem> - - <listitem> - <para>Roman Neuhauser - <email>neuhauser@chello.cz</email></para> - </listitem> - - <listitem> - <para>Roman V. Palagin - <email>romanp@unshadow.net</email></para> - </listitem> - - <listitem> - <para>Roman Shterenzon - <email>roman@xpert.com</email></para> - </listitem> - - <listitem> - <para>Roman Synyuk - <email>roman@univ.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Ron Bickers - <email>rbickers@intercenter.net</email></para> - </listitem> - - <listitem> - <para>Ron Lenk - <email>rlenk@widget.xmission.com</email></para> - </listitem> - - <listitem> - <para>Ronald Kuehn - <email>kuehn@rz.tu-clausthal.de</email></para> - </listitem> - - <listitem> - <para>Rudolf Cejka - <email>cejkar@fit.vutbr.cz</email></para> - </listitem> - - <listitem> - <para>Rui Lopes - <email>rui@ruilopes.com</email></para> - </listitem> - - <listitem> - <para>Ruslan Belkin - <email>rus@home2.UA.net</email></para> - </listitem> - - <listitem> - <para>Ruslan Shevchenko - <email>rssh@cam.grad.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Russell Jackson - <email>rjackson@cserv62.csub.edu</email></para> - </listitem> - - <listitem> - <para>Russell L. Carter - <email>rcarter@pinyon.org</email></para> - </listitem> - - <listitem> - <para>Russell Vincent - <email>rv@groa.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Ryan T. Dean - <email>rtdean@cytherianage.net</email></para> - </listitem> - - <listitem> - <para>Ryan Moe - <email>ryan@transaeris.com</email></para> - </listitem> - - <listitem> - <para>Ryan Thompson - <email>ryan@sasknow.com</email></para> - </listitem> - - <listitem> - <para>Ryan Younce - <email>ryany@pobox.com</email></para> - </listitem> - - <listitem> - <para>Ryuichiro IMURA - <email>imura@af.airnet.ne.jp</email></para> - </listitem> - - <listitem> - <para>SANETO Takanori - <email>sanewo@strg.sony.co.jp</email></para> - </listitem> - - <listitem> - <para>SASAKI Shunsuke - <email>ele@pop17.odn.ne.jp</email></para> - </listitem> - - <listitem> - <para>SAWADA Mizuki - <email>miz@qb3.so-net.ne.jp</email></para> - </listitem> - - <listitem> - <para>SUGIMURA Takashi - <email>sugimura@jp.FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>SURANYI Peter - <email>suranyip@jks.is.tsukuba.ac.jp</email></para> - </listitem> - - <listitem> - <para>Sakai Hiroaki - <email>sakai@miya.ee.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>Sakari Jalovaara - <email>sja@tekla.fi</email></para> - </listitem> - - <listitem> - <para>Sam Hartman - <email>hartmans@mit.edu</email></para> - </listitem> - - <listitem> - <para>Sam Lawrance - <email>boris@brooknet.com.au</email></para> - </listitem> - - <listitem> - <para>Samuel Lam - <email>skl@ScalableNetwork.com</email></para> - </listitem> - - <listitem> - <para>Samuel Tardieu - <email>sam@inf.enst.fr</email></para> - </listitem> - - <listitem> - <para>Samuele Zannoli - <email>zannoli@cs.unibo.it</email></para> - </listitem> - - <listitem> - <para>Samy Al Bahra - <email>samy@kerneled.com</email></para> - </listitem> - - <listitem> - <para>Sander Janssen - <email>janssen@rendo.dekooi.nl</email></para> - </listitem> - - <listitem> - <para>Sander Vesik - <email>sander@haldjas.folklore.ee</email></para> - </listitem> - - <listitem> - <para>Sandro Sigala - <email>ssigala@globalnet.it</email></para> - </listitem> - - <listitem> - <para>Sascha Blank - <email>blank@fox.uni-trier.de</email></para> - </listitem> - - <listitem> - <para>Sascha Holzleiter - <email>sascha@root-login.org</email></para> - </listitem> - - <listitem> - <para>Sascha Wildner - <email>swildner@channelz.GUN.de</email></para> - </listitem> - - <listitem> - <para>Satoh Junichi - <email>junichi@astec.co.jp</email></para> - </listitem> - - <listitem> - <para>Scot Elliott - <email>scot@poptart.org</email></para> - </listitem> - - <listitem> - <para>Scot W. Hetzel - <email>hetzels@westbend.net</email></para> - </listitem> - - <listitem> - <para>Scott A. Kenney - <email>saken@rmta.ml.org</email></para> - </listitem> - - <listitem> - <para>Scott A. Moberly - <email>smoberly@xavier.dyndns.org</email></para> - </listitem> - - <listitem> - <para>Scott Blachowicz - <email>scott.blachowicz@seaslug.org</email></para> - </listitem> - - <listitem> - <para>Scott Burris - <email>scott@pita.cns.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Flatman - <email>sf@slappy.org</email></para> - </listitem> - - <listitem> - <para>Scott Hazen Mueller - <email>scott@zorch.sf-bay.org</email></para> - </listitem> - - <listitem> - <para>Scott Michel - <email>scottm@cs.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Scott Reynolds - <email>scott@clmqt.marquette.mi.us</email></para> - </listitem> - - <listitem> - <para>Seamus Venasse - <email>svenasse@polaris.ca</email></para> - </listitem> - - <listitem> - <para>Sebastian Strollo - <email>seb@erix.ericsson.se</email></para> - </listitem> - - <listitem> - <para>Sebastian Yepes - <email>esn@x123.info</email></para> - </listitem> - - <listitem> - <para>Serge Gagnon - <email>gagnon_s@sympatico.ca</email></para> - </listitem> - - <listitem> - <para>Serge Negodyuck - <email>petr@petrovich.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Serge V. Vakulenko - <email>vak@zebub.msk.su</email></para> - </listitem> - - <listitem> - <para>Sergei Chechetkin - <email>csl@whale.sunbay.crimea.ua</email></para> - </listitem> - - <listitem> - <para>Sergei S. Laskavy - <email>laskavy@pc759.cs.msu.su</email></para> - </listitem> - - <listitem> - <para>Sergey Akifyev - <email>asa@gascom.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Gershtein - <email>sg@mplik.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Kosyakov - <email>ks@itp.ac.ru</email></para> - </listitem> - - <listitem> - <para>Sergey N. Vorokov - <email>serg@tmn.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Potapov - <email>sp@alkor.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Samoyloff - <email>gonza@techline.ru</email></para> - </listitem> - - <listitem> - <para>Sergey Shkonda - <email>serg@bcs.zp.ua</email></para> - </listitem> - - <listitem> - <para>Sergey V. Dorokhov - <email>svd@kbtelecom.nalnet.ru</email></para> - </listitem> - - <listitem> - <para>Sergio Lenzi - <email>lenzi@bsi.com.br</email></para> - </listitem> - - <listitem> - <para>Shaun Courtney - <email>shaun@emma.eng.uct.ac.za</email></para> - </listitem> - - <listitem> - <para>Shawn M. Carey - <email>smcarey@mailbox.syr.edu</email></para> - </listitem> - - <listitem> - <para>Shell Hung - <email>shell@shellhung.org</email></para> - </listitem> - - <listitem> - <para>Shen Chuan-Hsing - <email>statue@freebsd.sinica.edu.tw</email></para> - </listitem> - - <listitem> - <para>Shigio Yamaguchi - <email>shigio@tamacom.com</email></para> - </listitem> - - <listitem> - <para>Shinichiro Komatsu - <email>koma2@jiro.c.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Shinya Esu - <email>esu@yk.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Shinya FUJIE - <email>fujie@tk.elec.waseda.ac.jp</email></para> - </listitem> - - <listitem> - <para>Shin'ya Murakami - <email>murakami@ahs.scitec.kobe-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Shuichi Tanaka - <email>stanaka@bb.mbn.or.jp</email></para> - </listitem> - - <listitem> - <para>Simon - <email>simon@masi.ibp.fr</email></para> - </listitem> - - <listitem> - <para>Simon Barner - <email>barner@in.tum.de</email></para> - </listitem> - - <listitem> - <para>Simon Burge - <email>simonb@telstra.com.au</email></para> - </listitem> - - <listitem> - <para>Simon Dick - <email>simond@irrelevant.org</email></para> - </listitem> - - <listitem> - <para>Simon J Gerraty - <email>sjg@melb.bull.oz.au</email></para> - </listitem> - - <listitem> - <para>Simon Lang - <email>simon@lang-clan.de</email></para> - </listitem> - - <listitem> - <para>Simon Marlow - <email>simonm@dcs.gla.ac.uk</email></para> - </listitem> - - <listitem> - <para>Simon Schubert - <email>corecode@corecode.ath.cx</email></para> - </listitem> - - <listitem> - <para>Simon Shapiro - <email>shimon@simon-shapiro.org</email></para> - </listitem> - - <listitem> - <para>Sin'ichiro MIYATANI - <email>siu@phaseone.co.jp</email></para> - </listitem> - - <listitem> - <para>Slaven Rezic - <email>eserte@cs.tu-berlin.de</email></para> - </listitem> - - <listitem> - <para>Snow Chyld - <email>snowchyld+freebsdports@gmail.com</email></para> - </listitem> - - <listitem> - <para>Soochon Radee - <email>slr@mitre.org</email></para> - </listitem> - - <listitem> - <para>Soren Dayton - <email>csdayton@midway.uchicago.edu</email></para> - </listitem> - - <listitem> - <para>Soren Dossing - <email>sauber@netcom.com</email></para> - </listitem> - - <listitem> - <para>Soren S. Jorvang - <email>soren@wheel.dk</email></para> - </listitem> - - <listitem> - <para>SPF - <email>spf@xslt.cs.nccu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Stanislav A. Svirid - <email>count@riss-telecom.ru</email></para> - </listitem> - - <listitem> - <para>Stefan A. Deutscher - <email>sad@mailaps.org</email></para> - </listitem> - - <listitem> - <para>Stefan Eggers - <email>seggers@semyam.dinoco.de</email></para> - </listitem> - - <listitem> - <para>Stefan Ehmann - <email>shoesoft@gmx.net</email></para> - </listitem> - - <listitem> - <para>Stefan Grundmann - <email>sg-sendpr@waset.de</email></para> - </listitem> - - <listitem> - <para>Stefan Jahn - <email>stefan.jahn@nemesis-sektor.de</email></para> - </listitem> - - <listitem> - <para>Stefan Moeding - <email>s.moeding@ndh.net</email></para> - </listitem> - - <listitem> - <para>Stefan Petri - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Stefan `Sec` Zehl - <email>sec@42.org</email></para> - </listitem> - - <listitem> - <para>Stefan Schwarzer - <email>sschwarzer@sschwarzer.net</email></para> - </listitem> - - <listitem> - <para>Steffen Mazanek - <email>steffen.mazanek@unibw-muenchen.de</email></para> - </listitem> - - <listitem> - <para>Steffen Vogelreuter - <email>Steffen@Vogelreuter.De</email></para> - </listitem> - - <listitem> - <para>Stefan Walter - <email>sw@gegenunendlich.de</email></para> - </listitem> - - <listitem> - <para>Steinar Haug - <email>sthaug@nethelp.no</email></para> - </listitem> - - <listitem> - <para>Stephane E. Potvin - <email>sepotvin@videotron.ca</email></para> - </listitem> - - <listitem> - <para>Stephen Clawson - <email>sclawson@marker.cs.utah.edu</email></para> - </listitem> - - <listitem> - <para>Stephen F. Combs - <email>combssf@salem.ge.com</email></para> - </listitem> - - <listitem> - <para>Stephen Farrell - <email>stephen@farrell.org</email></para> - </listitem> - - <listitem> - <para>Stephen Gunn - <email>csg@fedex.com</email></para> - </listitem> - - <listitem> - <para>Stephen Hocking - <email>sysseh@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Stephen J. Roznowski - <email>sjr@home.net</email></para> - </listitem> - - <listitem> - <para>Stephen McKay - <email>syssgm@devetir.qld.gov.au</email></para> - </listitem> - - <listitem> - <para>Stephen Melvin - <email>melvin@zytek.com</email></para> - </listitem> - - <listitem> - <para>Stephen Weeks - <email>sweeks@sweeks.com</email></para> - </listitem> - - <listitem> - <para>Steve Bauer - <email>sbauer@rock.sdsmt.edu</email></para> - </listitem> - - <listitem> - <para>Steve Coltrin - <email>spcoltri@unm.edu</email></para> - </listitem> - - <listitem> - <para>Steve Deering - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Steve Gerakines - <email>steve2@genesis.tiac.net</email></para> - </listitem> - - <listitem> - <para>Steve Gericke - <email>steveg@comtrol.com</email></para> - </listitem> - - <listitem> - <para>Steven Honson - <email>shonson@isoproplex.net</email></para> - </listitem> - - <listitem> - <para>Steve Piette - <email>steve@simon.chi.il.US</email></para> - </listitem> - - <listitem> - <para>Steve Schwarz - <email>schwarz@alpharel.com</email></para> - </listitem> - - <listitem> - <para>Steven Enderle - <email>panic@subphase.de</email></para> - </listitem> - - <listitem> - <para>Steven G. Kargl - <email>kargl@troutmask.apl.washington.edu</email></para> - </listitem> - - <listitem> - <para>Steven H. Samorodin - <email>samorodi@NUXI.com</email></para> - </listitem> - - <listitem> - <para>Steven McCanne - <email>mccanne@cs.berkeley.edu</email></para> - </listitem> - - <listitem> - <para>Steven Plite - <email>splite@purdue.edu</email></para> - </listitem> - - <listitem> - <para>Steven Wallace - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Stijn Hoop - <email>stijn@win.tue.nl</email></para> - </listitem> - - <listitem> - <para>Stuart Henderson - <email>stuart@internationalschool.co.uk</email></para> - </listitem> - - <listitem> - <para>Sue Blake - <email>sue@welearn.com.au</email></para> - </listitem> - - <listitem> - <para>Sugimoto Sadahiro - <email>ixtl@komaba.utmc.or.jp</email></para> - </listitem> - - <listitem> - <para>Sugiura Shiro - <email>ssugiura@duo.co.jp</email></para> - </listitem> - - <listitem> - <para>Sujal Patel - <email>smpatel@wam.umd.edu</email></para> - </listitem> - - <listitem> - <para>Sune Stjerneby - <email>sst@vmunix.dk</email></para> - </listitem> - - <listitem> - <para>Sungman Cho - <email>smcho@tsp.korea.ac.kr</email></para> - </listitem> - - <listitem> - <para>Suzuki Yoshiaki - <email>zensyo@ann.tama.kawasaki.jp</email></para> - </listitem> - - <listitem> - <para>Svein Skogen - <email>tds@dmnstech.net</email></para> - </listitem> - - <listitem> - <para>Sybolt de Boer - <email>bolt@xs4all.nl</email></para> - </listitem> - - <listitem> - <para>TAKAHASHI Kaoru - <email>kaoru@kaisei.org</email></para> - </listitem> - - <listitem> - <para>Tadashi Kumano - <email>kumano@strl.nhk.or.jp</email></para> - </listitem> - - <listitem> - <para>Taguchi Takeshi - <email>taguchi@tohoku.iij.ad.jp</email></para> - </listitem> - - <listitem> - <para>Takahiro Yugawa - <email>yugawa@orleans.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Takashi Mega - <email>mega@minz.org</email></para> - </listitem> - - <listitem> - <para>Takashi Uozu - <email>j1594016@ed.kagu.sut.ac.jp</email></para> - </listitem> - - <listitem> - <para>TAKATSU Tomonari - <email>tota@rtfm.jp</email></para> - </listitem> - - <listitem> - <para>Takayuki Ariga - <email>a00821@cc.hc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takayuki Nakao - <email>t@nakao.org</email></para> - </listitem> - - <listitem> - <para>Takeru NAIKI - <email>naiki@bfd.es.hokudai.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi Amaike - <email>amaike@iri.co.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi MUTOH - <email>mutoh@info.nara-k.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi Ohashi - <email>ohashi@mickey.ai.kyutech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takeshi WATANABE - <email>watanabe@crayon.earth.s.kobe-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Takuya SHIOZAKI - <email>tshiozak@makino.ise.chuo-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Tatoku Ogaito - <email>tacha@tera.fukui-med.ac.jp</email></para> - </listitem> - - <listitem> - <para>Tatsuya Kudoh - <email>cdr@cosmonet.org</email></para> - </listitem> - - <listitem> - <para>Ted Buswell - <email>tbuswell@mediaone.net</email></para> - </listitem> - - <listitem> - <para>Ted Faber - <email>faber@isi.edu</email></para> - </listitem> - - <listitem> - <para>Ted Lemon - <email>mellon@isc.org</email></para> - </listitem> - - <listitem> - <para>Terry Lambert - <email>terry@lambert.org</email></para> - </listitem> - - <listitem> - <para>Terry Lee - <email>terry@uivlsi.csl.uiuc.edu</email></para> - </listitem> - - <listitem> - <para>Teruaki Ata - <email>PFA03027@nifty.ne.jp</email></para> - </listitem> - - <listitem> - <para>Tetsuro Yabu - <email>yabu@uopmu.ees.osakafu-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Tetsuya Furukawa - <email>tetsuya@secom-sis.co.jp</email></para> - </listitem> - - <listitem> - <para>Theo de Raadt - <email>deraadt@OpenBSD.org</email></para> - </listitem> - - <listitem> - <para>Thomas - <email>thomas@mathematik.uni-Bremen.de</email></para> - </listitem> - - <listitem> - <para>Thomas A. Stephens - <email>tas@stephens.org</email></para> - </listitem> - - <listitem> - <para>Thomas D. Dean - <email>tomdean@ix.netcom.com</email></para> - </listitem> - - <listitem> - <para>Thomas David Rivers - <email>rivers@dignus.com</email></para> - </listitem> - - <listitem> - <para>Thomas E. Zander - <email>riggs@rrr.de</email></para> - </listitem> - - <listitem> - <para>Thomas G. McWilliams - <email>tgm@netcom.com</email></para> - </listitem> - - <listitem> - <para>Thomas Kempka - <email>t.kempka@web.de</email></para> - </listitem> - - <listitem> - <para>Thomas König - <email>Thomas.Koenig@ciw.uni-karlsruhe.de</email></para> - </listitem> - - <listitem> - <para>Thomas M. Hermann - <email>Thomas.Hermann@cox.net</email></para> - </listitem> - - <listitem> - <para>Thomas Ptacek - <email>unknown</email></para> - </listitem> - - <listitem> - <para>Thomas Spreng - <email>spreng@socket.ch</email></para> - </listitem> - - <listitem> - <para>Thomas Stromberg - <email>tstrombe@rtci.com</email></para> - </listitem> - - <listitem> - <para>Thomas Valentino Crimi - <email>tcrimi+@andrew.cmu.edu</email></para> - </listitem> - - <listitem> - <para>Thomas Vogt - <email>thomas.vogt@bsdunix.ch</email></para> - </listitem> - - <listitem> - <para>Thomas Wintergerst - <email>thomas@lemur.nord.de</email></para> - </listitem> - - <listitem> - <para>Thomas-Martin Seck - <email>tmseck@netcologne.de</email></para> - </listitem> - - <listitem> - <para>Thorsten Greiner - <email>thorsten.greiner@web.de</email></para> - </listitem> - - <listitem> - <para>Þórður Ívarsson - <email>totii@est.is</email></para> - </listitem> - - <listitem> - <para>Tijl Coosemans - <email>tijl@ulyssis.org</email></para> - </listitem> - - <listitem> - <para>Tillman Hodgson - <email>tillman@seekingfire.com</email></para> - </listitem> - - <listitem> - <para>Tim Bishop - <email>tim@bishnet.net</email></para> - </listitem> - - <listitem> - <para>Tim Daneliuk - <email>tundra@tundraware.com</email></para> - </listitem> - - <listitem> - <para>Tim Hemel - <email>tim@n2it.net</email></para> - </listitem> - - <listitem> - <para>Tim Singletary - <email>tsingle@sunland.gsfc.nasa.gov</email></para> - </listitem> - - <listitem> - <para>Tim Wilkinson - <email>tim@sarc.city.ac.uk</email></para> - </listitem> - - <listitem> - <para>Timo J. Rinne - <email>tri@iki.fi</email></para> - </listitem> - - <listitem> - <para>Timothy Jensen - <email>toast@blackened.com</email></para> - </listitem> - - <listitem> - <para>Timur I. Bakeyev - <email>timur@gnu.org</email></para> - </listitem> - - <listitem> - <para>Tobias Reifenberger - <email>treif@mayn.de</email></para> - </listitem> - - <listitem> - <para>Tobias Roth - <email>ports@fsck.ch</email></para> - </listitem> - - <listitem> - <para>Toby Allsopp - <email>toby@mi6.gen.nz</email></para> - </listitem> - - <listitem> - <para>Todd Miller - <email>millert@openbsd.org</email></para> - </listitem> - - <listitem> - <para>Tom - <email>root@majestix.cmr.no</email></para> - </listitem> - - <listitem> - <para>Tom Gray - DCA - <email>dcasba@rain.org</email></para> - </listitem> - - <listitem> - <para>Tom Jobbins - <email>tom@tom.tj</email></para> - </listitem> - - <listitem> - <para>Tom McLaughlin - <email>tom@tmclaugh@sdf.lonestar.org</email></para> - </listitem> - - <listitem> - <para>Tom Mortensen - <email>tom@tavrasm.org</email></para> - </listitem> - - <listitem> - <para>Tom Pusateri - <email>pusateri@juniper.net</email></para> - </listitem> - - <listitem> - <para>Tom Rush - <email>tarush@mindspring.com</email></para> - </listitem> - - <listitem> - <para>Tom Samplonius - <email>tom@misery.sdf.com</email></para> - </listitem> - - <listitem> - <para>Tomohiko Kurahashi - <email>kura@melchior.q.t.u-tokyo.ac.jp</email></para> - </listitem> - - <listitem> - <para>Toni Viemero - <email>toni.viemero@iki.fi</email></para> - </listitem> - - <listitem> - <para>Tony Kimball - <email>alk@Think.COM</email></para> - </listitem> - - <listitem> - <para>Tony Li - <email>tli@jnx.com</email></para> - </listitem> - - <listitem> - <para>Tony Lynn - <email>wing@cc.nsysu.edu.tw</email></para> - </listitem> - - <listitem> - <para>Tony Maher - <email>tonym@biolateral.com.au</email></para> - </listitem> - - <listitem> - <para>Torbjorn Granlund - <email>tege@matematik.su.se</email></para> - </listitem> - - <listitem> - <para>Toshihiko SHIMOKAWA - <email>toshi@tea.forus.or.jp</email></para> - </listitem> - - <listitem> - <para>Toshihiro Kanda - <email>candy@kgc.co.jp</email></para> - </listitem> - - <listitem> - <para>Toshiomi Moriki - <email>Toshiomi.Moriki@ma1.seikyou.ne.jp</email></para> - </listitem> - - <listitem> - <para>Toshiya SAITOH - <email>toshiya@saitoh.nu</email></para> - </listitem> - - <listitem> - <para>Travis Campbell - <email>hcoyote@ghostar.org</email></para> - </listitem> - - <listitem> - <para>Travis Poppe - <email>tlp@liquidx.org</email></para> - </listitem> - - <listitem> - <para>Trefor S. - <email>trefor@flevel.co.uk</email></para> - </listitem> - - <listitem> - <para>Trenton Schulz - <email>twschulz@cord.edu</email></para> - </listitem> - - <listitem> - <para>Trevor Blackwell - <email>tlb@viaweb.com</email></para> - </listitem> - - <listitem> - <para>UMENO Takashi - <email>umeno@rr.iij4u.or.jp</email></para> - </listitem> - - <listitem> - <para>URATA Shuichiro - <email>s-urata@nmit.tmg.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>Udo Schweigert - <email>ust@cert.siemens.de</email></para> - </listitem> - - <listitem> - <para>Ugo Paternostro - <email>paterno@dsi.unifi.it</email></para> - </listitem> - - <listitem> - <para>Ulf Kieber - <email>kieber@sax.de</email></para> - </listitem> - - <listitem> - <para>Ulli Linzen - <email>ulli@perceval.camelot.de</email></para> - </listitem> - - <listitem> - <para>Ulrich Spoerlein - <email>q@uni.de</email></para> - </listitem> - - <listitem> - <para>Uwe Arndt - <email>arndt@mailhost.uni-koblenz.de</email></para> - </listitem> - - <listitem> - <para>Uwe Pierau - <email>uwe.pierau@tu-clausthal.de</email></para> - </listitem> - - <listitem> - <para>Vadim Belman - <email>voland@catpipe.net</email></para> - </listitem> - - <listitem> - <para>Vadim Chekan - <email>vadim@gc.lviv.ua</email></para> - </listitem> - - <listitem> - <para>Vadim Kolontsov - <email>vadim@tversu.ac.ru</email></para> - </listitem> - - <listitem> - <para>Vadim Mikhailov - <email>mvp@braz.ru</email></para> - </listitem> - - <listitem> - <para>Vaidas Zlotkus - <email>r2@music.lt</email></para> - </listitem> - - <listitem> - <para>Valentin Nechayev - <email>netch@lucky.net</email></para> - </listitem> - - <listitem> - <para>Valentin Zahariev - <email>curly@e-card.bg</email></para> - </listitem> - - <listitem> - <para>Van Jacobson - <email>van@ee.lbl.gov</email></para> - </listitem> - - <listitem> - <para>Vasily V. Grechishnikov - <email>bazilio@ns1.ied-vorstu.ac.ru</email></para> - </listitem> - - <listitem> - <para>Vasim Valejev - <email>vasim@uddias.diaspro.com</email></para> - </listitem> - - <listitem> - <para>Vassili Tchersky - <email>vt@bsd-fr.org</email></para> - </listitem> - - <listitem> - <para>Vernon J. Schryver - <email>vjs@mica.denver.sgi.com</email></para> - </listitem> - - <listitem> - <para>Veselin Slavov - <email>vess@btc.net</email></para> - </listitem> - - <listitem> - <para>Vic Abell - <email>abe@cc.purdue.edu</email></para> - </listitem> - - <listitem> - <para>Viktor Fomichev - <email>vfom@narod.ru</email></para> - </listitem> - - <listitem> - <para>Ville Eerola - <email>ve@sci.fi</email></para> - </listitem> - - <listitem> - <para>Vince Valenti - <email>vince@blue-box.net</email></para> - </listitem> - - <listitem> - <para>Vincent Poy - <email>vince@DNALOGIC.NET</email></para> - </listitem> - - <listitem> - <para>Vincent Tantardini - <email>vinc@freebsd-fr.org</email></para> - </listitem> - - <listitem> - <para>Vincenzo Capuano - <email>VCAPUANO@vmprofs.esoc.esa.de</email></para> - </listitem> - - <listitem> - <para>Virgil Champlin - <email>champlin@pa.dec.com</email></para> - </listitem> - - <listitem> - <para>Vivek Khera - <email>vivek@khera.org</email></para> - </listitem> - - <listitem> - <para>Vladimir A. Jakovenko - <email>vovik@ntu-kpi.kiev.ua</email></para> - </listitem> - - <listitem> - <para>Vladimir Kurtikov <email>vk@vk.pp.ru</email></para> - </listitem> - - <listitem> - <para>Vladimir Kushnir - <email>kushn@mail.kar.net</email></para> - </listitem> - - <listitem> - <para>Vladimir Savichev - <email>vlad@ariel.phys.wesleyan.edu</email></para> - </listitem> - - <listitem> - <para>Volker Quetschke - <email>quetschke@scytek.de</email></para> - </listitem> - - <listitem> - <para>Vsevolod Lobko - <email>seva@ip.net.ua</email></para> - </listitem> - - <listitem> - <para>Vyacheslav Ivanchenko - <email>ivi@dhs.net.ru</email></para> - </listitem> - - <listitem> - <para>W. Gerald Hicks - <email>wghicks@bellsouth.net</email></para> - </listitem> - - <listitem> - <para>W. Richard Stevens - <email>rstevens@noao.edu</email></para> - </listitem> - - <listitem> - <para>Walt Howard - <email>howard@ee.utah.edu</email></para> - </listitem> - - <listitem> - <para>Walt M. Shandruk - <email>walt@erudition.net</email></para> - </listitem> - - <listitem> - <para>Walter Hop - <email>walter@binity.com</email></para> - </listitem> - - <listitem> - <para>Walter Venable - <email>weaseal@hotmail.com</email></para> - </listitem> - - <listitem> - <para>Warren Toomey - <email>wkt@csadfa.cs.adfa.oz.au</email></para> - </listitem> - - <listitem> - <para>Wayne Scott - <email>wscott@ichips.intel.com</email></para> - </listitem> - - <listitem> - <para>Werner Griessl - <email>werner@btp1da.phy.uni-bayreuth.de</email></para> - </listitem> - - <listitem> - <para>Wes Santee - <email>wsantee@wsantee.oz.net</email></para> - </listitem> - - <listitem> - <para>Wietse Venema - <email>wietse@wzv.win.tue.nl</email></para> - </listitem> - - <listitem> - <para>Wiljo Heinen - <email>wiljo@freeside.ki.open.de</email></para> - </listitem> - - <listitem> - <para>Willem van Engen - <email>wvengen@stack.nl</email></para> - </listitem> - - <listitem> - <para>Willem Jan Withagen - <email>wjw@surf.IAE.nl</email></para> - </listitem> - - <listitem> - <para>William Jolitz - <email>withheld</email></para> - </listitem> - - <listitem> - <para>William Josephson - <email>wkj-freebsd@honk.eecs.harvard.edu</email></para> - </listitem> - - <listitem> - <para>William Liao - <email>william@tale.net</email></para> - </listitem> - - <listitem> - <para>Wojtek Pilorz - <email>wpilorz@celebris.bdk.lublin.pl</email></para> - </listitem> - - <listitem> - <para>Wolfgang Helbig - <email>helbig@ba-stuttgart.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Solfrank - <email>ws@tools.de</email></para> - </listitem> - - <listitem> - <para>Wolfgang Stanglmeier - <email>wolf@FreeBSD.org</email></para> - </listitem> - - <listitem> - <para>Woodchuck Dave - <email>djv@bedford.net</email></para> - </listitem> - - <listitem> - <para>Wouter Van Hemel - <email>wouter@pair.com</email></para> - </listitem> - - <listitem> - <para>Wu Ching-hong - <email>woju@FreeBSD.ee.Ntu.edu.TW</email></para> - </listitem> - - <listitem> - <para>&a.wylie;</para> - </listitem> - - <listitem> - <para>Xavier Beaudouin - <email>kiwi@oav.net</email></para> - </listitem> - - <listitem> - <para>Yannis Kotsinos - <email>zookie@med.auth.gr</email></para> - </listitem> - - <listitem> - <para>Yarema - <email>yds@ingress.com</email></para> - </listitem> - - <listitem> - <para>Yaroslav Terletsky - <email>ts@polynet.lviv.ua</email></para> - </listitem> - - <listitem> - <para>Yasuhiro Fukama - <email>yasuf@big.or.jp</email></para> - </listitem> - - <listitem> - <para>Yasuhito FUTATSUKI - <email>futatuki@fureai.or.jp</email></para> - </listitem> - - <listitem> - <para>Yen-Shuo Su - <email>yssu@CCCA.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Yin-Jieh Chen - <email>yinjieh@Crazyman.Dorm13.NCTU.edu.tw</email></para> - </listitem> - - <listitem> - <para>Yixin Jin - <email>yjin@rain.cs.ucla.edu</email></para> - </listitem> - - <listitem> - <para>Yoichi Asai - <email>yatt@msc.biglobe.ne.jp</email></para> - </listitem> - - <listitem> - <para>Yonatan Bokovza - <email>Yonatan@xpert.com</email></para> - </listitem> - - <listitem> - <para>Yoshiaki Uchikawa - <email>yoshiaki@kt.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Yuri Kurenkov - <email>y.kurenkov@init.ru</email></para> - </listitem> - - <listitem> - <para>Yoshihiko SARUMRU - <email>mistral@imasy.or.jp</email></para> - </listitem> - - <listitem> - <para>Yoshihisa NAKAGAWA - <email>y-nakaga@ccs.mt.nec.co.jp</email></para> - </listitem> - - <listitem> - <para>Yoshikazu Goto - <email>gotoh@ae.anritsu.co.jp</email></para> - </listitem> - - <listitem> - <para>Yoshimasa Ohnishi - <email>ohnishi@isc.kyutech.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yoshishige Arai - <email>ryo2@on.rim.or.jp</email></para> - </listitem> - - <listitem> - <para>Yu-Shun Wang - <email>yushunwa@isi.edu</email></para> - </listitem> - - <listitem> - <para>Yuichi MATSUTAKA - <email>matutaka@osa.att.ne.jp</email></para> - </listitem> - - <listitem> - <para>Yuichiro AIZAWA - <email>yaizawa@mdbl.sfc.keio.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yujiro MIYATA - <email>miyata@bioele.nuee.nagoya-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yusuke Nawano - <email>azuki@azkey.org</email></para> - </listitem> - - <listitem> - <para>Yuu Yashiki - <email>s974123@cc.matsuyama-u.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yuuichi Narahara - <email>aconitum@po.teleway.ne.jp</email></para> - </listitem> - - <listitem> - <para>Yuuki SAWADA - <email>mami@whale.cc.muroran-it.ac.jp</email></para> - </listitem> - - <listitem> - <para>Yuukis - <email>Ys@PixyGarden.net</email></para> - </listitem> - - <listitem> - <para>Yuval Yarom - <email>yval@cs.huji.ac.il</email></para> - </listitem> - - <listitem> - <para>Yves Fonk - <email>yves@cpcoup5.tn.tudelft.nl</email></para> - </listitem> - - <listitem> - <para>Yves Fonk - <email>yves@dutncp8.tn.tudelft.nl</email></para> - </listitem> - - <listitem> - <para>Zach Garner - <email>zach@neurosoft.org</email></para> - </listitem> - - <listitem> - <para>Zach Heilig - <email>zach@gaffaneys.com</email></para> - </listitem> - - <listitem> - <para>Zach Zurflu - <email>zach@pabst.bendnet.com</email></para> - </listitem> - - <listitem> - <para>Zahemszhky Gabor - <email>zgabor@code.hu</email></para> - </listitem> - - <listitem> - <para>Zhong Ming-Xun - <email>zmx@mail.CDPA.nsysu.edu.tw</email></para> - </listitem> - - <listitem> - <para>arci - <email>vega@sophia.inria.fr</email></para> - </listitem> - - <listitem> - <para>der Mouse - <email>mouse@Collatz.McRCIM.McGill.EDU</email></para> - </listitem> - </itemizedlist> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("article.sgml" "part" "sect1") - End: ---> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml b/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml deleted file mode 100644 index 08dbf4fc9f..0000000000 --- a/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml +++ /dev/null @@ -1,1420 +0,0 @@ -<!-- $FreeBSD$ --> -<!-- - NOTE TO NEW COMMITTERS: Core and committers lists are sorted in - alphabetical order by last name. Please keep in mind that fact while - adding your entity to the list of developers. ---> - - <itemizedlist> - <listitem> - <para>&a.tackerman;</para> - </listitem> - - <listitem> - <para>&a.akiyama;</para> - </listitem> - - <listitem> - <para>&a.jmas;</para> - </listitem> - - <listitem> - <para>&a.ambrisko;</para> - </listitem> - - <listitem> - <para>&a.will;</para> - </listitem> - - <listitem> - <para>&a.anholt;</para> - </listitem> - - <listitem> - <para>&a.mat;</para> - </listitem> - - <listitem> - <para>&a.babkin;</para> - </listitem> - - <listitem> - <para>&a.dbaker;</para> - </listitem> - - <listitem> - <para>&a.jhb;</para> - </listitem> - - <listitem> - <para>&a.dmlb;</para> - </listitem> - - <listitem> - <para>&a.mike;</para> - </listitem> - - <listitem> - <para>&a.dougb;</para> - </listitem> - - <listitem> - <para>&a.tobez;</para> - </listitem> - - <listitem> - <para>&a.pb;</para> - </listitem> - - <listitem> - <para>&a.abial;</para> - </listitem> - - <listitem> - <para>&a.jb;</para> - </listitem> - - <listitem> - <para>&a.nbm;</para> - </listitem> - - <listitem> - <para>&a.mbr;</para> - </listitem> - - <listitem> - <para>&a.torstenb;</para> - </listitem> - - <listitem> - <para>&a.mb;</para> - </listitem> - - <listitem> - <para>&a.harti;</para> - </listitem> - - <listitem> - <para>&a.obraun;</para> - </listitem> - - <listitem> - <para>&a.jmb;</para> - </listitem> - - <listitem> - <para>&a.brueffer;</para> - </listitem> - - <listitem> - <para>&a.markus;</para> - </listitem> - - <listitem> - <para>&a.wilko;</para> - </listitem> - - <listitem> - <para>&a.jake;</para> - </listitem> - - <listitem> - <para>&a.dburr;</para> - </listitem> - - <listitem> - <para>&a.adrian;</para> - </listitem> - - <listitem> - <para>&a.perky;</para> - </listitem> - - <listitem> - <para>&a.dwcjr;</para> - </listitem> - - <listitem> - <para>&a.charnier;</para> - </listitem> - - <listitem> - <para>&a.jon;</para> - </listitem> - - <listitem> - <para>&a.luoqi;</para> - </listitem> - - <listitem> - <para>&a.ache;</para> - </listitem> - - <listitem> - <para>&a.seanc;</para> - </listitem> - - <listitem> - <para>&a.kjc;</para> - </listitem> - - <listitem> - <para>&a.cjh;</para> - </listitem> - - <listitem> - <para>&a.cjc;</para> - </listitem> - - <listitem> - <para>&a.marck;</para> - </listitem> - - <listitem> - <para>&a.marcus;</para> - </listitem> - - <listitem> - <para>&a.nik;</para> - </listitem> - - <listitem> - <para>&a.archie;</para> - </listitem> - - <listitem> - <para>&a.chris;</para> - </listitem> - - <listitem> - <para>&a.alc;</para> - </listitem> - - <listitem> - <para>&a.cracauer;</para> - </listitem> - - <listitem> - <para>&a.dec;</para> - </listitem> - - <listitem> - <para>&a.davidc;</para> - </listitem> - - <listitem> - <para>&a.ceri;</para> - </listitem> - - <listitem> - <para>&a.brooks;</para> - </listitem> - - <listitem> - <para>&a.pjd;</para> - </listitem> - - <listitem> - <para>&a.bsd;</para> - </listitem> - - <listitem> - <para>&a.jwd;</para> - </listitem> - - <listitem> - <para>&a.pdeuskar;</para> - </listitem> - - <listitem> - <para>&a.mdodd;</para> - </listitem> - - <listitem> - <para>&a.danfe;</para> - </listitem> - - <listitem> - <para>&a.dd;</para> - </listitem> - - <listitem> - <para>&a.iedowse;</para> - </listitem> - - <listitem> - <para>&a.robert;</para> - </listitem> - - <listitem> - <para>&a.gad;</para> - </listitem> - - <listitem> - <para>&a.ale;</para> - </listitem> - - <listitem> - <para>&a.uhclem;</para> - </listitem> - - <listitem> - <para>&a.peadar;</para> - </listitem> - - <listitem> - <para>&a.tegge;</para> - </listitem> - - <listitem> - <para>&a.eik;</para> - </listitem> - - <listitem> - <para>&a.deischen;</para> - </listitem> - - <listitem> - <para>&a.eivind;</para> - </listitem> - - <listitem> - <para>&a.julian;</para> - </listitem> - - <listitem> - <para>&a.josef;</para> - </listitem> - - <listitem> - <para>&a.rse;</para> - </listitem> - - <listitem> - <para>&a.ue;</para> - </listitem> - - <listitem> - <para>&a.ru;</para> - </listitem> - - <listitem> - <para>&a.le;</para> - </listitem> - - <listitem> - <para>&a.se;</para> - </listitem> - - <listitem> - <para>&a.bde;</para> - </listitem> - - <listitem> - <para>&a.sef;</para> - </listitem> - - <listitem> - <para>&a.jedgar;</para> - </listitem> - - <listitem> - <para>&a.green;</para> - </listitem> - - <listitem> - <para>&a.fenner;</para> - </listitem> - - <listitem> - <para>&a.lioux;</para> - </listitem> - - <listitem> - <para>&a.fanf;</para> - </listitem> - - <listitem> - <para>&a.blackend;</para> - </listitem> - - <listitem> - <para>&a.scrappy;</para> - </listitem> - - <listitem> - <para>&a.lars;</para> - </listitem> - - <listitem> - <para>&a.petef;</para> - </listitem> - - <listitem> - <para>&a.dirk;</para> - </listitem> - - <listitem> - <para>&a.sf;</para> - </listitem> - - <listitem> - <para>&a.shige;</para> - </listitem> - - <listitem> - <para>&a.billf;</para> - </listitem> - - <listitem> - <para>&a.furuta;</para> - </listitem> - - <listitem> - <para>&a.gallatin;</para> - </listitem> - - <listitem> - <para>&a.patrick;</para> - </listitem> - - <listitem> - <para>&a.tg;</para> - </listitem> - - <listitem> - <para>&a.gibbs;</para> - </listitem> - - <listitem> - <para>&a.brandon;</para> - </listitem> - - <listitem> - <para>&a.gioria;</para> - </listitem> - - <listitem> - <para>&a.daichi;</para> - </listitem> - - <listitem> - <para>&a.cg;</para> - </listitem> - - <listitem> - <para>&a.edwin;</para> - </listitem> - - <listitem> - <para>&a.jmg;</para> - </listitem> - - <listitem> - <para>&a.znerd;</para> - </listitem> - - <listitem> - <para>&a.hanai;</para> - </listitem> - - <listitem> - <para>&a.roger;</para> - </listitem> - - <listitem> - <para>&a.mharo;</para> - </listitem> - - <listitem> - <para>&a.dannyboy;</para> - </listitem> - - <listitem> - <para>&a.dhartmei;</para> - </listitem> - - <listitem> - <para>&a.jhay;</para> - </listitem> - - <listitem> - <para>&a.sheldonh;</para> - </listitem> - - <listitem> - <para>&a.mikeh;</para> - </listitem> - - <listitem> - <para>&a.mheinen;</para> - </listitem> - - <listitem> - <para>&a.ghelmer;</para> - </listitem> - - <listitem> - <para>&a.mux;</para> - </listitem> - - <listitem> - <para>&a.chm;</para> - </listitem> - - <listitem> - <para>&a.nhibma;</para> - </listitem> - - <listitem> - <para>&a.flathill;</para> - </listitem> - - <listitem> - <para>&a.orion;</para> - </listitem> - - <listitem> - <para>&a.horikawa;</para> - </listitem> - - <listitem> - <para>&a.hosokawa;</para> - </listitem> - - <listitem> - <para>&a.mich;</para> - </listitem> - - <listitem> - <para>&a.cognet;</para> - </listitem> - - <listitem> - <para>&a.jeh;</para> - </listitem> - - <listitem> - <para>&a.hsu;</para> - </listitem> - - <listitem> - <para>&a.foxfair;</para> - </listitem> - - <listitem> - <para>&a.jkh;</para> - </listitem> - - <listitem> - <para>&a.tom;</para> - </listitem> - - <listitem> - <para>&a.mph;</para> - </listitem> - - <listitem> - <para>&a.iwasaki;</para> - </listitem> - - <listitem> - <para>&a.mjacob;</para> - </listitem> - - <listitem> - <para>&a.keith;</para> - </listitem> - - <listitem> - <para>&a.gj;</para> - </listitem> - - <listitem> - <para>&a.trevor;</para> - </listitem> - - <listitem> - <para>&a.kan;</para> - </listitem> - - <listitem> - <para>&a.phk;</para> - </listitem> - - <listitem> - <para>&a.tomsoft;</para> - </listitem> - - <listitem> - <para>&a.cokane;</para> - </listitem> - - <listitem> - <para>&a.johan;</para> - </listitem> - - <listitem> - <para>&a.joe;</para> - </listitem> - - <listitem> - <para>&a.vkashyap;</para> - </listitem> - - <listitem> - <para>&a.kato;</para> - </listitem> - - <listitem> - <para>&a.smkelly;</para> - </listitem> - - <listitem> - <para>&a.kris;</para> - </listitem> - - <listitem> - <para>&a.keramida;</para> - </listitem> - - <listitem> - <para>&a.kientzle;</para> - </listitem> - - <listitem> - <para>&a.fjoe;</para> - </listitem> - - <listitem> - <para>&a.kiri;</para> - </listitem> - - <listitem> - <para>&a.andreas;</para> - </listitem> - - <listitem> - <para>&a.ikob;</para> - </listitem> - - <listitem> - <para>&a.lkoeller;</para> - </listitem> - - <listitem> - <para>&a.sergei;</para> - </listitem> - - <listitem> - <para>&a.motoyuki;</para> - </listitem> - - <listitem> - <para>&a.maxim;</para> - </listitem> - - <listitem> - <para>&a.jkoshy;</para> - </listitem> - - <listitem> - <para>&a.rik;</para> - </listitem> - - <listitem> - <para>&a.rushani;</para> - </listitem> - - <listitem> - <para>&a.kuriyama;</para> - </listitem> - - <listitem> - <para>&a.clement;</para> - </listitem> - - <listitem> - <para>&a.mlaier;</para> - </listitem> - - <listitem> - <para>&a.alex;</para> - </listitem> - - <listitem> - <para>&a.erwin;</para> - </listitem> - - <listitem> - <para>&a.njl;</para> - </listitem> - - <listitem> - <para>&a.reg;</para> - </listitem> - - <listitem> - <para>&a.chern;</para> - </listitem> - - <listitem> - <para>&a.leeym;</para> - </listitem> - - <listitem> - <para>&a.sam;</para> - </listitem> - - <listitem> - <para>&a.stefanf;</para> - </listitem> - - <listitem> - <para>&a.stephane;</para> - </listitem> - - <listitem> - <para>&a.oliver;</para> - </listitem> - - <listitem> - <para>&a.netchild;</para> - </listitem> - - <listitem> - <para>&a.jlemon;</para> - </listitem> - - <listitem> - <para>&a.lesi;</para> - </listitem> - - <listitem> - <para>&a.truckman;</para> - </listitem> - - <listitem> - <para>&a.glewis;</para> - </listitem> - - <listitem> - <para>&a.pat;</para> - </listitem> - - <listitem> - <para>&a.ijliao;</para> - </listitem> - - <listitem> - <para>&a.clive;</para> - </listitem> - - <listitem> - <para>&a.linimon;</para> - </listitem> - - <listitem> - <para>&a.arved;</para> - </listitem> - - <listitem> - <para>&a.kevlo;</para> - </listitem> - - <listitem> - <para>&a.scottl;</para> - </listitem> - - <listitem> - <para>&a.ade;</para> - </listitem> - - <listitem> - <para>&a.mwlucas;</para> - </listitem> - - <listitem> - <para>&a.pav;</para> - </listitem> - - <listitem> - <para>&a.smace;</para> - </listitem> - - <listitem> - <para>&a.bmah;</para> - </listitem> - - <listitem> - <para>&a.mtm;</para> - </listitem> - - <listitem> - <para>&a.jmallett;</para> - </listitem> - - <listitem> - <para>&a.dwmalone;</para> - </listitem> - - <listitem> - <para>&a.nobutaka;</para> - </listitem> - - <listitem> - <para>&a.matusita;</para> - </listitem> - - <listitem> - <para>&a.sem;</para> - </listitem> - - <listitem> - <para>&a.mckay;</para> - </listitem> - - <listitem> - <para>&a.mckusick;</para> - </listitem> - - <listitem> - <para>&a.eric;</para> - </listitem> - - <listitem> - <para>&a.ken;</para> - </listitem> - - <listitem> - <para>&a.mezz;</para> - </listitem> - - <listitem> - <para>&a.dinoex;</para> - </listitem> - - <listitem> - <para>&a.hm;</para> - </listitem> - - <listitem> - <para>&a.sanpei;</para> - </listitem> - - <listitem> - <para>&a.bmilekic;</para> - </listitem> - - <listitem> - <para>&a.mini;</para> - </listitem> - - <listitem> - <para>&a.mita;</para> - </listitem> - - <listitem> - <para>&a.rsm;</para> - </listitem> - - <listitem> - <para>&a.non;</para> - </listitem> - - <listitem> - <para>&a.jim;</para> - </listitem> - - <listitem> - <para>&a.marcel;</para> - </listitem> - - <listitem> - <para>&a.emoore;</para> - </listitem> - - <listitem> - <para>&a.amorita;</para> - </listitem> - - <listitem> - <para>&a.dan;</para> - </listitem> - - <listitem> - <para>&a.tmm;</para> - </listitem> - - <listitem> - <para>&a.markm;</para> - </listitem> - - <listitem> - <para>&a.knu;</para> - </listitem> - - <listitem> - <para>&a.nakai;</para> - </listitem> - - <listitem> - <para>&a.max;</para> - </listitem> - - <listitem> - <para>&a.maho;</para> - </listitem> - - <listitem> - <para>&a.yoichi;</para> - </listitem> - - <listitem> - <para>&a.bland;</para> - </listitem> - - <listitem> - <para>&a.simon;</para> - </listitem> - - <listitem> - <para>&a.anders;</para> - </listitem> - - <listitem> - <para>&a.rnordier;</para> - </listitem> - - <listitem> - <para>&a.lofi;</para> - </listitem> - - <listitem> - <para>&a.obrien;</para> - </listitem> - - <listitem> - <para>&a.danny;</para> - </listitem> - - <listitem> - <para>&a.okazaki;</para> - </listitem> - - <listitem> - <para>&a.olgeni;</para> - </listitem> - - <listitem> - <para>&a.onoe;</para> - </listitem> - - <listitem> - <para>&a.andre;</para> - </listitem> - - <listitem> - <para>&a.osa;</para> - </listitem> - - <listitem> - <para>&a.philip;</para> - </listitem> - - <listitem> - <para>&a.hmp;</para> - </listitem> - - <listitem> - <para>&a.wpaul;</para> - </listitem> - - <listitem> - <para>&a.mp;</para> - </listitem> - - <listitem> - <para>&a.roam;</para> - </listitem> - - <listitem> - <para>&a.den;</para> - </listitem> - - <listitem> - <para>&a.cperciva;</para> - </listitem> - - <listitem> - <para>&a.alfred;</para> - </listitem> - - <listitem> - <para>&a.csjp;</para> - </listitem> - - <listitem> - <para>&a.wes;</para> - </listitem> - - <listitem> - <para>&a.gerald;</para> - </listitem> - - <listitem> - <para>&a.jdp;</para> - </listitem> - - <listitem> - <para>&a.krion;</para> - </listitem> - - <listitem> - <para>&a.bp;</para> - </listitem> - - <listitem> - <para>&a.rpratt;</para> - </listitem> - - <listitem> - <para>&a.steve;</para> - </listitem> - - <listitem> - <para>&a.mpp;</para> - </listitem> - - <listitem> - <para>&a.markp;</para> - </listitem> - - <listitem> - <para>&a.thomas;</para> - </listitem> - - <listitem> - <para>&a.hq;</para> - </listitem> - - <listitem> - <para>&a.darrenr;</para> - </listitem> - - <listitem> - <para>&a.rees;</para> - </listitem> - - <listitem> - <para>&a.greid;</para> - </listitem> - - <listitem> - <para>&a.mr;</para> - </listitem> - - <listitem> - <para>&a.arr;</para> - </listitem> - - <listitem> - <para>&a.trhodes;</para> - </listitem> - - <listitem> - <para>&a.benno;</para> - </listitem> - - <listitem> - <para>&a.paul;</para> - </listitem> - - <listitem> - <para>&a.luigi;</para> - </listitem> - - <listitem> - <para>&a.tjr;</para> - </listitem> - - <listitem> - <para>&a.jeff;</para> - </listitem> - - <listitem> - <para>&a.roberto;</para> - </listitem> - - <listitem> - <para>&a.chuckr;</para> - </listitem> - - <listitem> - <para>&a.jesusr;</para> - </listitem> - - <listitem> - <para>&a.guido;</para> - </listitem> - - <listitem> - <para>&a.groudier;</para> - </listitem> - - <listitem> - <para>&a.dima;</para> - </listitem> - - <listitem> - <para>&a.ps;</para> - </listitem> - - <listitem> - <para>&a.sada;</para> - </listitem> - - <listitem> - <para>&a.marks;</para> - </listitem> - - <listitem> - <para>&a.hrs;</para> - </listitem> - - <listitem> - <para>&a.nsayer;</para> - </listitem> - - <listitem> - <para>&a.sos;</para> - </listitem> - - <listitem> - <para>&a.wosch;</para> - </listitem> - - <listitem> - <para>&a.cy;</para> - </listitem> - - <listitem> - <para>&a.das;</para> - </listitem> - - <listitem> - <para>&a.schweikh;</para> - </listitem> - - <listitem> - <para>&a.lev;</para> - </listitem> - - <listitem> - <para>&a.gshapiro;</para> - </listitem> - - <listitem> - <para>&a.arun;</para> - </listitem> - - <listitem> - <para>&a.shiba;</para> - </listitem> - - <listitem> - <para>&a.nork;</para> - </listitem> - - <listitem> - <para>&a.tshiozak;</para> - </listitem> - - <listitem> - <para>&a.simokawa;</para> - </listitem> - - <listitem> - <para>&a.vanilla;</para> - </listitem> - - <listitem> - <para>&a.cshumway;</para> - </listitem> - - <listitem> - <para>&a.silby;</para> - </listitem> - - <listitem> - <para>&a.bms;</para> - </listitem> - - <listitem> - <para>&a.shafeeq;</para> - </listitem> - - <listitem> - <para>&a.demon;</para> - </listitem> - - <listitem> - <para>&a.jesper;</para> - </listitem> - - <listitem> - <para>&a.skv;</para> - </listitem> - - <listitem> - <para>&a.scop;</para> - </listitem> - - <listitem> - <para>&a.glebius;</para> - </listitem> - - <listitem> - <para>&a.kensmith;</para> - </listitem> - - <listitem> - <para>&a.msmith;</para> - </listitem> - - <listitem> - <para>&a.ben;</para> - </listitem> - - <listitem> - <para>&a.des;</para> - </listitem> - - <listitem> - <para>&a.sobomax;</para> - </listitem> - - <listitem> - <para>&a.dcs;</para> - </listitem> - - <listitem> - <para>&a.brian;</para> - </listitem> - - <listitem> - <para>&a.nsouch;</para> - </listitem> - - <listitem> - <para>&a.ssouhlal;</para> - </listitem> - - <listitem> - <para>&a.dds;</para> - </listitem> - - <listitem> - <para>&a.murray;</para> - </listitem> - - <listitem> - <para>&a.vs;</para> - </listitem> - - <listitem> - <para>&a.marius;</para> - </listitem> - - <listitem> - <para>&a.sumikawa;</para> - </listitem> - - <listitem> - <para>&a.clsung;</para> - </listitem> - - <listitem> - <para>&a.gsutter;</para> - </listitem> - - <listitem> - <para>&a.metal;</para> - </listitem> - - <listitem> - <para>&a.suz;</para> - </listitem> - - <listitem> - <para>&a.unfurl;</para> - </listitem> - - <listitem> - <para>&a.nyan;</para> - </listitem> - - <listitem> - <para>&a.tanimura;</para> - </listitem> - - <listitem> - <para>&a.taoka;</para> - </listitem> - - <listitem> - <para>&a.mi;</para> - </listitem> - - <listitem> - <para>&a.gordon;</para> - </listitem> - - <listitem> - <para>&a.lth;</para> - </listitem> - - <listitem> - <para>&a.thierry;</para> - </listitem> - - <listitem> - <para>&a.yar;</para> - </listitem> - - <listitem> - <para>&a.cwt;</para> - </listitem> - - <listitem> - <para>&a.viny;</para> - </listitem> - - <listitem> - <para>&a.ume;</para> - </listitem> - - <listitem> - <para>&a.semenu;</para> - </listitem> - - <listitem> - <para>&a.rv;</para> - </listitem> - - <listitem> - <para>&a.hoek;</para> - </listitem> - - <listitem> - <para>&a.logo;</para> - </listitem> - - <listitem> - <para>&a.nectar;</para> - </listitem> - - <listitem> - <para>&a.jayanth;</para> - </listitem> - - <listitem> - <para>&a.wjv;</para> - </listitem> - - <listitem> - <para>&a.bean;</para> - </listitem> - - <listitem> - <para>&a.ticso;</para> - </listitem> - - <listitem> - <para>&a.takawata;</para> - </listitem> - - <listitem> - <para>&a.adamw;</para> - </listitem> - - <listitem> - <para>&a.naddy;</para> - </listitem> - - <listitem> - <para>&a.assar;</para> - </listitem> - - <listitem> - <para>&a.dwhite;</para> - </listitem> - - <listitem> - <para>&a.nate;</para> - </listitem> - - <listitem> - <para>&a.wollman;</para> - </listitem> - - <listitem> - <para>&a.keichii;</para> - </listitem> - - <listitem> - <para>&a.joerg;</para> - </listitem> - - <listitem> - <para>&a.davidxu;</para> - </listitem> - - <listitem> - <para>&a.kbyanc;</para> - </listitem> - - <listitem> - <para>&a.jennifer;</para> - </listitem> - - <listitem> - <para>&a.emax;</para> - </listitem> - - <listitem> - <para>&a.yokota;</para> - </listitem> - - <listitem> - <para>&a.andy;</para> - </listitem> - - <listitem> - <para>&a.zarzycki;</para> - </listitem> - - <listitem> - <para>&a.bz;</para> - </listitem> - - <listitem> - <para>&a.phantom;</para> - </listitem> - - <listitem> - <para>&a.jmz;</para> - </listitem> - </itemizedlist> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("article.sgml" "part" "sect1") - End: ---> - diff --git a/en_US.ISO8859-1/articles/contributors/contrib.core.sgml b/en_US.ISO8859-1/articles/contributors/contrib.core.sgml deleted file mode 100644 index 3369f17118..0000000000 --- a/en_US.ISO8859-1/articles/contributors/contrib.core.sgml +++ /dev/null @@ -1,55 +0,0 @@ -<!-- $FreeBSD$ --> -<!-- - NOTE TO NEW COMMITTERS: Core and committers lists are sorted in - alphabetical order by last name. Please keep in mind that fact while - adding your entity to the list of developers. ---> - - <itemizedlist> - <listitem> - <para>&a.jhb;</para> - </listitem> - - <listitem> - <para>&a.kuriyama;</para> - </listitem> - - <listitem> - <para>&a.scottl;</para> - </listitem> - - <listitem> - <para>&a.imp;</para> - </listitem> - - <listitem> - <para>&a.markm;</para> - </listitem> - - <listitem> - <para>&a.wes;</para> - </listitem> - - <listitem> - <para>&a.murray;</para> - </listitem> - - <listitem> - <para>&a.rwatson;</para> - </listitem> - - <listitem> - <para>&a.peter;</para> - </listitem> - </itemizedlist> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("article.sgml" "part" "sect1") - End: ---> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.corealumni.sgml b/en_US.ISO8859-1/articles/contributors/contrib.corealumni.sgml deleted file mode 100644 index df2232a852..0000000000 --- a/en_US.ISO8859-1/articles/contributors/contrib.corealumni.sgml +++ /dev/null @@ -1,126 +0,0 @@ -<!-- $FreeBSD$ --> - - <itemizedlist> - <listitem> - <para>&a.grog; (2000-2004)</para> - </listitem> - - <listitem> - <para>&a.dg; (1992 - 2002)</para> - </listitem> - - <listitem> - <para>&a.dfr; (1999 - 2002)</para> - </listitem> - - <listitem> - <para>&a.msmith; (2000 - 2002)</para> - </listitem> - - <listitem> - <para>&a.jkh; (1992 - 2002)</para> - </listitem> - - <listitem> - <para>&a.asami; (1993 - 2001)</para> - </listitem> - - <listitem> - <para>&a.ache; (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.jmb; (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.bde; (1992 - 2000)</para> - </listitem> - - <listitem> - <para>&a.gibbs; (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.rich; (1994 - 2000)</para> - </listitem> - - <listitem> - <para>&a.phk; (1992 - 2000)</para> - </listitem> - - <listitem> - <para>&a.gpalmer; (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.sos; (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.wollman; (1993 - 2000)</para> - </listitem> - - <listitem> - <para>&a.joerg; (1995 - 2000)</para> - </listitem> - - <listitem> - <para>&a.jdp; (1997 - 2000)</para> - </listitem> - - <listitem> - <para>&a.guido; (1995 - 1999)</para> - </listitem> - - <listitem> - <para>John Dyson (1993 - 1998)</para> - </listitem> - - <listitem> - <para>&a.nate; (1992 - 1996)</para> - </listitem> - - <listitem> - <para>&a.rgrimes; (1992 - 1995)</para> - </listitem> - - <listitem> - <para>Andreas Schulz (1992 - 1995)</para> - </listitem> - - <listitem> - <para>&a.csgr; (1993 - 1995)</para> - </listitem> - - <listitem> - <para>&a.paul; (1992 - 1995)</para> - </listitem> - - <listitem> - <para>&a.smace; (1993 - 1994)</para> - </listitem> - - <listitem> - <para>Andrew Moore (1993 - 1994)</para> - </listitem> - - <listitem> - <para>Christoph Robitschko (1993 - 1994)</para> - </listitem> - - <listitem> - <para>J. T. Conklin (1992 - 1993)</para> - </listitem> - </itemizedlist> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("article.sgml" "part" "sect1") - End: - --> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.develalumni.sgml b/en_US.ISO8859-1/articles/contributors/contrib.develalumni.sgml deleted file mode 100644 index 61f062dd0e..0000000000 --- a/en_US.ISO8859-1/articles/contributors/contrib.develalumni.sgml +++ /dev/null @@ -1,288 +0,0 @@ -<!-- $FreeBSD$ --> - - <itemizedlist> - <listitem> - <para>&a.alane; (2002 - - <ulink url="http://freebsd.kde.org/memoriam/alane.php">2003</ulink>) - </para> - </listitem> - - <listitem> - <para>&a.amurai; (1995 - 2003)</para> - </listitem> - - <listitem> - <para>&a.jfitz; (1996 - 2003)</para> - </listitem> - - <listitem> - <para>&a.stb; (1994 - 2003)</para> - </listitem> - - <listitem> - <para>&a.csgr; (1994 - 2003)</para> - </listitem> - - <listitem> - <para>&a.mtaylor; (1999 - 2003)</para> - </listitem> - - <listitem> - <para>&a.pho; (1999 - 2003)</para> - </listitem> - - <listitem> - <para>&a.dufault; (1995 - 2003)</para> - </listitem> - - <listitem> - <para>&a.wsanchez; (2000 - 2003)</para> - </listitem> - - <listitem> - <para>&a.imura; (1999 - 2003)</para> - </listitem> - - <listitem> - <para>&a.cpiazza; (1999 - 2003) </para> - </listitem> - - <listitem> - <para>&a.davidn; (1996 - 2003)</para> - </listitem> - - <listitem> - <para>&a.jseger; (1997 - 2003)</para> - </listitem> - - <listitem> - <para>&a.toshi; (2000 - 2003)</para> - </listitem> - - <listitem> - <para>&a.newton; (1999 - 2003)</para> - </listitem> - - <listitem> - <para>&a.marko; (2000 - 2003)</para> - </listitem> - - <listitem> - <para>&a.lile; (1999 - 2003)</para> - </listitem> - - <listitem> - <para>&a.cp; (1999 - 2003)</para> - </listitem> - - <listitem> - <para>&a.ejc; (1999 - 2003)</para> - </listitem> - - <listitem> - <para>&a.shin; (1999 - 2003)</para> - </listitem> - - <listitem> - <para>&a.gpalmer; (1993 - 2003)</para> - </listitem> - - <listitem> - <para>&a.fsmp; (1997 - 2003)</para> - </listitem> - - <listitem> - <para>&a.rgrimes; (1992 - 2003)</para> - </listitem> - - <listitem> - <para>&a.mks; (1994 - 2003)</para> - </listitem> - - <listitem> - <para>&a.dt; (1998 - 2003)</para> - </listitem> - - <listitem> - <para>&a.jfieber; (1995 - 2003)</para> - </listitem> - - <listitem> - <para>&a.rvb; (1998 - 2003)</para> - </listitem> - - <listitem> - <para>&a.stark; (1997 - 2003)</para> - </listitem> - - <listitem> - <para>&a.helbig; (1997 - 2003)</para> - </listitem> - - <listitem> - <para>&a.thepish; (1998 - 2003)</para> - </listitem> - - <listitem> - <para>&a.adam; (1994 - 2003)</para> - </listitem> - - <listitem> - <para>&a.mbarkah; (1996 - 2003)</para> - </listitem> - - <listitem> - <para>&a.pds; (1997 - 2003)</para> - </listitem> - - <listitem> - <para>&a.smpatel; (1996 - 2003)</para> - </listitem> - - <listitem> - <para>&a.swallace; (1994 - 2003)</para> - </listitem> - - <listitem> - <para>&a.rich; (1994 - 2003)</para> - </listitem> - - <listitem> - <para>&a.ugen; (1994 - 2003)</para> - </listitem> - - <listitem> - <para>&a.ljo; (1994 - 2003)</para> - </listitem> - - <listitem> - <para>&a.pirzyk; (2001 - 2003)</para> - </listitem> - - <listitem> - <para>&a.dillon; (1998 - 2003)</para> - </listitem> - - <listitem> - <para>&a.dick; (1999 - 2003)</para> - </listitem> - - <listitem> - <para>&a.pst; (1994 - 2003)</para> - </listitem> - - <listitem> - <para>&a.erich; (1995 - 2002)</para> - </listitem> - - <listitem> - <para>&a.jasone; (1999 - 2002)</para> - </listitem> - - <listitem> - <para>&a.martin; (1994 - 2002)</para> - </listitem> - - <listitem> - <para>&a.graichen; (1996 - 2002)</para> - </listitem> - - <listitem> - <para>&a.asmodai; (1999 - 2002)</para> - </listitem> - - <listitem> - <para>&a.uch; (2000 - 2002)</para> - </listitem> - - <listitem> - <para>&a.jmacd; (1995 - 2002)</para> - </listitem> - - <listitem> - <para>&a.issei; (2000 - 2002)</para> - </listitem> - - <listitem> - <para>&a.itojun; (1997 - 2001)</para> - </listitem> - - <listitem> - <para>Nate Johnson (1996 - 2000)</para> - </listitem> - - <listitem> - <para>MAEKAWA Masahide (1999 - 2000)</para> - </listitem> - - <listitem> - <para>&a.tedm; (1997 - 2000)</para> - </listitem> - - <listitem> - <para>&a.karl; (1995 - 2000)</para> - </listitem> - - <listitem> - <para>Gary Clark II (1993 - 2000)</para> - </listitem> - - <listitem> - <para>James Raynard (1996 - 2000)</para> - </listitem> - - <listitem> - <para>Andreas Schulz (1992 - 1999)</para> - </listitem> - - <listitem> - <para>&a.jgreco; (1997 - 1999)</para> - </listitem> - - <listitem> - <para>Jamil Weatherby (1997 - 1999)</para> - </listitem> - - <listitem> - <para>Megan McCormack (1997 - 1998)</para> - </listitem> - - <listitem> - <para>John Dyson (1993 - 1998)</para> - </listitem> - - <listitem> - <para>Amancio Hasty (1997 - 1998)</para> - </listitem> - - <listitem> - <para>Drew Derbyshire (1997 - 1998)</para> - </listitem> - - <listitem> - <para>Andras Olah (1995 - 1996)</para> - </listitem> - - <listitem> - <para>Julian H. Stacey (1995)</para> - </listitem> - - <listitem> - <para>gjp (1995)</para> - </listitem> - - <listitem> - <para>Andrew L. Moore (1993 - 1995)</para> - </listitem> - </itemizedlist> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("article.sgml" "part" "sect1") - End: ---> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.ent b/en_US.ISO8859-1/articles/contributors/contrib.ent deleted file mode 100644 index 7fe5986b6b..0000000000 --- a/en_US.ISO8859-1/articles/contributors/contrib.ent +++ /dev/null @@ -1,9 +0,0 @@ -<!-- $FreeBSD$ --> - -<!ENTITY contrib.386bsd SYSTEM "contrib.386bsd.sgml"> -<!ENTITY contrib.additional SYSTEM "contrib.additional.sgml"> -<!ENTITY contrib.committers SYSTEM "contrib.committers.sgml"> -<!ENTITY contrib.core SYSTEM "contrib.core.sgml"> -<!ENTITY contrib.corealumni SYSTEM "contrib.corealumni.sgml"> -<!ENTITY contrib.develalumni SYSTEM "contrib.develalumni.sgml"> -<!ENTITY contrib.staff SYSTEM "contrib.staff.sgml"> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.staff.sgml b/en_US.ISO8859-1/articles/contributors/contrib.staff.sgml deleted file mode 100644 index acbb2da4b5..0000000000 --- a/en_US.ISO8859-1/articles/contributors/contrib.staff.sgml +++ /dev/null @@ -1,410 +0,0 @@ -<!-- $FreeBSD$ --> - - <sect2> - <title>The &os; documentation engineering team</title> - - <para>The &os; documentation engineering team is made up of the - following unelected individuals:</para> - - <itemizedlist> - <listitem> - <para>&a.murray;</para> - </listitem> - - <listitem> - <para>&a.kuriyama;</para> - </listitem> - - <listitem> - <para>&a.ru;</para> - </listitem> - - <listitem> - <para>&a.nik;</para> - </listitem> - - <listitem> - <para>&a.blackend;</para> - </listitem> - - <listitem> - <para>&a.hrs;</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>The &os; port management team</title> - - <para>The &os; port management team is made up of the - following unelected individuals:</para> - - <itemizedlist> - <listitem> - <para>&a.kris;</para> - </listitem> - - <listitem> - <para>&a.will;</para> - </listitem> - - <listitem> - <para>&a.marcus;</para> - </listitem> - - <listitem> - <para>&a.linimon;</para> - </listitem> - - <listitem> - <para>&a.eik;</para> - </listitem> - - <listitem> - <para>&a.krion;</para> - </listitem> - - </itemizedlist> - </sect2> - - - <sect2> - <title>The &os; Donations Team</title> - - <para>The &os; Donations Liaison Team consists of the - following designated individuals:</para> - - <itemizedlist> - <listitem> - <para>&a.mwlucas;</para> - </listitem> - - <listitem> - <para>&a.nsayer;</para> - </listitem> - - <listitem> - <para>&a.obrien;</para> - </listitem> - - <listitem> - <para>&a.trhodes;</para> - </listitem> - - <listitem> - <para>&a.wilko; (core team liaison)</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>The &os; Technical Review Board</title> - - <para>The &os; Technical Review Board consists of the following - appointed individuals:</para> - - <itemizedlist> - <listitem> - <para>&a.dfr;</para> - </listitem> - - <listitem> - <para>&a.jake;</para> - </listitem> - - <listitem> - <para>&a.jeff;</para> - </listitem> - - <listitem> - <para>&a.iedowse;</para> - </listitem> - - <listitem> - <para>&a.alc;</para> - </listitem> - - <listitem> - <para>&a.gallatin;</para> - </listitem> - - <listitem> - <para>&a.jhb;</para> - </listitem> - - <listitem> - <para>&a.peter;</para> - </listitem> - - <listitem> - <para>&a.imp;</para> - </listitem> - - <listitem> - <para>&a.sam;</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="staff-secteam"> - <title>The &os; Security Team:</title> - - <para>The current security team in &os; consists of:</para> - - <itemizedlist> - <listitem> - <para>&a.rwatson;</para> - </listitem> - - <listitem> - <para>&a.bms;</para> - </listitem> - - <listitem> - <para>&a.cperciva;</para> - </listitem> - - <listitem> - <para>&a.des;</para> - </listitem> - - <listitem> - <para>&a.gshapiro;</para> - </listitem> - - <listitem> - <para>&a.guido;</para> - </listitem> - - <listitem> - <para>&a.imp;</para> - </listitem> - - <listitem> - <para>&a.julian;</para> - </listitem> - - <listitem> - <para>&a.nectar;</para> - </listitem> - - <listitem> - <para>&a.trhodes;</para> - </listitem> - </itemizedlist> - </sect2> - - - <sect2> - <title>Misc Hats</title> - - <para>Current &os; Bugmeisters and <acronym>GNATS</acronym> admins:</para> - - <itemizedlist> - <listitem> - <para>&a.ceri;</para> - </listitem> - - <listitem> - <para>&a.keramida;</para> - </listitem> - - <listitem> - <para>&a.linimon;</para> - </listitem> - </itemizedlist> - - <para>Current &os; security officer:</para> - - <itemizedlist> - <listitem> - <para>&a.nectar;</para> - </listitem> - </itemizedlist> - - <para>Current &os; security officer deputy</para> - - <itemizedlist> - <listitem> - <para>&a.des;</para> - </listitem> - </itemizedlist> - - <para>Current &os; core team secretary:</para> - <itemizedlist> - <listitem> - <para>&a.wilko;</para> - </listitem> - </itemizedlist> - - </sect2> - </sect1> - - <sect1 id="staff-re"> - <title>&os; Release Engineering Teams</title> - - <sect2> - <title>Primary &os; Release Engineering Team</title> - - <para>The delegated individuals make up the primary &os; release - engineering team:</para> - - <itemizedlist> - <listitem> - <para>&a.jhb;</para> - </listitem> - - <listitem> - <para>&a.murray;</para> - </listitem> - - <listitem> - <para>&a.rwatson;</para> - </listitem> - - <listitem> - <para>&a.scottl;</para> - </listitem> - - <listitem> - <para>&a.steve;</para> - </listitem> - - <listitem> - <para>&a.kensmith;</para> - </listitem> - - <listitem> - <para>&a.hrs;</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Alpha Release Engineering</title> - - <para>The &os; Alpha release engineering team is made up of the - following delegated individuals:</para> - - <itemizedlist> - <listitem> - <para>&a.jhb;</para> - </listitem> - - <listitem> - <para>&a.murray;</para> - </listitem> - - <listitem> - <para>&a.rwatson;</para> - </listitem> - - <listitem> - <para>&a.scottl;</para> - </listitem> - - <listitem> - <para>&a.wilko;</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>IA-64 Release Engineering</title> - - <para>The IA-64 release engineering team is made up of the - following delegated individuals:</para> - - <itemizedlist> - <listitem> - <para>&a.marcel;</para> - </listitem> - - <listitem> - <para>&a.peter;</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>i386 Release Engineering</title> - - <para>The i386 release engineering team is made up of the - following delegated individuals:</para> - - <itemizedlist> - <listitem> - <para>&a.jhb;</para> - </listitem> - - <listitem> - <para>&a.murray;</para> - </listitem> - - <listitem> - <para>&a.rwatson;</para> - </listitem> - - <listitem> - <para>&a.scottl;</para> - </listitem> - - <listitem> - <para>&a.hrs;</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>PC98 Release Engineering</title> - - <para>The PC98 release engineering team is made up of the - following delegated individual:</para> - - <itemizedlist> - <listitem> - <para>&a.nyan;</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Sparc64 Release Engineering</title> - - <para>The Sparc64 release engineering team is made up of - of the following delegated individuals:</para> - - <itemizedlist> - <listitem> - <para>&a.jake;</para> - </listitem> - - <listitem> - <para>&a.murray;</para> - </listitem> - - <listitem> - <para>&a.jhb;</para> - </listitem> - - <listitem> - <para>&a.scottl;</para> - </listitem> - - <listitem> - <para>&a.phk;</para> - </listitem> - - <listitem> - <para>&a.tmm;</para> - </listitem> - - <listitem> - <para>&a.rwatson;</para> - </listitem> - - <listitem> - <para>&a.kensmith;</para> - </listitem> - </itemizedlist> - </sect2> diff --git a/en_US.ISO8859-1/articles/cvs-freebsd/Makefile b/en_US.ISO8859-1/articles/cvs-freebsd/Makefile deleted file mode 100644 index 1740a1a8e9..0000000000 --- a/en_US.ISO8859-1/articles/cvs-freebsd/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# $FreeBSD$ -# -# Article: Setting up a CVS repository - the FreeBSD way - -MAINTAINER= stijn@win.tue.nl - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml b/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml deleted file mode 100644 index 25f16e6a31..0000000000 --- a/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml +++ /dev/null @@ -1,686 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Setting up a CVS repository - the FreeBSD way</title> - - <author> - <firstname>Stijn</firstname> - <surname>Hoop</surname> - <affiliation> - <address><email>stijn@win.tue.nl</email></address> - </affiliation> - </author> - - <copyright> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <holder role="mailto:stijn@win.tue.nl">Stijn Hoop</holder> - </copyright> - - <releaseinfo>$FreeBSD$</releaseinfo> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This article describes the steps I took to set up a CVS repository - that uses the same scripts the FreeBSD project uses in their setup. - This has several advantages over a stock CVS setup, including more - granular access control to the source tree and generation of readable - email of every commit.</para> - </abstract> - </articleinfo> - - <sect1> - <title>Introduction</title> - - <para>Most of the open source software projects use - <application>CVS</application> as their source code control system. - While <application>CVS</application> is pretty good at this, it has its - share of flaws and weaknesses. One of these is that sharing a source - tree with other developers can quickly lead to a system administration - nightmare, especially if one wishes to protect parts of the tree from - general access.</para> - - <para>FreeBSD is one of the projects using <application>CVS</application>. - It also has a large base of developers located around the world. - They developed some scripts to make management of the repository easier. - Recently, these scripts were revisited and normalized by &a.joe; - to make it easier to reuse them in other projects. This - article describes one method of using the new scripts.</para> - - <para>To make the most use of the information in this article, you need to - be familiar with the basic method of operation of - <application>CVS</application>.</para> - </sect1> - - <sect1> - <title>First setup</title> - - <warning> - <para>It might be best to first perform this procedure with an empty - test repository, to make sure you understand all consequences. - As always, make sure you have recent, readable backups!</para> - </warning> - - <sect2> - <title>Initializing the repository</title> - - <para>The first thing to do when setting up a new repository is to tell - <application>CVS</application> to initialize it: - - <screen>&prompt.user; <userinput>cvs -d <replaceable>path-to-repository</replaceable> init</userinput></screen> - - This tells <application>CVS</application> to create the - <filename>CVSROOT</filename> administrative directory, where all the - customization takes place.</para> - </sect2> - - <sect2> - <title>The repository group</title> - - <para>Now we will create the group which will own the repository. - All committers need to be in this group, so that they can write to the - repository. We will assume the FreeBSD default of - <literal>ncvs</literal> for this group. - - <screen>&prompt.root; <userinput>pw groupadd <replaceable>ncvs</replaceable></userinput></screen> - - Next, you should &man.chown.8; the directory to the group - you just added: - - <screen>&prompt.root; <userinput>chown -R :<replaceable>ncvs</replaceable> <replaceable>path-to-your-repository</replaceable></userinput></screen> - - This ensures that no one can write to the repository without proper - group permissions.</para> - </sect2> - - <sect2> - <title>Getting the sources</title> - - <para>Now you need to obtain the <filename>CVSROOT</filename> directory - from the FreeBSD repository. This is most easily done by checking it - out from a FreeBSD anonymous CVS mirror. See <ulink - url="&url.books.handbook;/anoncvs.html">the relevant chapter in - the handbook</ulink> for more information. Let us assume that the - sources are stored in <filename>CVSROOT-freebsd</filename> in the - current directory.</para> - </sect2> - - <sect2> - <title>Copying the FreeBSD scripts</title> - - <para>Next, we will copy the FreeBSD <filename>CVSROOT</filename> - sources into your own repository. If you are accustomed to - <application>CVS</application>, you might be thinking that you can just - import the scripts, in an attempt to make synchronizing with later - versions easier. However, it turns out that - <application>CVS</application> has a deficiency in this area: - when importing sources into the <filename>CVSROOT</filename> directory, - it will not update the needed administrative files. In order to make - it recognize those, you will need to checkin each file after importing - them, losing the value of <literal>cvs import</literal>. Therefore, - the recommended method is to simply copy over the scripts.</para> - - <para>It does not matter if the above paragraph did not make sense to - you—the end result is the same. Simply check out your - <filename>CVSROOT</filename> and copy the FreeBSD files over your - local (untouched) copies: - - <screen>&prompt.user; <userinput>cvs -d <replaceable>path-to-your-repository</replaceable> checkout CVSROOT</userinput> -&prompt.user; <userinput>cd CVSROOT</userinput> -&prompt.user; <userinput>cp ../CVSROOT-freebsd/* .</userinput> -&prompt.user; <userinput>cvs add *</userinput></screen> - - Note that you will probably get a few warnings about some directories - not being copied; this is normal, you do not need those.</para> - </sect2> - - <sect2> - <title>The scripts</title> - - <para>Now you have in your working directory an exact copy of the scripts - that the FreeBSD project itself uses for their repository. A summary - of what each file is used for is included below.</para> - - <itemizedlist> - <listitem> - <para><filename>access</filename> - this file is not used in the - default setup. It is used in <link linkend="freebsdspecific">the - FreeBSD project specific setup</link>, where it controls access to - the repository. You can remove this file if you - do not wish to use this setup.</para> - </listitem> - - <listitem> - <para><filename>avail</filename> - this file controls access to the - repository. In this, you can specify groups of people that are - allowed access to the repository, as well as disallow commits on a - per-directory basis. You should tailor it to contain the groups - and directories that will be in your repository.</para> - </listitem> - - <listitem> - <para><filename>cfg.pm</filename> - this file parses your - configuration, and provides the default configuration. You should - <emphasis>not</emphasis> make changes to this file. Instead, put - your configuration changes in - <filename>cfg_local.pm</filename>.</para> - </listitem> - - <listitem> - <para><filename>cfg_local.pm</filename> - this file contains all - configurable parameters of the system. You should configure all - sorts of settings here, such as where commit mail is send, on what - hosts people can commit, and others. More information on this - below.</para> - </listitem> - - <listitem> - <para><filename>checkoutlist</filename> - this files lists all - files under control of <application>CVS</application> in this - directory, apart from the standard ones created by - <literal>cvs init</literal>. You should edit this to remove - some FreeBSD-specific files.</para> - </listitem> - - <listitem> - <para><filename>commit_prep.pl</filename> - this script performs - various pre-commit checks, based on whether you enabled them in your - <filename>cfg_local.pm</filename>. You should not have to touch - this.</para> - </listitem> - - <listitem> - <para><filename>commitcheck</filename> - this script is invoked - directly from <application>CVS</application>. It first checks - if the committer has access to the specified part of the tree - using <filename>cvs_acls.pl</filename>, and then runs - <filename>commit_prep.pl</filename> for the various pre-commit - checks. If those are OK, <application>CVS</application> will - allow the commit to proceed. You should not have to touch this - file.</para> - </listitem> - - <listitem> - <para><filename>commitinfo</filename> - this file is used by - <application>CVS</application> to determine which script to run - before a commit—in this case <filename>commitcheck</filename>. - You should not have to touch this file.</para> - </listitem> - - <listitem> - <para><filename>config</filename> - the configuration file for - this repository. You should change this as needed, but most - administrators can probably leave the defaults. More information on - the options that can be set here can be found in the - <application>CVS</application> manual.</para> - </listitem> - - <listitem> - <para><filename>cvs_acls.pl</filename> - this script determines - the committers identity, and whether he/she is allowed access to the - tree. It does this based on the <filename>avail</filename> file. - You should not have to touch this file.</para> - </listitem> - - <listitem> - <para><filename>cvsignore</filename> - this file specifies files - that <application>CVS</application> should not checkin in the - repository. You can edit this as you wish. More information about - this file is available in the <application>CVS</application> - manual.</para> - </listitem> - - <listitem> - <para><filename>cvswrappers</filename> - this file is used by - <application>CVS</application> to enable or disable keyword - expansion, or whether a file should be considered binary. You - can edit this as you wish. More information about this file - is available in the <application>CVS</application> manual. - Note that the <literal>-t</literal> and <literal>-f</literal> - options do not work correctly with client/server - <application>CVS</application>.</para> - </listitem> - - <listitem> - <para><filename>edithook</filename> - this file is not used - any more, but kept for historic reasons. You can safely - remove this file.</para> - </listitem> - - <listitem> - <para><filename>editinfo</filename> - <application>CVS</application> - uses this file for editor overrides. FreeBSD does not use this - functionality, as parsing the log message is done by - <filename>verifymsg</filename> and <filename>logcheck</filename>. - This is because the <filename>editinfo</filename> - functionality does not work properly with remote commits, or ones - that use the <literal>-m</literal> or <literal>-F</literal> - options. You should not have to touch this file.</para> - </listitem> - - <listitem> - <para><filename>exclude</filename> - this file lists regular - expressions that are used by <filename>commit_prep.pl</filename> - to determine files which cannot contain a revision header. In the - FreeBSD setup, all files under revision control need to have a - revision header (like $FreeBSD$). All filenames that - match one of the lines in this file are exempted from this check. - You should add expressions to this file as you checkin files that - cannot have a revision header. For the purpose of installing the - scripts, it may be best to exclude <filename>CVSROOT/</filename> - from header checks.</para> - </listitem> - - <listitem> - <para><filename>log_accum.pl</filename> - this is a script that takes - the log message as provided by the <filename>logcheck</filename> - script, and appends it to a log file in the repository for backup - purposes. It also handles mailing out a message to an email address - you provide (in <filename>cfg_local.pm</filename>). It hooks into - <application>CVS</application> via <filename>loginfo</filename>. - You should not have to touch this file.</para> - </listitem> - - <listitem> - <para><filename>logcheck</filename> - this file parses the commit - log message that committers provide, and attempts to sanitize it - somewhat. It hooks into <application>CVS</application> via - <filename>verifymsg</filename>. You should not have to touch - this file.</para> - - <note><para>This script depends on a local FreeBSD hack of - <application>CVS</application>: this version reads the log message - back in after this script has modified it. The stock version of - <application>CVS</application> does not do this which makes - <filename>logcheck</filename> unable to clean up the log message, - although it is still able to check that it is syntactically - OK. <application>CVS</application> 1.11.2 can be configured to - have the same behaviour as FreeBSD's version by setting - <literal>RereadLogAfterVerify=always</literal> in the - <filename>config</filename> file.</para></note> - </listitem> - - <listitem> - <para><filename>loginfo</filename> - this file is used by - <application>CVS</application> to control where log - information is sent; <filename>log_accum.pl</filename> hooks - in here. You should not have to touch this file.</para> - </listitem> - - <listitem> - <para><filename>modules</filename> - this file retains its - traditional meaning in <application>CVS</application>. You should - remove the FreeBSD modules from the stock version. You can edit this - as you wish. More information about this file is available in the - <application>CVS</application> manual.</para> - </listitem> - - <listitem> - <para><filename>notify</filename> - this file is used by - <application>CVS</application> in case someone sets a watch on a - file. It is not used in the FreeBSD repository. You can edit this as - you wish. More information about this file is available in the - <application>CVS</application> manual.</para> - </listitem> - - <listitem> - <para><filename>options</filename> - this file is specific to - the FreeBSD version of <application>CVS</application>, and is - also supported by the Debian version. It contains - the keyword to expand in revision headers. You should alter this to - match the keyword you specified in - <filename>cfg_local.pm</filename> (if you use that feature, which - is FreeBSD specific for now).</para> - </listitem> - - <listitem> - <para><filename>rcsinfo</filename> - this file maps directories in - the repository to template files such as - <filename>rcstemplate</filename>. By default, FreeBSD uses one - template for the whole repository. You can add others to this file - if you wish.</para> - </listitem> - - <listitem> - <para><filename>rcstemplate</filename> - this file is the actual - template committers will see when they make a checkin. You should - edit this to describe the various extra parameters you defined in - <filename>cfg_local.pm</filename>.</para> - </listitem> - - <listitem> - <para><filename>tagcheck</filename> - this files controls access - to tagging in the repository. The stock FreeBSD version disallows - tags with names of RELENG*, because of the release engineering - process. You should edit this file as desired.</para> - </listitem> - - <listitem> - <para><filename>taginfo</filename> - this file maps tag operations - on repository directories to access control scripts such as - <filename>tagcheck</filename>. You should not have to touch this - file.</para> - </listitem> - - <listitem> - <para><filename>unwrap</filename> - this script can be used to - automatically <quote>unwrap</quote> binary files (see - <filename>cvswrappers</filename>) on checkout. It is not used in - the current FreeBSD setup because the functionality it hooks into - does not work well with remote commits. You should not have to - touch this file.</para> - </listitem> - - <listitem> - <para><filename>verifymsg</filename> - this file maps repository - directories to post processor scripts of log messages such as - <filename>logcheck</filename>. You should not have to touch - this file.</para> - </listitem> - - <listitem> - <para><filename>wrap</filename> - this script can be used to - automatically <quote>wrap</quote> binary files (see - <filename>cvswrappers</filename>) on checkin. It is not used - in the current FreeBSD setup because the functionality it - hooks into does not work well with remote commits. You should - not have to touch this file.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Customizing the scripts</title> - - <para>The next step is to set up the scripts so that they work in - your environment. You should go over all files in the directory and - make your customizations. In particular, you might want to do edit the - following files:</para> - - <procedure> - <step> - <para>If you do not wish to use the <link linkend="freebsdspecific"> - FreeBSD specific features</link> of the scripts, you can safely - remove the <filename>access</filename> file: - - <screen>&prompt.user; <userinput>cvs rm -f access</userinput></screen></para> - </step> - - <step> - <para>Edit <filename>avail</filename> to contain the various - repository directories in which you want to control access. Make - sure you retain the <literal>avail||CVSROOT</literal> line, - otherwise you will lock yourself out in the next step.</para> - - <para>The other thing you can add in this file are committer groups. - By default, FreeBSD uses the <filename>access</filename> file to - list all its committers in, but you can use any file you wish. You - can also add groups if you want (the syntax is specified at the - top of <filename>cvs_acls.pl</filename>).</para> - </step> - - <step> - <para>Edit <filename>cfg_local.pm</filename> to contain the options - you want. In particular, you should take a look at the following - configurable items: - - <itemizedlist> - <listitem> - <para><literal>%TEMPLATE_HEADERS</literal> - these get - processed by the log scripts, and inserted below the - commit mail if present and non-empty in the commit - message. You can probably remove the <literal>PR</literal> - and <literal>MFC after</literal> entries. And of course - you can add your own.</para> - </listitem> - - <listitem> - <para><literal>$MAIL_BRANCH_HDR</literal> - if you want - to insert a header into each commit mail describing the - branch on which the commit was made, define this to match - your setup. Or leave it empty if you do not want such a - header.</para> - </listitem> - - <listitem> - <para><literal>@COMMIT_HOSTS</literal> - define this to - be a list of hosts on which people can commit.</para> - </listitem> - - <listitem> - <para><literal>$MAILADDRS</literal> - set this to the - admin or list address that should receive commit mail.</para> - </listitem> - - <listitem> - <para><literal>@LOG_FILE_MAP</literal> - change this array - as you wish - each regexp is matched on the directory of - the commit, and the commit log message gets stored in - the <filename>commitlogs</filename> subdirectory in - the filename mentioned.</para> - </listitem> - - <listitem> - <para><literal>$COMMITCHECK_EXTRA</literal> - if you do not - want to use <link linkend="freebsdspecific">the FreeBSD - specific access checks</link>, you should remove the - definition of <literal>$COMMITCHECK_EXTRA</literal> from - this file.</para> - </listitem> - </itemizedlist> - - <note><para>Changing the <literal>$IDHEADER</literal> parameter - is only guaranteed to work on FreeBSD platforms; it depends on - FreeBSD specific modifications to - <application>CVS</application>.</para></note> - - You can check <filename>cfg.pm</filename> to see which other - options can be changed, but the above is a reasonable subset.</para> - </step> - - <step> - <para>Edit <filename>exclude</filename> to remove the FreeBSD specific - entries (such as all lines beginning with <literal>^ports/</literal> - etc.). Furthermore, comment out the lines beginning with - <literal>^CVSROOT/</literal>, and add one line with only - <literal>^CVSROOT/</literal> on it. After the wrapper is - installed, you can add your header to the files in the - <filename>CVSROOT</filename> directory and restore these lines, - but for now they will only be in the way when you try to commit - later on.</para> - </step> - - <step> - <para>Edit <filename>modules</filename>, and delete all FreeBSD - stuff. Add your own modules if you wish.</para> - </step> - - <step> - <note><para>This step is only necessary if you specified a - value for <literal>$IDHEADER</literal> in - <filename>cfg_local.pm</filename> (which only works using a - FreeBSD modified <application>CVS</application>).</para></note> - - <para>Edit <filename>options</filename> to match the tag you - specified in <filename>cfg_local.pm</filename>. A global - search and replace of <literal>FreeBSD</literal> with your - tag should suffice.</para> - </step> - - <step> - <para>Edit <filename>rcstemplate</filename> to contain the same - keywords as specified in <filename>cfg_local.pm</filename>.</para> - </step> - - <step> - <para>Optionally remove the FreeBSD checks from - <filename>tagcheck</filename>. You can simply add - <literal>exit 0</literal> to the top of the file to disable all - checks on tagging.</para> - </step> - - <step> - <para>The last thing to do before you are finished, is to make sure - the commitlogs can be stored. By default these are stored in - the repository, in the <filename>commitlogs</filename> subdirectory - of the <filename>CVSROOT</filename> directory. This directory - needs to be created, so do the following: - - <screen>&prompt.user; <userinput>mkdir commitlogs</userinput> -&prompt.user; <userinput>cvs add commitlogs</userinput></screen></para> - </step> - </procedure> - - <para>Now, after careful review, you should commit your changes. Be - sure that you have granted yourself access to the - <filename>CVSROOT</filename> directory in your - <filename>avail</filename> before you do this, because otherwise you - will lock yourself out. So make sure everything is as you intend, and - then do the following: - - <screen>&prompt.user; <userinput>cvs commit -m '<replaceable>- Initial FreeBSD scripts commit</replaceable>'</userinput></screen></para> - </sect2> - - <sect2> - <title>Testing the setup</title> - - <para>You are ready for the first test: a forced commit to the - <filename>avail</filename> file, to make sure everything works as - expected. - - <screen>&prompt.user; <userinput>cvs commit -f -m '<replaceable>Forced commit to test the new CVSROOT scripts</replaceable>' avail</userinput></screen> - - If everything works, congratulations! You now have a working setup - of the FreeBSD scripts for your repository. If - <application>CVS</application> still complains about something, go - back and recheck if all of the above steps have been performed - correctly.</para> - </sect2> - </sect1> - - <sect1 id="freebsdspecific"> - <title>FreeBSD specific setup</title> - - <para>The FreeBSD project itself uses a slightly different setup, which - also uses files from the <filename>freebsd</filename> subdirectory of - the FreeBSD <filename>CVSROOT</filename>. The project uses this because - of the large number of committers, which all would have to be in the - same group. So, a simple wrapper was written which ensures that people - have the correct credentials to commit, and then sets the group id - to that of the repository.</para> - - <para>If your repository also needs this, the steps to set this up are - documented below. But first an overview of the files involved.</para> - - <sect2> - <title>Files used in the FreeBSD setup</title> - - <para> - <itemizedlist> - <listitem> - <para><filename>access</filename> - this file controls access - information. You should edit this file to include all members - of your project.</para> - </listitem> - - <listitem> - <para><filename>freebsd/commitmail.pl</filename> - this file is - not used any more, but kept for historic reasons. You should not - have to touch this file.</para> - </listitem> - - <listitem> - <para><filename>freebsd/cvswrap.c</filename> - this is the source - to the CVS wrapper that you will need to install to make all - access checks actually work. More information on this below. You - should edit the paths in the <literal>ACCESS</literal> and - <literal>REALCVS</literal> macros to match your setup.</para> - </listitem> - - <listitem> - <para><filename>freebsd/mailsend.c</filename> - this file is - needed by the FreeBSD setup of the mailing lists. You should - not have to touch this file.</para> - </listitem> - </itemizedlist> - </para> - </sect2> - - <sect2> - <title>The procedure</title> - - <procedure> - <step> - <para>Edit the <filename>access</filename> file to contain only - your username.</para> - </step> - - <step> - <para>Edit <filename>cvswrap.c</filename> to contain the - correct path for your setup. This is defined in a macro named - <literal>ACCESS</literal>. You should also change the location of - the real <command>cvs</command> binary if it is not appropriate to - your situation. The stock <filename>cvswrap.c</filename> expects - to be a replacement for the systemwide cvs command, which will be - moved to <filename>/usr/bin/ncvs</filename>.</para> - - <para>My copy of <filename>cvswrap.c</filename> has this:</para> - - <programlisting>#define ACCESS "/local/cvsroot/CVSROOT/access" -#define REALCVS "/usr/bin/ncvs"</programlisting> - </step> - - <step> - <para>Next up is installing the wrapper to ensure you become the - correct group when committing. The sources for this live in - <filename>cvswrap.c</filename> in your - <filename>CVSROOT</filename>.</para> - - <para>Compile the sources that you edited to include the correct - paths: - - <screen>&prompt.user; <userinput>cc -o cvs cvswrap.c</userinput></screen> - - And then install them (you have to be root for this step): - - <screen>&prompt.root; <userinput>mv /usr/bin/cvs /usr/bin/ncvs</userinput> -&prompt.root; <userinput>mv cvs /usr/bin/cvs</userinput> -&prompt.root; <userinput>chown root:<replaceable>ncvs</replaceable> /usr/bin/cvs /usr/bin/ncvs</userinput> -&prompt.root; <userinput>chmod o-rx /usr/bin/ncvs</userinput> -&prompt.root; <userinput>chmod u-w,g+s /usr/bin/cvs</userinput></screen> - - This installs the wrapper as the default <command>cvs</command> - command, making sure that anyone who wants to use the repository - has to have the correct access levels.</para> - </step> - - <step> - <para>You can now remove everyone from your repository group. All - access control is done by your wrapper, and this wrapper will - set the correct group for access.</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Testing the setup</title> - - <para>Your wrapper should now be setup. You can of course test this by - making a forced commit to the <filename>access</filename> file: - - <screen>&prompt.user; <userinput>cvs commit -f -m '<replaceable>Forced commit to test the new CVSROOT scripts</replaceable>' access</userinput></screen> - - Again, if this fails, check to see whether all of the above steps have - been executed correctly.</para> - </sect2> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/cvsup-advanced/Makefile b/en_US.ISO8859-1/articles/cvsup-advanced/Makefile deleted file mode 100644 index 8683682652..0000000000 --- a/en_US.ISO8859-1/articles/cvsup-advanced/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -# -# $FreeBSD$ -# -# Article: CVSup Advanced Points - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/cvsup-advanced/article.sgml b/en_US.ISO8859-1/articles/cvsup-advanced/article.sgml deleted file mode 100644 index 86a2a800b5..0000000000 --- a/en_US.ISO8859-1/articles/cvsup-advanced/article.sgml +++ /dev/null @@ -1,270 +0,0 @@ -<!-- - The FreeBSD Documentation Project ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>CVSup Advanced Points</title> - - <authorgroup> - <author> - <firstname>Salvo</firstname> - <surname>Bartolotta</surname> - - <affiliation> - <address><email>bartequi@neomedia.it</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.cvsup; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>The present article assumes a basic understanding of <application>CVSup</application> - operation. It documents several delicate issues connected with - source synchronization via <application>CVSup</application>, viz. effective solutions to - the problem of stale files as well as special source updating - cases; which issues are likely to cause apparently inexplicable - troubles.</para> - </abstract> - </articleinfo> - - <sect1 id="preface"> - <title>Preface</title> - - <para>This document is the fruit of the author's attempts to - fully understand the niceties of <application>CVSup</application> & source updating. :-) - While the author has made every effort to make these pages - as informative and correct as possible, he is only human and - may have made all sorts of typos, mistakes, etc. He will be - very grateful for any comments and/or suggestions you send to - his e-mail address, <email>bartequi@neomedia.it</email>.</para> - </sect1> - - - <sect1 id="introduction"> - <title>Introduction</title> - - <para>If you have visited - <ulink url="http://www.polstra.com/">John Polstra's site</ulink> - and read - <ulink url="http://www.polstra.com/projects/freeware/CVSup/faq.html">his -FAQ</ulink>, - you may have noticed Question 12 & 13.</para> - - <para>When updating any collection of sources (eg - <filename>/usr/ports</filename>), &man.cvsup.1; makes use of - the related checkouts file in order to perform the updating - process in the most efficient and correct way. In this example - (<filename>/usr/ports</filename>), the related checkouts file - is <filename>/usr/sup/ports-all/checkouts.cvs:.</filename> if - your base is <filename>/usr</filename>.</para> - - <para>A checkouts file contains information on the current status - of your sources—in a way, a sort of <quote>photograph</quote>. This - significant information enables <command>cvsup</command> to retrieve updates most - effectively. Further, and maybe more important, it enables <command>cvsup</command> - to correctly manage your sources by locally deleting any files - no longer present in the repository, thus leaving no stale files - on your system. In fact, without a checkouts file, <command>cvsup</command> would - <emphasis>not</emphasis> know which files your collection was composed of (cf - &man.cvsup.1; and the fallback method for details); as a result, - it could not delete on your system those files no longer present - in the repository. They would remain on your system (stale - files), and might cause you subtle build failures or other - trouble. For example, this problem is likely to occur if you - first update your ports collection several weeks after you - got your installation CD-ROMs.</para> - - <para>It is therefore recommended that you adopt the two-step procedure - outlined in the <application>CVSup</application> FAQ (cf Q12, Q13); in subsequent sections, you - will be given interesting and instructive concrete examples.</para> - </sect1> - - <sect1 id="script"> - <title>A useful python script: <command>cvsupchk</command></title> - - <para>Alternatively, in order to examine your sources for - inconsistencies, you may wish to utilize the <command>cvsupchk</command> python - script; which script is currently found in - <filename>/usr/ports/net/cvsup/work/cvsup-16.1/contrib/cvsupchk</filename>, - together with a nice <filename>README</filename>. Prerequisites:</para> - - <orderedlist> - <listitem> - <para><literal>/usr/ports/net/cvsup</literal> &prompt.root; -<userinput> make extract</userinput></para> - </listitem> - - <listitem> - <para>python (also found in the ports collection :-))</para> - </listitem> - - <listitem> - <para>a checkouts file for your collection of sources.</para> - </listitem> - </orderedlist> - - <para>If you are updating your sources for the very first time, - of course you do not have a checkouts file. After installing - python and updating your sources (eg <filename>/usr/ports</filename>), - you can check them thus:</para> - - <screen>&prompt.user; <filename>/path/to/</filename><userinput>cvsupchk -d /usr -c /usr/sup/ports-all/checkouts.cvs:. | more</userinput></screen> - - <para>If you want to check your RELENG_4 sources:</para> - - <screen>&prompt.user; <filename>/path/to/</filename><userinput>cvsupchk -d /usr -c /usr/sup/src-all/checkouts.cvs:RELENG_4 | more</userinput></screen> - - <para>In each case, <command>cvsupchk</command> will inspect your sources for - inconsistencies by utilizing the information contained in the - related checkouts file. Such anomalies as deleted files being - present (aka stale files), missing checked-out files, extra RCS - files, and dead directories will be printed to standard output.</para> - - <para>In the next section, we will provide important, typical - examples of source updating; which examples will show you the - role of checkouts files and the dangers of negligent source - management.</para> - </sect1> - - <sect1 id="examples"> - <title>Examples of more advanced source management</title> - - <sect2> - <title>How to safely change tags when updating -<literal>src-all</literal></title> - - <para>If you specify eg <literal>tag=A</literal> in your <filename>supfile</filename>, <command>cvsup</command> will create - a checkouts file called <filename>checkouts.cvs:A</filename>: - for instance, if <literal>tag=RELENG_4</literal>, a checkouts file called - <filename>checkouts.cvs:RELENG_4</filename> is generated. - This file will be used to retrieve and/or store information - identifying your 4-STABLE sources.</para> - - <para>When tracking <literal>src-all</literal>, if you wish to - pass from <literal>tag=A</literal> to <literal>tag=B</literal> (A less/greater than B not making - any difference) and if your checkouts file is - <filename>checkouts.cvs:A</filename>, the following actions - should be performed:</para> - - <orderedlist> - <listitem> - <para>&prompt.root; <userinput>mv checkouts.cvs:A -checkouts.cvs:B</userinput> - (This provides the subsequent step with the appropriate - checkouts file)</para> - </listitem> - - <listitem> - <para>write a <filename>supfile</filename> whose collection line reads:</para> - <programlisting>src-all tag=B</programlisting> - </listitem> - - <listitem> - <para>cvsup your sources using the new <filename>supfile</filename>.</para> - </listitem> - </orderedlist> - - <para>The <command>cvsup</command> utility will look for <filename>checkouts.cvs:B</filename>—in - that the target is B; that is, <command>cvsup</command> will make use of - the information contained therein to correctly manage your - sources.</para> - - <para>The benefits:</para> - - <itemizedlist> - <listitem> - <para>the sources are dealt with correctly (in particular, - no stale files)</para> - </listitem> - - <listitem> - <para>less load is placed on the server, in that <command>cvsup</command> - operates in the most efficient way.</para> - </listitem> - </itemizedlist> - - - <para>For example, <literal>A=RELENG_4</literal>, <literal>B=.</literal>. The period in <literal>B=.</literal> means - -CURRENT. This is a rather typical update, from 4-STABLE - to -CURRENT. While it is straightforward to <quote>downgrade</quote> your - sources (eg from -CURRENT to -STABLE), downgrading a system - is quite another matter. You are STRONGLY advised not to - attempt such an operation, unless you know exactly what you - are doing.</para> - </sect2> - - <sect2> - <title>Updating to the same tag as of a different date</title> - - <para>If you wish to switch from <literal>tag=A</literal> to <literal>tag=A</literal> as of a - different GMT date (say, <literal>date=D</literal>), you will execute the - following:</para> - - <orderedlist> - <listitem> - <para>write a <filename>supfile</filename> whose collection line reads:</para> - <programlisting>src-all tag=A date=D</programlisting> - </listitem> - - <listitem> - <para>update your sources using the new <filename>supfile</filename></para> - </listitem> - </orderedlist> - - <para>Whether the new date precedes that of the last sync - operation with <literal>tag=A</literal> or not, it is immaterial. For example, - in order to specify the date <quote>August 27, 2000, 10:00:00 GMT</quote> - you write the line:</para> - - - <programlisting>src-all tag=RELENG_4 date=2000.08.27.10.00.00</programlisting> - - <note><para>The format of a date is rigid. You have to specify - all the components of the date: century (<quote>20</quote>, ie the 21st - century, must be supplied whereas <quote>19</quote>, the past century, can - be omitted), year, month, day, hour, minutes, seconds—as - shown in the above example. For more information, please - see &man.cvsup.1;.</para></note> - - <para>Whether or not a date is specified, the checkouts file - is called <filename>checkouts.cvs:A</filename> (eg - <filename>checkouts.cvs:RELENG_4</filename>). As a result, - no particular action is needed in order to revert to the - previous state: you have to modify the date in the <filename>supfile</filename>, - and run <command>csvup</command> again.</para> - </sect2> - - - <sect2> - <title>Updating your ports collection for the first time</title> - - <para>Since ports are tagged <quote>.</quote> (ie -CURRENT), you can - correctly <quote>sync</quote> them for the first time by adding the date - keyword (cf &man.cvsup.1; for the exact format): you should - specify a date as close as possible to that of <quote>shipping</quote> of - your ports tree. After <command>cvsup</command> has correctly created the ports - checkouts file, which is precisely the goal of this first - special sync operation, the date field must be removed; - all subsequent updates will be carried out smoothly.</para> - - <para>If you have been reading the apparently nit-picking - remarks in these sections, you will probably have recognized - the potential for trouble in a source updating process. - A number of people have actually run into problems. You have - been warned. :-)</para> - </sect2> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/dialup-firewall/Makefile b/en_US.ISO8859-1/articles/dialup-firewall/Makefile deleted file mode 100644 index c512d68c66..0000000000 --- a/en_US.ISO8859-1/articles/dialup-firewall/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Dialup firewalling with FreeBSD - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/dialup-firewall/article.sgml b/en_US.ISO8859-1/articles/dialup-firewall/article.sgml deleted file mode 100644 index 66bf36dd46..0000000000 --- a/en_US.ISO8859-1/articles/dialup-firewall/article.sgml +++ /dev/null @@ -1,318 +0,0 @@ -<!-- - The FreeBSD Documentation Project ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Dialup firewalling with FreeBSD</title> - - <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Silver</surname> - - <affiliation> - <address><email>marcs@draenor.org</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This article documents how to set up a firewall using a PPP - dialup with FreeBSD and IPFW, and specifically with firewalling over - a dialup with a dynamically assigned IP address. This document does - not include information on setting up an initial PPP connection. - For more information on setting up a PPP connection, consult - the &man.ppp.8; manual page.</para> - </abstract> - </articleinfo> - - <sect1 id="preface"> - <title>Preface</title> - - <para>Dialup Firewalling with FreeBSD</para> - - <para>This document outlines the steps required to set up - firewalling with FreeBSD when an IP address is assigned dynamically - by your ISP. While every effort has been made to make this document - as informative and correct as possible, you are welcome to mail - any corrections, comments or suggestions to the author at - <email>marcs@draenor.org</email>.</para> - </sect1> - - <sect1 id="kernel"> - <title>Kernel Options</title> - - <para>In order to use IPFW, support for it must be compiled into the - kernel. For more information on how to recompile the kernel, - please see the <ulink - url="&url.books.handbook;/kernelconfig.html">kernel configuration - section in the Handbook</ulink>. The following options must be - added into your kernel configuration file for IPFW support:</para> - - <variablelist> - <varlistentry> - <term><literal>options IPFIREWALL</literal></term> - - <listitem> - <para>Enables the kernel firewall code.</para> - <note><para>This document assumes that you are running - &os; 5.X. Users running &os; 4.X will need to - recompile their kernels with <emphasis>IPFW2</emphasis> - support. &os; 4.X users should consult the &man.ipfw.8; - manual page for more information on using IPFW2 on their - systems, and should pay particular attention to the - <emphasis>USING IPFW2 IN FreeBSD-STABLE</emphasis> - section.</para></note> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options IPFIREWALL_VERBOSE</literal></term> - - <listitem> - <para>Sends logged packets to the system logger.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>options - IPFIREWALL_VERBOSE_LIMIT=<replaceable>500</replaceable></literal></term> - - <listitem> - <para>Limits the number of times a matching entry may be logged. - This allows you to log firewall activity without the risk of - syslog flooding in the event of a denial of service attack. - <replaceable>500</replaceable> is a reasonable number to use, but - may be adjusted based on your requirements.</para> - </listitem> - </varlistentry> - </variablelist> - - <warning><para>Once the kernel recompile has been completed, - <emphasis>do not reboot</emphasis> your system. Doing so may result - in you being locked out of your own system. You must only reboot - once the ruleset is in place and all the relevant configuration - files have been updated.</para></warning> - - </sect1> - - <sect1 id="rcconf"> - <title>Changing <filename>/etc/rc.conf</filename> to load the - firewall</title> - - <para><filename>/etc/rc.conf</filename> needs to be slightly - modified in order to tell the system about the firewall and to - specify the location for our rules file. Add the following lines - to <filename>/etc/rc.conf</filename>:</para> - - <programlisting>firewall_enable="YES" -firewall_script="/etc/firewall/fwrules"</programlisting> - - <para>For more information on the functions of these statements take - a look at <filename>/etc/defaults/rc.conf</filename> and read - &man.rc.conf.5;</para> - </sect1> - - <sect1> - <title>Enable PPP's network address translation</title> - - <para>In order to allow clients on your network to connect via - your gateway, you will need to enable PPP's network address - translation (NAT). In order to use PPP's NAT functions, add the - following lines to <filename>/etc/rc.conf</filename>:</para> - - <programlisting>ppp_enable="YES" -ppp_mode="auto" -ppp_nat="YES" -ppp_profile="<replaceable>your_profile</replaceable>"</programlisting> - - <note><para>Take care to change <literal>your_profile</literal> to - the name of your own dialup profile.</para></note> - </sect1> - - <sect1 id="rules"> - <title>The rule set for the firewall</title> - - <para>This is the point where we define the firewall rules for your - system. The ruleset that we're about to describe is a generic - template for most dialup users. While it will not suit the exact - needs of every user, it provides you with a basic idea of how IPFW - works and should be fairly easy to customize.</para> - - <para>First, let's start with the basics of closed firewalling. - Closed firewalling is based on the idea that everything is denied - by default. The system administrator may then explicitly add - rules for traffic that he or she would like to allow. Rules - should be in the order of allow first, and then deny. The premise - is that you add the rules for everything you would like to allow, - and then everything else is automatically denied.</para> - - <para>Following that, let's create the directory where we will store our - firewall rules. In this example, we'll use <filename - class="directory">/etc/firewall</filename>. Change into the - directory and edit the file <filename>fwrules</filename> as we - specified in <filename>rc.conf</filename>. Please note that you - can change this filename to anything you wish. This guide merely - gives an example of a filename you may want to use.</para> - - <para>Now, let's look at a nicely commented sample firewall - file.</para> - - <programlisting># Define the firewall command (as in /etc/rc.firewall) for easy -# reference. Helps to make it easier to read. -fwcmd="/sbin/ipfw" - -# Define our outside interface. With userland-ppp this -# defaults to tun0. -oif="tun0" - -# Define our inside interface. This is usually your network -# card. Be sure to change this to match your own network -# interface. -iif="fxp0" - -# Force a flushing of the current rules before we reload. -$fwcmd -f flush - -# Check the state of all packets. -$fwcmd add check-state - -# Stop spoofing on the outside interface. -$fwcmd add deny ip from any to any in via $oif not verrevpath - -# Allow all connections that we initiate, and keep their state. -# but deny established connections that don't have a dynamic rule. -$fwcmd add allow ip from me to any out via $oif keep-state -$fwcmd add deny tcp from any to any established in via $oif - -# Allow all connections within our network. -$fwcmd add allow ip from any to any via $iif - -# Allow all local traffic. -$fwcmd add allow all from any to any via lo0 -$fwcmd add deny all from any to 127.0.0.0/8 -$fwcmd add deny ip from 127.0.0.0/8 to any - -# Allow internet users to connect to the port 22 and 80. -# This example specifically allows connections to the sshd and a -# webserver. -$fwcmd add allow tcp from any to me dst-port 22,80 in via $oif setup keep-state - -# Allow ICMP packets: remove type 8 if you don't want your host -# to be pingable. -$fwcmd add allow icmp from any to any via $oif icmptypes 0,3,8,11,12 - -# Deny and log all the rest. -$fwcmd add deny log ip from any to any</programlisting> - - <para>You now have a fully functional firewall that only allows - connections to ports 22 and 80 and will log any other connection - attempts. You may now safely reboot and the firewall should - be automatically started and the ruleset loaded. If you find this - incorrect in any way or experience any problems, or have any - suggestions to improve this page, please email me.</para> - </sect1> - - <sect1> - <title>Questions</title> - - <qandaset> - <qandaentry> - <question> - <para>I get messages like <errorname>limit 500 reached on entry - 2800</errorname> and after that I my machine stops logging - denied packets that match that rule number. Is my firewall - still working?</para> - </question> - - <answer> - <para>This merely means that the maximum logging count for - the rule has been reached. The rule itself is still - working, but it will no longer log until such time as you - reset the logging counters. An example of how to clear your - counters can be found below:</para> -<screen>&prompt.root; <userinput>ipfw resetlog</userinput></screen> - <para>Alternatively, you may increase the log limit in - your kernel configuration with the - <option>IPFIREWALL_VERBOSE_LIMIT</option> option as - described above. You may also change this limit (without - recompiling your kernel and having to reboot) by using the - net.inet.ip.fw.verbose_limit &man.sysctl.8; value.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>There must be something wrong. I followed your instructions - to the letter and now I am locked out.</para> - </question> - - <answer> - <para>This tutorial assumes that you are running - <emphasis>userland-ppp</emphasis>, therefore the supplied rule set - operates on the <devicename>tun0</devicename> interface, which - corresponds to the first connection made with &man.ppp.8; (a.k.a. - <emphasis>user-ppp</emphasis>). Additional connections would use - <devicename>tun1</devicename>, <devicename>tun2</devicename> and so - on.</para> - - <para>You should also note that &man.pppd.8; uses the - <devicename>ppp0</devicename> interface instead, so if you - start the connection with &man.pppd.8; you must substitute - <devicename>tun0</devicename> for - <devicename>ppp0</devicename>. A quick way to edit the - firewall rules to reflect this change is shown below. The - original rule set is backed up as - <filename>fwrules_tun0</filename>.</para> - - <screen> &prompt.user; <userinput>cd /etc/firewall</userinput> - /etc/firewall&prompt.user; <userinput>su</userinput> - <prompt>Password:</prompt> - /etc/firewall&prompt.root; <userinput>mv fwrules fwrules_tun0</userinput> - /etc/firewall&prompt.root; <userinput>cat fwrules_tun0 | sed s/tun0/ppp0/g > fwrules</userinput> - </screen> - - <para>To know whether you are currently using &man.ppp.8; or - &man.pppd.8; you can examine the output of - &man.ifconfig.8; once the connection is up. E.g., for a - connection made with &man.pppd.8; you would see something - like this (showing only the relevant lines):</para> - - <screen> &prompt.user; <userinput>ifconfig</userinput> - <emphasis>(skipped...)</emphasis> - ppp0: flags=<replaceable>8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524</replaceable> - inet <replaceable>xxx.xxx.xxx.xxx</replaceable> --> <replaceable>xxx.xxx.xxx.xxx</replaceable> netmask <replaceable>0xff000000</replaceable> - <emphasis>(skipped...)</emphasis> - </screen> - - <para>On the other hand, for a connection made with - &man.ppp.8; (<emphasis>user-ppp</emphasis>) you should see - something similar to this:</para> - - <screen> &prompt.user; <userinput>ifconfig</userinput> - <emphasis>(skipped...)</emphasis> - ppp0: flags=<replaceable>8010<POINTOPOINT,MULTICAST> mtu 1500</replaceable> - <emphasis>(skipped...)</emphasis> - tun0: flags=<replaceable>8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524</replaceable> - <emphasis>(IPv6 stuff skipped...)</emphasis> - inet <replaceable>xxx.xxx.xxx.xxx</replaceable> --> <replaceable>xxx.xxx.xxx.xxx</replaceable> netmask <replaceable>0xffffff00</replaceable> - Opened by PID <replaceable>xxxxx</replaceable> - <emphasis>(skipped...)</emphasis></screen> - </answer> - </qandaentry> - </qandaset> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/diskless-x/Makefile b/en_US.ISO8859-1/articles/diskless-x/Makefile deleted file mode 100644 index 77fd3e8065..0000000000 --- a/en_US.ISO8859-1/articles/diskless-x/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Diskless X Server: a how to guide - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/diskless-x/article.sgml b/en_US.ISO8859-1/articles/diskless-x/article.sgml deleted file mode 100644 index f4100741c0..0000000000 --- a/en_US.ISO8859-1/articles/diskless-x/article.sgml +++ /dev/null @@ -1,358 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD$ ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Diskless X Server: a how to guide</title> - - <authorgroup> - <author> - <firstname>Jerry</firstname> - <surname>Kendall</surname> - <affiliation> - <address> - <email>jerry@kcis.com</email> - </address> - </affiliation> - </author></authorgroup> - - <pubdate>28-December-1996</pubdate> - - <copyright> - <year>1996</year> - <holder>Jerry Kendall</holder> - </copyright> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.3com; - &tm-attrib.microsoft; - &tm-attrib.sun; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>With the help of some friends on the FreeBSD-hackers list, I have - been able to create a diskless X terminal. The creation of the X - terminal required first creating a diskless system with minimal - utilities mounted via NFS. These same steps were used to create 2 - separate diskless systems. The first is <hostid - role="fqdn">altair.example.com</hostid>. A diskless X terminal that I - run on my old 386DX-40. It has a 340Meg hard disk but, I did not want - to change it. So, it boots from <hostid - role="fqdn">antares.example.com</hostid> across a Ethernet. The second - system is a 486DX2-66. I set up a diskless FreeBSD (complete) that - uses no local disk. The server in that case is a Sun 670MP running - &sunos; 4.1.3. The same setup configuration was needed for both.</para> - - <para>I am sure that there is stuff that needs to be added - to this. Please send me any comments.</para> - </abstract> - </articleinfo> - - <sect1> - <title>Creating the boot floppy (On the diskless system)</title> - - <para>Since the network boot loaders will not work with some of the TSR's - and such that &ms-dos; uses, it is best to create a dedicated boot floppy - or, if you can, create an &ms-dos; menu that will (via the - <filename>config.sys</filename>/<filename>autoexec.bat</filename> files) - ask what configuration to load when the system starts. The later is the - method that I use and it works great. My &ms-dos; (6.x) menu is - below.</para> - - <example> - <title><filename>config.sys</filename></title> - - <programlisting>[menu] -menuitem=normal, normal -menuitem=unix, unix -[normal] -.... -normal config.sys stuff -... -[unix]</programlisting> - </example> - - <example> - <title><filename>autoexec.bat</filename></title> - - <programlisting>@ECHO OFF -goto %config% - -:normal -... -normal autoexec.bat stuff -... -goto end - -:unix -cd \netboot -nb8390.com - -:end</programlisting> - </example> - </sect1> - - <sect1> - <title>Getting the network boot programs (On the server)</title> - - <para>Compile the <quote>net-boot</quote> programs that are located in - <filename>/usr/src/sys/i386/boot/netboot</filename>. You should read - the comments at the top of the <filename>Makefile</filename>. Adjust as - required. Make a backup of the original in case something goes wrong. When - the build is done, there should be 2 &ms-dos; executables, - <filename>nb8390.com</filename> and <filename>nb3c509.com</filename>. - One of these two programs will be what you need to run on the diskless - server. It will load the kernel from the boot server. At this point, - put both programs on the &ms-dos; boot floppy created earlier.</para> - </sect1> - - <sect1> - <title>Determine which program to run (On the diskless system)</title> - - <para>If you know the chipset that your Ethernet adapter uses, this is - easy. If you have the NS8390 chipset, or a NS8390 based chipset, use - <filename>nb8390.com</filename>. If you have a &tm.3com; 509 based chipset, - use the <filename>nb3C509.com</filename> boot program. If you are not - sure which you have, try using one, if it says <errorname>No adapter - found</errorname>, try the other. Beyond that, you are pretty much on - your own.</para> - </sect1> - - <sect1> - <title>Booting across the network</title> - - <para>Boot the diskless system with out any config.sys/autoexec.bat - files. Try running the boot program for your Ethernet adapter.</para> - - <para>My Ethernet adapter is running in WD8013 16bit mode so I run - <filename>nb8390.com</filename></para> - - <screen><prompt>C:></prompt> <userinput>cd \netboot</userinput> -<prompt>C:></prompt> <userinput>nb8390</userinput> - -<prompt>Boot from Network (Y/N) ?</prompt> <userinput>Y</userinput> - -BOOTP/TFTP/NFS bootstrap loader ESC for menu - -Searching for adapter.. -WD8013EBT base 0x0300, memory 0x000D8000, addr 00:40:01:43:26:66 - -Searching for server...</screen> - - <para>At this point, my diskless system is trying to find a machine to act - as a boot server. Make note of the <literal>addr</literal> line above, - you will need this number later. Reset the diskless system and modify - your <filename>config.sys</filename> and - <filename>autoexec.bat</filename> files to do these steps automatically - for you. Perhaps in a menu. If you had to run - <command>nb3c509.com</command> instead of <command>nb8390.com</command> - the output is the same as above. If you got <errorname>No adapter - found</errorname> at the <literal>Searching for adapter...</literal> - message, verify that you did indeed set the compile time defines in the - <filename>Makefile</filename> correctly.</para> - </sect1> - - <sect1> - <title>Allowing systems to boot across the network (On the server)</title> - - <para>Make sure the <filename>/etc/inetd.conf</filename> file has entries - for tftp and bootps. Mine are listed below:</para> - - <programlisting>tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /tftpboot -# -# Additions by who ever you are -bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab</programlisting> - - <para>If you have to change the <filename>/etc/inetd.conf</filename> file, - send a <literal>HUP</literal> signal to &man.inetd.8;. To do this, get the - process ID of <command>inetd</command> with <command>ps -ax | grep inetd | grep -v - grep</command>. Once you have it, send it a <literal>HUP</literal> signal. Do this by - <command>kill -HUP <pid></command>. This will force <command>inetd</command> to - re-read its config file.</para> - - <para>Did you remember to note the <literal>addr</literal> line from the - output of the boot loader on the diskless system? Guess what, here is - where you need it.</para> - - <para>Add an entry to <filename>/etc/bootptab</filename> (maybe creating the - file). It should be laid out identical to this:</para> - - <programlisting>altair:\ - :ht=ether:\ - :ha=004001432666:\ - :sm=255.255.255.0:\ - :hn:\ - :ds=199.246.76.1:\ - :ip=199.246.76.2:\ - :gw=199.246.76.1:\ - :vm=rfc1048:</programlisting> - - <para>The lines are as follows:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry><literal>altair</literal></entry> - <entry>the diskless systems name without the domain name.</entry> - </row> - - <row> - <entry><literal>ht=ether</literal></entry> - <entry>the hardware type of <quote>ethernet</quote>.</entry> - </row> - - <row> - <entry><literal>ha=004001432666</literal></entry> - <entry>the hardware address (the number noted above).</entry> - </row> - - <row> - <entry><literal>sm=255.255.255.0</literal></entry> - <entry>the subnet mask.</entry> - </row> - - <row> - <entry><literal>hn</literal></entry> - <entry>tells server to send client's hostname to the - client.</entry> - </row> - - <row> - <entry><literal>ds=199.246.76.1</literal></entry> - <entry>tells the client who the domain server is.</entry> - </row> - - <row> - <entry><literal>ip=199.246.76.2</literal></entry> - <entry>tells the client what its IP address is.</entry> - </row> - - <row> - <entry><literal>gw=199.246.76.1</literal></entry> - <entry>tells the client what the default gateway is.</entry> - </row> - - <row> - <entry><literal>vm=...</literal></entry> - <entry>just leave it there.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>Be sure to set up the IP addresses correctly, the addresses above - are my own.</para> - </note> - - <para>Create the directory <filename>/tftpboot</filename> on the server it will contain the - configuration files for the diskless systems that the server will serve. - These files will be named <filename>cfg.<replaceable>ip</replaceable></filename> where <replaceable>ip</replaceable> is the IP - address of the diskless system. The config file for <hostid>altair</hostid> is - <filename>/tftpboot/cfg.199.246.76.2</filename>. The contents is:</para> - - <programlisting>rootfs 199.246.76.1:/DiskLess/rootfs/altair -hostname altair.example.com</programlisting> - - <para>The line <literal>hostname altair.example.com</literal> simply tells - the diskless system what its fully qualified domain name is.</para> - - <para>The line <literal>rootfs - 199.246.76.1:/DiskLess/rootfs/altair</literal> tells the diskless - system where its NFS mountable root filesystem is located.</para> - - <note> - <para>The NFS mounted root filesystem will be mounted <emphasis>read - only</emphasis>.</para> - </note> - - <para>The hierarchy for the diskless system can be re-mounted allowing - read-write operations if required.</para> - - <para>I use my spare 386DX-40 as a dedicated X terminal.</para> - - <para>The hierarchy for <hostid>altair</hostid> is:</para> - - <literallayout>/ -/bin -/etc -/tmp -/sbin -/dev -/dev/fd -/usr -/var -/var/run</literallayout> - - <para>The actual list of files is:</para> - - <screen>-r-xr-xr-x 1 root wheel 779984 Dec 11 23:44 ./kernel --r-xr-xr-x 1 root bin 299008 Dec 12 00:22 ./bin/sh --rw-r--r-- 1 root wheel 499 Dec 15 15:54 ./etc/rc --rw-r--r-- 1 root wheel 1411 Dec 11 23:19 ./etc/ttys --rw-r--r-- 1 root wheel 157 Dec 15 15:42 ./etc/hosts --rw-r--r-- 1 root bin 1569 Dec 15 15:26 ./etc/XF86Config.altair --r-x------ 1 bin bin 151552 Jun 10 1995 ./sbin/init --r-xr-xr-x 1 bin bin 176128 Jun 10 1995 ./sbin/ifconfig --r-xr-xr-x 1 bin bin 110592 Jun 10 1995 ./sbin/mount_nfs --r-xr-xr-x 1 bin bin 135168 Jun 10 1995 ./sbin/reboot --r-xr-xr-x 1 root bin 73728 Dec 13 22:38 ./sbin/mount --r-xr-xr-x 1 root wheel 1992 Jun 10 1995 ./dev/MAKEDEV.local --r-xr-xr-x 1 root wheel 24419 Jun 10 1995 ./dev/MAKEDEV</screen> - - <para>If you are not using &man.devfs.5; (which is the default - in FreeBSD 5.X), you should make sure that you - do not forget to run <command>MAKEDEV all</command> in the - <filename>dev</filename> directory.</para> - - <para>My <filename>/etc/rc</filename> for <hostid>altair</hostid> - is:</para> - -<programlisting>#!/bin/sh -# -PATH=/bin:/ -export PATH -# -# configure the localhost -/sbin/ifconfig lo0 127.0.0.1 -# -# configure the ethernet card -/sbin/ifconfig ed0 199.246.76.2 netmask 0xffffff00 -# -# mount the root filesystem via NFS -/sbin/mount antares:/DiskLess/rootfs/altair / -# -# mount the /usr filesystem via NFS -/sbin/mount antares:/DiskLess/usr /usr -# -/usr/X11R6/bin/XF86_SVGA -query antares -xf86config /etc/XF86Config.altair > /dev/null 2>&1 -# -# Reboot after X exits -/sbin/reboot -# -# We blew up.... -exit 1</programlisting> - - <para>Any comments and all questions welcome.</para> - </sect1> -</article> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO8859-1/articles/euro/Makefile b/en_US.ISO8859-1/articles/euro/Makefile deleted file mode 100644 index e1247939d0..0000000000 --- a/en_US.ISO8859-1/articles/euro/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -# -# $FreeBSD$ -# -# Article: The Euro symbol on FreeBSD - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/euro/article.sgml b/en_US.ISO8859-1/articles/euro/article.sgml deleted file mode 100644 index 1e30e30ae2..0000000000 --- a/en_US.ISO8859-1/articles/euro/article.sgml +++ /dev/null @@ -1,352 +0,0 @@ -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>The Euro symbol on - <systemitem class="osname">FreeBSD</systemitem></title> - - <authorgroup> - <author> - <firstname>Aaron</firstname> - - <surname>Kaplan</surname> - - <affiliation> - <address> - <email>aaron@lo-res.org</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2002</year> - <year>2003</year> - <holder>The FreeBSD Documentation Project</holder> - </copyright> - - <pubdate role="rcs">$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This document will try to help you in getting started with the new - <keycap>Euro</keycap> Symbol on your new keyboard that you had to buy - in early 2002 because of the switch to the new common currency. We - will first focus on the more important parts like being able to - correctly display the symbol on the console. Later sections will deal - with configuring particular programs like - <application>X11</application>. - </para> - - <para>Lots of helpful input came from Oliver Fromme, Tom Rhodes and - countless others. Thanks! Without you this article would not have been - possible! - </para> - </abstract> - </articleinfo> - - <sect1> - <title>The Euro in a nutshell</title> - - <para>If you already feel comfortable with - <ulink url="&url.books.handbook;/l10n.html">localization</ulink> as - described in the <systemitem class="osname">FreeBSD</systemitem> - Handbook you might be only interested in the following facts which - will get you started quickly:</para> - - <variablelist> - <varlistentry> - <term>ISO8859-15</term> - - <listitem> - <para>This is a slight modification of the commonly used ISO8859-1 - character map. It includes the Euro symbol. Used for the - <envar>LANG</envar>, <envar>LC_CTYPE</envar> environment - variables.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>iso15-8x16.fnt</filename></term> - - <listitem> - <para>The &man.vidcontrol.1; font for the console</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>/usr/share/syscons/keymaps/*.iso.kbd</filename></term> - - <listitem> - <para>Appropriate keyboard maps depending on your language. Set your - <literal>keymap</literal> entry in <filename>rc.conf</filename> to - one of these.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><envar>LC_CTYPE</envar></term> - - <listitem> - <para>Used to specify the correct character type in your - locale.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>XkbLayout "<replaceable>lang</replaceable>(euro)"</literal></term> - - <listitem> - <para><application>XFree86</application> config option.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>/usr/X11R6/lib/X11/fonts/*/fonts.alias</filename></term> - <listitem> - <para>Be sure to adapt your X11 fonts to - <literal>-*-..-*-iso8859-15</literal></para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1> - <title>A general remark</title> - - <para>In the following sections we will often refer to - <emphasis>ISO8859-15</emphasis>. This is the standard notation starting - with <systemitem class="osname">FreeBSD</systemitem> 4.5. In older - versions, the standard notation was either - <emphasis>ISO_8859-15</emphasis> or <emphasis>DIS_8859-15</emphasis>. - </para> - - <para>If you are using an older version of - <systemitem class="osname">FreeBSD</systemitem>, be sure to take a - look at <filename>/usr/share/locale/</filename> in order to find out - which naming convention is in place.</para> - </sect1> - - <sect1> - <title>The console</title> - - <sect2> - <title>Setting up your console font</title> - - <para>Depending on your console resolution and size you will need one of - the following lines in <filename>rc.conf</filename>:</para> - - <programlisting>font8x16="iso15-8x16.fnt" # from /usr/share/syscons/fonts/* -font8x14="iso15-8x14.fnt" -font8x8="iso15-8x8.fnt"</programlisting> - - <para>This will effectively select the ISO8859-15 also known as Latin-9 - font. ISO8859-15 is a variation of ISO8859-1. You can tell the - difference between the two by looking at the Euro symbol: its decimal - value is 164. In ISO8859-1 you will notice a circle with four little - strokes at the corners. This is often termed the <quote>universal currency - symbol</quote>. In ISO8859-15, instead of the little circle, you have the - Euro Symbol. Otherwise the fonts are more or less identical.</para> - - <warning> - <para>As of the time of this writing the only usable font seems to be - <literal>iso15-8x16.fnt</literal>. The others seem to only show - ISO8859-1 even though the name suggest otherwise.</para> - </warning> - - <note> - <para>By specifying this font some console applications will look - garbled. This is due to the fact that they assume you are using a - different font/character set such as ANSI 850. One notable example - is <application>sysinstall</application>. However most of the - time this should not be of much concern.</para> - </note> - - <para>As the next step you should either reboot your system to let the - changes take effect or (manually) take the steps that would have been - taken at the system startup:</para> - - <screen>&prompt.user; <userinput>vidcontrol -f <replaceable>iso15-8x16.fnt</replaceable></userinput></screen> - - <para>To check if the font has been selected execute the following short - <command><anchor id="awk-test">awk</command> script:</para> - - <programlisting>#!/usr/bin/awk -f -BEGIN { - for(i=160;i<180;i++) - printf"%3d %c\n",i,i -}</programlisting> - - <para>The result should reveal the Euro sign at position 164.</para> - </sect2> - - <sect2> - <title>Setting up your keyboard for the Euro</title> - - <para>Most keyboard maps should already be set up correctly. I.e: If you - have a german keyboard and your Umlaut keys are working, you can - safely skip this section since the keyboard already maps whatever key - combination is necessary (e.g.: <keycombo action=simul><keycap>Alt - Gr</keycap><keycap>e</keycap></keycombo>) to decimal value 164. - If running into problems, the best way to check is to take a look at - <filename>/usr/share/syscons/keymaps/*.kbd</filename>. The format of - the key mapping files is described in &man.keyboard.4;. - &man.kbdcontrol.1; can be used to load a custom keymap.</para> - - <para>Once the correct keyboard map is selected, it should be added to - <filename>/etc/rc.conf</filename> with the line:</para> - - <programlisting>keymap="<replaceable>german.iso</replaceable>" # or another map</programlisting> - - <para>As stated above, this step has most probably already been taken - by you at installation time (with - <application>sysinstall</application>). If not, either reboot or - load the new keymap via &man.kbdcontrol.1;.</para> - - <para>To verify the keyboard mapping, switch to a new console and at - the login prompt, <emphasis>instead of logging</emphasis> in, try to - type the <keycap>Euro</keycap> key. If it is not working, either - file a bug report via &man.send-pr.1; or make sure you in fact chose - the right keyboard map.</para> - - <note> - <para>At this stage the Euro key will not yet work in - <application>bash </application> or - <application>tcsh</application>.</para> - </note> - </sect2> - - <sect2> - <title>Fixing the environment variables</title> - - <para>The shells (<application>bash</application>, <application>tcsh</application>) revert to the &man.readline.3; library - which in turn respects the <envar>LC_CTYPE</envar> environment - variable. <envar>LC_CTYPE</envar> must be set before the shell is - completely running. Luckily it suffices to add the line:</para> - - <programlisting>export LC_CTYPE=<replaceable>de_DE</replaceable>.ISO8859-15</programlisting> - - <para>to your <filename>.bash_profile</filename> (<application>bash</application>), or:</para> - - <programlisting>setenv LC_CTYPE <replaceable>de_DE</replaceable>.ISO8859-15</programlisting> - - <para>to your <filename>.login</filename> (<application>tcsh</application>) file. Of course, - <replaceable>de_DE</replaceable> should be replaced by your language. - Next, log out, log back in again, and verify your Euro key is working. - By now most console applications should respond to the Euro key. Extra - configuration steps for special programs like - <application>pine</application> might still be necessary - however.</para> - - <note> - <para>An alternative to modifying <filename>.login</filename> and - <filename>.bash_profile</filename> is to set the environment - variables through the &man.login.conf.5; mechanism. This approach - has the advantage of assigning login classes to certain users (e.g. - French users, Italian users, etc) <emphasis>in one - place</emphasis>.</para> - </note> - </sect2> - </sect1> - - <sect1> - <title>Modifying X11</title> - - <para>Modify <filename>/etc/XF86Config</filename> in the following - manner:</para> - - <programlisting>Option "XkbLayout" "<replaceable>de</replaceable>(euro)"</programlisting> - - <para>Again, replace <replaceable>de</replaceable> with your language. By - now, the keyboard should be set up correctly. As in the console section, - the correct font must be chosen. For <application>KDE</application>, go - to the <application>KDE control center</application> -> - Personalization -> Country & Language -> Charset and change it - to <literal>ISO8859-15</literal>. Similar steps apply to - <application>kmail</application> and other applications.</para> - - <para>Another good idea is to modify your <filename>fonts.alias</filename> - files. Notably the <literal>fixed</literal> font should be changed to - the right character set: The author's - <filename>/usr/X11R6/lib/X11/fonts/misc/fonts.alias</filename> looks - like this:</para> - - <programlisting>! $Xorg: fonts.alias,v 1.3 2000/08/21 16:42:31 coskrey Exp $ -fixed -misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso8859-15 -variable -*-helvetica-bold-r-normal-*-*-120-*-*-*-*-iso8859-15 -(...)</programlisting> - - <para>As in the console sections, special applications still have - ISO8859-1 fonts configured in their respective &man.xrdb.1; databases. One - notable example is <application>xterm</application>. As a general rule - of thumb it suffices to change the corresponding configuration file in - <filename>/usr/X11R6/lib/X11/app-defaults</filename> and add the correct - font. Let us demonstrate this with - <application>xterm</application>.</para> - - <screen>&prompt.root; cd /usr/X11R6/lib/X11/app-defaults/ -&prompt.root; vi XTerm</screen> - - <para>Add the following line to the beginning of the file:</para> - - <programlisting>*font: -misc-fixed-medium-r-normal-*-*-120-*-*-c-*-iso8859-15</programlisting> - - <para>Finally, restart X and make sure, fonts can be displayed by - executing the above <link linkend="awk-test">awk script</link>. All - major applications should respect the keyboard mapping and the font - settings.</para> - </sect1> - - <sect1> - <title>Open problems</title> - - <para>Of course, the author would like to receive feedback. In addition, - at least let me know if you have fixes for one of these open - problems:</para> - - <itemizedlist> - <listitem> - <para>Describe alternative way of setting up <application>XFree86</application>: - <filename role="package">x11/xkeycaps</filename></para> - </listitem> - - <listitem> - <para>Settings in <application>GNOME</application></para> - </listitem> - - <listitem> - <para>Settings in <application>XFCE</application></para> - </listitem> - - <listitem> - <para>Settings for <application>(X)Emacs</application></para> - </listitem> - - <listitem> - <para>Describe UTF-8</para> - </listitem> - - <listitem> - <para>Describe <application>libiconv</application> as a effective way - to convert between ISO8859-15 and UTF-{8,16} from within - applications</para> - </listitem> - </itemizedlist> - </sect1> -</article> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO8859-1/articles/explaining-bsd/Makefile b/en_US.ISO8859-1/articles/explaining-bsd/Makefile deleted file mode 100644 index e0728a0215..0000000000 --- a/en_US.ISO8859-1/articles/explaining-bsd/Makefile +++ /dev/null @@ -1,21 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Explaining BSD - -MAINTAINER=grog@FreeBSD.org - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/explaining-bsd/article.sgml b/en_US.ISO8859-1/articles/explaining-bsd/article.sgml deleted file mode 100644 index e33f805a47..0000000000 --- a/en_US.ISO8859-1/articles/explaining-bsd/article.sgml +++ /dev/null @@ -1,563 +0,0 @@ -<!-- $FreeBSD$ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Explaining BSD</title> - - <author> - <firstname>Greg</firstname> - <surname>Lehey</surname> - - <affiliation> - <address><email>grog@FreeBSD.org</email></address> - </affiliation> - </author> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.apple; - &tm-attrib.linux; - &tm-attrib.opengroup; - &tm-attrib.sun; - &tm-attrib.xfree86; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>In the open source world, the word <quote>Linux</quote> is almost - synonymous with <quote>Operating System</quote>, but it is not the only - open source &unix; operating system. According - to the <ulink - url="http://www.leb.net/hzo/ioscount/data/r.9904.txt">Internet - Operating System Counter</ulink>, as of April 1999 31.3% of the - world's network connected machines run Linux. 14.6% run BSD &unix;. - Some of the world's largest web operations, such as <ulink - url="http://www.yahoo.com/">Yahoo!</ulink>, run BSD. The world's - busiest FTP server, <ulink - url="ftp://ftp.cdrom.com/">ftp.cdrom.com</ulink>, uses BSD to - transfer 1.4 TB of data a day. Clearly this is not a niche - market: BSD is a well-kept secret.</para> - - <para>So what is the secret? Why is BSD not better known? This white - paper addresses these and other questions.</para> - - <para>Throughout this paper, differences between BSD and Linux will be - noted <emphasis>like this</emphasis>.</para> - </abstract> - </articleinfo> - - <sect1> - <title>What is BSD?</title> - - <para>BSD stands for <quote>Berkeley Software Distribution</quote>. It is - the name of distributions of source code from the University of - California, Berkeley, which were originally extensions to AT&T's - Research &unix; operating system. Several open source operating system - projects are based on a release of this source code known as - 4.4BSD-Lite. In addition, they comprise a number of packages from other - Open Source projects, including notably the GNU project. The overall - operating system comprises:</para> - - <itemizedlist> - <listitem> - <para>The BSD kernel, which handles process scheduling, memory - management, symmetric multi-processing (SMP), device drivers, - etc.</para> - - <para><emphasis>Unlike the Linux kernel, there are several different - BSD kernels with differing capabilities.</emphasis></para> - </listitem> - - <listitem> - <para>The C library, the base API for the system.</para> - - <para><emphasis>The BSD C library is based on code from Berkeley, not - the GNU project.</emphasis></para> - </listitem> - - <listitem> - <para>Utilities such as shells, file utilities, compilers and - linkers.</para> - - <para><emphasis>Some of the utilities are derived from the GNU - project, others are not.</emphasis></para> - </listitem> - - <listitem> - <para>The X Window system, which handles graphical display.</para> - - <para>The X Window system used in most versions of BSD is maintained - by a separate project, the - <ulink url="http://www.XFree86.org/">&xfree86; project</ulink>. - This is the same code as Linux uses. BSD does not normally - specify a <quote>graphical desktop</quote> such as GNOME or KDE, - though these are available.</para> - </listitem> - - <listitem> - <para>Many other programs and utilities.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>What, a real &unix;?</title> - - <para>The BSD operating systems are not clones, but open source - derivatives of AT&T's Research &unix; operating system, which is also - the ancestor of the modern &unix; System V. This may surprise you. How - could that happen when AT&T has never released its code as open - source?</para> - - <para>It is true that AT&T &unix; is not open source, and in a copyright - sense BSD is very definitely <emphasis>not</emphasis> &unix;, but on the - other hand, AT&T has imported sources from other projects, - noticeably the Computer Sciences Research Group of the University of - California in Berkeley, CA. Starting in 1976, the CSRG started - releasing tapes of their software, calling them <emphasis>Berkeley - Software Distribution</emphasis> or <emphasis>BSD</emphasis>.</para> - - <para>Initial BSD releases consisted mainly of user programs, but that - changed dramatically when the CSRG landed a contract with the Defense - Advanced Projects Research Agency (DARPA) to upgrade the communications - protocols on their network, ARPANET. The new protocols were known as - the <emphasis>Internet Protocols</emphasis>, later - <emphasis>TCP/IP</emphasis> after the most important protocols. The - first widely distributed implementation was part of 4.2BSD, in - 1982.</para> - - <para>In the course of the 1980s, a number of new workstation companies - sprang up. Many preferred to license &unix; rather than developing - operating systems for themselves. In particular, Sun Microsystems - licensed &unix; and implemented a version of 4.2BSD, which they called - &sunos;. When AT&T themselves were allowed to sell &unix; commercially, - they started with a somewhat bare-bones implementation called System - III, to be quickly followed by System V. The System V code base did not - include networking, so all implementations included additional software - from the BSD, including the TCP/IP software, but also utilities such as - the <emphasis>csh</emphasis> shell and the <emphasis>vi</emphasis> - editor. Collectively, these enhancements were known as the - <emphasis>Berkeley Extensions</emphasis>.</para> - - <para>The BSD tapes contained AT&T source code and thus required a - &unix; source license. By 1990, the CSRG's funding was running out, and - it faced closure. Some members of the group decided to release the BSD - code, which was Open Source, without the AT&T proprietary code. - This finally happened with the <emphasis>Networking Tape 2</emphasis>, - usually known as <emphasis>Net/2</emphasis>. Net/2 was not a complete - operating system: about 20% of the kernel code was missing. One of the - CSRG members, William F. Jolitz, wrote the remaining code and released - it in early 1992 as <emphasis>386BSD</emphasis>. At the same time, - another group of ex-CSRG members formed a commercial company called - <ulink url="http://www.bsdi.com/">Berkeley Software Design Inc.</ulink> - and released a beta version of an operating system called - <ulink url="http://www.bsdi.com/">BSD/386</ulink>, which was based on - the same sources. The name of the operating system has since changed - to BSD/OS.</para> - - <para>386BSD never became a stable operating system. Instead, two other - projects split off from it in 1993: - <ulink url="http://www.NetBSD.org/">NetBSD</ulink> and - <ulink url="&url.base;/index.html">FreeBSD</ulink>. The two projects - originally diverged due to differences in patience waiting for - improvements to 386BSD: the NetBSD people started early in the year, - and the first version of FreeBSD was not ready until the end of the - year. In the meantime, the code base had diverged sufficiently to - make it difficult to merge. In addition, the projects had different - aims, as we will see below. In 1996, a further project, - <ulink url="http://www.OpenBSD.org/">OpenBSD</ulink>, split off from - NetBSD.</para> - </sect1> - - <sect1> - <title>Why is BSD not better known?</title> - - <para>For a number of reasons, BSD is relatively unknown:</para> - - <orderedlist> - <listitem> - <para>The BSD developers are often more interested in polishing their - code than marketing it.</para> - </listitem> - - <listitem> - <para>Much of Linux's popularity is due to factors external to the - Linux projects, such as the press, and to companies formed to - provide Linux services. Until recently, the open source BSDs had no - such proponents.</para> - </listitem> - - <listitem> - <para>BSD developers tend to be more experienced than Linux - developers, and have less interest in making the system easy to use. - Newcomers tend to feel more comfortable with Linux.</para> - </listitem> - - <listitem> - <para>In 1992, AT&T sued - <ulink url="http://www.bsdi.com/">BSDI</ulink>, - the vendor of BSD/386, alleging that the product contained - AT&T-copyrighted code. The case was settled out of court in - 1994, but the spectre of the litigation continues to haunt people. - As recently as March 2000 an article published on the web claimed - that the court case had been <quote>recently settled</quote>.</para> - - <para>One detail that the lawsuit did clarify is the naming: in the - 1980s, BSD was known as <quote>BSD &unix;</quote>. With the - elimination of the last vestige of AT&T code from BSD, it - also lost the right to the name &unix;. Thus you will see - references in book titles to <quote>the 4.3BSD &unix; operating - system</quote> and <quote>the 4.4BSD operating - system</quote>.</para> - </listitem> - - <listitem> - <para>There is a perception that the BSD projects are fragmented and - belligerent. The - <ulink url="http://interactive.wsj.com/bin/login?Tag=/&URI=/archive/retrieve.cgi%253Fid%253DSB952470579348918651.djm&">Wall Street - Journal</ulink> spoke of <quote>balkanization</quote> of the - BSD projects. Like the law suit, this perception bases mainly - on ancient history.</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title>Comparing BSD and Linux</title> - - <para>So what is really the difference between, say, Debian Linux and - FreeBSD? For the average user, the difference is surprisingly small: - Both are &unix; like operating systems. Both are developed by - non-commercial projects (this does not apply to many other Linux - distributions, of course). In the following section, we will look at BSD - and compare it to Linux. The description applies most closely to - FreeBSD, which accounts for an estimated 80% of the BSD installations, - but the differences from NetBSD and OpenBSD are small.</para> - - <sect2> - <title>Who owns BSD?</title> - - <para>No one person or corporation owns BSD. It is created and - distributed by a community of highly technical and committed - contributors all over the world. Some of the components of BSD are - Open Source projects managed by a different project maintainer.</para> - </sect2> - - <sect2> - <title>How is BSD developed and updated?</title> - - <para>The BSD kernels are developed and updated following the Open - Source development model. Each project maintains a publicly - accessible <emphasis>source tree</emphasis> under the - <ulink url="http://www.sourcegear.com/CVS/">Concurrent Versions - System</ulink> (CVS), which contains all source files for the - project, including documentation and other incidental files. CVS - allows users to <quote>check out</quote> (in other words, to - extract a copy of) any desired version of the system.</para> - - <para>A large number of developers worldwide contribute to improvements - to BSD. They are divided into three kinds:</para> - - <itemizedlist> - <listitem> - <para><firstterm>Contributors</firstterm> write code or documentation. - They are not permitted to commit (add code) directly to the source - tree. In order for their code to be included in the system, it - must be reviewed and checked in by a registered developer, known - as a <emphasis>committer</emphasis>.</para> - </listitem> - - <listitem> - <para><firstterm>Committers</firstterm> are developers with write - access to the source tree. In order to become a committer, an - individual must show ability in the area in which he is - active.</para> - - <para> - It is at the individual committer's discretion whether he should - obtain authority before committing changes to the source tree. In - general, an experienced committer may make changes which are - obviously correct without obtaining consensus. For example, a - documentation project committer may correct typographical or - grammatical errors without review. On the other hand, developers - making far-reaching or complicated changes are expected to submit - their changes for review before committing them. In extreme - cases, a core team member with a function such as Principal - Architect may order that changes be removed from the tree, a - process known as <firstterm>backing out</firstterm>. All committers - receive mail describing each individual commit, so it is not - possible to commit secretly.</para> - </listitem> - - <listitem> - <para>The <firstterm>Core team</firstterm>. FreeBSD and - NetBSD each have a core team which manages the project. The - core teams developed in the course of the projects, and their role - is not always well-defined. It is not necessary to be a developer - in order to be a core team member, though it is normal. The rules - for the core team vary from one project to the other, but in - general they have more say in the direction of the project than - non-core team members have.</para> - </listitem> - </itemizedlist> - - <para>This arrangement differs from Linux in a number of ways:</para> - - <orderedlist> - <listitem> - <para>No one person controls the content of the system. In - practice, this difference is overrated, since the Chief Architect - can require that code be backed out, and even in the Linux project - several people are permitted to make changes.</para> - </listitem> - - <listitem> - <para>On the other hand, there <emphasis>is</emphasis> a central - repository, a single place where you can find the entire operating - system sources, including all older versions.</para> - </listitem> - - <listitem> - <para>BSD projects maintain the entire <quote>Operating - System</quote>, not only the kernel. This distinction is only - marginally useful: neither BSD nor Linux is useful without - applications. The applications used under BSD are frequently the - same as the applications used under Linux.</para> - </listitem> - - <listitem> - <para>As a result of the formalized maintenance of a single CVS - source tree, BSD development is clear, and it is possible to - access any version of the system by release number or by date. - CVS also allows incremental updates to the system: for example, - the FreeBSD repository is updated about 100 times a day. Most of - these changes are small.</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>BSD releases</title> - - <para>Each BSD project provides the system in three different - <quote>releases</quote>. As with Linux, releases are assigned a - number such as 1.4.1 or 3.5. In addition, the version number has a - suffix indicating its purpose:</para> - - <orderedlist> - <listitem> - <para>The development version of the system is called - <firstterm>CURRENT</firstterm>. FreeBSD assigns a number to - CURRENT, for example FreeBSD 5.0-CURRENT. NetBSD uses a slightly - different naming scheme and appends a single-letter suffix which - indicates changes in the internal interfaces, for example NetBSD - 1.4.3G. OpenBSD does not assign a number ("OpenBSD-current"). - All new development on the system goes into this branch.</para> - </listitem> - - <listitem> - <para>At regular intervals, between two and four times a year, the - projects bring out a <firstterm>RELEASE</firstterm> version of the - system, which is available on CD-ROM and for free download from - FTP sites, for example OpenBSD 2.6-RELEASE or NetBSD 1.4-RELEASE. - The RELEASE version is intended for end users and is the normal - version of the system. NetBSD also provides <emphasis>patch - releases</emphasis> with a third digit, for example NetBSD - 1.4.2.</para> - </listitem> - - <listitem> - <para>As bugs are found in a RELEASE version, they are fixed, and - the fixes are added to the CVS tree. In FreeBSD, the resultant - version is called the <firstterm>STABLE</firstterm> version, while in NetBSD and OpenBSD - it continues to be called the RELEASE version. Smaller new - features can also be added to this branch after a period of test - in the CURRENT branch.</para> - </listitem> - </orderedlist> - - <para><emphasis>By contrast, Linux maintains two separate code trees: - the stable version and the development version. Stable versions - have an even minor version number, such as 2.0, 2.2 or 2.4. - Development versions have an odd minor version number, such as 2.1, - 2.3 or 2.5. In each case, the number is followed by a further - number designating the exact release. In addition, each vendor adds - their own userland programs and utilities, so the name of the - distribution is also important. Each distribution vendor also - assigns version numbers to the distribution, so a complete - description might be something like <quote>TurboLinux 6.0 with kernel - 2.2.14</quote></emphasis></para> - </sect2> - - <sect2> - <title>What versions of BSD are available?</title> - - <para>In contrast to the numerous Linux distributions, there are only - three open source BSDs. Each BSD project maintains its own source - tree and its own kernel. In practice, though, there appear to be - fewer divergences between the userland code of the projects than there - is in Linux.</para> - - <para>It is difficult to categorize the goals of each project: the - differences are very subjective. Basically,</para> - - <itemizedlist> - <listitem> - <para>FreeBSD aims for high performance and ease of use by - end users, and is a favourite of web content providers. It runs - on PCs and Compaq's Alpha processors. The FreeBSD project has - significantly more users than the other projects.</para> - </listitem> - - <listitem> - <para>NetBSD aims for maximum portability: <quote>of course it runs - NetBSD</quote>. It runs on machines from palmtops to large - servers, and has even been used on NASA space missions. It is a - particularly good choice for running on old non-Intel - hardware.</para> - </listitem> - - <listitem> - <para>OpenBSD aims for security and code purity: it uses a - combination of the open source concept and rigorous code reviews - to create a system which is demonstrably correct, making it the - choice of security-conscious organizations such as banks, stock - exchanges and US Government departments. Like NetBSD, it runs on - a number of platforms.</para> - </listitem> - </itemizedlist> - - <para>There are also two additional BSD &unix; operating systems which are not - open source, BSD/OS and Apple's &macos; X:</para> - - <itemizedlist> - <listitem> - <para>BSD/OS is the oldest of the 4.4BSD derivatives. It - is not open source, though source code licenses are available at - relatively low cost. It resembles FreeBSD in many ways.</para> - </listitem> - - <listitem> - <para><ulink url="http://www.apple.com/macosx/server/">&macos; - X</ulink> is the latest version of the operating system for - <ulink url="http://www.apple.com/">Apple Computer Inc.'s</ulink> - &macintosh; line. The BSD core of this operating - system, <ulink - url="http://developer.apple.com/darwin/">Darwin</ulink>, - is available as a fully functional open source operating - system for x86 and PPC computers. The Aqua/Quartz - graphics system and many other proprietary aspects of - &macos; X remain closed-source, however. Several Darwin - developers are also FreeBSD committers, and - vice-versa.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>How does the BSD license differ from the GNU Public - license?</title> - - <para>Linux is available under the - <ulink url="http://www.fsf.org/copyleft/gpl.html">GNU General Public - License</ulink> (GPL), which is designed to eliminate closed - source software. In particular, any derivative work of a product - released under the GPL must also be supplied with source code if - requested. By contrast, the - <ulink url="http://www.opensource.org/licenses/bsd-license.html">BSD - license</ulink> is less restrictive: binary-only distributions are - allowed. This is particularly attractive for embedded - applications.</para> - </sect2> - - <sect2> - <title>What else should I know?</title> - - <para>Since fewer applications are available for BSD than Linux, the BSD - developers created a Linux compatibility package, which allows Linux - programs to run under BSD. The package includes both kernel - modifications, in order to correctly perform Linux system calls, and - Linux compatibility files such as the C library. There is no - noticeable difference in execution speed between a Linux application - running on a Linux machine and a Linux application running on a BSD - machine of the same speed.</para> - - <para>The <quote>all from one supplier</quote> nature of BSD means that - upgrades are much easier to handle than is frequently the case with - Linux. BSD handles library version upgrades by providing - compatibility modules for earlier library versions, so it is possible - to run binaries which are several years old with no problems.</para> - </sect2> - - <sect2> - <title>Which should I use, BSD or Linux?</title> - - <para>What does this all mean in practice? Who should use BSD, who - should use Linux?</para> - - <para>This is a very difficult question to answer. Here are some - guidelines:</para> - - <itemizedlist> - <listitem> - <para><quote>If it ain't broke, don't fix it</quote>: If you already - use an open source operating system, and you are happy with it, - there is probably no good reason to change.</para> - </listitem> - - <listitem> - <para>BSD systems, in particular FreeBSD, can have notably higher - performance than Linux. But this is not across the board. In many - cases, there is little or no difference in performance. In some - cases, Linux may perform better than FreeBSD.</para> - </listitem> - - <listitem> - <para>In general, BSD systems have a better reputation for - reliability, mainly as a result of the more mature code - base.</para> - </listitem> - - <listitem> - <para>The BSD license may be more attractive than the GPL.</para> - </listitem> - - <listitem> - <para>BSD can execute most Linux binaries, while Linux can not execute BSD - binaries. Many BSD implementations can also execute binaries - from other &unix; like systems. As a result, BSD may present an - easier migration route from other systems than - Linux would.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Who provides support, service, and training for BSD?</title> - - <para>BSDi have always supported BSD/OS, and they have recently - announced support contracts for FreeBSD.</para> - - <para>In addition, each of the projects has a list of consultants for - hire: - <ulink url="&url.base;/commercial/consulting_bycat.html">FreeBSD</ulink>, - <ulink url="http://www.netbsd.org/gallery/consultants.html">NetBSD</ulink>, - and <ulink url="http://www.openbsd.org/support.html">OpenBSD</ulink>.</para> - </sect2> - </sect1> -</article> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO8859-1/articles/fbsd-from-scratch/Makefile b/en_US.ISO8859-1/articles/fbsd-from-scratch/Makefile deleted file mode 100644 index 980700e113..0000000000 --- a/en_US.ISO8859-1/articles/fbsd-from-scratch/Makefile +++ /dev/null @@ -1,30 +0,0 @@ -# -# $FreeBSD$ -# -# Article: FreeBSD From Scratch - -DOC?= article - -FORMATS?= html - -MAINTAINER= schweikh@FreeBSD.org - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -EXTRAS= stage_1.conf.default -EXTRAS+= stage_1.sh -EXTRAS+= stage_2.conf.default -EXTRAS+= stage_2.sh -EXTRAS+= stage_3.mk - -SRCS= article.sgml -SRCS+= ${EXTRAS} - -afterinstall: -.for entry in ${EXTRAS} - ${INSTALL_DOCS} ${.CURDIR}/${entry} ${DESTDIR} -.endfor - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/fbsd-from-scratch/article.sgml b/en_US.ISO8859-1/articles/fbsd-from-scratch/article.sgml deleted file mode 100644 index ea477f5369..0000000000 --- a/en_US.ISO8859-1/articles/fbsd-from-scratch/article.sgml +++ /dev/null @@ -1,642 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -<!ENTITY scratch.ap "<application>FreeBSD From Scratch</application>"> -]> - -<article> - <articleinfo> - <title>FreeBSD From Scratch</title> - - <author> - <firstname>Jens</firstname> - <surname>Schweikhardt</surname> - <affiliation> - <address><email>schweikh@FreeBSD.org</email></address> - </affiliation> - </author> - <copyright> - <year>2002,2003,2004</year> - <holder>Jens Schweikhardt</holder> - </copyright> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.adobe; - &tm-attrib.general; - </legalnotice> - </articleinfo> - - <abstract> - <para>This article describes my efforts at &scratch.ap;: a fully - automated installation of a customized &os; system compiled from - source, including compilation of all your favorite ports and - configured to match your idea of the perfect system. If you - think <command>make world</command> is a wonderful concept, - &scratch.ap; extends it to <command>make evenmore</command>.</para> - </abstract> - - <sect1 id="introduction"> - <title>Introduction</title> - - <para>Have you ever upgraded your system with <command>make world</command>? - There is a problem if you have only one system on your disks. If - the <maketarget>installworld</maketarget> fails partway through, - you are left with a broken system that might not even boot any - longer. Or maybe the <maketarget>installworld</maketarget> runs - smoothly but the new kernel does not boot. Then it is time to - reach for the Fixit CD and dig for those backups you have taken - half a year ago.</para> - - <para>I believe in the <quote>wipe your disks when upgrading systems</quote> - paradigm. Wiping disks, or rather partitions, makes sure there is no - old cruft left lying around, something which most upgrade procedures - just do not care about. But wiping the partitions means you have to - also recompile/reinstall all your ports and packages and then - redo all your carefully crafted configuration tweaks. - If you think that this task should be automated as well, read on.</para> - </sect1> - - <sect1 id="why"> - <title>Why would I (not) want &scratch.ap;?</title> - - <para>This is a legitimate question. We have - <application>sysinstall</application> and the well known way to - compile the kernel and the userland tools.</para> - - <para>The problem with <application>sysinstall</application> is - that it is severely limited in what, where and how it can install.</para> - - <itemizedlist> - <listitem> - <para>It is normally used to install pre-built distribution sets and - packages from some other source (CD, DVD, FTP). It cannot install - the result of a <literal>make buildworld</literal>.</para> - </listitem> - - <listitem> - <para>It cannot install a second system under a directory - in a running system.</para> - </listitem> - - <listitem> - <para>It cannot install in <application>Vinum</application> - partitions.</para> - </listitem> - - <listitem> - <para>It cannot compile ports, only install precompiled packages.</para> - </listitem> - - <listitem> - <para>It is hard to script or to make arbitrary post-installation - changes.</para> - </listitem> - - <listitem> - <para>Last but not least, <application>sysinstall</application> - is semi-officially at its End-Of-Life.</para> - </listitem> - </itemizedlist> - - <para>The well known way to build and install the world, as - described in <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html">the - Handbook</ulink>, by default replaces - the existing system. Only the kernel and modules are saved. - System binaries, headers and a lot of other files are overwritten; - obsolete files are still present and can cause surprises. If the - upgrade fails for any reason, it may be hard or even impossible to - restore the previous state of the system.</para> - - <para>&scratch.ap; solves all these problems. The strategy is - simple: use a running system to install a new system under an empty - directory tree, while new partitions are mounted appropriately - in that tree. Many config files can be copied to the appropriate - place and &man.mergemaster.8; can take care of those that cannot. - Arbitrary post-configuration of the new system can be - done from within the old system, up to the point where you can - chroot to the new system. In other words, we go through three - stages, where each stage consists of either running a shell - script or invoke <command>make</command>:</para> - - <orderedlist> - <listitem> - <para><filename>stage_1.sh</filename>: - Create a new bootable system under an empty directory and merge - or copy as many files as are necessary. - Then boot the new system.</para> - </listitem> - - <listitem> - <para><filename>stage_2.sh</filename>: - Install desired ports.</para> - </listitem> - - <listitem> - <para><filename>stage_3.mk</filename>: - Do post-configuration for software installed in previous stage.</para> - </listitem> - </orderedlist> - - <para>Once you have used &scratch.ap; to build a second system and - found it works satisfactorily for a couple of weeks, you can then - use it again to reinstall the original system. From now on, whenever - you feel like an update is in order, you simply toggle the - partitions you want to wipe and reinstall.</para> - - <para>Maybe you have heard of or even tried <ulink - url="http://www.linuxfromscratch.org/">Linux From Scratch</ulink>, - or LFS for short. LFS also describes how to build and install a - system from scratch in empty partitions using a running system. - The focus in LFS seems to be to show the role of each system - component (such as kernel, compiler, devices, shell, terminal database, - etc) and the details of each component's installation. - &scratch.ap; does not go into that much detail. My goal is to - provide an automated and complete installation, not explaining all - the gory details that go on under the hood when making the world. - In case you want to explore &os; at this level of detail, start - looking at <filename>/usr/src/Makefile</filename> and follow the - actions of a <command>make buildworld</command>.</para> - - <para>There are also downsides in the approach taken by &scratch.ap; - that you should bear in mind.</para> - - <!-- XXX: A nice idea would be to write stage_2.sh using a jail - that runs into the newly installed world from stage_1. Having - properly set up a network address as the jail's primary IP - address, it might even be possible to build ports in a chroot - without uninstalling anything from the 'host' system. But - keep in mind that even jails run on the 'host' kernel. --> - - <itemizedlist> - <listitem> - <para>While compiling the ports during stage two the system can - not be used for its usual duties. If you run a production server - you have to consider the downtime caused by stage two. The ports - compiled by <filename>stage_2.conf.default</filename> below require - about 4 hours to build on an AMD1800+ SCSI system with 10krpm disks - and 1GB of RAM. If you prefer to install packages instead of ports, - you can significantly reduce the downtime to about 10 minutes.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="prerequisites"> - <title>Prerequisites</title> - - <para>For going the &scratch.ap; way, you need to have:</para> - - <itemizedlist> - <listitem> - <para>A running &os; system with sources and a ports tree.</para> - </listitem> - - <listitem> - <para>At least one unused partition where the new system will be - installed.</para> - </listitem> - - <listitem> - <para>Experience with running &man.mergemaster.8;. Or at least no fear - doing so.</para> - </listitem> - - <listitem> - <para>If you have no or only a slow link to the Internet: the distfiles - for your favorite ports.</para> - </listitem> - - <listitem> - <para>Basic knowledge of shell scripting with the Bourne shell, - &man.sh.1;.</para> - </listitem> - - <listitem> - <para>Finally, you should also be able to tell your boot - loader how to boot the new system, either interactively, or - by means of a config file.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="stage1"> - <title>Stage One: System Installation</title> - - <para>The first version of this article used a single shell script - for stage one where all your customization had to be done by editing - the script. After valuable user feedback I have decided to - separate the code and data in the scripts. This allows to have - different configuration data sets to install different systems - without changing any of the code scripts.</para> - - <para>The code script for stage one is - <filename>stage_1.sh</filename> and when run with exactly one - argument, like</para> - - <informalexample> - <screen>&prompt.root; <userinput>./stage_1.sh <replaceable>default</replaceable></userinput></screen> - </informalexample> - - <para>will read its configuration from - <filename>stage_1.conf.default</filename> and write a log to - <filename>stage_1.log.default</filename>.</para> - - <para>Further below you find my <filename>stage_1.conf.default</filename>. - You need to customize it in various places to match your idea of the - <quote>perfect system</quote>. I have tried to extensively comment - the places you should adapt. The configuration script must provide - four shell functions, <command>create_file_systems</command>, - <command>create_etc_fstab</command>, <command>copy_files</command> - and <command>all_remaining_customization</command> (in case it - matters: this is also the sequence in which they will be called - from <filename>stage_1.sh</filename>).</para> - - <para>The points to ponder are:</para> - - <itemizedlist> - <listitem> - <para>Partition layout.</para> - - <para>I do not subscribe to the idea of a single huge partition - for the whole system. My systems generally have at least - one partition for - <filename>/</filename>, - <filename>/usr</filename> and - <filename>/var</filename> with - <filename>/tmp</filename> symlinked to - <filename>/var/tmp</filename>. - In addition I share the file systems for - <filename>/home</filename> (user homes), - <filename>/home/ncvs</filename> (&os; CVS repository replica), - <filename>/usr/ports</filename> (the ports tree), - <filename>/src</filename> (various checked out src trees) and - <filename>/share</filename> (other shared data without the need - for backups, like the news spool).</para> - </listitem> - - <listitem> - <para>Luxury items.</para> - - <para>What you want immediately after booting the new system and - even before starting stage two. The reason for not simply - chrooting to the new system during stage one and installing - all my beloved ports is that in theory and in practice there - are bootstrap and consistency issues: stage one has your old - kernel running, but the chrooted environment consists of new - binaries and headers. If the new binaries use a new system - call, these binaries will die with <literal>SIGSYS, Bad - system call</literal>, because the old kernel does not have - that system call. I have seen other issues when I tried - building <filename role="package">lang/perl5</filename>.</para> - - </listitem> - </itemizedlist> - - <para>Before you run <filename>stage_1.sh</filename> make sure - you have completed the usual tasks in preparation for - <command>make installworld installkernel</command>, like:</para> - - <itemizedlist> - <listitem> - <para>configured your kernel config file</para> - </listitem> - - <listitem> - <para>successfully completed <command>make buildworld</command></para> - </listitem> - - <listitem> - <para>successfully completed <command>make buildkernel - KERNCONF=<replaceable>whatever</replaceable></command></para> - </listitem> - </itemizedlist> - - <para>When you run <filename>stage_1.sh</filename> for the first - time, and the config files copied from your running system to the - new system are not up-to-date with respect to what is under - <filename>/usr/src</filename>, <command>mergemaster</command> will - ask you how to proceed. I recommend merging the changes. If you get - tired of going through the dialogues you can simply update the files - on your <emphasis>running</emphasis> system once (Only if this is an - option. You probably do not want to do this if one of your systems - runs <literal>-STABLE</literal> and the other - <literal>-CURRENT</literal>. The changes may be incompatible). - Subsequent <command>mergemaster</command> invocations will detect - that the RCS version IDs match those under - <filename>/usr/src</filename> and skip the file.</para> - - <para>The <filename>stage_1.sh</filename> script will stop at the - first command that fails (returns a non-zero exit status) due to - <command>set -e</command>, so you cannot overlook errors. It will - also stop if you use an unset environment variable, probably due - to a typo. You should correct any errors in your version of - <filename>stage_1.conf.default</filename> before you go on.</para> - - <para>In <filename>stage_1.sh</filename> we invoke - <command>mergemaster</command>. Even if none of the files requires a - merge, it will display and ask at the end</para> - - <screen>*** Comparison complete - -Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] <userinput>no</userinput></screen> - - <para>Please answer <literal>no</literal> or just hit - <keycap>Enter</keycap>. The reason is that <command>mergemaster</command> - will have left a few zero sized files below - <filename>/var/tmp/temproot.stage1</filename> which will be copied to the - new system later (unless already there).</para> - - <para>After that it will list the files it installed, making use of - a pager, &man.more.1; by default, optionally &man.less.1;:</para> - -<screen>*** You chose the automatic install option for files that did not - exist on your system. The following were installed for you: - /newroot/etc/defaults/rc.conf - ... - /newroot/COPYRIGHT - -(END)</screen> - - <para>Type <keycap>q</keycap> to quit the pager. Then you will - be informed about <filename>login.conf</filename>:</para> - - <screen>*** You installed a login.conf file, so make sure that you run - '/usr/bin/cap_mkdb /newroot/etc/login.conf' - to rebuild your login.conf database - - Would you like to run it now? y or n [n]</screen> - - <para>The answer does not matter since we will run &man.cap.mkdb.1; in any - case.</para> - - <para>Here is the author's <ulink - url="stage_1.conf.default"><filename>stage_1.conf.default</filename></ulink>, - which you need to modify substantially. The comments give you - enough information what to change.</para> - - <warning> - <para>Please pay attention to the &man.newfs.8; commands. - While you can not create new file systems on mounted partitions, the - script will happily erase any unmounted - <filename>/dev/da0s1a</filename>, <filename>/dev/da0s1e</filename> - and <filename>/dev/da2s1e</filename>. This can be enough to ruin - your day, so be sure to modify the device names.</para> - </warning> - -<programlisting><inlinegraphic fileref="stage_1.conf.default" format="linespecific"></programlisting> - - <para>Download <ulink - url="stage_1.conf.default"><filename>stage_1.conf.default</filename> - </ulink>.</para> - - <para>Running this script installs a system that when booted - provides:</para> - <itemizedlist> - <listitem> - <para>Inherited users and groups.</para> - </listitem> - <listitem> - <para>Firewalled Internet connectivity over Ethernet and PPP.</para> - </listitem> - <listitem> - <para>Correct time zone and NTP.</para> - </listitem> - <listitem> - <para>Some more minor configuration, like - <filename>/etc/ttys</filename> and - <command>inetd</command>.</para> - </listitem> - </itemizedlist> - - <para>Other areas are prepared for configuration, but will not work - until stage two is completed. For example we have copied files to - configure printing and X11. Printing however is likely to need - applications not found in the base system, like &postscript; - utilities. X11 will not run before we have compiled the server, - libraries and programs.</para> - </sect1> - - <sect1 id="stage2"> - <title>Stage Two: Ports Installation</title> - - <note> - <para>It is also possible to install the (precompiled) - packages at this stage, instead of compiling ports. In this case, - <filename>stage_2.sh</filename> would be nothing more than a list of - <command>pkg_add</command> commands. I trust you know how to write - such a script. Here we concentrate on the more flexible and - traditional way of using the ports.</para> - </note> - - <para>The following <filename>stage_2.sh</filename> script is how I - install my favorite ports. It can be run any number of times and - will skip all ports that are already installed. It supports the - <emphasis>dryrun</emphasis> option (<option>-n</option>) to just - show what would be done. You run it like <filename>stage_1.sh</filename> - with exactly one argument to denote a config file, e.g.</para> - - <informalexample> - <screen>&prompt.root; <userinput>./stage_2.sh <replaceable>default</replaceable></userinput></screen> - </informalexample> - - <para>which will read the list of ports from - <filename>stage_2.conf.default</filename>.</para> - - <para>The list of ports consists of lines with two or more space - separated words: the category and the port, optionally followed by - an installation command that will compile and install the port - (default: <command>make install BATCH=yes < /dev/null</command>). - Empty lines and lines - starting with # are ignored. Most of the time it suffices to only - name category and port. A few ports however can be fine tuned by - specifying <command>make</command> variables, e.g.:</para> - - <programlisting>www mozilla make WITHOUT_MAILNEWS=yes WITHOUT_CHATZILLA=yes install</programlisting> - - <para>In fact you can specify arbitrary shell commands, so you are - not restricted to simple <command>make</command> invocations:</para> - - <programlisting>java linux-sun-jdk13 yes | make install -news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" make install</programlisting> - - <para>Note that the line for - <filename role="package">news/inn-stable</filename> is an example - for a one-shot shell variable assignment to - <literal>CONFIGURE_ARGS</literal>. The port - <filename>Makefile</filename> will use this as an initial value - and augment some other essential args. The difference to - specifying a <application>make</application> variable on the command line - with</para> - - <programlisting>news inn-stable make CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" install</programlisting> - - <para>is that the latter will override instead of augment. It depends on - the particular port which method you want.</para> - - <para>Be careful that your ports do not use an interactive install, i.e. - they should not try to read from stdin other than what you explicitly - give them on stdin. If they do, they will read the next line(s) from - your list of ports in the here-document and get confused. If - <filename>stage_2.sh</filename> mysteriously skips a port or stops - processing, this is likely the reason.</para> - - <para>Below is <filename>stage_2.conf.default</filename>. A log file named - <filename>LOGDIR/category+port</filename> is created for each port - it actually installs.</para> - -<programlisting><inlinegraphic fileref="stage_2.conf.default" format="linespecific"></programlisting> - - <para>Download <ulink - url="stage_2.conf.default"><filename>stage_2.conf.default</filename></ulink>.</para> - </sect1> - - <sect1 id="stage3"> - <title>Stage Three</title> - - <para>You have installed your beloved ports during stage two. Some - ports require a little bit of configuration. This is what stage three, - the post-configuration is for. I could have integrated this - post-configuration at the end of the <filename>stage_2.sh</filename> - script. However, I think there is a conceptual difference between - installing a port and modifying its out-of-the-box configuration - that warrants a separate stage.</para> - - <para>I have chosen to implement stage three as a - <filename>Makefile</filename> because this allows easy selection of - what you want to configure simply by running:</para> - - <informalexample> - <screen>&prompt.root; <userinput>make -f stage_3.mk <replaceable>target</replaceable></userinput></screen> - </informalexample> - - <para>As with <filename>stage_2.sh</filename> make sure you have - <filename>stage_3.mk</filename> available after booting the new - system, either by putting it on a shared partition or copying it - somewhere on the new system.</para> - </sect1> - - <sect1 id="limitations"> - <title>Limitations</title> - - <para>The automated installation of a port may prove difficult if it - is interactive and does not support <command>make BATCH=YES - install</command>. For a few ports the interaction is nothing more - than typing <literal>yes</literal> when asked to accept some license. - If such input is read from the standard input, we simply pipe the - appropriate answers to the installation command (usually <command>make - install</command>; this is how I deal with <filename - role="package">java/linux-sun-jdk14</filename> in - <filename>stage_2.conf.default</filename>).</para> - - <para>This strategy for example does not work for <filename - role="package">editors/staroffice52</filename>, which requires that - X11 is running. The installation procedure involves a fair amount of - clicking and typing, so it cannot be automated like other ports can. - However the following workaround does the trick for me: first I - create a staroffice package on the old system with</para> - - <informalexample> - <screen>&prompt.root; <userinput>cd /usr/ports/editors/staroffice52</userinput> -&prompt.root; <userinput>make package</userinput> -===> Building package for staroffice-5.2_1 -Creating package /usr/ports/editors/staroffice52/staroffice-5.2_1.tbz -Registering depends:. -Creating bzip'd tar ball in '/usr/ports/editors/staroffice52/staroffice-5.2_1.tbz'</screen> - </informalexample> - - <para>and during stage two I simply use:</para> - - <informalexample> - <screen>&prompt.root; <userinput>pkg_add /usr/ports/editors/staroffice52/staroffice-5.2_1.tbz</userinput></screen> - </informalexample> - - <para>You should also be aware of upgrade issues for config files. - In general you do not know when and if the format or contents of a - config file changes. A new group may be added to - <filename>/etc/group</filename>, or <filename>/etc/passwd</filename> - may gain another field. All of this has happened in the past. Simply - copying a config file from the old to the new system may be enough - most of the time, but in these cases it was not. If you update a - system the canonical way (by overwriting the old files) you are - expected to use <command>mergemaster</command> to deal with changes - where you effectively want to merge your local config with - potentially new items. Unfortunately, <command>mergemaster</command> - is only available for base system files, not for anything installed - by ports. Some third party software seems to be especially designed - to keep me on my toes by changing the config file format every - fortnight. To detect such silent changes, I keep a copy of the - modified config files in the same place where I keep - <filename>stage_3.mk</filename> and compare the result with a - <application>make</application> rule, e.g. for - <application>apache</application>'s <filename>httpd.conf</filename> - in target <command>config_apache</command> with</para> - -<programlisting> -@if ! cmp -s /usr/local/etc/apache2/httpd.conf httpd.conf; then \ - echo "ATTENTION: the httpd.conf has changed. Please examine if"; \ - echo "the modifications are still correct. Here is the diff:"; \ - diff -u /usr/local/etc/apache2/httpd.conf httpd.conf; \ -fi -</programlisting> - - <para>If the diff is innocuous I can make the message go away with - <command>cp /usr/local/etc/apache2/httpd.conf - httpd.conf</command>.</para> - - <para>I have used &scratch.ap; several times to update a - <literal>5-CURRENT</literal> to <literal>5-CURRENT</literal>, i.e. - I have never tried to install a <literal>5-CURRENT</literal> from - a <literal>4-STABLE</literal> system or vice versa. Due to the - number of changes between different major release numbers I would - expect this process to be a bit more involved. Using &scratch.ap; - for upgrades within the realm of <literal>4-STABLE</literal> - should work painlessly (although I have not yet tried it.) Users of - <literal>4-STABLE</literal> may want to consider the following - areas:</para> - - <note> - <para>If you do not use the device file system, &man.devfs.5;, you - may want to create devices for some of your hardware with - &man.MAKEDEV.8; in <command>all_remaining_customization</command>. - </para> - </note> - </sect1> - - <sect1 id="files"> - <title>The Files</title> - - <para>Here are the three files you need beside the config files - already shown above.</para> - - <para>This is the <ulink - url="stage_1.sh"><filename>stage_1.sh</filename></ulink> - script, which you should not need to modify.</para> - -<programlisting><inlinegraphic fileref="stage_1.sh" format="linespecific"></programlisting> - - <para>Download <ulink - url="stage_1.sh"><filename>stage_1.sh</filename></ulink>.</para> - - <para>This is the <ulink - url="stage_2.sh"><filename>stage_2.sh</filename></ulink> - script. You may want to modify the variables at the - beginning.</para> - -<programlisting><inlinegraphic fileref="stage_2.sh" format="linespecific"></programlisting> - - <para>Download <ulink - url="stage_2.sh"><filename>stage_2.sh</filename></ulink>.</para> - - <para>This is my <ulink - url="stage_3.mk"><filename>stage_3.mk</filename></ulink> to - give you an idea how to automate all reconfiguration.</para> - -<programlisting><inlinegraphic fileref="stage_3.mk" format="linespecific"></programlisting> - - <para>Download <ulink - url="stage_3.mk"><filename>stage_3.mk</filename></ulink>.</para> - </sect1> - -</article> diff --git a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_1.conf.default b/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_1.conf.default deleted file mode 100644 index 84da99943f..0000000000 --- a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_1.conf.default +++ /dev/null @@ -1,184 +0,0 @@ -# This file: stage_1.conf.default, sourced by stage_1.sh. -# -# $Id: stage_1.conf.default,v 1.3 2004-07-19 21:02:26 schweikh Exp $ -# $FreeBSD$ - -# Root mount point where you create the new system. Because it is only -# used as a mount point, no space will be used on that file system as all -# files are of course written to the mounted file system(s). -DESTDIR="/newroot" - -# Where your src tree is. -SRC="/usr/src" - -# Your kernel config name as from make buildkernel KERNCONF=... -KERNCONF="HAL9000" - -# Available time zones are those under /usr/share/zoneinfo. -TIMEZONE="Europe/Berlin" - -# -# The create_file_systems function must create the mountpoints under -# DESTDIR, create the file systems, and then mount them under DESTDIR. -# -create_file_systems () { - # The new root file system. Mandatory. - # Change DEVICE names or risk foot shooting. - # You must use newfs -O 1 for the root fs if you want to boot it from grub. - DEVICE=/dev/da0s1a - mkdir -m 755 -p ${DESTDIR} - chown root:wheel ${DESTDIR} - newfs -U -O 1 ${DEVICE} - mount -o noatime ${DEVICE} ${DESTDIR} - - # Additional file systems and initial mount points. Optional. - DEVICE=/dev/da0s1e - mkdir -m 755 -p ${DESTDIR}/var - chown root:wheel ${DESTDIR}/var - newfs -U ${DEVICE} - mount -o noatime ${DEVICE} ${DESTDIR}/var - - DEVICE=/dev/da2s1e - mkdir -m 755 -p ${DESTDIR}/usr - chown root:wheel ${DESTDIR}/usr - newfs -U ${DEVICE} - mount -o noatime ${DEVICE} ${DESTDIR}/usr -} - -# -# The create_etc_fstab function must create an fstab matching the -# file systems created in create_file_systems. -# -create_etc_fstab () { - cat <<EOF >${DESTDIR}/etc/fstab -# Device Mountpoint FStype Options Dump Pass# -/dev/da0s1b none swap sw 0 0 -/dev/da1s1b none swap sw 0 0 -/dev/da2s2b none swap sw 0 0 -/dev/da3s2b none swap sw 0 0 -/dev/da0s1a / ufs rw,noatime 1 1 -/dev/da0s1e /var ufs rw,noatime 1 1 -/dev/da2s1e /usr ufs rw,noatime 1 1 -/dev/vinum/Share /share ufs rw,noatime 0 2 -/dev/vinum/home /home ufs rw,noatime 0 2 -/dev/vinum/ncvs /home/ncvs ufs rw,noatime 0 2 -/dev/vinum/ports /usr/ports ufs rw,noatime 0 2 -/dev/ad1s1a /flash ufs rw,noatime 0 0 -/dev/ad0s1 /2k ntfs ro,noauto 0 0 -/dev/ad0s6 /linux ext2fs ro,noauto 0 0 -# -/dev/cd0 /cdrom cd9660 ro,noauto 0 0 -/dev/cd1 /dvd cd9660 ro,noauto 0 0 -proc /proc procfs rw 0 0 -linproc /compat/linux/proc linprocfs rw 0 0 -EOF - chmod 644 ${DESTDIR}/etc/fstab - chown root:wheel ${DESTDIR}/etc/fstab -} - -# -# The copy_files function is used to copy files before mergemaster is run. -# -copy_files () { - # Add or remove from this list at your discretion. Mostly mandatory. - for f in \ - /.profile \ - /etc/group \ - /etc/hosts \ - /etc/inetd.conf \ - /etc/ipfw.conf \ - /etc/make.conf \ - /etc/master.passwd \ - /etc/nsswitch.conf \ - /etc/ntp.conf \ - /etc/printcap \ - /etc/profile \ - /etc/rc.conf \ - /etc/resolv.conf \ - /etc/start_if.xl0 \ - /etc/ttys \ - /etc/ppp/* \ - /etc/mail/aliases \ - /etc/mail/aliases.db \ - /etc/mail/hal9000.mc \ - /etc/mail/service.switch \ - /etc/ssh/*key* \ - /etc/ssh/*_config \ - /etc/X11/XF86Config-4 \ - /var/cron/tabs/* \ - /var/files \ - /root/.profile \ - /boot/*.bmp \ - /boot/loader.conf \ - /boot/device.hints ; do - cp -p ${f} ${DESTDIR}${f} - done -} - -# -# Everything else you want to tune in the new system. -# NOTE: Do not install too many binaries here. With the old system running and -# the new binaries and headers installed you are likely to run into bootstrap -# problems. Ports should be compiled after you have booted in the new system. -# -all_remaining_customization () { - # Without the compat symlink the linux_base files end up on the root fs: - cd ${DESTDIR} - mkdir -m 755 usr/compat; chown root:wheel usr/compat; ln -s usr/compat - mkdir -m 755 usr/compat/linux; chown root:wheel usr/compat/linux - mkdir -m 555 usr/compat/linux/proc; chown root:wheel usr/compat/linux/proc - mkdir -m 755 boot/grub; chown root:wheel boot/grub - mkdir -m 755 linux 2k; chown root:wheel linux 2k - mkdir -m 755 src; chown root:wheel src - mkdir -m 755 share; chown root:wheel share - mkdir -m 755 dvd cdrom flash; chown root:wheel dvd cdrom flash - mkdir -m 755 home; chown root:wheel home - mkdir -m 755 usr/ports; chown root:wheel usr/ports - - # My personal preference is to symlink tmp -> var/tmp. Optional. - cd ${DESTDIR}; rmdir tmp; ln -s var/tmp - - # Make spooldirs for the printers in my /etc/printcap. - cd ${DESTDIR}/var/spool/output/lpd; mkdir -p as od ev te lp da - touch ${DESTDIR}/var/log/lpd-errs - - # If you do not have /home on a shared partition, you may want to copy it: - # mkdir -p ${DESTDIR}/home - # cd /home; tar cf - . | (cd ${DESTDIR}/home; tar xpvf -) - - case ${REVISION} in - 4.*) - # 4.x without devfs: create non-standard devices to match your hardware. - cd ${DESTDIR}/dev - ./MAKEDEV all - ./MAKEDEV da0 da0s1h da0s2h da0s3h da0s4h - ./MAKEDEV da1 da1s1h da1s2h da1s3h da1s4h - ./MAKEDEV da2 da2s1h da2s2h da2s3h da2s4h - ./MAKEDEV da3 da3s1h da3s2h da3s3h da3s4h - ./MAKEDEV bktr0 cd1 - if test -d /dev/vinum; then - # 'vinum makedev' can only create devices in /dev, thus use cpio. - cd /dev; find vinum -print | cpio -pv ${DESTDIR}/dev - fi - - # Make the floppy group wheel writable. - chown root:wheel ${DESTDIR}/dev/fd0* - chmod g+w ${DESTDIR}/dev/fd0* - ;; - - 5.*) - # Make the floppy group wheel writable. - printf '%s\n' 'own fd0 root:wheel' >> ${DESTDIR}/etc/devfs.conf - printf '%s\n' 'perm fd0 0660' >> ${DESTDIR}/etc/devfs.conf - ;; - - *) - printf '%s\n' "REVISION ${REVISION} not supported" - exit 1 - ;; - - esac -} - -# vim: tabstop=2:expandtab:shiftwidth=2:syntax=sh: -# EOF $RCSfile: stage_1.conf.default,v $ diff --git a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_1.sh b/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_1.sh deleted file mode 100644 index d4f8e65f62..0000000000 --- a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_1.sh +++ /dev/null @@ -1,167 +0,0 @@ -#!/bin/sh -# -# stage_1.sh - FreeBSD From Scratch, Stage 1: System Installation. -# Usage: ./stage_1.sh profile -# will read ./stage_1.conf.profile -# and write ./stage_1.log.profile -# -# Author: Jens Schweikhardt -# $Id: stage_1.sh,v 1.5 2004-07-19 21:02:26 schweikh Exp $ -# $FreeBSD$ - -PATH=/bin:/usr/bin:/sbin:/usr/sbin - -# Prerequisites: -# -# a) Successfully completed "make buildworld" and "make buildkernel" -# b) Unused partitions (at least one for the root fs, probably more for -# the new /usr and /var, to your liking.) -# c) A customized stage_1.conf.profile file. - -if test $# -ne 1; then - echo "usage: stage_1.sh profile" 1>&2 - exit 1 -fi - -# ---------------------------------------------------------------------------- # -# Step 1: Create an empty directory tree below $DESTDIR. -# ---------------------------------------------------------------------------- # - -step_one () { - create_file_systems - # Now create all the other directories. Mandatory. - cd ${SRC}/etc; make distrib-dirs DESTDIR=${DESTDIR} -} - -# ---------------------------------------------------------------------------- # -# Step 2: Fill the empty /etc directory tree and put a few files in /. -# ---------------------------------------------------------------------------- # - -step_two () { - copy_files - - # Delete mergemaster's temproot, if any. - TEMPROOT=/var/tmp/temproot.stage1 - if test -d ${TEMPROOT}; then - chflags -R 0 ${TEMPROOT} - rm -rf ${TEMPROOT} - fi - export MAKEDEVPATH="/bin:/sbin:/usr/bin" - mergemaster -i -m ${SRC}/etc -t ${TEMPROOT} -D ${DESTDIR} - cap_mkdb ${DESTDIR}/etc/login.conf - pwd_mkdb -d ${DESTDIR}/etc -p ${DESTDIR}/etc/master.passwd - - # Mergemaster does not create empty files, e.g. in /var/log. Do so now, - # but do not clobber files that may have been copied with copy_files. - cd ${TEMPROOT} - find . -type f | sed 's,^\./,,' | - while read f; do - if test -r ${DESTDIR}/${f}; then - echo "${DESTDIR}/${f} already exists; not copied" - else - echo "Creating empty ${DESTDIR}/${f}" - cp -p ${f} ${DESTDIR}/${f} - fi - done - chflags -R 0 ${TEMPROOT} - rm -rf ${TEMPROOT} -} - -# ---------------------------------------------------------------------------- # -# Step 3: Install world. -# ---------------------------------------------------------------------------- # - -step_three () { - cd ${SRC} - make installworld DESTDIR=${DESTDIR} - # Install additional compatibility libraries (optional). Use this if you - # have programs dynamically linked against libc.so.4, i.e. if you see - # /usr/libexec/ld-elf.so.1: Shared object "libc.so.4" not found - cd lib/compat/compat4x.i386 - make all install DESTDIR=${DESTDIR} -} - -# ---------------------------------------------------------------------------- # -# Step 4: Install kernel and modules. -# ---------------------------------------------------------------------------- # - -step_four () { - cd ${SRC} - # The loader.conf and device.hints are required by the installkernel target. - # If you have not copied them in Step 2, cp them as shown in the next 2 lines. - # cp sys/boot/forth/loader.conf ${DESTDIR}/boot/defaults - # cp sys/i386/conf/GENERIC.hints ${DESTDIR}/boot/device.hints - make installkernel DESTDIR=${DESTDIR} KERNCONF=${KERNCONF} -} - -# ---------------------------------------------------------------------------- # -# Step 5: Install /etc/fstab and time zone info. -# ---------------------------------------------------------------------------- # - -step_five () { - create_etc_fstab - - # Setup time zone info; pretty much mandatory. - cp ${DESTDIR}/usr/share/zoneinfo/${TIMEZONE} ${DESTDIR}/etc/localtime - if test -r /etc/wall_cmos_clock; then - cp -p /etc/wall_cmos_clock ${DESTDIR}/etc/wall_cmos_clock - fi -} - -# ---------------------------------------------------------------------------- # -# Step 6: All remaining customization. -# ---------------------------------------------------------------------------- # - -step_six () { - all_remaining_customization -} - -do_steps () { - echo "PROFILE=${PROFILE}" - echo "DESTDIR=${DESTDIR}" - echo "SRC=${SRC}" - echo "KERNCONF=${KERNCONF}" - echo "TIMEZONE=${TIMEZONE}" - echo "TYPE=${TYPE}" - echo "REVISION=${REVISION}" - echo "BRANCH=${BRANCH}" - echo "RELDATE=${RELDATE}" - step_one - step_two - step_three - step_four - step_five - step_six -} - -# ---------------------------------------------------------------------------- # -# The ball starts rolling here. -# ---------------------------------------------------------------------------- # - -PROFILE="$1" -set -x -e -u # Stop for any error or use of an undefined variable. -. ./stage_1.conf.${PROFILE} - -# Determine a few variables from the sources that were used to make the -# world. The variables can be used to modify actions, e.g. depending on -# whether we install a 4.x or 5.x system. The __FreeBSD_version numbers -# for RELDATE are documented in the Porter's Handbook, -# doc/en_US.ISO8859-1/books/porters-handbook/freebsd-versions.html. -# Scheme is: <major><two digit minor><0 if release branch, otherwise 1>xx -# The result will be something like -# -# TYPE="FreeBSD" -# REVISION="4.9" -# BRANCH="RC" { "CURRENT", "STABLE", "RELEASE" } -# RELDATE="502101" -# -eval $(awk '/^(TYPE|REVISION|BRANCH)=/' ${SRC}/sys/conf/newvers.sh) -RELDATE=$(awk '/^[ \t]*#[ \t]*define[ \t][ \t]*__FreeBSD_version[ \t]/ { - print $3 - }' ${SRC}/sys/sys/param.h) - -echo "=> Logging to stage_1.log.${PROFILE}" -do_steps 2>&1 | tee stage_1.log.${PROFILE} - -# vim: tabstop=2:expandtab:shiftwidth=2: -# EOF $RCSfile: stage_1.sh,v $ diff --git a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_2.conf.default b/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_2.conf.default deleted file mode 100644 index 173b5650c8..0000000000 --- a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_2.conf.default +++ /dev/null @@ -1,85 +0,0 @@ -# vim: syntax=sh -# $Id: stage_2.conf.default,v 1.3 2004-07-19 20:42:13 schweikh Exp $ -# $FreeBSD$ -shells zsh -devel gettext make BATCH=yes install -lang perl5.8 make install; use.perl port -archivers unzip -archivers zip -security sudo -x11-servers XFree86-4-Server -x11 wrapper -x11 XFree86-4-clients -x11 XFree86-4-documents -x11-fonts XFree86-4-font75dpi -x11-fonts XFree86-4-font100dpi -x11-fonts XFree86-4-fontScalable -x11-fonts urwfonts -x11-fonts webfonts make WITH_NETSCAPE_ALIASES=yes install -x11-toolkits open-motif -x11-wm ctwm -security openssh-askpass -astro xplanet -astro xephem -editors vim -print ghostscript-gnu make A4=yes BATCH=yes install -print psutils-a4 -print a2ps-a4 -print gv -print acroread5 -print transfig -print teTeX -# NOTE: jdk14 needs linprocfs(5) mounted or it will hang indefinitely. -java linux-sun-jdk14 mount -a linproc; yes | make install -java jdk14 mount -a linproc; make -DNODEBUG install -www apache2 -www weblint -www amaya -www firefox make BATCH=yes install -www mozilla make WITHOUT_MAILNEWS=yes WITHOUT_COMPOSER=yes WITHOUT_LDAP=yes WITHOUT_CHATZILLA=yes WITHOUT_XMLTERM=yes install -www checkbot -www privoxy -graphics xfig -graphics xv -multimedia xawtv -graphics graphviz -lang expect -lang gawk -lang TenDRA unset MAKEOBJDIRPREFIX; make install -news tin -net freebsd-uucp -net cvsup-without-gui -net pathchar make NO_CHECKSUM=yes install -ftp wget -textproc ispell -german ispell-neu -german ispell-alt -textproc docproj make JADETEX=no HAVE_MOTIF=yes BATCH=yes install < /dev/null -sysutils samefile -sysutils lsof -sysutils pstree -sysutils cdrtools -sysutils grub -sysutils smartmontools -sysutils vobcopy -devel ddd -devel gindent -devel ctags -devel ElectricFence -devel strace -devel perltidy -mail procmail make BATCH=yes install -mail metamail -mail mutt-devel -emulators mtools -sysutils portupgrade -news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" make install -misc figlet-fonts -security gpa -mail spamoracle -multimedia mplayer make WITHOUT_RUNTIME_CPUDETECTION=yes WITH_GUI=yes BATCH=yes install -multimedia mplayer-fonts -audio wavplay -games xmahjongg -games xdemineur -editors openoffice-1.1 diff --git a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_2.sh b/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_2.sh deleted file mode 100644 index 699c940353..0000000000 --- a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_2.sh +++ /dev/null @@ -1,131 +0,0 @@ -#!/bin/sh -# -# stage_2.sh - FreeBSD From Scratch, Stage 2: Ports Installation. -# Usage: ./stage_2.sh [-hnp] configname -# -# Author: Jens Schweikhardt -# $Id: stage_2.sh,v 1.5 2004-07-19 21:02:26 schweikh Exp $ -# $FreeBSD$ - -DBDIR="/var/db/pkg" -PORTS="/usr/ports" -: ${PACKAGES:=${PORTS}/packages} -LOGDIR="/home/root/setup/ports.log"; mkdir -p ${LOGDIR} -PKG_PATH="/cdrom/packages/All:/dvd/packages/All" -PKG= - -MYNAME="$(basename $0)" -usage () { - exec >&2 - echo "usage: ${MYNAME} [-hnp] configname" - echo "" - echo " Options:" - echo " -h Print this help text." - echo " -n Dryrun: just show what would be done." - echo " -p Install a precompiled package if one can be found." - echo "" - echo " The config file (stage_2.conf.configname) is a list of" - echo " ports to install with one entry per line. Each line" - echo " consists of two or three space separated fields:" - echo " category, port, and optionally a build command." - echo "" - exit 1 -} - -# Look for a package in these locations in sequence. -# Returns as soon as the first is found. Result on stdout. -# -# ${PORTS}/${CATEGORY}/${NAME} -# ${PACKAGES}/All -# ${PACKAGES}/${CATEGORY} -# ${PKG_PATH} -# -find_package () { - echo "${PORTS}/${CATEGORY}/${NAME}:${PACKAGES}/All:${PACKAGES}/${CATEGORY}:${PKG_PATH}" | - tr : '\n' | - while read d; do - test -d "${d}" || continue - PKG=$(ls ${d}/${PKGNAME}.* 2>/dev/null) - test $? -eq 0 && echo "${PKG}" && return - done -} - -# -# Parse command line arguments. -# -args=`getopt hnp $*` -if test $? != 0; then - usage -fi -set -- $args -DRYRUN= -CHKPKG= -for i; do - case "$i" in - -n) DRYRUN="yes"; shift;; - -p) CHKPKG="yes"; shift;; - --) shift; break;; - *) usage;; - esac -done -if test $# -eq 1; then - DATAFILE="$1" -else - usage -fi - -# -# Loop over the ports list. -# -while read CATEGORY NAME CMD; do - case "${CATEGORY}" in - \#*) continue;; - '') continue;; - esac - DIR="${PORTS}/${CATEGORY}/${NAME}" - if ! test -d "${DIR}"; then - echo "$DIR does not exist -- ignored" - continue - fi - cd ${DIR} - PKGNAME=`make -V PKGNAME` - if test -n "${CHKPKG}"; then - PKG=$(find_package) - else - PKG="" - fi - if test -d "${DBDIR}/${PKGNAME}"; then - echo "${CATEGORY}/${NAME} already installed as ${PKGNAME}" - continue - fi - LOG="${LOGDIR}/${CATEGORY}+${NAME}" - echo "===> Installing ${CATEGORY}/${NAME}; logging to ${LOG}" - test -n "${CMD}" || CMD="make install BATCH=yes < /dev/null" - if test -n "${DRYRUN}"; then - if test -n "${PKG}"; then - echo pkg_add -v ${PKG} - else - echo "${CMD}" - fi - continue - fi - date "++++ Started %v %T +++" > ${LOG} - STARTED=$(date +%s) - ( - if test -n "${PKG}"; then - echo "Found package ${PKG}" - pkg_add -v ${PKG} - else - echo "CMD: ${CMD}" - make clean - eval "${CMD}" - make clean # Uncomment if diskspace is tight under ${PORTS}. - fi - ) 2>&1 | tee -a ${LOG} - FINISHED=$(date +%s) - DURATION=$(dc -e "${FINISHED} ${STARTED} - p") - date "++++ Finished %v %T after ${DURATION} secs +++" >> ${LOG} -done < stage_2.conf.${DATAFILE} - -# vim: tabstop=4: -# EOF $RCSfile: stage_2.sh,v $ diff --git a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_3.mk b/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_3.mk deleted file mode 100644 index 8715e96eba..0000000000 --- a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_3.mk +++ /dev/null @@ -1,231 +0,0 @@ -# stage_3.mk - FreeBSD From Scratch, Stage 3: Ports Post-Configuration. -# Usage: make -f stage_3.mk all (config everything) -# or make -f stage_3.mk target (to just config target) -# -# Author: Jens Schweikhardt -# -# It is a good idea to make sure any target can be made more than -# once without ill effect. -# -# $Id: stage_3.mk,v 1.4 2004-07-19 20:42:14 schweikh Exp $ -# $FreeBSD$ - -.POSIX: - -message: - @echo "Please use one of the following targets:" - @echo "config_apache" - @echo "config_firefox" - @echo "config_inn" - @echo "config_javaplugin" - @echo "config_nullplugin" - @echo "config_privoxy" - @echo "config_smartd" - @echo "config_sudo" - @echo "config_TeX" - @echo "config_tin" - @echo "config_uucp" - @echo "all -- all of the above" - - -all: \ - config_apache \ - config_firefox \ - config_inn \ - config_javaplugin \ - config_nullplugin \ - config_privoxy \ - config_smartd \ - config_sudo \ - config_TeX \ - config_tin \ - config_uucp - - -config_apache: - # 1. Modify httpd.conf. - perl -pi \ - -e 's/^\s*ServerAdmin.*/ServerAdmin schweikh\@schweikhardt.net/;' \ - -e 's/^\s*Listen.*/Listen 127.0.0.1:80/;' \ - -e 's/^\s*StartServers.*/StartServers 2/;' \ - -e 's/^\s*MinSpareServers.*/MinSpareServers 2/;' \ - -e 's,/usr/local/www/cgi-bin/,/home/opt/www/cgi-bin/,;' \ - /usr/local/etc/apache2/httpd.conf - # 2. Restore symlinks to web pages. - cd /usr/local/www/data; \ - ln -fs /home/schweikh/prj/homepage schweikhardt.net; \ - ln -fs /home/opt/www/test . - # Test if the httpd.conf has changed. - @if ! cmp -s /usr/local/etc/apache2/httpd.conf httpd.conf; then \ - echo "ATTENTION: the httpd.conf has changed. Please examine if"; \ - echo "the modifications are still correct. Here is the diff:"; \ - diff -u /usr/local/etc/apache2/httpd.conf httpd.conf; \ - fi - if test -f /var/run/httpd.pid; then \ - /usr/local/etc/rc.d/apache2.sh stop; \ - /usr/local/etc/rc.d/apache2.sh start; \ - else \ - /usr/local/etc/rc.d/apache2.sh start; \ - fi - -config_firefox: - # Make this group wheel writable to allow extensions being installed. - chmod -R g+w /usr/X11R6/lib/firefox/lib/mozilla-1.6/chrome - -config_inn: - pw usermod -n news -d /usr/local/news -s /bin/sh - mkdir -p /share/news/spool/outgoing \ - /share/news/spool/incoming \ - /share/news/spool/articles \ - /share/news/spool/overview \ - /share/news/spool/tmp \ - /share/news/db - chown -R news:news /share/news - # Give the news system its initial configuration. - cd /home/root/setup; \ - if test ! -f /share/news/db/active; then \ - echo "installing /share/news/db/active"; \ - install -C -o news -g news -m 664 active /share/news/db; \ - fi; \ - if test ! -f /share/news/db/newsgroups; then \ - echo "installing /share/news/db/newsgroups"; \ - install -C -o news -g news -m 664 newsgroups /share/news/db; \ - fi - # The innd.sh that comes with the port is broken, it - # checks for history.pag which does not exist. - cd /home/root/setup; \ - install -C -o root -g wheel -m 555 innd.sh /usr/local/etc/rc.d - # Configure storage method. - cd /home/root/setup; \ - printf "%s\n%s\n%s\n%s\n" \ - "method tradspool {" \ - " newsgroups: *" \ - " class: 0" \ - "}" \ - >storage.conf; \ - install -C -o news -g news -m 664 storage.conf /usr/local/news/etc - # Configure newsfeeds. - printf "%s\n%s\n" \ - "ME:*::" \ - "shuttle/news2.shuttle.de:!junk,!control:B32768/512,Tf,Wfb:" \ - >/usr/local/news/etc/newsfeeds - # Configure inn.conf. - perl -pi \ - -e 's/^#*\s*(organization:\s*).*/$$1"An Open Pod Bay Door"/;' \ - -e 's/^#*\s*(pathhost:\s*).*/$$1hal9000.schweikhardt.net/;' \ - -e 's/^#*\s*(server:).*/$$1 localhost/;' \ - -e 's/^#*\s*(domain:).*/$$1 schweikhardt.net/;' \ - -e 's/^#*\s*(fromhost:).*/$$1 schweikhardt.net/;' \ - -e 's,^#*\s*(moderatormailer:).*,$$1 \%s\@moderators.isc.org,;' \ - -e 's,^#*\s*(pathdb:\s*).*,$$1/share/news/db,;' \ - -e 's,/usr/local/news/spool,/share/news/spool,;' \ - /usr/local/news/etc/inn.conf - # Create empty history, if none there. - # See post-install in /usr/ports/news/inn-stable/Makefile. - cd /share/news/db; \ - if test ! -f history; then \ - touch history; \ - chmod 644 history; \ - chown news:news history; \ - su -fm news -c "/usr/local/news/bin/makedbz -i"; \ - for s in dir hash index; do \ - mv history.n.$${s} history.$${s}; \ - done; \ - fi - # Configure send-uucp. - echo shuttle:shuttle >/usr/local/news/etc/send-uucp.cf - # Satisfy inncheck: - cd /usr/local/news/etc; \ - chown news:news *; \ - chmod 640 control.ctl expire.ctl nntpsend.ctl readers.conf - /usr/local/news/bin/inncheck - # Test if the inn.conf has changed. - @if ! cmp -s /usr/local/news/etc/inn.conf inn.conf; then \ - echo "ATTENTION: the inn.conf has changed. Please examine if"; \ - echo "the modifications are still correct. Here is the diff:"; \ - diff -u /usr/local/news/etc/inn.conf inn.conf; \ - fi - if ! test -f /usr/local/news/run/innd.pid; then \ - /usr/local/etc/rc.d/innd.sh start; \ - fi - -config_javaplugin: - # Mozilla Firefox: - cd /usr/X11R6/lib/firefox/lib/mozilla-1.6/plugins; \ - ln -fs /usr/local/jdk1.4.2/jre/plugin/i386/ns610/libjavaplugin_oji.so - # Plain Mozilla: - #cd /usr/X11R6/lib/mozilla/plugins; \ - #ln -fs /usr/local/jdk1.4.2/jre/plugin/i386/ns610/libjavaplugin_oji.so - -# Move the nullplugin out of the way. With a .mozilla/*/*/prefs.js entry of -# user_pref("plugin.display_plugin_downloader_dialog", false); -# this suppresses popup dialogs for unavailable plugins (flash, ...) -config_nullplugin: - find /usr/X11R6/lib -name libnullplugin.so -exec mv {} {}.orig \; - -config_privoxy: - install -C -o root -g wheel -m 644 conf/privoxy/config \ - /usr/local/etc/privoxy - install -C -o root -g wheel -m 755 conf/privoxy/privoxy.sh \ - /usr/local/etc/rc.d - /usr/local/etc/rc.d/privoxy.sh restart - -config_smartd: - cp smartd.sh /usr/local/etc/rc.d/smartd.sh - cp smartd.conf /usr/local/etc/smartd.conf - -config_sudo: - if ! grep -q schweikh /usr/local/etc/sudoers; then \ - echo 'schweikh ALL = (ALL) NOPASSWD: ALL' >> /usr/local/etc/sudoers; \ - fi - -config_TeX: - # textproc/docproj advises: to typeset the FreeBSD Handbook with JadeTeX, - # change the following settings to the listed values: - perl -pi \ - -e 's/^% original texmf.cnf/% texmf.cnf/;' \ - -e 's/^(hash_extra\s*=\s*).*/$${1}60000/;' \ - -e 's/^(pool_size\s*=\s*).*/$${1}1000000/;' \ - -e 's/^(max_strings\s*=\s*).*/$${1}70000/;' \ - -e 's/^(save_size\s*=\s*).*/$${1}10000/;' \ - /usr/local/share/texmf/web2c/texmf.cnf - # Test if the texmf.cnf has changed. - @if ! cmp -s /usr/local/share/texmf/web2c/texmf.cnf texmf.cnf; then \ - echo "ATTENTION: the texmf.cnf has changed. Please examine if"; \ - echo "the modifications are still correct. Here is the diff:"; \ - diff -u /usr/local/share/texmf/web2c/texmf.cnf texmf.cnf; \ - fi - -config_tin: - # Point tin to our files. - printf "%s\n%s\n%s\n" \ - "activefile=/share/news/db/active" \ - "newsgroupsfile=/share/news/db/newsgroups" \ - "spooldir=/share/news/spool/articles" \ - >/usr/local/etc/tin.defaults - -config_uucp: - cd /etc/mail; make install SENDMAIL_MC=/etc/mail/hal9000.mc - # Make the uucp user's shell the correct uucico, so su(1) works. - chpass -s /usr/local/libexec/uucp/uucico uucp - # UUCP expects to find /usr/bin/rnews. - cd /usr/bin; ln -fs ../local/news/bin/rnews . - # Actual UUCP configuration. - echo nodename js2015 > /usr/local/etc/uucp/config - echo shuttle js2015 `cat uucp` > /usr/local/etc/uucp/call - printf 'port tcp\ntype tcp\n' > /usr/local/etc/uucp/port - printf "%s\n%s\n%s\n%s\n%s\n%s\n%s\n" \ - "call-login *" \ - "call-password *" \ - "time any" \ - "system shuttle" \ - "address mail.s.shuttle.de" \ - "commands rmail rnews" \ - "port tcp" \ - >/usr/local/etc/uucp/sys - cd /usr/local/etc/uucp; chown uucp:uucp *; chmod o-rwx * - # Trigger uucico after booting. - mkdir -p /usr/local/etc/rc.d; cp uucp.sh /usr/local/etc/rc.d - -# vim: tabstop=4: -# EOF $RCSfile: stage_3.mk,v $ diff --git a/en_US.ISO8859-1/articles/filtering-bridges/Makefile b/en_US.ISO8859-1/articles/filtering-bridges/Makefile deleted file mode 100644 index d9e00e9285..0000000000 --- a/en_US.ISO8859-1/articles/filtering-bridges/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Filtering Bridges - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/filtering-bridges/article.sgml b/en_US.ISO8859-1/articles/filtering-bridges/article.sgml deleted file mode 100644 index 123545c19e..0000000000 --- a/en_US.ISO8859-1/articles/filtering-bridges/article.sgml +++ /dev/null @@ -1,397 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Filtering Bridges</title> - - <authorgroup> - <author> - <firstname>Alex</firstname> - <surname>Dupre</surname> - <affiliation> - <address><email>ale@FreeBSD.org</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.3com; - &tm-attrib.intel; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>Often it is useful to divide one physical network (like an - Ethernet) into two separate segments without having to create subnets, - and use a router to link them together. The device that connects the - two networks in this way is called a bridge. A FreeBSD system with - two network interfaces is enough in order to act as a bridge.</para> - - <para>A bridge works by scanning the addresses of <acronym>MAC</acronym> - level (Ethernet addresses) of the devices connected to each of its - network interfaces and then forwarding the traffic between the two - networks only if the source and the destination are on different - segments. Under many points of view a bridge is similar to an Ethernet - switch with only two ports.</para> - </abstract> - </articleinfo> - - <sect1 id="filtering-bridges-why"> - <title>Why use a filtering bridge?</title> - - <para>More and more frequently, thanks to the lowering costs of broad band - Internet connections (xDSL) and also because of the reduction of - available IPv4 addresses, many companies are connected to the Internet - 24 hours on 24 and with few (sometimes not even a power of 2) IP - addresses. In these situations it is often desirable to have a firewall - that filters incoming and outgoing traffic from and towards Internet, - but a packet filtering solution based on router may not be applicable, - either due to subnetting issues, the router is owned by the connectivity - supplier (<acronym>ISP</acronym>), or because it does not support such - functionalities. In these scenarios the use of a filtering bridge is - highly advised.</para> - - <para>A bridge-based firewall can be configured and inserted between the - xDSL router and your Ethernet hub/switch without any IP numbering - issues.</para> - </sect1> - - <sect1 id="filtering-bridges-how"> - <title>How to Install</title> - - <para>Adding bridge functionalities to a FreeBSD system is not difficult. - Since 4.5 release it is possible to load such functionalities as modules - instead of having to rebuild the kernel, simplifying the procedure a - great deal. In the following subsections I will explain both - installation ways.</para> - - <important> - <para><emphasis>Do not</emphasis> follow both instructions: a procedure - <emphasis>excludes</emphasis> the other one. Select the best choice - according to your needs and abilities.</para> - </important> - - <para>Before going on, be sure to have at least two Ethernet cards that - support the promiscuous mode for both reception and transmission, since - they must be able to send Ethernet packets with any address, not just - their own. Moreover, to have a good throughput, the cards should be PCI - bus mastering cards. The best choices are still the Intel ðerexpress; - Pro, followed by the &tm.3com; 3c9xx series. To simplify the firewall - configuration it may be useful to have two cards of different - manufacturers (using different drivers) in order to distinguish clearly - which interface is connected to the router and which to the inner - network.</para> - - <sect2 id="filtering-bridges-kernel"> - <title>Kernel Configuration</title> - - <para>So you have decided to use the older but well tested installation - method. To begin, you have to add the following rows to your kernel - configuration file:</para> - - <programlisting>options BRIDGE -options IPFIREWALL -options IPFIREWALL_VERBOSE</programlisting> - - <para>The first line is to compile the bridge support, the second one is - the firewall and the third one is the logging functions of the - firewall.</para> - - <para>Now it is necessary to build and install the new kernel. You may - find detailed instructions in the <ulink - url="&url.books.handbook;/kernelconfig-building.html">Building - and Installing a Custom Kernel</ulink> section of the FreeBSD - Handbook.</para> - </sect2> - - <sect2 id="filtering-bridges-modules"> - <title>Modules Loading</title> - - <para>If you have chosen to use the new and simpler installation - method, the only thing to do now is add the following row to - <filename>/boot/loader.conf</filename>:</para> - - <programlisting>bridge_load="YES"</programlisting> - - <para>In this way, during the system startup, the - <filename>bridge.ko</filename> module will be loaded together with the - kernel. It is not required to add a similar row for the - <filename>ipfw.ko</filename> module, since it will be loaded - automatically after the execution of the steps in the following - section.</para> - </sect2> - </sect1> - - <sect1 id="filtering-bridges-finalprep"> - <title>Final Preparation</title> - - <para>Before rebooting in order to load the new kernel or the required - modules (according to the previously chosen installation method), you - have to make some changes to the <filename>/etc/rc.conf</filename> - configuration file. The default rule of the firewall is to reject all IP - packets. Initially we will set up an <option>open</option> firewall, in order to verify - its operation without any issue related to packet filtering (in case you - are going to execute this procedure remotely, such configuration will - avoid you to remain isolated from the network). Put these lines in - <filename>/etc/rc.conf</filename>:</para> - - <programlisting>firewall_enable="YES" -firewall_type="open" -firewall_quiet="YES" -firewall_logging="YES"</programlisting> - - <para>The first row will enable the firewall (and will load the module - <filename>ipfw.ko</filename> if it is not compiled in the kernel), the - second one to set up it in <option>open</option> mode (as explained in - <filename>/etc/rc.firewall</filename>), the third one to not show rules - loading and the fourth one to enable logging support.</para> - - <para>About the configuration of the network interfaces, the most used way - is to assign an IP to only one of the network cards, but the bridge will - work equally even if both interfaces or none has a configured IP. In the - last case (IP-less) the bridge machine will be still more hidden, as - inaccessible from the network: to configure it, you have to login from - console or through a third network interface separated from the bridge. - Sometimes, during the system startup, some programs require network - access, say for domain resolution: in this case it is necessary to - assign an IP to the external interface (the one connected to Internet, - where <acronym>DNS</acronym> server resides), since the bridge will be - activated at the end of the startup procedure. It means that the - <devicename>fxp0</devicename> interface (in our case) must be mentioned - in the ifconfig section of the <filename>/etc/rc.conf</filename> file, - while the <devicename>xl0</devicename> is not. Assigning an IP to both - the network cards does not make much sense, unless, during the start - procedure, applications should access to services on both Ethernet - segments.</para> - - <para>There is another important thing to know. When running IP over - Ethernet, there are actually two Ethernet protocols in use: one is IP, - the other is <acronym>ARP</acronym>. <acronym>ARP</acronym> does the - conversion of the IP address of a host into its Ethernet address - (<acronym>MAC</acronym> layer). In order to allow the communication - between two hosts separated by the bridge, it is necessary that the - bridge will forward <acronym>ARP</acronym> packets. Such protocol is not - included in the IP layer, since it exists only with IP over Ethernet. - The FreeBSD firewall filters exclusively on the IP layer and therefore - all non-IP packets (<acronym>ARP</acronym> included) will be forwarded - without being filtered, even if the firewall is configured to not permit - anything.</para> - - <para>Now it is time to reboot the system and use it as before: there will - be some new messages about the bridge and the firewall, but the bridge - will not be activated and the firewall, being in <option>open</option> mode, will not - avoid any operations.</para> - - <para>If there are any problems, you should sort them out now - before proceeding.</para> - </sect1> - - <sect1 id="filtering-bridges-enabling"> - <title>Enabling the Bridge</title> - - <para>At this point, to enable the bridge, you have to execute the - following commands (having the shrewdness to replace the names of the - two network interfaces <devicename>fxp0</devicename> and - <devicename>xl0</devicename> with your own ones):</para> - - <screen>&prompt.root; <userinput>sysctl net.link.ether.bridge.config=fxp0:0,xl0:0</userinput> -&prompt.root; <userinput>sysctl net.link.ether.bridge.ipfw=1</userinput> -&prompt.root; <userinput>sysctl net.link.ether.bridge.enable=1</userinput></screen> - - <para>The first row specifies which interfaces should be activated by the - bridge, the second one will enable the firewall on the bridge and - finally the third one will enable the bridge.</para> - - <note> - <para>If you have &os; 5.1-RELEASE or previous the sysctl variables - are spelled differently. See &man.bridge.4; for details.</para> - </note> - - <para>At this point you should be able to insert the machine between two - sets of hosts without compromising any communication abilities between - them. If so, the next step is to add the - <literal>net.link.ether.bridge.<replaceable>[blah]</replaceable>=<replaceable>[blah]</replaceable></literal> - portions of these rows to the <filename>/etc/sysctl.conf</filename> - file, in order to have them execute at startup.</para> - </sect1> - - <sect1 id="filtering-bridges-ipfirewall"> - <title>Configuring The Firewall</title> - - <para>Now it is time to create your own file with custom firewall rules, - in order to secure the inside network. There will be some complication - in doing this because not all of the firewall functionalities are - available on bridged packets. Furthermore, there is a difference between - the packets that are in the process of being forwarded and packets that - are being received by the local machine. In general, incoming packets - are run through the firewall only once, not twice as is normally the - case; in fact they are filtered only upon receipt, so rules that use - <option>out</option> or <option>xmit</option> will never match. Personally, I use <option>in via</option> which is an - older syntax, but one that has a sense when you read it. Another - limitation is that you are restricted to use only <option>pass</option> or <option>drop</option> - commands for packets filtered by a bridge. Sophisticated things like - <option>divert</option>, <option>forward</option> or <option>reject</option> are not available. Such options can - still be used, but only on traffic to or from the bridge machine itself - (if it has an IP address).</para> - - <para>New in FreeBSD 4.0, is the concept of stateful filtering. This is a - big improvement for <acronym>UDP</acronym> traffic, which typically is a - request going out, followed shortly thereafter by a response with the - exact same set of IP addresses and port numbers (but with source and - destination reversed, of course). For firewalls that have no - statekeeping, there is almost no way to deal with this sort of traffic - as a single session. But with a firewall that can <quote>remember</quote> an outgoing - <acronym>UDP</acronym> packet and, for the next few minutes, allow a - response, handling <acronym>UDP</acronym> services is trivial. The - following example shows how to do it. It is possible to do the same thing - with <acronym>TCP</acronym> packets. This allows you to avoid some - denial of service attacks and other nasty tricks, but it also typically - makes your state table grow quickly in size.</para> - - <para>Let's look at an example setup. Note first that at the top of - <filename>/etc/rc.firewall</filename> there are already standard rules - for the loopback interface <devicename>lo0</devicename>, so we should not - have to care for them anymore. Custom rules should be put in a separate - file (say <filename>/etc/rc.firewall.local</filename>) and loaded at - system startup, by modifying the row of - <filename>/etc/rc.conf</filename> where we defined the <option>open</option> - firewall:</para> - - <programlisting>firewall_type="/etc/rc.firewall.local"</programlisting> - - <important> - <para>You have to specify the <emphasis>full</emphasis> path, otherwise - it will not be loaded with the risk to remain isolated from the - network.</para> - </important> - - <para>For our example imagine to have the <devicename>fxp0</devicename> - interface connected towards the outside (Internet) and the - <devicename>xl0</devicename> towards the inside - (<acronym>LAN</acronym>). The bridge machine has the IP <hostid - role="ipaddr">1.2.3.4</hostid> (it is not possible that your - <acronym>ISP</acronym> can give you a class A address like this, but for - our example it is good).</para> - - <programlisting># Things that we have kept state on before get to go through in a hurry -add check-state - -# Throw away RFC 1918 networks -add drop all from 10.0.0.0/8 to any in via fxp0 -add drop all from 172.16.0.0/12 to any in via fxp0 -add drop all from 192.168.0.0/16 to any in via fxp0 - -# Allow the bridge machine to say anything it wants -# (if the machine is IP-less do not include these rows) -add pass tcp from 1.2.3.4 to any setup keep-state -add pass udp from 1.2.3.4 to any keep-state -add pass ip from 1.2.3.4 to any - -# Allow the inside hosts to say anything they want -add pass tcp from any to any in via xl0 setup keep-state -add pass udp from any to any in via xl0 keep-state -add pass ip from any to any in via xl0 - -# TCP section -# Allow SSH -add pass tcp from any to any 22 in via fxp0 setup keep-state -# Allow SMTP only towards the mail server -add pass tcp from any to relay 25 in via fxp0 setup keep-state -# Allow zone transfers only by the slave name server [dns2.nic.it] -add pass tcp from 193.205.245.8 to ns 53 in via fxp0 setup keep-state -# Pass ident probes. It is better than waiting for them to timeout -add pass tcp from any to any 113 in via fxp0 setup keep-state -# Pass the "quarantine" range -add pass tcp from any to any 49152-65535 in via fxp0 setup keep-state - -# UDP section -# Allow DNS only towards the name server -add pass udp from any to ns 53 in via fxp0 keep-state -# Pass the "quarantine" range -add pass udp from any to any 49152-65535 in via fxp0 keep-state - -# ICMP section -# Pass 'ping' -add pass icmp from any to any icmptypes 8 keep-state -# Pass error messages generated by 'traceroute' -add pass icmp from any to any icmptypes 3 -add pass icmp from any to any icmptypes 11 - -# Everything else is suspect -add drop log all from any to any</programlisting> - - <para>Those of you who have set up firewalls before may notice some things - missing. In particular, there are no anti-spoofing rules, in fact we did - <emphasis>not</emphasis> add:</para> - - <programlisting>add deny all from 1.2.3.4/8 to any in via fxp0</programlisting> - - <para>That is, drop packets that are coming in from the outside claiming - to be from our network. This is something that you would commonly do to - be sure that someone does not try to evade the packet filter, by - generating nefarious packets that look like they are from the inside. - The problem with that is that there is <emphasis>at least</emphasis> one - host on the outside interface that you do not want to ignore: the - router. But usually, the <acronym>ISP</acronym> anti-spoofs at their - router, so we do not need to bother that much.</para> - - <para>The last rule seems to be an exact duplicate of the default rule, - that is, do not let anything pass that is not specifically allowed. But - there is a difference: all suspected traffic will be logged.</para> - - <para>There are two rules for passing <acronym>SMTP</acronym> and - <acronym>DNS</acronym> traffic towards the mail server and the name - server, if you have them. Obviously the whole rule set should be - flavored to personal taste, this is only a specific example (rule format - is described accurately in the &man.ipfw.8; man page). Note that in - order for <quote>relay</quote> and <quote>ns</quote> to work, name service lookups must work - <emphasis>before</emphasis> the bridge is enabled. This is an example of - making sure that you set the IP on the correct network card. - Alternatively it is possible to specify the IP address instead of the - host name (required if the machine is IP-less).</para> - - <para>People that are used to setting up firewalls are probably also used - to either having a <option>reset</option> or a <option>forward</option> rule for ident packets - (<acronym>TCP</acronym> port 113). Unfortunately, this is not an - applicable option with the bridge, so the best thing is to simply pass - them to their destination. As long as that destination machine is not - running an ident daemon, this is relatively harmless. The alternative is - dropping connections on port 113, which creates some problems with - services like <acronym>IRC</acronym> (the ident probe must - timeout).</para> - - <para>The only other thing that is a little weird that you may have - noticed is that there is a rule to let the bridge machine speak, and - another for internal hosts. Remember that this is because the two sets - of traffic will take different paths through the kernel and into the - packet filter. The inside net will go through the bridge, while the - local machine will use the normal IP stack to speak. Thus the two rules - to handle the different cases. The <literal>in via - <devicename>fxp0</devicename></literal> rules work for both paths. In general, if - you use <option>in via</option> rules throughout the filter, you will need to make an - exception for locally generated packets, because they did not come in - via any of our interfaces.</para> - </sect1> - - <sect1 id="filtering-bridges-contributors"> - <title>Contributors</title> - - <para>Many parts of this article have been taken, updated and adapted from - an old text about bridging, edited by Nick Sayer. A pair of inspirations - are due to an introduction on bridging by Steve Peterson.</para> - - <para>A big thanks to Luigi Rizzo for the implementation of the bridge - code in FreeBSD and for the time he has dedicated to me answering all of - my related questions.</para> - - <para>A thanks goes out also to Tom Rhodes who looked over my job of - translation from Italian (the original language of this article) into - English.</para> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/fonts/Makefile b/en_US.ISO8859-1/articles/fonts/Makefile deleted file mode 100644 index 0163a287fa..0000000000 --- a/en_US.ISO8859-1/articles/fonts/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Fonts and FreeBSD - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/fonts/article.sgml b/en_US.ISO8859-1/articles/fonts/article.sgml deleted file mode 100644 index 6130925e28..0000000000 --- a/en_US.ISO8859-1/articles/fonts/article.sgml +++ /dev/null @@ -1,979 +0,0 @@ -<!-- $FreeBSD$ --> -<!-- The FreeBSD Documentation Project --> -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<!-- Recently, I wanted to figure out how to use some additional fonts that - I had accumulated. I finally figured out *how to do it* from the various - manual pages and documentation. Since it might be of use to other users, - and I didn't see any reference to this topic in the FAQ or handbook, I - thought I'd try my hand at a simple cookbook tutorial addressing the - use of fonts. I have included my unanswered questions at the end of - the document. - - Anyway, here's what I put together. This is my present understanding of - fonts and how to use them with FreeBSD. I am sure that there are errors or - misunderstandings, but it contains enough valid information to allow the - use of additional fonts with Ghostscript, X11 and Groff. This is my first - attempt to write anything along the lines of a tutorial/FAQ, so I am sure - it is pretty raw. There are probably better ways to do some of this stuff, - and I would welcome being corrected. - --> - -<!-- The section "Setting a virtual console to 80x60 line mode" was - updated to reflect changes in FreeBSD system configuration - files by Mark Ovens <mark@ukug.uk.FreeBSD.org> 27/5/00 - --> - -<article> - <articleinfo> - <title>Fonts and FreeBSD</title> - - <subtitle>A Tutorial</subtitle> - - <authorgroup> - <author> - <firstname>Dave</firstname> - - <surname>Bodenstab</surname> - - <affiliation> - <address> - <email>imdave@synet.net</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>Wed Aug 7, 1996</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.adobe; - &tm-attrib.apple; - &tm-attrib.linux; - &tm-attrib.microsoft; - &tm-attrib.opengroup; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This document contains a description of the various font - files that may be used with FreeBSD and the syscons driver, - X11, Ghostscript and Groff. Cookbook examples are provided - for switching the syscons display to 80x60 mode, and for using - type 1 fonts with the above application programs.</para> - </abstract> - </articleinfo> - - <sect1> - <title>Introduction</title> - - <para>There are many sources of fonts available, and one might ask - how they might be used with FreeBSD. The answer can be found by - carefully searching the documentation for the component that one - would like to use. This is very time consuming, so this - tutorial is an attempt to provide a shortcut for others who - might be interested.</para> - </sect1> - - <sect1> - <title>Basic terminology</title> - - <para>There are many different font formats and associated font - file suffixes. A few that will be addressed here are:</para> - - <variablelist> - <varlistentry> - <term><filename>.pfa</filename>, <filename>.pfb</filename></term> - - <listitem> - <para>&postscript; type 1 fonts. The - <filename>.pfa</filename> is the - <emphasis>A</emphasis>scii form and - <filename>.pfb</filename> the <emphasis>B</emphasis>inary - form.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.afm</filename></term> - - <listitem> - <para>The font metrics associated with a type 1 font.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.pfm</filename></term> - - <listitem> - <para>The printer font metrics associated with a type 1 - font.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.ttf</filename></term> - - <listitem> - <para>A &truetype; font</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.fot</filename></term> - - <listitem> - <para>An indirect reference to a TrueType font (not an - actual font)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.fon</filename>, <filename>.fnt</filename></term> - - <listitem> - <para>Bitmapped screen fonts</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The <filename>.fot</filename> file is used by &windows; as - sort of a symbolic link to the actual &truetype; font - (<filename>.ttf</filename>) file. The <filename>.fon</filename> - font files are also used by Windows. I know of no way to use - this font format with FreeBSD.</para> - </sect1> - - <sect1> - <title>What font formats can I use?</title> - - <para>Which font file format is useful depends on the application - being used. FreeBSD by itself uses no fonts. Application - programs and/or drivers may make use of the font files. Here is - a small cross reference of application/driver to the font type - suffixes:</para> - - <variablelist> - <varlistentry> - <term>Driver</term> - - <listitem> - <variablelist> - <varlistentry> - <term>syscons</term> - - <listitem> - <para><filename>.fnt</filename></para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term>Application</term> - - <listitem> - <variablelist> - <varlistentry> - <term>Ghostscript</term> - - <listitem> - <para><filename>.pfa</filename>, - <filename>.pfb</filename>, - <filename>.ttf</filename></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>X11</term> - - <listitem> - <para><filename>.pfa</filename>, - <filename>.pfb</filename></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Groff</term> - - <listitem> - <para><filename>.pfa</filename>, - <filename>.afm</filename></para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Povray</term> - - <listitem> - <para><filename>.ttf</filename></para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> - - <para>The <filename>.fnt</filename> suffix is used quite - frequently. I suspect that whenever someone wanted to create a - specialized font file for their application, more often than not - they chose this suffix. Therefore, it is likely that files with - this suffix are not all the same format; specifically, the - <filename>.fnt</filename> files used by syscons under FreeBSD - may not be the same format as a <filename>.fnt</filename> file - one encounters in the &ms-dos;/&windows; environment. I have not - made any attempt at using other <filename>.fnt</filename> files - other than those provided with FreeBSD.</para> - </sect1> - - <sect1> - <title>Setting a virtual console to 80x60 line mode</title> - - <para>First, an 8x8 font must be loaded. To do this, - <filename>/etc/rc.conf</filename> should contain the - line (change the font name to an appropriate one for - your locale):</para> - - <informalexample> - <programlisting>font8x8="iso-8x8" # font 8x8 from /usr/share/syscons/fonts/* (or NO).</programlisting> - </informalexample> - - <para>The command to actually switch the mode is - &man.vidcontrol.1;:</para> - - <informalexample> - <screen>&prompt.user; <userinput>vidcontrol VGA_80x60</userinput></screen> - </informalexample> - - <para>Various screen-oriented programs, such as &man.vi.1;, must - be able to determine the current screen dimensions. As this is - achieved this through <command>ioctl</command> calls to the console - driver (such as &man.syscons.4;) they will correctly determine the new - screen dimensions.</para> - - <para>To make this more seamless, one can embed these commands in - the startup scripts so it takes place when the system boots. - To do this is add this line to <filename>/etc/rc.conf</filename> - </para> - - <informalexample> - <programlisting>allscreens_flags="VGA_80x60" # Set this vidcontrol mode for all virtual screens - </programlisting> - </informalexample> - - <para>References: &man.rc.conf.5;, &man.vidcontrol.1;.</para> - </sect1> - - <sect1> - <title>Using type 1 fonts with X11</title> - - <para>X11 can use either the <filename>.pfa</filename> or the - <filename>.pfb</filename> format fonts. The X11 fonts are - located in various subdirectories under - <filename>/usr/X11R6/lib/X11/fonts</filename>. Each font file - is cross referenced to its X11 name by the contents of the - <filename>fonts.dir</filename> file in each directory.</para> - - <para>There is already a directory named <filename>Type1</filename>. The - most straight forward way to add a new font is to put it into - this directory. A better way is to keep all new fonts in a - separate directory and use a symbolic link to the additional - font. This allows one to more easily keep track of ones fonts - without confusing them with the fonts that were originally - provided. For example:</para> - - <informalexample> - <screen><lineannotation>Create a directory to contain the font files</lineannotation> -&prompt.user; <userinput>mkdir -p /usr/local/share/fonts/type1</userinput> -&prompt.user; <userinput>cd /usr/local/share/fonts/type1</userinput> - -<lineannotation>Place the .pfa, .pfb and .afm files here</lineannotation> -<lineannotation>One might want to keep readme files, and other documentation</lineannotation> -<lineannotation>for the fonts here also</lineannotation> -&prompt.user; <userinput>cp /cdrom/fonts/atm/showboat/showboat.pfb .</userinput> -&prompt.user; <userinput>cp /cdrom/fonts/atm/showboat/showboat.afm .</userinput> - -<lineannotation>Maintain an index to cross reference the fonts</lineannotation> -&prompt.user; <userinput>echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX</userinput></screen> - </informalexample> - - <para>Now, to use a new font with X11, one must make the font file - available and update the font name files. The X11 font names - look like:</para> - - <informalexample> - <screen>-bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 - | | | | | | | | | | | | \ \ - | | | | | \ \ \ \ \ \ \ +----+- character set - | | | | \ \ \ \ \ \ \ +- average width - | | | | \ \ \ \ \ \ +- spacing - | | | \ \ \ \ \ \ +- vertical res. - | | | \ \ \ \ \ +- horizontal res. - | | | \ \ \ \ +- points - | | | \ \ \ +- pixels - | | | \ \ \ - foundry family weight slant width additional style</screen> - </informalexample> - - <para>A new name needs to be created for each new font. If you - have some information from the documentation that accompanied - the font, then it could serve as the basis for creating the - name. If there is no information, then you can get some idea by - using &man.strings.1; on the font file. For example:</para> - - <informalexample> - <screen>&prompt.user; <userinput>strings showboat.pfb | more</userinput> -%!FontType1-1.0: Showboat 001.001 -%%CreationDate: 1/15/91 5:16:03 PM -%%VMusage: 1024 45747 -% Generated by Fontographer 3.1 -% Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten. -FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup -/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse -{save true}{false}ifelse}{false}ifelse -12 dict begin -/FontInfo 9 dict dup begin - /version (001.001) readonly def - /FullName (Showboat) readonly def - /FamilyName (Showboat) readonly def - /Weight (Medium) readonly def - /ItalicAngle 0 def - /isFixedPitch false def - /UnderlinePosition -106 def - /UnderlineThickness 16 def - /Notice (Showboat - 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def -end readonly def -/FontName /Showboat def ---stdin--</screen> - </informalexample> - - <para>Using this information, a possible name might be:</para> - - <informalexample> - <screen>-type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1</screen> - </informalexample> - - <para>The components of our name are:</para> - - <variablelist> - <varlistentry> - <term>Foundry</term> - - <listitem> - <para>Lets just name all the new fonts - <literal>type1</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Family</term> - - <listitem> - <para>The name of the font.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Weight</term> - - <listitem> - <para>Normal, bold, medium, semibold, etc. From the - &man.strings.1; - output above, it appears that this font has a weight of - <emphasis>medium</emphasis>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Slant</term> - - <listitem> - <para><emphasis remap=bf>r</emphasis>oman, <emphasis - remap=bf>i</emphasis>talic, <emphasis - remap=bf>o</emphasis>blique, etc. Since the - <emphasis>ItalicAngle</emphasis> is zero, - <emphasis>roman</emphasis> will be used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Width</term> - - <listitem> - <para>Normal, wide, condensed, extended, etc. Until it can - be examined, the assumption will be - <emphasis>normal</emphasis>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Additional style</term> - - <listitem> - <para>Usually omitted, but this will indicate that the font - contains decorative capital letters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Spacing</term> - - <listitem> - <para>proportional or monospaced. - <emphasis>Proportional</emphasis> is used since - <emphasis>isFixedPitch</emphasis> is false.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>All of these names are arbitrary, but one should strive to - be compatible with the existing conventions. A font is - referenced by name with possible wild cards by an X11 program, - so the name chosen should make some sense. One might begin by - simply using - - <informalexample> - <screen>…-normal-r-normal-…-p-… - </screen> - </informalexample> - - as the name, and then use - &man.xfontsel.1; - to examine it and adjust the name based on the appearance of the - font.</para> - - <para>So, to complete our example:</para> - - <informalexample> - <screen><lineannotation>Make the font accessible to X11</lineannotation> -&prompt.user; <userinput>cd /usr/X11R6/lib/X11/fonts/Type1</userinput> -&prompt.user; <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</userinput> - -<lineannotation>Edit fonts.dir and fonts.scale, adding the line describing the font -and incrementing the number of fonts which is found on the first line.</lineannotation> -&prompt.user; <userinput>ex fonts.dir -:1p -25 -:1c -26 -. -:$a -showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 -. -:wq</userinput> - -<lineannotation><filename>fonts.scale</filename> seems to be identical to <filename>fonts.dir</filename>…</lineannotation> -&prompt.user; <userinput>cp fonts.dir fonts.scale</userinput> - -<lineannotation>Tell X11 that things have changed</lineannotation> -&prompt.user; <userinput>xset fp rehash</userinput> - -<lineannotation>Examine the new font</lineannotation> -&prompt.user; <userinput>xfontsel -pattern -type1-*</userinput></screen> - </informalexample> - - <para>References: &man.xfontsel.1;, &man.xset.1;, <citetitle>The X - Windows System in a Nutshell</citetitle>, <ulink - url="http://www.ora.com/">O'Reilly & - Associates</ulink>.</para> - </sect1> - - <sect1> - <title>Using type 1 fonts with Ghostscript</title> - - <para>Ghostscript references a font via its <filename>Fontmap</filename> - file. This must be modified in a similar way to the X11 - <filename>fonts.dir</filename> file. Ghostscript can use either - the <filename>.pfa</filename> or the <filename>.pfb</filename> - format fonts. Using the font from the previous example, here is - how to use it with Ghostscript:</para> - - <informalexample> - <screen><lineannotation>Put the font in Ghostscript's font directory</lineannotation> -&prompt.user; <userinput>cd /usr/local/share/ghostscript/fonts</userinput> -&prompt.user; <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</userinput> - -<lineannotation>Edit Fontmap so Ghostscript knows about the font</lineannotation> -&prompt.user; <userinput>cd /usr/local/share/ghostscript/4.01</userinput> -&prompt.user; <userinput>ex Fontmap -:$a -/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat -. -:wq</userinput> - -<lineannotation>Use Ghostscript to examine the font</lineannotation> -&prompt.user; <userinput>gs prfont.ps</userinput> -Aladdin Ghostscript 4.01 (1996-7-10) -Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights -reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... - /1899520 581354 1300084 13826 0 done. -GS><userinput>Showboat DoFont</userinput> -Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... - 1939688 565415 1300084 16901 0 done. ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< ->>showpage, press <return> to continue<< -GS><userinput>quit</userinput></screen> - </informalexample> - - <para>References: <filename>fonts.txt</filename> in the - Ghostscript 4.01 distribution</para> - </sect1> - - <sect1> - <title>Using type 1 fonts with Groff</title> - - <para>Now that the new font can be used by both X11 and - Ghostscript, how can one use the new font with groff? First of - all, since we are dealing with type 1 &postscript; fonts, the - groff device that is applicable is the <emphasis>ps</emphasis> - device. A font file must be created for each font that groff - can use. A groff font name is just a file in - <filename>/usr/share/groff_font/devps</filename>. With our - example, the font file could be - <filename>/usr/share/groff_font/devps/SHOWBOAT</filename>. The - file must be created using tools provided by groff.</para> - - <para>The first tool is <command>afmtodit</command>. This is not - normally installed, so it must be retrieved from the source - distribution. I found I had to change the first line of the - file, so I did:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp</userinput> -&prompt.user; <userinput>ex /tmp/afmtodit.pl -:1c -#!/usr/bin/perl -P- -. -:wq</userinput></screen> - </informalexample> - - <para>This tool will create the groff font file from the metrics - file (<filename>.afm</filename> suffix.) Continuing with our - example:</para> - - <informalexample> - <screen><lineannotation>Many <filename>.afm</filename> files are in Mac format… ^M delimited lines -We need to convert them to &unix; style ^J delimited lines</lineannotation> -&prompt.user; <userinput>cd /tmp</userinput> -&prompt.user; <userinput>cat /usr/local/share/fonts/type1/showboat.afm | - tr '\015' '\012' >showboat.afm</userinput> - -<lineannotation>Now create the groff font file</lineannotation> -&prompt.user; <userinput>cd /usr/share/groff_font/devps</userinput> -&prompt.user; <userinput>/tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT</userinput></screen> - </informalexample> - - <para>The font can now be referenced with the name - SHOWBOAT.</para> - - <para>If ghostscript is used to drive the printers on the system, - then nothing more needs to be done. However, if true PostScript - printers are used, then the font must be down loaded to the - printer in order for the font to be used (unless the printer - happens to have the showboat font built in or on an accessible - font disk.) The final step is to create a down loadable font. - The <command>pfbtops</command> tool is used to create the - <filename>.pfa</filename> format of the font, and the - <filename>download</filename> file is modified to reference the new - font. The <filename>download</filename> file must reference the - internal name of the font. This can easily be determined from - the groff font file as illustrated:</para> - - <informalexample> - <screen><lineannotation>Create the <filename>.pfa</filename> font file</lineannotation> -&prompt.user; <userinput>pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa</userinput></screen> - </informalexample> - - <para>Of course, if the <filename>.pfa</filename> file is already - available, just use a symbolic link to reference it.</para> - - <informalexample> - <screen><lineannotation>Get the internal font name</lineannotation> -&prompt.user; <userinput>fgrep internalname SHOWBOAT</userinput> -internalname Showboat - -<lineannotation>Tell groff that the font must be down loaded</lineannotation> -&prompt.user; <userinput>ex download -:$a -Showboat showboat.pfa -. -:wq</userinput></screen> - </informalexample> - - <para>To test the font:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cd /tmp</userinput> -&prompt.user; <userinput>cat >example.t <<EOF -.sp 5 -.ps 16 -This is an example of the Showboat font: -.br -.ps 48 -.vs (\n(.s+2)p -.sp -.ft SHOWBOAT -ABCDEFGHI -.br -JKLMNOPQR -.br -STUVWXYZ -.sp -.ps 16 -.vs (\n(.s+2)p -.fp 5 SHOWBOAT -.ft R -To use it for the first letter of a paragraph, it will look like: -.sp 50p -\s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the -showboat font as its first letter. -Additional vertical space must be used to allow room for the larger -letter. -EOF</userinput> -&prompt.user; <userinput>groff -Tps example.t >example.ps</userinput> - -<lineannotation>To use ghostscript/ghostview</lineannotation> -&prompt.user; <userinput>ghostview example.ps</userinput> - -<lineannotation>To print it</lineannotation> -&prompt.user; <userinput>lpr -Ppostscript example.ps</userinput></screen> - </informalexample> - - <para>References: - <filename>/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man</filename>, - &man.groff.font.5;, &man.groff.char.7;, &man.pfbtops.1;.</para> - </sect1> - - <sect1> - <title>Converting TrueType fonts to a groff/PostScript format for - groff</title> - - <para>This potentially requires a bit of work, simply because it - depends on some utilities that are not installed as part of the - base system. They are:</para> - - <variablelist> - <varlistentry> - <term><command>ttf2pf</command></term> - - <listitem> - <para>TrueType to PostScript conversion utilities. This - allows conversion of a TrueType font to an ascii font - metric (<filename>.afm</filename>) file.</para> - - <para>Currently available at <ulink - url="http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/"></ulink>. - Note: These files are PostScript programs and must be - downloaded to disk by holding down the - <keycap>Shift</keycap> key when clicking on the link. - Otherwise, your browser may try to launch - <application>ghostview</application> to view them.</para> - - <para>The files of interest are:</para> - - <itemizedlist> - <listitem> - <para><filename>GS_TTF.PS</filename></para> - </listitem> - - <listitem> - <para><filename>PF2AFM.PS</filename></para> - </listitem> - - <listitem> - <para><filename>ttf2pf.ps</filename></para> - </listitem> - </itemizedlist> - - <para>The funny upper/lower case is due to their being - intended also for DOS shells. - <filename>ttf2pf.ps</filename> makes use of the others as - upper case, so any renaming must be consistent with this. - (Actually, <filename>GS_TTF.PS</filename> and - <filename>PFS2AFM.PS</filename> are supposedly part of the - ghostscript distribution, but it is just as easy to use - these as an isolated utility. FreeBSD does not seem to - include the latter.) You also may want to have these - installed to - <filename>/usr/local/share/groff_font/devps</filename>(?).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>afmtodit</command></term> - - <listitem> - <para>Creates font files for use with groff from ascii font - metrics file. This usually resides in the directory, - <filename>/usr/src/contrib/groff/afmtodit</filename>, and - requires some work to get going.</para> - - <note> - <para> If you are paranoid about working in the - <filename>/usr/src</filename> tree, simply copy the - contents of the above directory to a work - location.</para> - </note> - - <para>In the work area, you will need to make the utility. - Just type:</para> - - <screen><prompt>#</prompt> <userinput>make -f Makefile.sub afmtodit</userinput> - </screen> - - <para>You may also need to copy - <filename>/usr/contrib/groff/devps/generate/textmap</filename> - to - <filename>/usr/share/groff_font/devps/generate</filename> - if it does not already exist.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Once all these utilities are in place, you are ready to - commence:</para> - - <orderedlist> - <listitem> - <para>Create the <filename>.afm</filename> file by - typing:</para> - - <screen><prompt>%</prompt> <userinput>gs <optional>-dNODISPLAY</optional> <optional>-q</optional> -- ttf2pf.ps <replaceable>TTF_name</replaceable> <optional><replaceable>PS_font_name</replaceable> <optional><replaceable>AFM_name</replaceable></optional></optional></userinput> - </screen> - - <para>Where, <replaceable>TTF_name</replaceable> is your - TrueType font file, <replaceable>PS_font_name</replaceable> - is the file name for the <filename>.pfa</filename> file, - <replaceable>AFM_name</replaceable> is the name you wish for - the <filename>.afm</filename> file. If you do not specify - output file names for the <filename>.pfa</filename> or - <filename>.afm</filename> files, then default names will be - generated from the TrueType font file name.</para> - - <para>This also produces a <filename>.pfa</filename> file, the - ascii PostScript font metrics file - (<filename>.pfb</filename> is for the binary form). This - will not be needed, but could (I think) be useful for a - fontserver.</para> - - <para>For example, to convert the 30f9 Barcode font using the - default file names, use the following command:</para> - - <screen><prompt>%</prompt> <userinput>gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf</userinput> -Aladdin Ghostscript 5.10 (1997-11-23) -Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Converting 3of9.ttf to 3of9.pfa and 3of9.afm. - </screen> - - <para>If you want the converted fonts to be stored in - <filename>A.pfa</filename> and <filename>B.afm</filename>, - then use this command:</para> - - <screen><prompt>%</prompt> <userinput>gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B</userinput> -Aladdin Ghostscript 5.10 (1997-11-23) -Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. -This software comes with NO WARRANTY: see the file PUBLIC for details. -Converting 3of9.ttf to A.pfa and B.afm. - </screen> - </listitem> - - <listitem> - <para>Create the groff PostScript file:</para> - - <para>Change directories to - <filename>/usr/share/groff_font/devps</filename> so as to - make the following command easier to execute. You will - probably need root privileges for this. (Or, if you are - paranoid about working there, make sure you reference the - files <filename>DESC</filename>, - <filename>text.enc</filename> and - <filename>generate/textmap</filename> as being in this - directory.)</para> - - <screen><prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc file.afm \ - generate/textmap <replaceable>PS_font_name</replaceable></userinput> - </screen> - - <para>Where, <filename>file.afm</filename> is the - <replaceable>AFM_name</replaceable> created by - <command>ttf2pf.ps</command> above, and - <replaceable>PS_font_name</replaceable> is the font name - used from that command, as well as the name that - &man.groff.1; will use for references to this font. For - example, assuming you used the first - <command>tiff2pf.ps</command> command above, then the 3of9 - Barcode font can be created using the command:</para> - - <screen><prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc 3of9.afm \ - generate/textmap 3of9</userinput> - </screen> - - <para>Ensure that the resulting - <replaceable>PS_font_name</replaceable> file (e.g., - <filename>3of9</filename> in the example above) is located - in the directory - <filename>/usr/share/groff_font/devps</filename> by copying - or moving it there.</para> - - <para>Note that if <filename>ttf2pf.ps</filename> assigns a - font name using the one it finds in the TrueType font file - and you want to use a different name, you must edit the - <filename>.afm</filename> file prior to running - <command>afmtodit</command>. This name must also match the - one used in the Fontmap file if you wish to pipe - &man.groff.1; into &man.gs.1;.</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title>Can TrueType fonts be used with other programs?</title> - - <para>The TrueType font format is used by Windows, Windows 95, and - Mac's. It is quite popular and there are a great number of - fonts available in this format.</para> - - <para>Unfortunately, there are few applications that I am aware of - that can use this format: Ghostscript and Povray come to mind. - Ghostscript's support, according to the documentation, is - rudimentary and the results are likely to be inferior to type 1 - fonts. Povray version 3 also has the ability to use TrueType - fonts, but I rather doubt many people will be creating documents - as a series of raytraced pages :-).</para> - - <para>This rather dismal situation may soon change. The <ulink - url="http://www.freetype.org/">FreeType Project</ulink> is - currently developing a useful set of FreeType tools:</para> - - <itemizedlist> - <listitem> - <para>The freetype module is included with XFree86 4.x. For - more information please see the <ulink - url="&url.books.handbook;/x-fonts.html">FreeBSD - Handbook</ulink> or the <ulink - url="http://www.xfree86.org/4.0.2/fonts.html">XFree86 4.0.2 - Fonts</ulink> page.</para> - </listitem> - - <listitem> - <para>The <command>xfsft</command> font server for X11 can - serve TrueType fonts in addition to regular fonts. Though - currently in beta, it is said to be quite usable. See - <ulink - url="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">Juliusz - Chroboczek's page</ulink> for further information. - Porting instructions for FreeBSD can be found at <ulink - url="http://math.missouri.edu/~stephen/software/">Stephen - Montgomery's software page</ulink>.</para> - </listitem> - - <listitem> - <para><command>xfstt</command> is another font server for X11, - available under <ulink url=" - ftp://sunsite.unc.edu/pub/Linux/X11/fonts/"></ulink>.</para> - </listitem> - - <listitem> - <para>A program called <command>ttf2bdf</command> can produce - BDF files suitable for use in an X environment from TrueType - files. Linux binaries are said to be available from <ulink - url="ftp://crl.nmsu.edu/CLR/multiling/General/"></ulink>.</para> - </listitem> - - <listitem> - <para>For people requiring the use of Asian TrueType fonts, - the <command>XTT</command> font server may be worth a look. - Information about <command>XTT</command> can be found at - URL: <ulink - url="http://hawk.ise.chuo-u.ac.jp/student/person/tshiozak/study/freebsd-at-random/x-tt/index-en.html"></ulink>.</para> - </listitem> - - <listitem> - <para>and others …</para> - </listitem> - </itemizedlist> - - <para>The <ulink - url="http://freetype.sourceforge.net/projects.html">FreeType Projects - page </ulink> is a good starting point for information on - these and other free TrueType projects.</para> - </sect1> - - <sect1> - <title>Where can additional fonts be obtained?</title> - - <para>Many fonts are available on the Internet. They are either - entirely free, or are share-ware. In addition, there are many - inexpensive CDROMs available that contain many fonts. Some - Internet locations (as of August 1996) are:</para> - - <itemizedlist> - <listitem> - <para><ulink url="ftp://ftp.winsite.com/"></ulink> - (Formerly CICA)</para> - </listitem> - - <listitem> - <para><ulink url="http://www.simtel.net/"></ulink></para> - </listitem> - - <listitem> - <para><ulink url="ftp://ftp.coast.net/"></ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://af-pc-plloyd.ecel.uwa.edu.au/fonts/"></ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.esselte.com/letraset/"></ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.inil.com/users/elfring/esf.htm"></ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>Additional questions</title> - - <itemizedlist> - <listitem> - <para>What use are the <filename>.pfm</filename> files?</para> - </listitem> - - <listitem> - <para>Can one generate the <filename>.afm</filename> file from - a <filename>.pfa</filename> or - <filename>.pfb</filename>?</para> - </listitem> - - <listitem> - <para>How to generate the groff character mapping files for - PostScript fonts with non-standard character names?</para> - </listitem> - - <listitem> - <para>Can xditview and devX?? devices be set up to access all - the new fonts?</para> - </listitem> - - <listitem> - <para>It would be good to have examples of using TrueType - fonts with povray and ghostscript.</para> - </listitem> - </itemizedlist> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/formatting-media/Makefile b/en_US.ISO8859-1/articles/formatting-media/Makefile deleted file mode 100644 index 90e09b2607..0000000000 --- a/en_US.ISO8859-1/articles/formatting-media/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Formatting Media For Use With FreeBSD - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/formatting-media/article.sgml b/en_US.ISO8859-1/articles/formatting-media/article.sgml deleted file mode 100644 index 18746cb746..0000000000 --- a/en_US.ISO8859-1/articles/formatting-media/article.sgml +++ /dev/null @@ -1,630 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> -<!-- $FreeBSD$ --> -<article> - <articleinfo> - <title>Formatting Media For Use With FreeBSD</title> - - <subtitle>A Tutorial</subtitle> - - <authorgroup> - <author> - <firstname>Doug</firstname> - - <surname>White</surname> - - <affiliation> - <address> - <email>dwhite@resnet.uoregon.edu</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>March 1997</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.iomega; - &tm-attrib.opengroup; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This document describes how to slice, partition, and - format hard disk drives and similar media for use with - FreeBSD. The examples given have been tested under FreeBSD - 2.2 and should work for other releases. The text has been updated - for FreeBSD version 4.</para> - </abstract> - </articleinfo> - - <sect1> - <title>Introduction & Definitions</title> - - <sect2> - <title>Overview</title> - - <para>Successfully adding disks to an existing system is the - mark of an experienced system administrator. Slicing, - partitioning, and adding disks requires a careful dance of - proper command and name syntax. One slipped finger and an - entire disk could disappear in seconds. This document is - written in an attempt to simplify this process and avoid - accidents. Thankfully, enhancements to existing tools - (notably sysinstall) have greatly improved this process in - recent releases of FreeBSD.</para> - - <para>There are two possible modes of disk formatting:</para> - - <itemizedlist> - <listitem> - <para><firstterm>compatibility mode</firstterm>: Arranging a - disk so that it has a slice table for use with other - operating systems.</para> - </listitem> - - <listitem> - <para><firstterm>dedicated mode</firstterm>, sometimes called - <firstterm>dangerously dedicated mode</firstterm>: Formatting a disk - with no slice table. This makes the process of adding disks easier, - however non-FreeBSD operating systems may not accept the disk. The - term <emphasis>dangerously</emphasis> refers to the danger that the - system may not recognize a disk formatted in this manner.</para> - </listitem> </itemizedlist> - - <para>For most cases, dedicated mode is the easiest to set up - and use in existing systems, as a new disk is usually - dedicated entirely to FreeBSD. However, compatibility mode - insures optimum interoperability with future installations at - a cost of increased complexity.</para> - - <para>In addition to selecting the mode, two methods of slicing - the disk are available. One is using the system installation - tool <command>/stand/sysinstall</command>. 2.1.7-RELEASE and - later versions of <command>sysinstall</command> contain code - to ease setup of disks during normal system operation, mainly - allowing access to the Label and Partition editors and a Write - feature which will update just the selected disk and slice - without affecting other disks. The other method is running - the tools manually from a root command line. For - dedicated mode, only three or four commands are involved while - <command>sysinstall</command> requires some - manipulation.</para> - </sect2> - - <sect2> - <title>Definitions</title> - - <para>&unix; disk management over the centuries has invented many - new definitions for old words. The following glossary covers - the definitions used in this document and (hopefully) for - FreeBSD in general.</para> - -<!-- I'm tempted to use GLOSSARY here but will resort to a list for -now. --> - - <itemizedlist> - <listitem> - <para>compatibility mode: Arranging a disk so that it has a - slice table for use with other operating systems. Oppose - dedicated mode.</para> - </listitem> - - <listitem> - <para>(dangerously) dedicated mode: Formatting a disk with no - slice table. This makes the process of adding disks - easier, however non-FreeBSD operating systems may not - accept the disk. Oppose compatibility mode.</para> - </listitem> - - <listitem> - <para>disk: Hard disks, CDROMs, magneto-optical devices and - &iomegazip;/&jaz; removable media are example of storage devices - commonly used today. The basic principle of the way these - work is that one or more spinning disks spin by a motor, - while a head, moving on a radial path close to the disks, - reads from or writes data to the disk. Writing is done by - modifying some physical properties of the disk (magnetic - flow, reflectivity, etc.) while reading is done by - <quote>detecting</quote> changes to the same physical - properties of the disk.</para> - </listitem> - - <listitem> - <para>slice: A division of a disk. Up to four slices are - permitted on one disk in the PC standard. Slices are - composed of contiguous sectors. Slices are recorded in a - <quote>slice table</quote> used by the system BIOS to - locate bootable partitions. The slice table is usually - called the <quote>partition table</quote> in DOS parlance. Maintained by - the fdisk utility.</para> - </listitem> - - <listitem> - <para>partition: A division of a slice. Usually used in - reference to divisions of the FreeBSD slice of a disk. - Each filesystem and swap area on a disk resides in a - partition. Maintained using the disklabel utility.</para> - </listitem> - - <listitem> - <para>sector: Smallest subdivision of a disk. One sector - usually represents 512 bytes of data.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>Warnings & Pitfalls</title> - - <para>Building disks is not something to take lightly. It is - quite possible to destroy the contents of other disks in your - system if the proper precautions are not taken.</para> - - <para><emphasis>Check your work carefully.</emphasis> It is very simple - to destroy the incorrect disk when working with these - commands. When in doubt consult the kernel boot output for - the proper device.</para> - - <para>Needless to say, we are not responsible for any damage to - any data or hardware that you may experience. You work at - your own risk!</para> - </sect2> - - <sect2> - <title>Zip, Jaz, and Other Removables</title> - - <para>Removable disks can be formatted in the same way as normal - hard disks. It is essential to have the disk drive connected - to the system and a disk placed in the drive during startup, - so the kernel can determine the drive's geometry. Check the - <command>dmesg</command> output and make sure your device and - the disk's size is listed. If the kernel reports - - <informalexample> - <screen>Can't get the size</screen> - </informalexample> - - then the disk was not in the drive. In this case, you will - need to restart the machine before attempting to format - disks.</para> - </sect2> - </sect1> - - <sect1> - <title>Formatting Disks in Dedicated Mode</title> - - <sect2> - <title>Introduction</title> - - <para>This section details how to make disks that are totally - dedicated to FreeBSD. Remember, dedicated mode disks sometimes - cannot be booted by the PC architecture.</para> - </sect2> - - <sect2> - <title>Making Dedicated Mode Disks using Sysinstall</title> - - <para><command>/stand/sysinstall</command>, the system - installation utility, has been expanded in recent versions to - make the process of dividing disks properly a less tiring - affair. The fdisk and disklabel editors built into sysinstall - are GUI tools that remove much of the confusion from slicing - disks. For FreeBSD versions 2.1.7 and later, this is perhaps - the simplest way to slice disks.</para> - - <procedure> - <step> - <para>Start sysinstall as root by typing - - <informalexample> - <screen>&prompt.root; <userinput>/stand/sysinstall</userinput></screen> - </informalexample> - - from the command prompt.</para> - </step> - - <step> - <para>Select <command>Index</command>.</para> - </step> - - <step> - <para>Select <command>Partition</command>.</para> - </step> - - <step> - <para>Select the disk to edit with arrow keys and - <keycap>SPACE</keycap>.</para> - </step> - - <step> - <para>If you are using this entire disk for FreeBSD, select - <command>A</command>.</para> - </step> - - <step> - <para>When asked: - - <informalexample> - <screen>Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)?</screen> - </informalexample> - - answer <command>No</command>.</para> - </step> - - <step> - <para>When asked if you still want to do this, answer - <command>Yes</command>.</para> - </step> - - <step> - <para>Select <command>Write</command>.</para> - </step> - - <step> - <para>When warned about writing on installed systems, answer - <command>Yes</command>.</para> - </step> - - <step> - <para><command>Quit</command>the FDISK Editor and - <keycap>ESCAPE</keycap> back to the Index menu.</para> - </step> - - <step> - <para>Select <command>Label</command> from the Index - menu.</para> - </step> - - <step> - <para>Label as desired. For a single partition, enter - <command>C</command> to Create a partition, accept the - default size, partition type Filesystem, and a mountpoint - (which is not used).</para> - </step> - - <step> - <para>Enter <command>W</command> when done and confirm to - continue. The filesystem will be newfs'd for you, unless - you select otherwise (for new partitions you will want to - do this!). You will get the error: - - <informalexample> - <screen>Error mounting /mnt/dev/ad2s1e on /mnt/blah : No such file or directory</screen> - </informalexample> - - Ignore.</para> - </step> - - <step> - <para>Exit out by repeatedly pressing - <keycap>ESCAPE</keycap>.</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Making Dedicated Mode Disks Using the Command Line</title> - - <para>Execute the following commands, replacing <devicename>ad2</devicename> with the - disk name.</para> - - <informalexample> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/ad2 count=2</userinput> -&prompt.root; <userinput>disklabel /dev/ad2 | disklabel -B -R -r ad2 /dev/stdin</userinput> -<lineannotation>We only want one partition, so using slice 'c' should be fine:</lineannotation> -&prompt.root; <userinput>newfs /dev/ad2c</userinput></screen> - </informalexample> - - <para>If you need to edit the disklabel to create multiple - partitions (such as swap), use the following: </para> - - <informalexample> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/ad2 count=2</userinput> -&prompt.root; <userinput>disklabel /dev/ad2 > /tmp/label</userinput> -<lineannotation>Edit disklabel to add partitions:</lineannotation> -&prompt.root; <userinput>vi /tmp/label</userinput> -&prompt.root; <userinput>disklabel -B -R -r ad2 /tmp/label</userinput> -<lineannotation>newfs partitions appropriately</lineannotation></screen> - </informalexample> - - <para>Your disk is now ready for use.</para> - </sect2> - </sect1> - - <sect1> - <title>Making Compatibility Mode Disks</title> - - <sect2> - <title>Introduction</title> - - <para>The command line is the easiest way to make dedicated - disks, and the worst way to make compatibility disks. The - command-line <command>fdisk</command> utility requires higher math skills and an - in-depth understanding of the slice table, which is more than - most people want to deal with. Use sysinstall for - compatibility disks, as described below.</para> - </sect2> - - <sect2> - <title>Making Compatibility Mode Disks Using Sysinstall</title> - - <procedure> - <step> - <para>Start sysinstall as root by typing - - <informalexample> - <screen>&prompt.root; <userinput>/stand/sysinstall</userinput></screen> - </informalexample> - - from the command prompt.</para> - </step> - - <step> - <para>Select <command>Index</command>.</para> - </step> - - <step> - <para>Select <command>Partition</command>.</para> - </step> - - <step> - <para>Select the disk to edit with arrow keys and - <keycap>SPACE</keycap>.</para> - </step> - - <step> - <para>If you are using this entire disk for FreeBSD, select - <command>A</command>.</para> - </step> - - <step> - <para>When asked: - - <informalexample> - <screen>Do you want to do this with a true partition entry so as to remain -cooperative with any future possible operating systems on the -drive(s)?</screen> - </informalexample> - - answer <command>yes</command>.</para> - </step> - - <step> - <para>Select <command>Write</command>.</para> - </step> - - <step> - <para>When asked to install the boot manager, select None - with <keycap>SPACE</keycap> then hit - <keycap>ENTER</keycap> for OK.</para> - </step> - - <step> - <para><command>Quit</command> the FDISK Editor.</para> - </step> - - <step> - <para>You will be asked about the boot manager, select - <command>None</command> again. </para> - </step> - - <step> - <para>Select <command>Label</command> from the Index - menu.</para> - </step> - - <step> - <para>Label as desired. For a single partition, accept the - default size, type filesystem, and a mountpoint (which - is not used).</para> - </step> - - <step> - <para>The filesystem will be newfs'd for you, unless you - select otherwise (for new partitions you will want to do - this!). You will get the error: - - <informalexample> - <screen>Error mounting /mnt/dev/ad2s1e on /mnt/blah : No such file or directory</screen> - </informalexample> - - Ignore.</para> - </step> - - <step> - <para>Exit out by repeatedly pressing - <keycap>ESCAPE</keycap>.</para> - </step> - </procedure> - - <para>Your new disk is now ready for use.</para> - </sect2> - </sect1> - - <sect1> - <title>Other Disk Operations</title> - - <sect2> - <title>Adding Swap Space</title> - - <para>As a system grows, its need for swap space can also grow. - Although adding swap space to existing disks is very - difficult, a new disk can be partitioned with additional swap - space.</para> - - <para>To add swap space when adding a disk to a system:</para> - - <procedure> - <step> - <para>When partitioning the disk, edit the disklabel and - allocate the amount of swap space to add in partition `b' - and the remainder in another partition, such as `a' or - `e'. The size is given in 512 byte blocks.</para> - </step> - - <step> - <para>When newfsing the drive, do NOT newfs the `c' - partition. Instead, newfs the partition where the - non-swap space lies.</para> - </step> - - <step> - <para>Add an entry to <filename>/etc/fstab</filename> as - follows:</para> - - <informalexample> - <programlisting>/dev/ad0b none swap sw 0 0 - </programlisting> - </informalexample> - - <para>Change <filename>/dev/ad0b</filename> to the device of the newly added - space.</para> - </step> - - <step> - <para>To make the new space immediately available, use the - <command>swapon</command> command. - - <informalexample> - <screen>&prompt.root; <userinput>swapon /dev/da0b</userinput> -swapon: added /dev/da0b as swap space</screen> - </informalexample> - </para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Copying the Contents of Disks</title> -<!-- Should have specific tag --> - - <para>Submitted By: Renaud Waldura - (<email>renaud@softway.com</email>) </para> - - <para>To move file from your original base disk to the fresh new - one, do: - - <informalexample> - <screen>&prompt.root; <userinput>mount /dev/ad2 /mnt</userinput> -&prompt.root; <userinput>pax -r -w -p e /usr/home /mnt</userinput> -&prompt.root; <userinput>umount /mnt</userinput> -&prompt.root; <userinput>rm -rf /usr/home/*</userinput> -&prompt.root; <userinput>mount /dev/ad2 /usr/home</userinput></screen> - </informalexample> - </para> - </sect2> - - <sect2> - <title>Creating Striped Disks using CCD</title> - - <para>Commands Submitted By: Stan Brown - (<email>stanb@awod.com</email>) </para> - - <para>The Concatenated Disk Driver, or CCD, allows you to treat - several identical disks as a single disk. Striping can result - in increased disk performance by distributing reads and writes - across the disks. See the &man.ccd.4; and &man.ccdconfig.8; - manual pages or the <ulink - url="http://stampede.cs.berkeley.edu/ccd/">CCD - Homepage</ulink> for further details.</para> - - <para>You no longer need to build a special kernel to run ccd. When you - run <command>ccdconfig</command>, it will load the KLD for you if the - kernel does not contain CCD support.</para> - - <para>You build CCDs on disk partitions of type - <emphasis>4.2BSD</emphasis>. If you want to use the entire disk, you - still need to create a new partition. For example, <userinput>disklabel - -e</userinput> might show:</para> - - <informalexample> - <screen># size offset fstype [fsize bsize bps/cpg] - c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597)</screen> - </informalexample> - - <para>You should not use partition <emphasis>c</emphasis> for the CCD, - since it is of type <emphasis>unused</emphasis>. Instead, create a new - partition of exactly the same size, but with type - <emphasis>4.2BSD</emphasis>:</para> - - <informalexample> - <screen># size offset fstype [fsize bsize bps/cpg] - c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) -<userinput> e: 60074784 0 4.2BSD 0 0 0 # (Cyl. 0 - 59597)</userinput></screen> - </informalexample> - - <para>To create a new CCD, execute the following commands. This - describes how to add three disks together; simply add or remove devices - as necessary. Remember that the disks to be striped must be - <emphasis>identical.</emphasis></para> - - <informalexample> - <screen>&prompt.root; <userinput>cd /dev ; sh MAKDEV ccd0</userinput> - -&prompt.root; <userinput>disklabel -r -w da0 auto</userinput> -&prompt.root; <userinput>disklabel -r -w da1 auto</userinput> -&prompt.root; <userinput>disklabel -r -w da2 auto</userinput> - -&prompt.root; <userinput>disklabel -e da0</userinput> -<lineannotation>Add partition e with type 4.2BSD</lineannotation> -&prompt.root; <userinput>disklabel -e da1</userinput> -<lineannotation>Add partition e with type 4.2BSD</lineannotation> -&prompt.root; <userinput>disklabel -e da2</userinput> -<lineannotation>Add partition e with type 4.2BSD</lineannotation> - -&prompt.root; <userinput>ccdconfig ccd0 273 0 /dev/da0e /dev/da1e /dev/da2e</userinput> - -&prompt.root; <userinput>newfs /dev/ccd0c</userinput></screen> - </informalexample> - - <para>The value 273 is the stripe size. This is the number of disk - sectors (of 512 bytes each) in each block of data on the CCD. It should - be at least 128 kB, and it should not be not be a power of 2.</para> - - <para>Now you can mount and use your CCD by referencing device - <filename>/dev/ccd0c</filename>.</para> - - <para>A more powerful and flexible alternative to CCD is Vinum. See the - <ulink url="http://www.vinumvm.org/">Vinum Project home page</ulink> - for further details.</para> - </sect2> - </sect1> - - <sect1> - <title>Credits</title> - - <para>The author would like to thank the following individuals for - their contributions to this project:</para> - - <itemizedlist> - <listitem> - <para>Darryl Okahata - (<email>darrylo@hpnmhjw.sr.hp.com</email>) for his simple - dedicated mode setup documentation which I have used - repeatedly on FreeBSD-questions.</para> - </listitem> - - <listitem> - <para>&a.jkh; for making sysinstall useful for this type of task. - </para> - </listitem> - - <listitem> - <para>John Fieber (<email>jfieber@indiana.edu</email>) for - making information and examples of the DocBook DTD on which - this document is based.</para> - </listitem> - - <listitem> - <para>&a.grog; for checking my work and pointing out inaccuracies, - as well as miscellaneous support.</para> - </listitem> - </itemizedlist> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/freebsd-questions/Makefile b/en_US.ISO8859-1/articles/freebsd-questions/Makefile deleted file mode 100644 index 216dfe9c92..0000000000 --- a/en_US.ISO8859-1/articles/freebsd-questions/Makefile +++ /dev/null @@ -1,21 +0,0 @@ -# -# $FreeBSD$ -# -# Article: How to get best results from the FreeBSD-questions mailing list - -MAINTAINER=grog@FreeBSD.org - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/freebsd-questions/article.sgml b/en_US.ISO8859-1/articles/freebsd-questions/article.sgml deleted file mode 100644 index 820a729d42..0000000000 --- a/en_US.ISO8859-1/articles/freebsd-questions/article.sgml +++ /dev/null @@ -1,627 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>How to get best results from the FreeBSD-questions mailing - list</title> - - <author> - <firstname>Greg</firstname> - <surname>Lehey</surname> - - <affiliation> - <address><email>grog@FreeBSD.org</email></address> - </affiliation> - </author> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.microsoft; - &tm-attrib.netscape; - &tm-attrib.opengroup; - &tm-attrib.qualcomm; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This document provides useful information for people looking to - prepare an e-mail to the FreeBSD-questions mailing list. Advice and - hints are given that will maximize the chance that the reader will - receive useful replies.</para> - - <para>This document is regularly posted to the FreeBSD-questions mailing - list.</para> - </abstract> - </articleinfo> - - <sect1> - <title id="Introduction">Introduction</title> - - <para><literal>FreeBSD-questions</literal> is a mailing list maintained by - the FreeBSD project to help people who have questions about the normal - use of FreeBSD. Another group, <literal>FreeBSD-hackers</literal>, - discusses more advanced questions such as future development - work.</para> - - <note> - <para>The term <quote>hacker</quote> has nothing to do with breaking - into other people's computers. The correct term for the latter - activity is <quote>cracker</quote>, but the popular press has not found - out yet. The FreeBSD hackers disapprove strongly of cracking - security, and have nothing to do with it. For a longer description of - hackers, see Eric Raymond's <ulink - url="http://www.catb.org/~esr/faqs/hacker-howto.html">How To Become - A Hacker</ulink></para> - </note> - - <para>This is a regular posting aimed to help both those seeking advice - from FreeBSD-questions (the <quote>newcomers</quote>), and also those - who answer the questions (the <quote>hackers</quote>).</para> - - <para>Inevitably there is some friction, which stems from the different - viewpoints of the two groups. The newcomers accuse the hackers of being - arrogant, stuck-up, and unhelpful, while the hackers accuse the - newcomers of being stupid, unable to read plain English, and expecting - everything to be handed to them on a silver platter. Of course, there is - an element of truth in both these claims, but for the most part these - viewpoints come from a sense of frustration.</para> - - <para>In this document, I would like to do something to relieve this - frustration and help everybody get better results from - FreeBSD-questions. In the following section, I recommend how to submit - a question; after that, we will look at how to answer one.</para> - </sect1> - - <sect1> - <title id="subscribe">How to subscribe to FreeBSD-questions</title> - - <para>FreeBSD-questions is a mailing list, so you need mail access. Point - your WWW browser to <ulink url="&a.questions.url;">FreeBSD-question Info Page</ulink>. - In the section titled <quote>Subscribing to freebsd-questions</quote> fill - in the <quote>Your email address</quote> field; the other fields are optional. - </para> - - <note> - <para>The password fields in the subscription form provide only mild - security, but should prevent others from messing with your - subscription. <emphasis>Do not use a valuable password</emphasis> as - it will occasionally be emailed back to you in cleartext.</para> - </note> - - <para>You will receive a confirmation message from - <application>mailman</application>; follow the included instructions - to complete your subscription.</para> - - <para>Finally, when you get the <quote>Welcome</quote> message from - <application>mailman</application> telling you the details of the list - and subscription area password, <emphasis>please save it</emphasis>. - If you ever should want to leave the list, you will need the information - there. See the next section for more details.</para> - </sect1> - - <sect1> - <title id="unsubscribe">How to unsubscribe from FreeBSD-questions</title> - - <para>When you subscribed to FreeBSD-questions, you got a welcome message - from <application>mailman</application>. In this message, amongst - other things, it told you how to unsubscribe. Here is a typical - message:</para> - - <literallayout class="monospaced">Welcome to the freebsd-questions@freebsd.org mailing list! - -To post to this list, send your email to: - - freebsd-questions@freebsd.org - -General information about the mailing list is at: - - http://lists.freebsd.org/mailman/listinfo/freebsd-questions - -If you ever want to unsubscribe or change your options (e.g., switch to -or from digest mode, change your password, etc.), visit your -subscription page at: - -http://lists.freebsd.org/mailman/options/freebsd-questions/grog%40lemsi.de - -You can also make such adjustments via email by sending a message to: - - freebsd-questions-request@freebsd.org - -with the word `help' in the subject or body (don't include the -quotes), and you will get back a message with instructions. - -You must know your password to change your options (including changing -the password, itself) or to unsubscribe. It is: - - 12345 - -Normally, Mailman will remind you of your freebsd.org mailing list -passwords once every month, although you can disable this if you -prefer. This reminder will also include instructions on how to -unsubscribe or change your account options. There is also a button on -your options page that will email your current password to you.</literallayout> - - <para>From the URL specified in your <quote>Welcome</quote> message you - may visit the <quote>Account management page</quote> and enter a request - to <quote>Unsubscribe</quote> you from FreeBSD-questions mailing - list.</para> - - <para>A confirmation message will be sent to you from - <application>mailman</application>; follow the included instructions - to finish unsubscribing.</para> - - <para>If you have done this, and you still can not figure out what - is going on, send a message to - <email>freebsd-questions-request@FreeBSD.org</email>, and they will - sort things out for you. <emphasis>Do not</emphasis> send a message to - FreeBSD-questions: they can not help you.</para> - </sect1> - - <sect1> - <title id="askwho">Should I ask <literal>-questions</literal> or - <literal>-hackers</literal>?</title> - - <para>Two mailing lists handle general questions about FreeBSD, - <literal>FreeBSD-questions</literal> and - <literal>FreeBSD-hackers</literal>. In some cases, it is not really - clear which group you should ask. The following criteria should help - for 99% of all questions, however:</para> - - <orderedlist> - <listitem> - <para>If the question is of a general nature, ask - <literal>FreeBSD-questions</literal>. Examples might be questions - about installing FreeBSD or the use of a particular &unix; - utility.</para> - </listitem> - - <listitem> - <para>If you think the question relates to a bug, but you are not sure, - or you do not know how to look for it, send the message to - <literal>FreeBSD-questions</literal>.</para> - </listitem> - - <listitem> - <para>If the question relates to a bug, and you are - <emphasis>sure</emphasis> that it is a bug (for example, you can - pinpoint the place in the code where it happens, and you maybe have - a fix), then send the message to - <literal>FreeBSD-hackers</literal>.</para> - </listitem> - - <listitem> - <para>If the question relates to enhancements to FreeBSD, and you - can make suggestions about how to implement them, then send the - message to <literal>FreeBSD-hackers</literal>.</para> - </listitem> - </orderedlist> - - <para>There are also a number of other specialized mailing lists, for - example <literal>FreeBSD-isp</literal>, which caters to the interests of - ISPs (Internet Service Providers) who run FreeBSD. If you happen to be - an ISP, this does not mean you should automatically send your questions - to <literal>FreeBSD-isp</literal>. The criteria above still apply, and - it is in your interest to stick to them, since you are more likely to get - good results that way.</para> - </sect1> - - <sect1> - <title id="before">Before submitting a question</title> - - <para>You can (and should) do some things yourself before asking a question - on one of the mailing lists:</para> - - <itemizedlist> - <listitem> - <para>Try solving the problem on your own. If you post a question which - shows that you have tried to solve the problem, your question will - generally attract more positive attention from people reading it. - Trying to solve the problem yourself will also enhance your understanding - of FreeBSD, and will eventually let you use your knowledge to help others - by answering questions posted to the mailing lists. - </para> - </listitem> - - <listitem> - <para>Read the manual pages, and the FreeBSD documentation (either - installed in <filename>/usr/doc</filename> or accessible via WWW at - <ulink url="http://www.FreeBSD.org"></ulink>), especially the - <ulink url="&url.books.handbook;/index.html">handbook</ulink> - and the <ulink url="&url.books.faq;/index.html">FAQ</ulink>. - </para> - </listitem> - - <listitem> - <para>Browse and/or search the archives for the mailing list, to see if your - question or a similar one has been asked (and possibly answered) on the - list. You can browse and/or search the mailing list archives - at <ulink url="http://www.FreeBSD.org/mail"></ulink> - and <ulink url="http://www.FreeBSD.org/search/search.html#mailinglists"></ulink> - respectively. This can be done at other WWW sites as well, for example - at <ulink url="http://marc.theaimsgroup.com"></ulink>. - </para> - </listitem> - - <listitem> - <para>Use a search engine such as <ulink url="http://www.google.com">Google</ulink> - or <ulink url="http://www.yahoo.com">Yahoo</ulink> to find answers to your question. - Google even has a <ulink - url="http://www.google.com/bsd">BSD-specific search interface</ulink>. - </para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title id="submit">How to submit a question</title> - - <para>When submitting a question to FreeBSD-questions, consider the - following points:</para> - - <itemizedlist> - <listitem> - <para>Remember that nobody gets paid for answering a FreeBSD - question. They do it of their own free will. You can influence this - free will positively by submitting a well-formulated question - supplying as much relevant information as possible. You can - influence this free will negatively by submitting an incomplete, - illegible, or rude question. It is perfectly possible to send a - message to FreeBSD-questions and not get an answer even if you - follow these rules. It is much more possible to not get an answer if - you do not. In the rest of this document, we will look at how to get - the most out of your question to FreeBSD-questions.</para> - </listitem> - - <listitem> - <para>Not everybody who answers FreeBSD questions reads every message: - they look at the subject line and decide whether it interests them. - Clearly, it is in your interest to specify a subject. <quote>FreeBSD - problem</quote> or <quote>Help</quote> are not enough. If you provide no subject at - all, many people will not bother reading it. If your subject is not - specific enough, the people who can answer it may not read - it.</para> - </listitem> - - <listitem> - <para>Format your message so that it is legible, and - PLEASE DO NOT SHOUT!!!!!. We appreciate that a lot of people do not - speak English as their first language, and we try to make - allowances for that, but it is really painful to try to read a - message written full of typos or without any line breaks.</para> - - <para>Do not underestimate the effect that a poorly formatted mail - message has, not just on the FreeBSD-questions mailing list. - Your mail message is all people see of you, and if it is poorly - formatted, one line per paragraph, badly spelt, or full of - errors, it will give people a poor impression of you.</para> - - <para>A lot of badly formatted messages come from - <ulink url="http://www.lemis.com/email.html">bad mailers or badly - configured mailers</ulink>. The following mailers are known to - send out badly formatted messages without you finding out about - them:</para> - - <itemizedlist> - <listitem> - <para>cc:Mail</para> - </listitem> - - <listitem> - <para>&eudora;</para> - </listitem> - - <listitem> - <para>exmh</para> - </listitem> - - <listitem> - <para>µsoft; Exchange</para> - </listitem> - - <listitem> - <para>µsoft; Internet Mail</para> - </listitem> - - <listitem> - <para>µsoft; &outlook;</para> - </listitem> - - <listitem> - <para>&netscape;</para> - </listitem> - </itemizedlist> - - <para>As you can see, the mailers in the Microsoft world are frequent - offenders. If at all possible, use a &unix; mailer. If you must use a - mailer under Microsoft environments, make sure it is set up - correctly. Try not to use <acronym>MIME</acronym>: a lot of people - use mailers which do not get on very well with - <acronym>MIME</acronym>.</para> - </listitem> - - <listitem> - <para>Make sure your time and time zone are set correctly. This may - seem a little silly, since your message still gets there, but many - of the people you are trying to reach get several hundred messages a - day. They frequently sort the incoming messages by subject and by - date, and if your message does not come before the first answer, they - may assume they missed it and not bother to look.</para> - </listitem> - - <listitem> - <para>Do not include unrelated questions in the same message. Firstly, - a long message tends to scare people off, and secondly, it is more - difficult to get all the people who can answer all the questions to - read the message.</para> - </listitem> - - <listitem> - <para>Specify as much information as possible. This is a difficult - area, and we need to expand on what information you need to submit, - but here is a start:</para> - - <itemizedlist> - <listitem> - <para>In nearly every case, it is important to know the version of - FreeBSD you are running. This is particularly the case for - FreeBSD-CURRENT, where you should also specify the date of the - sources, though of course you should not be sending questions - about -CURRENT to FreeBSD-questions.</para> - </listitem> - - <listitem><para>With any problem which <emphasis>could</emphasis> be - hardware related, tell us about your hardware. In case of - doubt, assume it is possible that it is hardware. What kind of - CPU are you using? How fast? What motherboard? How much - memory? What peripherals?</para> - - <para>There is a judgement call here, of course, but the output of - the &man.dmesg.8; command can frequently be very useful, since it - tells not just what hardware you are running, but what version of - FreeBSD as well.</para> - </listitem> - - <listitem> - <para>If you get error messages, do not say <quote>I get error - messages</quote>, say (for example) <quote>I get the error - message 'No route to host'</quote>.</para> - </listitem> - - <listitem> - <para>If your system panics, do not say <quote>My system - panicked</quote>, say (for example) <quote>my system panicked - with the message 'free vnode isn't'</quote>.</para> - </listitem> - - <listitem> - <para>If you have difficulty installing FreeBSD, please tell us - what hardware you have. In particular, it is important to know - the IRQs and I/O addresses of the boards installed in your - machine.</para> - </listitem> - - <listitem> - <para>If you have difficulty getting PPP to run, describe the - configuration. Which version of PPP do you use? What kind of - authentication do you have? Do you have a static or dynamic IP - address? What kind of messages do you get in the log - file?</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>A lot of the information you need to supply is the output of - programs, such as &man.dmesg.8;, or console messages, which usually - appear in <filename>/var/log/messages</filename>. Do not try to copy - this information by typing it in again; it is a real pain, and you are - bound to make a mistake. To send log file contents, either make a - copy of the file and use an editor to trim the information to what - is relevant, or cut and paste into your message. For the output of - programs like &man.dmesg.8;, redirect the output to a file and - include that. For example,</para> - - <screen>&prompt.user; <userinput>dmesg > /tmp/dmesg.out</userinput></screen> - - <para>This redirects the information to the file - <filename>/tmp/dmesg.out</filename>.</para> - </listitem> - - <listitem> - <para>If you do all this, and you still do not get an answer, there - could be other reasons. For example, the problem is so complicated - that nobody knows the answer, or the person who does know the answer - was offline. If you do not get an answer after, say, a week, it - might help to re-send the message. If you do not get an answer to - your second message, though, you are probably not going to get one - from this forum. Resending the same message again and again will - only make you unpopular.</para> - </listitem> - </itemizedlist> - - <para>To summarize, let's assume you know the answer to the following - question (yes, it is the same one in each case). - You choose which of these two questions you would be more prepared to - answer:</para> - - <example> - <title>Message 1</title> - - <literallayout class="monospaced">Subject: HELP!!?!?? -I just can't get hits damn silly FereBSD system to -workd, and Im really good at this tsuff, but I have never seen -anythign sho difficult to install, it jst wont work whatever I try -so why don't you guys tell me what I doing wrong.</literallayout> - </example> - - <example> - <title>Message 2</title> - - <literallayout class="monospaced">Subject: Problems installing FreeBSD - -I've just got the FreeBSD 2.1.5 CDROM from Walnut Creek, and I'm having a lot -of difficulty installing it. I have a 66 MHz 486 with 16 MB of -memory and an Adaptec 1540A SCSI board, a 1.2GB Quantum Fireball -disk and a Toshiba 3501XA CDROM drive. The installation works just -fine, but when I try to reboot the system, I get the message -<quote>Missing Operating System</quote>.</literallayout> - </example> - </sect1> - - <sect1> - <title id="followup">How to follow up to a question</title> - - <para>Often you will want to send in additional information to a question - you have already sent. The best way to do this is to reply to your - original message. This has three advantages:</para> - - <orderedlist> - <listitem> - <para>You include the original message text, so people will know what - you are talking about. Do not forget to trim unnecessary text out, - though.</para> - </listitem> - - <listitem> - <para>The text in the subject line stays the same (you did remember to - put one in, did you not?). Many mailers will sort messages by - subject. This helps group messages together.</para> - </listitem> - - <listitem> - <para>The message reference numbers in the header will refer to the - previous message. Some mailers, such as - <ulink url="http://www.mutt.org/">mutt</ulink>, can - <emphasis>thread</emphasis> messages, showing the exact - relationships between the messages.</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title id="answer">How to answer a question</title> - - - <para>Before you answer a question to FreeBSD-questions, consider:</para> - - <orderedlist> - <listitem> - <para>A lot of the points on submitting questions also apply to - answering questions. Read them.</para> - </listitem> - - <listitem> - <para>Has somebody already answered the question? The easiest way to - check this is to sort your incoming mail by subject: then - (hopefully) you will see the question followed by any answers, all - together.</para> - - <para>If somebody has already answered it, it does not automatically - mean that you should not send another answer. But it makes sense to - read all the other answers first.</para> - </listitem> - - <listitem> - <para>Do you have something to contribute beyond what has already been - said? In general, <quote>Yeah, me too</quote> answers do not help - much, although there are exceptions, like when somebody is - describing a problem he is having, and he does not know whether it is - his fault or whether there is something wrong with the hardware or - software. If you do send a <quote>me too</quote> answer, you should - also include any further relevant information.</para> - </listitem> - - <listitem> - <para>Are you sure you understand the question? Very frequently, the - person who asks the question is confused or does not express himself - very well. Even with the best understanding of the system, it is - easy to send a reply which does not answer the question. This - does not help: you will leave the person who submitted the question - more frustrated or confused than ever. If nobody else answers, and - you are not too sure either, you can always ask for more - information.</para> - </listitem> - - <listitem> - <para>Are you sure your answer is correct? - If not, wait a day or so. If nobody else comes up with a - better answer, you can still reply and say, for example, <quote>I - do not know if this is correct, but since nobody else has - replied, why don't you try replacing your ATAPI CDROM with - a frog?</quote>.</para> - </listitem> - - <listitem> - <para>Unless there is a good reason to do otherwise, reply to the - sender and to FreeBSD-questions. Many people on the - FreeBSD-questions are <quote>lurkers</quote>: they learn by reading - messages sent and replied to by others. If you take a message which - is of general interest off the list, you are depriving these people - of their information. Be careful with group replies; lots of people - send messages with hundreds of CCs. If this is the case, be sure to - trim the Cc: lines appropriately.</para> - </listitem> - - <listitem> - <para>Include relevant text from the original message. Trim it to the - minimum, but do not overdo it. It should still be possible for - somebody who did not read the original message to understand what - you are talking about.</para> - </listitem> - - <listitem> - <para>Use some technique to identify which text came from the original - message, and which text you add. I personally find that prepending - <quote><literal>> </literal></quote> to the original message - works best. Leaving white space after the - <quote><literal>> </literal></quote> and leave empty lines - between your text and the original text both make the result more - readable.</para> - </listitem> - - <listitem> - <para>Put your response in the correct place (after the text to which - it replies). It is very difficult to read a thread of responses - where each reply comes before the text to which it replies.</para> - </listitem> - - <listitem> - <para>Most mailers change the subject line on a reply by prepending a - text such as <quote>Re: </quote>. If your mailer does not do it - automatically, you should do it manually.</para> - </listitem> - - <listitem> - <para>If the submitter did not abide by format conventions (lines too - long, inappropriate subject line), <emphasis>please</emphasis> fix - it. In the case of an incorrect subject line (such as - <quote>HELP!!??</quote>), change the subject line to (say) - <quote>Re: Difficulties with sync PPP (was: HELP!!??)</quote>. That - way other people trying to follow the thread will have less - difficulty following it.</para> - - <para>In such cases, it is appropriate to say what you did and why you - did it, but try not to be rude. If you find you can not answer - without being rude, do not answer.</para> - - <para>If you just want to reply to a message because of its bad - format, just reply to the submitter, not to the list. You can just - send him this message in reply, if you like.</para> - </listitem> - </orderedlist> - </sect1> -</article> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO8859-1/articles/hats/Makefile b/en_US.ISO8859-1/articles/hats/Makefile deleted file mode 100644 index 070310e5a8..0000000000 --- a/en_US.ISO8859-1/articles/hats/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Working with Hats - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/hats/article.sgml b/en_US.ISO8859-1/articles/hats/article.sgml deleted file mode 100644 index 1e0b4a7226..0000000000 --- a/en_US.ISO8859-1/articles/hats/article.sgml +++ /dev/null @@ -1,117 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Working with Hats</title> - - <authorgroup> - <author> - <firstname>Warner</firstname> - <surname>Losh</surname> - <contrib>Contributed by</contrib> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <copyright> - <year>2002</year> - <year>2003</year> - <holder role="mailto:imp@FreeBSD.org">Warner Losh</holder> - </copyright> - </articleinfo> - - <note> - <para>This is not an official statement from core, but rather one - core member's personal interpretation of core's position, both - as a sitting member of core and as a former security - officer. This is only a guideline, not as a cudgel for - grievances. Much like &man.style.9; is a guideline for the - source code, this document is not intended as an absolute - straight jacket.</para> - </note> - - <para>When core appoints someone to a hat, they expect that person - to be responsible for an area of the source code tree. Core - expects that person to be the final authority in that area of the - tree, or have enough self knowledge to know that they are not and - to seek qualified help. Core expects that person to guide - development in that area of the tree. Sometimes this means taking - an pro-active role in day to day affairs, while other times this - means taking a reactive role in reviewing committed code.</para> - - <para>When people submit patches that potentially impact this area - of the tree, core expects the hat or his appointed deputies to - review the patches appropriately. Core expects that the hat will - work with the patch submitter to correct issues that there may be - with the patches. Core expects the hat to offer solutions and - work with the submitter to reach a compromise. Core expects the - hat to be courteous. It is reasonable for hats to request that - normal project rules be followed when reviewing patches (eg, that - they generally conform to &man.style.9; or the prevailing style of the - file, that style and content changes be separated, etc).</para> - - <para>When a dispute arises, core expects the hat to make his or her - best efforts to compromise or otherwise resolve the dispute. The - hat is expected to be courteous to all parties involved. In - extreme cases, core recognizes that hats may need to wield a big - stick and say <quote>no, that is not acceptable and cannot go in - (or must be backed out).</quote> Core views this last power as one - of last resort, and would frown on hats using that either too - often or as the first response.</para> - - <para>Often real life interferes with a hat's ability to perform their duties. A - condition that core generally imposes upon the hats of the world - is that they have a deputy that can act in their absence. This - deputy is expected to be an active participant in the team that - the hat puts together and should be conversant with all the issues - that surround the part of the tree that the hat is guiding. The - deputy is expected to be able to act in the absence of the hat. - For example, the security officer deputies send out security - advisories when the SO is not around. In extreme cases, the - deputy can defer an issue until the hat returns, but that is - expected to be the exception rather than the rule, especially if - the hat's return is far in the future.</para> - - <para>Hats are answerable to core. If they are doing good jobs, - core will leave them alone. If they are doing a bad job, core has - the option to remove them. Hats are expected to work with core if - core has issues with their performance of their duties They serve - at the pleasure of core.</para> - - <para>Core sometimes will impose additional, specific requirements - for a given hat that does not apply to all hats. These conditions - may change over time.</para> - - <para>Committers and others working with hats are expected to use - common sense, and be polite to the hats. They are expected to - work with the hat and his team to come to a solution acceptable to - everybody. In the event that no compromise can be reached, the - committers are expected to accept the decisions of the hat with - good grace. In exceptional cases, these decisions can be appealed - to core. However, core generally will not override the decisions - of the hats that it appoints unless the hat acted in bad faith or - arbitrarily. Core is not a technical review board, and has - created the hats as mini-TRBs to give dispute resolution a proper - framework.</para> - - <para>If a committer feels that a hat is abusing his or her power, - or being regularly rude to contributors, then they should bring - the matter to core. This problem can be technical, social, - procedural, or some combination or subset of these. Core will hear - the case and reach a decision, and expects both sides to abide by - their decision. Core appreciates specific complaints rather than - general ones as those are easier to resolve.</para> - - <para>Core expects committers to work together in the appropriate - mailing lists to resolve their issues. The hat and his team - should be relatively rarely involved in their role as hat, and - instead should usually be just another committer. (The one - exception to this is the security officer hat, which needs to - secretly solve vulnerabilities before they are announced.) The - hat should be a <quote>first among equals,</quote> not a chairman.</para> - -</article> diff --git a/en_US.ISO8859-1/articles/hubs/Makefile b/en_US.ISO8859-1/articles/hubs/Makefile deleted file mode 100644 index cded48ba4b..0000000000 --- a/en_US.ISO8859-1/articles/hubs/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Mirroring FreeBSD - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/hubs/article.sgml b/en_US.ISO8859-1/articles/hubs/article.sgml deleted file mode 100644 index eebcbe54a9..0000000000 --- a/en_US.ISO8859-1/articles/hubs/article.sgml +++ /dev/null @@ -1,1122 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -<!ENTITY % not.published "IGNORE"> -]> - -<article> - <articleinfo> - <title>Mirroring FreeBSD</title> - <pubdate>$FreeBSD$</pubdate> - <authorgroup> - <author> - <firstname>Jun</firstname> - <surname>Kuriyama</surname> - <affiliation> - <address><email>kuriyama@FreeBSD.org</email></address> - </affiliation> - </author> - <author> - <firstname>Valentino</firstname> - <surname>Vaschetto</surname> - <affiliation> - <address><email>logo@FreeBSD.org</email></address> - </affiliation> - </author> - <author> - <firstname>Daniel</firstname> - <surname>Lang</surname> - <affiliation> - <address><email>dl@leo.org</email></address> - </affiliation> - </author> - <author> - <firstname>Ken</firstname> - <surname>Smith</surname> - <affiliation> - <address><email>kensmith@FreeBSD.org</email></address> - </affiliation> - </author> - </authorgroup> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.cvsup; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>An in-progress article on how to mirror FreeBSD, aimed at - hub administrators.</para> - </abstract> - </articleinfo> - - <sect1 id="mirror-contact"> - <title>Contact Information</title> - - <para>The Mirror System Coordinators can be reached through email - at <email>mirror-admin@FreeBSD.org</email>. There is also - a &a.hubs;.</para> - </sect1> - - <sect1 id="mirror-requirements"> - <title>Requirements for FreeBSD mirrors</title> - <sect2 id="mirror-diskspace"> - <title>Disk Space</title> - <para> - Disk space is one of the most important requirements. - Depending on the set of releases, architectures, - and degree of completeness you want to mirror, a huge - amount of disk space may be consumed. Also keep in mind - that <emphasis>official</emphasis> mirrors are probably required to be - complete. The CVS repository and the web pages should - always be mirrored completely. Also note that the - numbers stated here are reflecting the current - state (at &rel2.current;-RELEASE/&rel.current;-RELEASE). Further development and - releases will only increase the required amount. - Also make sure to keep some (ca. 10-20%) extra space - around just to be sure. - Here are some approximate figures: - </para> - <itemizedlist> - <listitem><para>Full FTP Distribution: 126 GB</para></listitem> - <listitem><para>CVS repository: 2.7 GB</para></listitem> - <listitem><para>CTM deltas: 1.8 GB</para></listitem> - <listitem><para>Web pages: 300 MB</para></listitem> - </itemizedlist> - </sect2> - <sect2 id="mirror-bandwidth"> - <title>Network Connection/Bandwidth</title> - <para> - Of course, you need to be connected to the Internet. - The required bandwidth depends on your intended use - of the mirror. If you just want to mirror some - parts of FreeBSD for local use at your site/intranet, - the demand may be much smaller than if you want to - make the files publicly available. If you intend - to become an official mirror, the bandwidth required will be even higher. We can only give rough - estimates here: - </para> - <itemizedlist> - <listitem><para>Local site, no public access: basically no minimum, - but < 2 Mbps could make syncing too slow.</para></listitem> - <listitem><para>Unofficial public site: 34 Mbps is probably a good start.</para></listitem> - <listitem><para>Official site: > 100 Mbps is recommended, and your host - should be connected as close as possible to your border router.</para></listitem> - </itemizedlist> - </sect2> - <sect2 id="mirror-system"> - <title>System Requirements, CPU, RAM</title> - <para> - One thing this depends on the expected number of clients, - which is determined by the server's policy. It is - also affected by the types of services you want to offer. - Plain FTP or HTTP services may not require a huge - amount of resources. Watch out if you provide - CVSup, rsync or even AnonCVS. This can have a huge - impact on CPU and memory requirements. Especially - rsync is considered a memory hog, and CVSup does - indeed consume some CPU. For AnonCVS it might - be a nice idea to set up a memory resident file system (MFS) of at least - 300 MB, so you need to take this into account - for your memory requirements. The following - are just examples to give you a very rough hint. - </para> - <para> - For a moderately visited site that offers - <application>rsync</application>, you might - consider a current CPU with around 800MHz - 1 GHz, - and at least 512MB RAM. This is probably the - minimum you want for an <emphasis>official</emphasis> - site. - </para> - <para> - For a frequently used site you definitely need - more RAM (consider 2GB as a good start) - and possibly more CPU, which could also mean - that you need to go for a SMP system. - </para> - <para> - You also want to consider a fast disk subsystem. - Operations on the CVS repository require a fast - disk subsystem (RAID is highly advised). A SCSI - controller that has a cache of its own can also - speed up things since most of these services incur a - large number of small modifications to the disk. - </para> - </sect2> - <sect2 id="mirror-services"> - <title>Services to offer</title> - <para> - Every mirror site is required to have a set of core services - available. In addition to these required services, there are - a number of optional services that - server administrators may choose to offer. This section explains - which services you can provide and how to go about implementing them. - </para> - <sect3 id="mirror-serv-ftp"> - <title>FTP (required for FTP fileset)</title> - <para> - This is one of the most basic services, and - it is required for each mirror offering public - FTP distributions. FTP access must be - anonymous, and no upload/download ratios - are allowed (a ridiculous thing anyway). - Upload capability is not required (and <emphasis>must</emphasis> - never be allowed for the FreeBSD file space). - Also the FreeBSD archive should be available under - the path <filename>/pub/FreeBSD</filename>. - </para> - <para> - There is a lot of software available which - can be set up to allow anonymous FTP - (in alphabetical order). - <itemizedlist> - <listitem><para><command>/usr/libexec/ftpd</command>: FreeBSD's own ftpd - can be used. Be sure to read &man.ftpd.8;.</para> - </listitem> - <listitem> - <para><filename role="package">ftp/ncftpd</filename>: A commercial package, - free for educational use.</para> - </listitem> - <listitem> - <para><filename role="package">ftp/oftpd</filename>: An ftpd designed with - security as a main focus.</para> - </listitem> - <listitem> - <para><filename role="package">ftp/proftpd</filename>: A modular and very flexible ftpd.</para> - </listitem> - <listitem> - <para><filename role="package">ftp/pure-ftpd</filename>: Another ftpd developed with - security in mind.</para> - </listitem> - <listitem><para><filename role="package">ftp/twoftpd</filename>: As above.</para></listitem> - <listitem><para><filename role="package">ftp/vsftpd</filename>: The <quote>very secure</quote> ftpd.</para></listitem> - <listitem> - <para><filename role="package">ftp/wu-ftpd</filename>: The ftpd from Washington - University. It has become infamous, because of the huge - amount of security issues that have been found in it. - If you do choose to use this software be sure to - keep it up to date. - </para> - </listitem> - </itemizedlist> - FreeBSD's <application>ftpd</application>, <application>proftpd</application>, - <application>wu-ftpd</application> and maybe <application>ncftpd</application> - are among the most commonly ones. - The others do not have a large userbase among mirror sites. One - thing to consider is that you may need flexibility in limiting - how many simultaneous connections are allowed, thus limiting how - much network bandwidth and system resources are consumed. - </para> - </sect3> - <sect3 id="mirror-serv-rsync"> - <title>RSYNC (optional for FTP fileset)</title> - <para> - <application>rsync</application> is often offered for access to the - contents of the FTP area of FreeBSD, so other mirror sites can use your system as their source. The - protocol is different from FTP in many ways. - It is much more - bandwidth friendly, as only differences between files - are transferred instead of whole files when they change. - <application>rsync</application> does require a significant amount of memory for - each instance. The size depends on the size of - the synced module in terms of the number of directories and - files. <application>rsync</application> can use <command>rsh</command> and - <command>ssh</command> (now default) as a transport, - or use its own protocol for stand-alone access - (this is the preferred method for public rsync servers). - Authentication, connection limits, and other restrictions - may be applied. There is just one software package - available: - <itemizedlist> - <listitem><para><filename role="package">net/rsync</filename></para></listitem> - </itemizedlist> - </para> - </sect3> - <sect3 id="mirror-serv-http"> - <title>HTTP (required for web pages, optional for FTP fileset)</title> - <para> - If you want to offer the FreeBSD web pages, you need - to install a web server a.k.a. <application>httpd</application>. - You may optionally offer the FTP fileset via HTTP. - The choice of web server software is left up to the mirror administrator. - Some of the most popular choices are: - - <itemizedlist> - <listitem> - <para><filename role="package">www/apache13</filename>: - Apache is the most widely deployed web server on the Internet. It - is used extensively by the FreeBSD Project. You may also - wish to use the next generation of the Apache web server, - available in the ports collection as <filename - role="package">www/apache2</filename>.</para> - </listitem> - - <listitem> - <para><filename role="package">www/thttpd</filename>: - If you are going to be serving a large amount of static content - you may find that using an application such as thttpd is more - efficient than Apache. It is optimized for excellent performance - on FreeBSD.</para> - </listitem> - - <listitem> - <para><filename role="package">www/boa</filename>: - Boa is another alternative to thttpd and Apache. It should - provide considerably better performance than Apache for purely - static content. It does not, at the time of writing, contain the - same set of optimizations for FreeBSD that are found in - thttpd.</para> - </listitem> - </itemizedlist> - </para> - </sect3> - <sect3 id="mirror-serv-cvsup"> - <title>CVSup (desired for CVS repository)</title> - <para> - <application>CVSup</application> is a very efficient way of distributing files. - It works similar to <application>rsync</application>, but was specially designed for - use with CVS repositories. If you want to offer the - FreeBSD CVS repository, you really want to consider - offering it via <application>CVSup</application>. It is possible to offer - the CVS repository via <application>AnonCVS</application>, FTP, - <application>Rsync</application> or HTTP, but - people would benefit much more from <application>CVSup</application> access. - <application>CVSup</application> was developed by &a.jdp;. - It is a bit tricky to install on non-FreeBSD platforms, - since it is written in Modula-3 and therefore requires - a Modula-3 environment. John Polstra has built a - stripped down version of M3 that is sufficient to - run <application>CVSup</application>, and can be installed much easier. - See <ulink url="http://www.polstra.com/projects/freeware/ezm3/">Ezm3</ulink> - for details. Related ports are: - - <itemizedlist> - <listitem> - <para><filename role="package">net/cvsup</filename>: The native CVSup port (client and server) - which requires <filename role="package">lang/ezm3</filename> now.</para> - </listitem> - <listitem> - <para><filename role="package">net/cvsup-mirror</filename>: The CVSup mirror kit, which requires - <filename role="package">net/cvsup</filename>, and configures it mirror-ready. Some - site administrators may want a different setup though. - </para> - </listitem> - </itemizedlist> - - There are a few more like - <filename role="package">net/cvsup-without-gui</filename> you might want to have - a look at. If you prefer a static binary package, take a look - <ulink url="http://people.FreeBSD.org/~jdp/s1g/">here</ulink>. - This page still refers to the S1G bug that was present - in <application>CVSup</application>. Maybe - John will set up a generic download-site to get - static binaries for various platforms. - </para> - <para> - It is possible to use <application>CVSup</application> to offer - any kind of fileset, not just CVS repositories, - but configuration can be complex. - <application>CVSup</application> is known to eat some CPU on both the server and the - client, since it needs to compare lots of files. - </para> - </sect3> - <sect3 id="mirror-anoncvs"> - <title>AnonCVS (optional for CVS repository)</title> - <para> - If you have the CVS repository, you may want to offer - anonymous CVS access. A short warning first: - There is not much demand for it, - it requires some experience, and you need to know - what you are doing. - </para> - <para> - Generally there are two ways - to access a CVS repository remotely: via - <emphasis>pserver</emphasis> or via <command>ssh</command> - (we don't consider <command>rsh</command>). - For anonymous access, <emphasis>pserver</emphasis> is - very well suited, but some still offer <command>ssh</command> - access as well. There is a custom crafted - <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/FreeBSD-CVS/anoncvs.shar">wrapper</ulink> - in the CVS repository, to be used as a login-shell for the - anonymous ssh account. It does a chroot, and therefore - requires the CVS repository to be available under the - anonymous user's home-directory. This may not be possible - for all sites. If you just offer <emphasis>pserver</emphasis> - this restriction does not apply, but you may run with - more security risks. You don't need to install any special - software, since &man.cvs.1; comes with - FreeBSD. You need to enable access via <command>inetd</command>, - so add an entry into your <filename>/etc/inetd.conf</filename> - like this: - <programlisting> -cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --allow-root=/home/ncvs pserver - </programlisting> - See the manpage for details of the options. Also see the CVS <emphasis>info</emphasis> - page about additional ways to make sure access is read-only. - It is advised that you create an unprivileged account, - preferably called <username>anoncvs</username>. - Also you need to create a file <filename>passwd</filename> - in your <filename>/home/ncvs/CVSROOT</filename> and assign a - CVS password (empty or <literal>anoncvs</literal>) to that user. - The directory <filename>/anoncvstmp</filename> is a special - purpose memory based file system. It is not required but - advised since &man.cvs.1; creates a shadow directory - structure in your <filename>/tmp</filename> which is - not used after the operation but slows things - dramatically if real disk operations are required. - Here is an excerpt from <filename>/etc/fstab</filename>, - how to set up such a MFS: - <programlisting> -/dev/da0s1b /anoncvstmp mfs rw,-s=786432,-b=4096,-f=512,-i=560,-c=3,-m=0,nosuid,nodev 0 0 - </programlisting> - This is (of course) tuned a lot, and was suggested by &a.jdp;. - </para> - </sect3> - </sect2> - </sect1> - <sect1 id="mirror-howto"> - <title>How to Mirror FreeBSD</title> - <para> - Ok, now you know the requirements and how to offer - the services, but not how to get it. :-) - This section explains how to actually mirror - the various parts of FreeBSD, what tools to use, - and where to mirror from. - </para> - <sect2 id="mirror-ftp"> - <title>FTP</title> - <para> - The FTP area is the largest amount of data that - needs to be mirrored. It includes the <emphasis>distribution - sets</emphasis> required for network installation, the - <emphasis>branches</emphasis> which are actually snapshots - of checked-out source trees, the <emphasis>ISO Images</emphasis> - to write CD-ROMs with the installation distribution, - a live file system, lots of packages, the ports tree, - distfiles, and a huge amount of packages. All of course - for various FreeBSD versions, - and various architectures. - </para> - <sect3 id="mirror-ftp-ftp"> - <title>With FTP mirror</title> - <para> - You can use a <application>FTP mirror</application> - program to get the files. There are a lot around and - widely used, like: - <itemizedlist> - <listitem><para><filename role="package">ftp/mirror</filename></para></listitem> - <listitem><para><filename role="package">ftp/ftpmirror</filename></para></listitem> - <listitem><para><filename role="package">ftp/emirror</filename></para></listitem> - <listitem><para><filename role="package">ftp/spegla</filename></para></listitem> - <listitem><para><filename role="package">ftp/omi</filename></para></listitem> - <listitem><para>some even use <filename role="package">ftp/wget</filename></para></listitem> - </itemizedlist> - - <filename role="package">ftp/mirror</filename> was very popular, but seemed - to have some drawbacks, as it is written in &man.perl.1;, - and had real problems with mirroring large - directories like a FreeBSD site. There are rumors that - the current version has fixed this by allowing - a different algorithm for comparing - the directory structure to be specified. - </para> - <para> - In general FTP is not really good for mirroring. It transfers - the whole file if it has changed, and does - not create a single data stream which would benefit from - a large TCP congestion window. - </para> - </sect3> - <sect3 id="mirror-ftp-rsync"> - <title>With RSYNC</title> - <para> - A better way to mirror the FTP area is <application>rsync</application>. - You can install the port <filename role="package">net/rsync</filename> and then use - rsync to sync with your upstream host. - <application>rsync</application> is already mentioned - in <xref linkend="mirror-serv-rsync">. - Since <application>rsync</application> access is not - required, your preferred upstream site may not allow it. - You may need to hunt around a little bit to find a site - that allows <application>rsync</application> access. - <note> - <para> - Since the number of <application>rsync</application> - clients will have a significant impact on the server - machine, most admins impose limitations on their - server. For a mirror, you should ask the site maintainer - you are syncing from about their policy, and maybe - an exception for your host (since you are a mirror). - </para> - </note> - A command line to mirror FreeBSD could look like that: - <screen>&prompt.user; <userinput>rsync -vaz --delete ftp4.de.FreeBSD.org::FreeBSD/ /pub/FreeBSD/</userinput> - </screen> - Consult the documentation for <application>rsync</application>, - which is also available at - <ulink url="http://rsync.samba.org/">http://rsync.samba.org/</ulink> - about the various options to be used with rsync. - If you sync the whole module (unlike subdirectories), - be aware that the module-directory (here "FreeBSD") - will not be created, so you cannot omit the target directory. - Also you might - want to set up a script framework that calls such a command - via &man.cron.8;. - </para> - </sect3> - <sect3 id="mirror-ftp-cvsup"> - <title>With CVSup</title> - <para> - A few sites, including the one-and-only <hostid role="fqdn">ftp-master.FreeBSD.org</hostid> - even offer <application>CVSup</application> to mirror the contents of - the FTP space. You need to install a <application>cvsup</application> - client, preferably from the port <filename role="package">net/cvsup</filename>. - (Also reread <xref linkend="mirror-serv-cvsup">.) - A sample <filename>supfile</filename> suitable for <hostid role="fqdn">ftp-master.FreeBSD.org</hostid> - looks like this: - <programlisting> - # - # FreeBSD archive supfile from master server - # - *default host=ftp-master.FreeBSD.org - *default base=/usr - *default prefix=/pub - #*default release=all - *default delete use-rel-suffix - *default umask=002 - - # If your network link is a T1 or faster, comment out the following line. - #*default compress - - FreeBSD-archive release=all preserve - </programlisting> - - It seems <application>CVSup</application> would be the best - way to mirror the archive in terms of efficiency, but - it is only available from few sites. - <note id="mirror-cvsup-s-option"> - <para> - Please have look at the <application>CVSup</application> documentation - like &man.cvsup.1; and consider using the <option>-s</option> - option, as it can reduce the amount of work to be done - a lot. - </para> - </note> - </para> - </sect3> - </sect2> - <sect2 id="mirror-cvs"> - <title>Mirroring the CVS repository</title> - <para> - Again you have various possibilities, but the most - recommended one is to use <link linkend="mirror-cvs-cvsup">CVSup</link>. - </para> - <sect3 id="mirror-cvs-cvsup"> - <title>Using CVSup</title> - <para> - <application>CVSup</application> was already described to some - detail in <xref linkend="mirror-serv-cvsup"> and <xref linkend="mirror-ftp-cvsup">. - </para> - <para> - Here we just describe an example to set up the <filename>supfile</filename>: - <programlisting> - # - # FreeBSD CVS supfile from master server - # - *default host=cvsup-master.FreeBSD.org - *default base=/usr - *default prefix=/pub/FreeBSD/development/FreeBSD-CVS - *default release=cvs - *default delete use-rel-suffix - *default umask=002 - - # If your network link is a T1 or faster, comment out the following line. - #*default compress - - cvs-all - </programlisting> - - You should also have a look at <filename>/usr/share/examples/cvsup</filename> - </para> - <note> - <para> - Please do not forget to consider the hint - mentioned in <link linkend="mirror-cvsup-s-option">this note</link> - above. - </para> - </note> - </sect3> - <sect3 id="mirror-cvs-other"> - <title>Using other methods</title> - <para> - Using other methods than <application>CVSup</application> is - generally not recommended. We describe them in short here - anyway. Since most sites offer the CVS repository as - part of the FTP fileset under the path - <filename>/pub/FreeBSD/development/FreeBSD-CVS</filename>, - the following methods could be used. - <itemizedlist> - <listitem><para><application>FTP</application></para></listitem> - <listitem><para><application>RSYNC</application></para></listitem> - <listitem><para>maybe even <application>HTTP</application></para></listitem> - </itemizedlist> - - If you find a site that supports it, you could use - <filename role="package">net/sup</filename>. But it is inferior to <application>CVSup</application> - and its deficiencies caused John Polstra to develop - <application>CVSup</application> in the first place, so - it is clearly not recommended. - - <important> - <para> - You can <emphasis>NOT</emphasis> use AnonCVS to - mirror the CVS repository since CVS does not allow - you to access the repository itself, but only checked - out versions of the modules. - </para> - </important> - </para> - </sect3> - </sect2> - <sect2 id="mirror-www"> - <title>Mirroring the WWW pages</title> - <para> - The best way is to check out the <emphasis>www</emphasis> - distribution from CVS. If you have a local mirror of the - CVS repository, it is probably as easy as: - <screen>&prompt.user; <userinput>cvs -d /home/ncvs co www</userinput></screen> - and a <emphasis>cronjob</emphasis>, that calls <command>cvs up -d -P</command> - on a regular basis, maybe just after your repository was updated. - Of course, the files need to remain in a directory available - for public WWW access. The installation and configuration of a - web server is not discussed here. - </para> - - <note><para>For the website to be visible, users must execute the &man.make.1; - command in the main <filename>www</filename> directory. This command - will create the standard <filename>*.html</filename> files for web - viewing. For this to work however, the - <filename role="package">textproc/docproj</filename> port must be - installed.</para></note> - <para> - If you don't have a local repository, you can use - <application>CVSup</application> to maintain an <quote>up to date copy</quote> - of the www pages. A sample supfile can be found in - <filename>/usr/share/examples/cvsup/www-supfile</filename> and - could look like this: - <programlisting> - # - # WWW module supfile for FreeBSD - # - *default host=cvsup3.de.FreeBSD.org - *default base=/usr - *default prefix=/usr/local - *default release=cvs tag=. - *default delete use-rel-suffix - - # If your network link is a T1 or faster, comment out the following line. - *default compress - - # This collection retrieves the www/ tree of the FreeBSD repository - www - </programlisting> - </para> - <para> - Using <filename role="package">ftp/wget</filename> or other web-mirror tools is - probably not recommended. - </para> - <sect3 id="mirror-www-doc"> - <title>Mirroring the FreeBSD documentation</title> - <para> - Since the documentation is referenced a lot from the - web pages, it is recommended that you mirror the - FreeBSD documentation as well. However, this is not - as trivial as the www-pages alone. - </para> - <para> - First of all, you should get the doc sources, - again preferably via <application>CVSup</application>. - Here is a corresponding sample supfile: - <programlisting> - # - # FreeBSD documentation supfile - # - *default host=cvsup3.de.FreeBSD.org - *default base=/usr - *default prefix=/usr/share - *default release=cvs tag=. - *default delete use-rel-suffix - - # If your network link is a T1 or faster, comment out the following line. - #*default compress - - # This will retrieve the entire doc branch of the FreeBSD repository. - # This includes the handbook, FAQ, and translations thereof. - doc-all - </programlisting> - </para> - <para> - Then you need to install a couple of ports. - You are lucky, there is a meta-port: - <filename role="package">textproc/docproj</filename> to do the work - for you. You need to set up some - environment variables, like - <literal>SGML_CATALOG_FILES</literal>. - Also have a look at your <filename>/etc/make.conf</filename> - (copy <filename>/etc/defaults/make.conf</filename> if - you do not have one), and look at the - <literal>DOC_LANG</literal> variable. - Now you are probably ready to run <command>make</command> - in you doc directory (<filename>/usr/share/doc</filename> - by default) and build the documentation. - Again you need to make it accessible for your web server - and make sure the links point to the right location. - <important> - <para> - The building of the documentation, as well as lots - of side issues, is documented itself in: - <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/fdp-primer/">fdp-primer</ulink>. - Please read this piece of documentation, especially if you - have problems building the documentation. - </para> - </important> - <note> - <para> - XXX MAYBE THIS CAN BE LINKED FROM WITHIN - NOT USING AN ABSOLUTE URL XXX - </para> - </note> - </para> - </sect3> - </sect2> - <sect2 id="mirror-how-often"> - <title>How often should I mirror?</title> - <para> - Every mirror should be updated on a regular - basis. You will certainly need some script - framework for it that will be called by - &man.cron.8;. Since nearly every admin - does this his own way, we cannot give - specific instructions. It could work - like this: - </para> - <procedure> - <step> - <para> - Put the command to run your mirroring application - in a script. Use of a plain <command>/bin/sh</command> - script is recommended. - </para> - </step> - <step> - <para> - Add some output redirections so diagnostic - messages are logged to a file. - </para> - </step> - <step> - <para> - Test if your script works. Check the logs. - </para> - </step> - <step> - <para> - Use &man.crontab.1; to add the script to the - appropriate user's &man.crontab.5;. This should be a - different user than what your FTP daemon runs as so that - if file permissions inside your FTP area are not - world-readable those files can not be accessed by anonymous - FTP. This is used to <quote>stage</quote> releases — - making sure all of the official mirror sites have all of the - necessary release files on release day. - </para> - </step> - </procedure> - <para> - Here are some recommended schedules: - <itemizedlist> - <listitem><para>FTP fileset: daily</para></listitem> - <listitem><para>CVS repository: daily to hourly</para></listitem> - <listitem><para>WWW pages: daily</para></listitem> - </itemizedlist> - </para> - </sect2> - </sect1> - <sect1 id="mirror-where"> - <title>Where to mirror from</title> - <para> - This is an important issue. So this section will - spend some effort to explain the backgrounds. We will say this - several times: under no circumstances should you mirror from - <hostid role="fqdn">ftp.FreeBSD.org</hostid>. - </para> - <sect2 id="mirror-where-organization"> - <title>A few words about the organization</title> - <para> - Mirrors are organized by country. All - official mirrors have a DNS entry of the form - <hostid role="fqdn">ftpN.CC.FreeBSD.org</hostid>. - <emphasis>CC</emphasis> (i.e. country code) is the - <emphasis>top level domain</emphasis> (TLD) - of the country where this mirror is located. - <emphasis>N</emphasis> is a number, - telling that the host would be the <emphasis>Nth</emphasis> - mirror in that country. - (Same applies to <hostid>cvsupN.CC.FreeBSD.org</hostid>, - <hostid>wwwN.CC.FreeBSD.org</hostid>, etc.) - There are mirrors with no <emphasis>CC</emphasis> part. - These are the mirror sites that are very well connected and - allow a large number of concurrent users. - <hostid role="fqdn">ftp.FreeBSD.org</hostid> is actually two machines, one currently - located in Denmark and the other in the United States. - It is <emphasis>NOT</emphasis> a master site and should never be - used to mirror from. Lots of online documentation leads - <quote>interactive</quote>users to - <hostid role="fqdn">ftp.FreeBSD.org</hostid> so automated mirroring - systems should find a different machine to mirror from. - </para> - <para> - Additionally there exists a hierarchy of mirrors, which - is described in terms of <emphasis>tiers</emphasis>. - The master sites are not referred to but can be - described as <emphasis>Tier-0</emphasis>. Mirrors - that mirror from these sites can be considered - <emphasis>Tier-1</emphasis>, mirrors of <emphasis>Tier-1</emphasis>-mirrors, - are <emphasis>Tier-2</emphasis>, etc. - Official sites are encouraged to be of a low <emphasis>tier</emphasis>, - but the lower the tier the higher the requirements in - terms as described in <xref linkend="mirror-requirements">. - Also access to low-tier-mirrors may be restricted, and - access to master sites is definitely restricted. - The <emphasis>tier</emphasis>-hierarchy is not reflected - by DNS and generally not documented anywhere except - for the master sites. However, official mirrors with low numbers - like 1-4, are usually <emphasis>Tier-1</emphasis> - (this is just a rough hint, and there is no rule). - </para> - </sect2> - <sect2 id="mirror-where-where"> - <title>Ok, but where should I get the stuff now?</title> - <para> - Under no circumstances should you mirror from <hostid - role="fqdn">ftp.FreeBSD.org</hostid>. - The short answer is: from the - site that is closest to you in Internet terms, or gives you - the fastest access. - </para> - <sect3 id="mirror-where-simple"> - <title>I just want to mirror from somewhere!</title> - <para> - If you have no special intentions or - requirements, the statement in <xref linkend="mirror-where-where"> - applies. This means: - </para> - <procedure> - <step> - <para> - Look at available mirrors in your country. - The <ulink url="http://mirrorlist.FreeBSD.org/">FreeBSD - Mirror Database</ulink> can help you with this. - </para> - </step> - <step> - <para> - Check for those which provide fastest access - (number of hops, round-trip-times) - and offer the services you intend to - use (like <application>rsync</application> - or <application>CVSup</application>). - </para> - </step> - <step> - <para> - Contact the administrators of your chosen site stating your - request, and asking about their terms and - policies. - </para> - </step> - <step> - <para> - Set up your mirror as described above. - </para> - </step> - </procedure> - </sect3> - <sect3 id="mirror-where-official"> - <title>I'm an official mirror, what is the right site for me?</title> - <para> - In general the description in <xref linkend="mirror-where-simple"> - still applies. Of course you may want to put some - weight on the fact that your upstream should be of - a low tier. - There are some other considerations about <emphasis>official</emphasis> - mirrors that are described in <xref linkend="mirror-official">. - </para> - </sect3> - <sect3 id="mirror-where-master"> - <title>I want to access the master sites!</title> - <para> - If you have good reasons and good prerequisites, - you may want and get access to one of the - master sites. Access to these sites is - generally restricted, and there are special policies - for access. If you are already an <emphasis>official</emphasis> - mirror, this certainly helps you getting access. - In any other case make sure your country really needs another mirror. - If it already has three or more, ask the <quote>zone administrator</quote> (<email>hostmaster@CC.FreeBSD.org</email>) or &a.hubs; first.</para> - - <para> - Whoever helped you become, an <emphasis>official</emphasis> - should have helped you gain access to an appropriate upstream - host, either one of the master sites or a suitable Tier-1 - site. If not, you can send email to - <email>mirror-admin@FreeBSD.org</email> to request help with - that. - </para> - <para> - There are three master sites for the FTP fileset and - one for the CVS repository (the web pages and docs are - obtained from CVS, so there is no need for master). - </para> - <sect4 id="mirror-where-master-ftp"> - <title>ftp-master.FreeBSD.org</title> - <para> - This is the master site for the FTP fileset. - </para> - <para> - <hostid>ftp-master.FreeBSD.org</hostid> provides - <application>rsync</application> and <application>CVSup</application> - access, rather in addition to ftp protocol. - Refer to <xref linkend="mirror-ftp-rsync"> and - <xref linkend="mirror-ftp-cvsup"> how to access - via these protocols. - </para> - <para> - Mirrors should be encouraged to also allow <application>rsync</application> - access for the FTP contents, since they are - <emphasis>Tier-1</emphasis>-mirrors. - </para> - </sect4> - <sect4 id="mirror-where-master-cvsup"> - <title>cvsup-master.FreeBSD.org</title> - <para> - This is the master site for the CVS repository. - </para> - <para> - <hostid>cvsup-master.FreeBSD.org</hostid> provides - <application>CVSup</application> access only. - See <xref linkend="mirror-cvs-cvsup"> for details. - </para> - <para> - To get access, you need to contact &a.cvsup-master;. - Make sure you read - <ulink url="http://people.FreeBSD.org/~jdp/cvsup-access/">FreeBSD CVSup Access Policy</ulink> - first! - </para> - <para> - Set up the required authentication by following - <ulink url="http://people.FreeBSD.org/~jdp/cvpasswd/">these - instructions</ulink>. Make sure you specify the server as - <hostid>freefall.FreeBSD.org</hostid> on the <command>cvpasswd</command> - command line, as described in this document, - even when you are contacting - <hostid>cvsup-master.FreeBSD.org</hostid> - </para> - </sect4> - </sect3> - </sect2> - </sect1> - <sect1 id="mirror-official"> - <title>Official Mirrors</title> - <para> - Official mirrors are mirrors that - <itemizedlist> - <listitem> - <para> - a) have a <hostid>FreeBSD.org</hostid> DNS entry - (usually a CNAME). - </para> - </listitem> - <listitem> - <para> - b) are listed as an official mirror in the FreeBSD - documentation (like handbook). - </para> - </listitem> - </itemizedlist> - - So far to distinguish official mirrors. - Official mirrors are not necessarily <emphasis>Tier-1</emphasis>-mirrors. - However you probably won't find a <emphasis>Tier-1</emphasis>-mirror, - that is not also official. - </para> - <sect2 id="mirror-official-requirements"> - <title>Special Requirements for official (tier-1) mirrors</title> - <para> - It is not so easy to state requirements for all - official mirrors, since the project is sort of - tolerant here. It is more easy to say, - what <emphasis>official tier-1 mirrors</emphasis> - are required to. All other official mirrors - can consider this a big <emphasis>should</emphasis>. - <note> - <para> - The following applies mainly to the FTP fileset, - since a CVS repository should always be mirrored - completely, and the web pages are a case of - its own. - </para> - </note> - </para> - <para> - Tier-1 mirrors are required to: - <itemizedlist> - <listitem><para>carry the complete fileset</para></listitem> - <listitem><para>allow access to other mirror sites</para></listitem> - <listitem><para>provide <application>FTP</application> and - <application>RSYNC</application> access</para></listitem> - </itemizedlist> - - Furthermore, admins should be subscribed to the &a.hubs;. - See <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">this link</ulink> for details, how to subscribe. - </para> - <important> - <para>It is <emphasis>very</emphasis> important for a hub administrator, especially - Tier-1 hub admins, to check the - <ulink url="http://www.FreeBSD.org/releng/">release schedule</ulink> - for the next FreeBSD release. This is important because it will tell you when the - next release is scheduled - to come out, and thus giving you time to prepare for the big spike of traffic which follows it. - </para> - <para> - It is also important that hub administrators try to keep their mirrors as up-to-date as - possible (again, even more crucial for Tier-1 mirrors). If Mirror1 doesn't update for a - while, lower tier mirrors will begin to mirror old data from Mirror1 and thus begins - a downward spiral... Keep your mirrors up to date! - </para> - </important> - </sect2> - <sect2 id="mirror-official-become"> - <title>How to become official then?</title> - <para> - An interesting question, especially, since the state - of being official comes with some benefits, like a much - higher bill from your ISP as more people will be using - your site. Also it may be a key requirement to get access - to a master site. - </para> - <para> - Before applying, please consider (again) if - another official mirror is really needed for - your region. Check first with your zone administrator (<email>hostmaster@CC.FreeBSD.org</email>) or, if that fails, ask on the &a.hubs;. - </para> - <para>Ok, here is how to do it:</para> - <procedure> - <step> - <para> - Get the mirror running in first place (maybe not - using a master site, yet). - </para> - </step> - <step> - <para> - <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">Subscribe</ulink> to the &a.hubs;. - </para> - </step> - <step> - <para> - If everything works so far, contact the DNS administrator responsible - for your region/country, and ask for a DNS entry for your - site. The admin should able to be contacted via - <email>hostmaster@CC.FreeBSD.org</email>, where - <emphasis>CC</emphasis> is your country code/TLD. - Your DNS entry will be as described - in <xref linkend="mirror-where-organization">. - </para> - <para> - If there is no subdomain set up for your - country yet, you should contact - <email>mirror-admin@FreeBSD.org</email>, - or you can try the &a.hubs; first. - </para> - </step> - <step> - <para> - Whoever helps you get an official name should send email - to <email>mirror-admin@FreeBSD.org</email> so your site will be - added to the mirror list in the - <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook">FreeBSD - Handbook</ulink>. - </para> - </step> - </procedure> - <para>That is it.</para> - </sect2> - </sect1> - <sect1 id="mirror-statpages"> - <title>Some statistics from mirror sites</title> - <para> - Here are links to the stat pages of your favorite mirrors - (a.k.a. the only ones who feel like providing stats). - </para> - <sect2 id="mirror-statpagesftp"> - <title>FTP site statistics</title> - <itemizedlist> - <listitem> - <para>ftp2.FreeBSD.org - <email>grisha@ispol.com</email> - - <ulink url="http://people.FreeBSD.org/~logo/ftp2/">(Bandwidth)</ulink> - </para> - </listitem> - <listitem> - <para>ftp.is.FreeBSD.org - <email>hostmaster@is.FreeBSD.org</email> - - <ulink url="http://www.rhnet.is/status/draupnir/draupnir.html"> - (Bandwidth)</ulink> <ulink url="http://www.rhnet.is/status/ftp/ftp-notendur.html">(FTP - processes)</ulink> <ulink url="http://www.rhnet.is/status/ftp/http-notendur.html">(HTTP processes) - </ulink> - </para> - </listitem> - <listitem> - <para>ftp.cz.FreeBSD.org - <email>cejkar@fit.vutbr.cz</email> - - <ulink url="http://www.cz.FreeBSD.org/stats/mrtg/net.html">(Bandwidth)</ulink> - <ulink url="http://www.freebsd.cz/stats/mrtg/ftpd.html">(FTP processes)</ulink> - <ulink url="http://www.freebsd.cz/stats/mrtg/rsyncd.html">(Rsync processes)</ulink> - </para> - </listitem> - <listitem> - <para>ftp4.de.FreeBSD.org - <email>dl@leo.org</email> - - <ulink url="http://admin.leo.org/mrtg/services/ftp/ftp.html">(FTP users)</ulink> - <ulink url="http://admin.leo.org/mrtg/services/rsync/rsync.html">(RSYNC users)</ulink> - </para> - </listitem> - </itemizedlist> - </sect2> - <sect2 id="mirror-statpagescvsup"> - <title>CVSup site stats</title> - <itemizedlist> - <listitem> - <para>cvsup[23456].jp.FreeBSD.org - <email>kuriyama@FreeBSD.org</email> - <ulink - url="http://home.jp.FreeBSD.org/stats/mrtg/cvsup/">(CVSup processes)</ulink></para> - </listitem> - <listitem> - <para>cvsup.cz.FreeBSD.org - <email>cejkar@fit.vutbr.cz</email> - - <ulink url="http://www.freebsd.cz/stats/mrtg/cvsupd.html">(CVSup processes)</ulink></para> - </listitem> - <listitem> - <para>[cvsup3|anoncvs].de.FreeBSD.org - <email>dl@leo.org</email> - - <ulink url="http://admin.leo.org/mrtg/services/cvsup/cvsup.html">(CVSup processes)</ulink></para> - </listitem> - </itemizedlist> - </sect2> - </sect1> -</article> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO8859-1/articles/ipsec-must/Makefile b/en_US.ISO8859-1/articles/ipsec-must/Makefile deleted file mode 100644 index bcc0fec86e..0000000000 --- a/en_US.ISO8859-1/articles/ipsec-must/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Independent Verification of IPsec Functionality in FreeBSD - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/ipsec-must/article.sgml b/en_US.ISO8859-1/articles/ipsec-must/article.sgml deleted file mode 100644 index a5562b631e..0000000000 --- a/en_US.ISO8859-1/articles/ipsec-must/article.sgml +++ /dev/null @@ -1,344 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD$ ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Independent Verification of IPsec Functionality in FreeBSD</title> - - <author> - <firstname>David</firstname> - <surname>Honig</surname> - - <affiliation> - <address><email>honig@sprynet.com</email></address> - </affiliation> - </author> - - <pubdate>3 May 1999</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.opengroup; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>You installed IPsec and it seems to be working. How do you - know? I describe a method for experimentally verifying that IPsec is - working.</para> - </abstract> - </articleinfo> - - <sect1 id="problem"> - <title>The Problem</title> - - <para>First, let's assume you have <link linkend="ipsec-install"> - installed <emphasis>IPsec</emphasis></link>. How do you know - it is <link linkend="caveat">working</link>? Sure, your - connection will not work if it is misconfigured, and it will work - when you finally get it right. &man.netstat.1; will list it. - But can you independently confirm it?</para> - </sect1> - - <sect1 id="solution"> - <title>The Solution</title> - - <para>First, some crypto-relevant info theory:</para> - - <orderedlist> - <listitem> - <para>encrypted data is uniformly distributed, i.e., has maximal - entropy per symbol;</para> - </listitem> - - <listitem> - <para>raw, uncompressed data is typically redundant, i.e., has - sub-maximal entropy.</para> - </listitem> - </orderedlist> - - <para>Suppose you could measure the entropy of the data to- and - from- your network interface. Then you could see the difference - between unencrypted data and encrypted data. This would be true - even if some of the data in <quote>encrypted mode</quote> was - not encrypted---as the outermost IP header must be, if the - packet is to be routable.</para> - - <sect2 id="MUST"> - <title>MUST</title> - - <para>Ueli Maurer's <quote>Universal Statistical Test for Random - Bit Generators</quote>(<ulink - url="http://www.geocities.com/SiliconValley/Code/4704/universal.pdf"> - <acronym>MUST</acronym></ulink>) quickly measures the entropy - of a sample. It uses a compression-like algorithm. <link - linkend="code">The code is given below</link> for a variant - which measures successive (~quarter megabyte) chunks of a - file.</para> - </sect2> - - <sect2 id="tcpdump"> - <title>Tcpdump</title> - - <para>We also need a way to capture the raw network data. A - program called &man.tcpdump.1; lets you do this, if you have - enabled the <emphasis>Berkeley Packet Filter</emphasis> - interface in your <link linkend="kernel">kernel's config - file</link>.</para> - - <para>The command</para> - - <screen><userinput><command>tcpdump</command> -c 4000 -s 10000 -w <replaceable>dumpfile.bin</replaceable></userinput></screen> - - <para>will capture 4000 raw packets to - <replaceable>dumpfile.bin</replaceable>. Up to 10,000 bytes per - packet will be captured in this example.</para> - </sect2> - </sect1> - - <sect1 id="experiment"> - <title>The Experiment</title> - - <para>Here is the experiment:</para> - - <procedure> - <step> - <para>Open a window to an IPsec host and another window to an - insecure host.</para> - </step> - - <step> - <para>Now start <link linkend="tcpdump">capturing - packets</link>.</para> - </step> - - <step> - <para>In the <quote>secure</quote> window, run the &unix; - command &man.yes.1;, which will stream the <literal>y</literal> - character. After a while, stop this. Switch to the - insecure window, and repeat. After a while, stop.</para> - </step> - - <step> - <para>Now run <link linkend="code">MUST</link> on the - captured packets. You should see something like the - following. The important thing to note is that the secure - connection has 93% (6.7) of the expected value (7.18), and - the <quote>normal</quote> connection has 29% (2.1) of the - expected value.</para> - - <screen>&prompt.user; <userinput>tcpdump -c 4000 -s 10000 -w <replaceable>ipsecdemo.bin</replaceable></userinput> -&prompt.user; <userinput>uliscan <replaceable>ipsecdemo.bin</replaceable></userinput> - -Uliscan 21 Dec 98 -L=8 256 258560 -Measuring file ipsecdemo.bin -Init done -Expected value for L=8 is 7.1836656 -6.9396 -------------------------------------------------------- -6.6177 ----------------------------------------------------- -6.4100 --------------------------------------------------- -2.1101 ----------------- -2.0838 ----------------- -2.0983 -----------------</screen> - </step> - </procedure> - </sect1> - - <sect1 id="caveat"> - <title>Caveat</title> - - <para>This experiment shows that IPsec <emphasis>does</emphasis> - seem to be distributing the payload data - <emphasis>uniformly</emphasis>, as encryption should. However, - the experiment described here <emphasis>cannot</emphasis> - detect many possible flaws in a system (none of which do I have - any evidence for). These include poor key generation or - exchange, data or keys being visible to others, use of weak - algorithms, kernel subversion, etc. Study the source; know the - code.</para> - </sect1> - - <sect1 id="IPsec"> - <title>IPsec---Definition</title> - - <para>Internet Protocol security extensions to IPv4; required for - IPv6. A protocol for negotiating encryption and authentication - at the IP (host-to-host) level. SSL secures only one application - socket; <application>SSH</application> secures only a login; - <application>PGP</application> secures only a specified file or - message. IPsec encrypts everything between two hosts.</para> - </sect1> - - <sect1 id="ipsec-install"> - <title>Installing IPsec</title> - - <para>Most of the modern versions of FreeBSD have IPsec support - in their base source. So you will probably will need to include - <option>IPSEC</option> option in your kernel config and, after - kernel rebuild and reinstall, configure IPsec connections using - &man.setkey.8; command.</para> - - <para>A comprehensive guide on running IPsec on FreeBSD is - provided in <ulink - url="&url.books.handbook;/ipsec.html">FreeBSD - Handbook</ulink>.</para> - </sect1> - - <sect1 id="kernel"> - <title>src/sys/i386/conf/KERNELNAME</title> - - <para>This needs to be present in the kernel config file in order - to be able to capture network data with &man.tcpdump.1;. Be sure - to run &man.config.8; after adding this, and rebuild and - reinstall.</para> - - <programlisting>device bpf</programlisting> - </sect1> - - <sect1 id="code"> - <title>Maurer's Universal Statistical Test (for block size=8 - bits)</title> - - <para>You can find the same code at <ulink - url="http://www.geocities.com/SiliconValley/Code/4704/uliscanc.txt"> - this link</ulink>.</para> - -<programlisting>/* - ULISCAN.c ---blocksize of 8 - - 1 Oct 98 - 1 Dec 98 - 21 Dec 98 uliscan.c derived from ueli8.c - - This version has // comments removed for Sun cc - - This implements Ueli M Maurer's "Universal Statistical Test for Random - Bit Generators" using L=8 - - Accepts a filename on the command line; writes its results, with other - info, to stdout. - - Handles input file exhaustion gracefully. - - Ref: J. Cryptology v 5 no 2, 1992 pp 89-105 - also on the web somewhere, which is where I found it. - - -David Honig - honig@sprynet.com - - Usage: - ULISCAN filename - outputs to stdout -*/ - -#define L 8 -#define V (1<<L) -#define Q (10*V) -#define K (100 *Q) -#define MAXSAMP (Q + K) - -#include <stdio.h> -#include <math.h> - -int main(argc, argv) -int argc; -char **argv; -{ - FILE *fptr; - int i,j; - int b, c; - int table[V]; - double sum = 0.0; - int iproduct = 1; - int run; - - extern double log(/* double x */); - - printf("Uliscan 21 Dec 98 \nL=%d %d %d \n", L, V, MAXSAMP); - - if (argc < 2) { - printf("Usage: Uliscan filename\n"); - exit(-1); - } else { - printf("Measuring file %s\n", argv[1]); - } - - fptr = fopen(argv[1],"rb"); - - if (fptr == NULL) { - printf("Can't find %s\n", argv[1]); - exit(-1); - } - - for (i = 0; i < V; i++) { - table[i] = 0; - } - - for (i = 0; i < Q; i++) { - b = fgetc(fptr); - table[b] = i; - } - - printf("Init done\n"); - - printf("Expected value for L=8 is 7.1836656\n"); - - run = 1; - - while (run) { - sum = 0.0; - iproduct = 1; - - if (run) - for (i = Q; run && i < Q + K; i++) { - j = i; - b = fgetc(fptr); - - if (b < 0) - run = 0; - - if (run) { - if (table[b] > j) - j += K; - - sum += log((double)(j-table[b])); - - table[b] = i; - } - } - - if (!run) - printf("Premature end of file; read %d blocks.\n", i - Q); - - sum = (sum/((double)(i - Q))) / log(2.0); - printf("%4.4f ", sum); - - for (i = 0; i < (int)(sum*8.0 + 0.50); i++) - printf("-"); - - printf("\n"); - - /* refill initial table */ - if (0) { - for (i = 0; i < Q; i++) { - b = fgetc(fptr); - if (b < 0) { - run = 0; - } else { - table[b] = i; - } - } - } - } -}</programlisting> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/java-tomcat/Makefile b/en_US.ISO8859-1/articles/java-tomcat/Makefile deleted file mode 100644 index 41b2a16407..0000000000 --- a/en_US.ISO8859-1/articles/java-tomcat/Makefile +++ /dev/null @@ -1,21 +0,0 @@ -# -# $FreeBSD$ -# -# Author: Victoria Chan, Hiten Pandya -# Article: Java and Jakarta Tomcat on FreeBSD - -MAINTAINER=vkchan@kendryl.net hiten@uk.FreeBSD.org - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/java-tomcat/article.sgml b/en_US.ISO8859-1/articles/java-tomcat/article.sgml deleted file mode 100644 index 62b421d349..0000000000 --- a/en_US.ISO8859-1/articles/java-tomcat/article.sgml +++ /dev/null @@ -1,611 +0,0 @@ -<!-- Copyright (c) 2002, 2003, 2004 - Hiten Pandya <hmp@FreeBSD.org>, Victoria Chan <vkchan@kendryl.net>. - - All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, - THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS AND CONTRIBUTORS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED - OF THE POSSIBILITY OF SUCH DAMAGE. ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -<!-- - URL Entities. These are in place, to allow wrapping long URLs to the 80th - column. ---> -<!ENTITY wwwurl "http://www.FreeBSD.org"> -<!ENTITY ftpurl "ftp://ftp.FreeBSD.org"> -<!ENTITY sunurl "http://www.sun.com"> -<!ENTITY tomcaturl "http://jakarta.apache.org/tomcat"> - -<!-- The Download URL is too long! :-) --> -<!ENTITY tomcat406 "http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.0.6/bin/"> -]> - -<article> - - <!-- START of Article Metadata --> - <articleinfo> - <title>&java; and Jakarta Tomcat on FreeBSD</title> - - <authorgroup> - <author> - <firstname>Victoria</firstname> - <surname>Chan</surname> - <affiliation> - <address><email>vkchan@kendryl.net</email></address> - </affiliation> - </author> - - <author> - <firstname>Hiten</firstname> - <surname>Pandya</surname> - <affiliation> - <address><email>hmp@FreeBSD.org</email></address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2002</year> - <year>2003</year> - <year>2004</year> - <holder role="mailto:vkchan@kendryl.net">Victoria Chan</holder> - <holder role="mailto:hmp@FreeBSD.org">Hiten Pandya</holder> - </copyright> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.cvsup; - &tm-attrib.linux; - &tm-attrib.microsoft; - &tm-attrib.sun; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This document is presented in hopes of making it easier for - anyone that needs to get &java; up and running on FreeBSD, with the - least amount of aggravation. Plan on spending a whole day on such - a project as it will take time to assemble all the pieces and - compile them individually, and then as a whole. It also shows how - to install the famous Jakarta Tomcat Servlet and &jsp; container on - the FreeBSD operating system.</para> - </abstract> - </articleinfo> - <!-- END of Article Metadata--> - - <sect1> - <title>Introduction</title> - - <para>The &java; programming language was birthed on <literal>May 23rd - 1995</literal>. One would expect that after all this time, &java; - applications would be easy to install and ready to run from a single - package, or port on FreeBSD, thus making it available for the - <quote>masses</quote>. This is not the case, unfortunately, as - the &java; distribution is held very closely by Sun Microsystems, - and prohibits re-distribution. All &java; Applets must be compiled - from source code, together with the &java; Development Kit from Sun - Microsystems. All these ingredients must be blended together in - the right order, assembled, and compiled by the end user. With - such distribution philosophies at heart, it is my opinion that - &java; will always be developer or hacker use only. I certainly - found this to be true when I needed to serve up some - <filename>.jsp</filename> pages for a client on my web server, - and needed to get <filename - role="package">www/jakarta-tomcat4</filename> to work with - <filename role="package">www/apache13</filename> on my FreeBSD - system.</para> - - <para>The Tomcat portion of the install is very straight forward, but - the difficulty I had was getting &java; Development Kit up and - running for FreeBSD 4.X, as Sun Microsystems only supplies - Binaries for Linux, &solaris;, and &windowsnt;. This means that I - had to compile my own &jdk; for FreeBSD. I began by searching for - documentation on the Internet. I quickly found that there is more - source code than I need along with patches to the source code, but - very little documentation of what to do after obtaining - everything.</para> - - <para>In this article, you will find how to install the &java; - Development Kit for FreeBSD, and how to get up and running with - Tomcat. A <xref linkend="ref"> section is also provided for - further reading.</para> - </sect1> - - <sect1> - <title>The &java; Environment</title> - - <para>Ensure that you have the current ports collection as - <command>make</command> it will fail if it attempts to build older - source. You can upgrade your entire ports collection by using - <application>CVSup</application>. See <ulink - url="&url.books.handbook;/cvsup.html">Using CVSup</ulink> section - of the Handbook for more information. You can also download the - ports you need manually from <ulink - url="&ftpurl;/pub/FreeBSD/ports/"></ulink> to - get you going.</para> - - <note> - <para>You will need the <literal>Linux Emulation</literal> - (Linux-ABI) enabled in your kernel configuration. Simply add - the following option to your kernel configuration file and - recompile it. Instructions for building a kernel can be found - in the <ulink url="&url.books.handbook;/index.html">FreeBSD - Handbook</ulink>.</para> - - <programlisting>options COMPAT_LINUX</programlisting> - - <para>The above option will add Linux-ABI support to your - kernel, when it is recompiled.</para> - </note> - - <para>The list of dependencies below, are required to be installed - manually in a certain order. Dependencies that are automatically - downloaded are not listed here.</para> - - <itemizedlist> - <listitem> - <para><filename role="package">java/jdk13</filename></para> - </listitem> - - <listitem> - <para><filename role="package">java/linux-jdk13</filename></para> - </listitem> - </itemizedlist> - - <para>You will need to get the following:</para> - - <procedure> - <step> - <para>Download <filename>bsd-jdk131-patches-9.tar.gz</filename> - from <ulink - url="http://www.eyesbeyond.com/freebsddom/java/jdk13.html"></ulink> - and place it under <filename>/usr/ports/distfiles</filename>.</para> - </step> - - <step> - <para>Next get out your web browser and head on over to - <ulink url="http://java.sun.com/j2se/1.3/download-linux.html"></ulink> - and find SDK downloads. Click on the <quote>continue</quote> - button below <quote>GNUZIP Tar Shell Script</quote>. Be sure - you read every word of the license page before you click on - the <quote>Accept</quote> button! You will be brought to a - page titled <quote>Download Java(TM) 2 SDK, Standard Edition - 1.3.1_10</quote>. Scroll to the bottom and click on the - <quote>HTTP download</quote> button. When the <quote>File - Download</quote> box comes up, be sure to click on the - <quote>Open</quote> button rather than the <quote>Save</quote> - button. You will be presented with another <quote>File - Download</quote> box - this time choose <quote>Save</quote> - and you will be able to save - <filename>j2sdk-1_3_1_10-linux-i386.bin</filename>. - Place it in <filename>/usr/ports/distfiles</filename>.</para> - </step> - - <step> - <para>Go to <ulink - url="http://www.sun.com/software/java2/download.html"></ulink>. - In the table under <literal>Produce Description</literal>, - named <literal>Java 2 SDK 1.3.1</literal>, go to the - right-hand cell and click <quote>download</quote>. You will - be taken to the <quote>Sign On</quote> page, where you must - sign in if you already have an account, or register for - access. Once you have signed on, you will be taken to the - <quote>Legal</quote> page, where you must accept the license - agreement; scroll down (reading the license) and click on the - <quote>Continue</quote> button. Next page, is the - <quote>Receipt</quote> page. This is where you will save your - order number. You will be able to choose the location that is - nearest to you. Click on <quote>Java 2 SDK, Standard Edition, - version 1.3.1</quote>. Save the - <filename>j2sdk-1_3_1-src.tar.gz</filename> to the - <filename>/usr/ports/distfiles/</filename> directory.</para> - </step> - </procedure> - - <note> - <para>It is very important for you to read the License Agreement - which has been issued by Sun Microsystems Corp. There are - several restrictions in place on the use of &java;, which you must - address. The FreeBSD Project does not take any responsibilities - for your actions.</para> - - <para>Do not discard any of the downloaded files, as they will be - needed for building some of the native ports for FreeBSD, which - are discussed later on.</para> - </note> - - <para>Now that you have assembled all the source files and ports, - you need to start by building <filename - role="package">java/linux-jdk13</filename>:</para> - - <screen>&prompt.root; cd /usr/ports/java/linux-jdk13 -&prompt.root; make all install clean</screen> - - <para>Once you have built <filename - role="package">java/linux-jdk13</filename>, you need to test it, to - make sure it works as intended. To do that:</para> - - <screen>&prompt.root; cd /usr/local/linux-jdk1.3.1/bin -&prompt.root; ./java -version</screen> - - <para>The output of the above command should be as follows:</para> - - <programlisting>java version "1.3.1_10" -Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_10-b02) -Classic VM (build 1.3.1_02-b02, green threads, nojit)</programlisting> - - <para>If you did not get the correct response, you need to:</para> - - <screen>&prompt.root; cd /usr/ports/java/linux-jdk13 -&prompt.root; make deinstall</screen> - - <para>And make sure that <filename>/usr/local</filename> does not - contain a <filename>linux-jdk1.3.1</filename> directory. If you - find a fragment of the directory, delete it. Repeat the - build and install process for <filename - role="package">java/linux-jdk13</filename>.</para> - - <para>To make the native <literal>Java Development Kit - 1.3.1</literal> for FreeBSD, do the following:</para> - - <procedure> - <step> - <para>Make sure you have the - <filename>j2sdk-1_3_1-src.tar.gz</filename> file in your - <filename>/usr/ports/distfiles</filename>. This file is needed - for applying the <quote>patch-set</quote> discussed below.</para> - </step> - - <step> - <para>You will need to download the <literal>patch set</literal> - for building the port. The patch-set file is called - <filename>bsd-jdk131-patches-9.tar.gz</filename>. You should - also make sure the integrity of the files by matching it with - the following <acronym>MD5</acronym> checksum.</para> - - <programlisting> -MD5 (bsd-jdk131-patches-9.tar.gz) = 29c83880d3555abcf74fc7df9db1959f</programlisting> - - <para>The patch-set is available from: <ulink - url="http://www.eyesbeyond.com/freebsddom/java/index.html"></ulink></para> - </step> - </procedure> - - <para>The last procedure discussed above (building the native - &jdk;) will take some time.</para> - </sect1> - - <sect1> - <title>Jakarta Tomcat Setup</title> - - <sect2> - <title>Overview</title> - - <para>&java; is becoming an even more popular for making diverse - and scalable platform independent solutions. One of the most - growing needs of &java; is in the <acronym>ASP</acronym> (Application - Service Provider) market. &java; serves as the perfect - solution for these types of markets, with the following - advantages:</para> - - <itemizedlist> - <listitem> - <para>Platform Independence</para> - </listitem> - - <listitem> - <para>Industry Wide Commitment</para> - </listitem> - - <listitem> - <para>Scalability</para> - </listitem> - - <listitem> - <para>Reliable Performance</para> - </listitem> - - <listitem> - <para>Distributed, Multi-threaded, Secure etc.</para> - </listitem> - </itemizedlist> - - <para>A very important and growing technology which has emerged - from &java; is <acronym>&jsp;</acronym> (&javaserver.pages;).</para> - - <para><acronym>&jsp;</acronym> (&javaserver.pages;) is a server-side - technology introduced by <literal>Sun Microsystems - Corp.</literal>, which provides a quick simple way to generate - dynamic content from within <acronym>HTML</acronym> pages. It - uses <acronym>XML</acronym> tags along with &java; scriptlets to - encapsulate and separate the logic from the design and display. - When a <acronym>&jsp;</acronym> page is invoked, it is dynamically - converted into a Servlet and processed by the server to produce - the resulting <acronym>HTML/XML</acronym> page for the client. - When <acronym>&jsp;</acronym> is used in conjunction with - JavaBeans, it is possible to produce very diverse and scalable - applications, which may be combined with the strength and - performance of FreeBSD.</para> - - <para><application>Tomcat</application> is an open-source - implementation of the &java; Servlets and &javaserver.pages; - technologies, developed under the Jakarta project at the Apache - Software Foundation. Tomcat implements a new Servlet framework - (called Catalina) that is based on completely new architecture - with the Servlet 2.3 and <acronym>&jsp;</acronym> 1.2 - specifications. It includes many additional features that make - it a useful platform for developing and deploying web - applications and web services. In a nutshell, Tomcat is an - application server written in 100% Pure &java;.</para> - - <para>Tomcat is used for many purposes, and is not limited to - Application Servers. It provides an open platform to develop - extensible web and content management services. When Tomcat is - used with an optimized FreeBSD system, it can provide highly - reliable and fast pacing services.</para> - - <para>Please refer to the <xref linkend="ref"> section for more - information on Tomcat and <acronym>&jsp;</acronym>. The next - section will demonstrate how to build the <quote>Tomcat - Environment</quote> for FreeBSD. The version of Tomcat used in - this guide is <literal>4.0.6</literal>. This version contains - major bug fixes, and the following updates/changes:</para> - - <itemizedlist> - <listitem> - <para><literal>JSP 1.2 Specification</literal></para> - </listitem> - - <listitem> - <para><literal>Java Servlet 2.3 Specification</literal></para> - </listitem> - - <listitem> - <para><literal>Full backward compatibility with the Java Servlet - 2.2 and JSP 1.1 Specification</literal></para> - </listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>The Tomcat environment for FreeBSD</title> - - <para>It is very simple to install Tomcat on a FreeBSD machine, - after setting up the necessary &java; environment, which we have - previously completed.</para> - - <para>In-order to set up Tomcat on FreeBSD, follow the below - procedure:</para> - - <procedure> - <step> - <para>Follow the above steps to set up the necessary &java; - environment.</para> - </step> - - <step> - <para>Set an environment variable <envar>JAVA_HOME</envar> - which, points to the directory where you have installed the - &jdk; (the examples below point to a native build of the - &jdk;). If you are using &man.sh.1; as your shell, you can set - <envar>JAVA_HOME</envar> with:</para> - - <screen>&prompt.root; export JAVA_HOME="/usr/local/jdk1.3.1"</screen> - - <para>Those who use &man.csh.1; or a compatible shell, must use a - slightly different command:</para> - - <screen>&prompt.root; setenv JAVA_HOME /usr/local/jdk1.3.1</screen> - - <para>This environment variable should be made permanent by - adding it into either <filename>.profile</filename> or - <filename>.cshrc</filename>, depending on the shell you are - using. This variable is very crucial for the functioning of - all the &java; based programs, including Tomcat itself.</para> - </step> - - <step> - <para>Download the Tomcat <quote>binary distribution</quote> - from the Jakarta website, which is located at - <literal><ulink url="&tomcat406"></ulink></literal>. The - file to download is called - <filename>jakarta-tomcat-4.0.6.tar.gz</filename>.</para> - </step> - - <step> - <para>The compressed and archived file we downloaded in the - previous step uses special <quote>GNU Extensions</quote>. - In-order to untar and uncompress the file, we will need to - install <literal>GNU Tar (<filename - role="package">archivers/gtar</filename>)</literal>, by - doing the following:</para> - - <screen>&prompt.root; cd /usr/ports/archivers/gtar && make all install clean</screen> - </step> - - <step> - <para>Un-tar and Un-compress the - <filename>jakarta-tomcat-4.0.6.tar.gz</filename> file into - the <filename>/usr/local</filename> directory and rename the - directory to <filename>tomcat-4.0</filename> for ease of - reference:</para> - - <screen>&prompt.root; cd /usr/local -&prompt.root; gtar zxvf jakarta-tomcat-4.0.6.tar.gz -&prompt.root; ls jakarta* -jakarta-tomcat-4.0.6 -&prompt.root; mv jakarta-tomcat-4.0.6 tomcat-4.0</screen> - - <para>You can remove the - <filename>jakarta-tomcat-4.0.6.tar.gz</filename> at your - preference.</para> - </step> - </procedure> - - <note> - <para><literal>Installation by using the source code is currently - out of scope for this document. Please refer to the following - files for addition information on building from source, - available from your Tomcat distribution - directory:</literal></para> - - <itemizedlist> - <listitem> - <para><filename>/usr/local/tomcat-4.0/README.txt</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/tomcat-4.0/BUILDING.txt</filename></para> - </listitem> - </itemizedlist> - </note> - </sect2> - - <sect2> - <title>Operating Tomcat - Basics</title> - - <para>Now that we have finished installing Tomcat. The following - example shows how to start the Tomcat server:</para> - - <screen>&prompt.root; cd /usr/local/tomcat-4.0/bin -&prompt.root; ./startup.sh (for starting Tomcat)</screen> - - <para>You can test if your Tomcat server has started by visiting - the following URL: <literal>http://127.0.0.1:8080</literal> or - <literal>http://localhost:8080</literal>. To stop - Tomcat:</para> - - <screen>&prompt.root; cd /usr/local/tomcat-4.0/bin -&prompt.root; ./shutdown.sh</screen> - - <para>(for stopping Tomcat)</para> - - <para>The <filename>startup.sh</filename> and - <filename>shutdown.sh</filename> are frontends to the - <filename>catalina.sh</filename> executable script in the same - directory; if you would like to start Tomcat automatically at - boot-time run:</para> - - <screen>&prompt.root; cd /usr/local/etc/rc.d -&prompt.root; ln -s /usr/local/tomcat-4.0/bin/catalina.sh</screen> - - <para>Edit the <filename>catalina.sh</filename>, and add the - following at the beginning of the file (after the comment - box):</para> - - <programlisting>JAVA_HOME=/usr/local/jdk1.3.1</programlisting> - - <para>If your port <literal>8080</literal> is occupied by some other - service, you can change it by editing the - <filename>server.xml</filename> in your Tomcat's - <filename>conf/</filename> directory. In the example below, the - port will be changed to 80, assuming there is no service running - on that port.</para> - - <screen>&prompt.root; cd /usr/local/tomcat-4.0/conf -&prompt.root; fgrep -n 8080 server.xml -~65: By default, a non-SSL HTTP/1.1 Connector is established on port 8080. -~89: port="8080" minProcessors="5" maxProcessors="75" -&prompt.root; cat server.xml | sed s/8080/80/ > server.xml.new -&prompt.root; mv server.xml.new server.xml</screen> - </sect2> - </sect1> - - <sect1 id="ref" xreflabel="reference"> - <title>Reference</title> - - <informaltable frame="none"> - <tgroup cols="1"> - <tbody> - <row> - <entry> - <ulink url="&wwwurl;/java">The FreeBSD &java; Project</ulink> - </entry> - </row> - - <row> - <entry> - <ulink url="http://java.sun.com">JavaSoft. Home of &java;</ulink> - </entry> - </row> - - <row> - <entry> - <ulink - url="&sunurl;/software/communitysource/java2/licensing.html">The - Sun Community Source Licensing for &java;</ulink> - </entry> - </row> - - <row> - <entry> - <ulink url="&tomcaturl">Jakarta Tomcat Homepage</ulink> - </entry> - </row> - - <row> - <entry> - <ulink url="http://java.sun.com/docs/index.html">J2SE - Documentation</ulink> - </entry> - </row> - - <row> - <entry> - <ulink url="&wwwurl;/ports/java.html">FreeBSD Ports - &java; - Section</ulink> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <sect2> - <title>Conclusion</title> - - <para>Finally, we are at the end of the article and have a working - version of Tomcat. We hope that you have learned the basics of - installing and building the &java; Development Kit on FreeBSD, - along with installation of the Tomcat binary distribution - application server released by the Apache Software Foundation. - The <xref linkend="ref"> section contains pointers to additional - resources on this topic, some which are in print, some which are - on the World Wide Web, or both.</para> - - <para>The most important thing is drive space. I suggest having - <literal>700MB</literal> or more free space in - <filename>/usr</filename>. I hope this article has helped you - in some small way. For questions, comments, compliments, or - rants, please direct them to the authors.</para> - </sect2> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/laptop/Makefile b/en_US.ISO8859-1/articles/laptop/Makefile deleted file mode 100644 index 554a79327f..0000000000 --- a/en_US.ISO8859-1/articles/laptop/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -# -# $FreeBSD$ -# -# Article: FreeBSD on Laptops -# - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/laptop/article.sgml b/en_US.ISO8859-1/articles/laptop/article.sgml deleted file mode 100644 index ea6d649d0a..0000000000 --- a/en_US.ISO8859-1/articles/laptop/article.sgml +++ /dev/null @@ -1,304 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>FreeBSD on Laptops</title> - - <pubdate>$FreeBSD$</pubdate> - - <abstract> - <para>FreeBSD works fine on most laptops, with a few caveats. - Some issues specific to running FreeBSD on laptops, relating - to different hardware requirements from desktops, are - discussed below.</para> - </abstract> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.linux; - &tm-attrib.microsoft; - &tm-attrib.xfree86; - &tm-attrib.general; - </legalnotice> - </articleinfo> - - <para>FreeBSD is often thought of as a server operating system, but - it works just fine on the desktop, and if you want to use it on - your laptop you can enjoy all the usual benefits: systematic - layout, easy administration and upgrading, the ports/packages - system for adding software, and so on. (Its other benefits, - such as stability, network performance, and performance under - a heavy load, may not be obvious on a laptop, of course.) - However, installing it on laptops often involves problems which - are not encountered on desktop machines and are not commonly - discussed (laptops, even more than desktops, are fine-tuned for - µsoft.windows;). This article aims to discuss some of these - issues. Several people have also documented their experiences - with &os; on specific laptop models on webpages which are not - part of the &os; documentation. You might very well find some - information if you type the name of your laptop model and the - word <quote>&os;</quote> into a search engine of your - choice. Additionally there is a &os;-specific online database - which aims to give information on hardware issues with laptops, - <ulink url="http://gerda.univie.ac.at/freebsd-laptops/">The &os; - Laptop Compatibility List</ulink>.</para> - - <para>For communications with other &os; laptop users, check out - the &a.mobile.name; list.</para> - - <sect1> - <title>&xfree86;</title> - - <para>Recent versions of <application>&xfree86;</application> work with most display adapters - available on laptops these days. Acceleration may not be - supported, but a generic SVGA configuration should work.</para> - - <para>Check your laptop documentation for which card you have, - and check in the <application>&xfree86;</application> documentation or - the <ulink - url="http://www.xfree86.org/current/Status.html">Driver Status for - &xfree86;</ulink> page - to see whether it is specifically supported. If it is not, use - a generic device (do not go for a name which just looks - similar). In <application>&xfree86;</application> version 4, you can try your luck - with the command <userinput>XFree86 -configure</userinput> - which auto-detects a lot of configurations.</para> - - <para>The problem often is configuring the monitor. Common - resources for <application>&xfree86;</application> focus on CRT monitors; getting a - suitable modeline for an LCD display may be tricky. You may - be lucky and not need to specify a modeline, or just need to - specify suitable <literal>HorizSync</literal> and <literal>VertRefresh</literal> ranges. If that - does not work, the best option is to check web resources - devoted to configuring X on laptops (these are often - Linux oriented sites but it does not matter because both systems - use <application>&xfree86;</application>) and copy a modeline posted by someone for similar - hardware.</para> - - <para>Most laptops come with two buttons on their pointing - devices, which is rather problematic in X (since the middle - button is commonly used to paste text); you can map a - simultaneous left-right click in your X configuration to - a middle button click with the line</para> - - <programlisting> - Option "Emulate3Buttons" - </programlisting> - - <para>in the <filename>XF86Config</filename> file in the <literal>InputDevice</literal> - section (for <application>&xfree86;</application> version 4; for version 3, put just the line - <literal>Emulate3Buttons</literal>, without the quotes, in the - <literal>Pointer</literal> section.)</para> - </sect1> - - <sect1> - <title>Modems</title> - <para> - Laptops usually come with internal (on-board) modems. - Unfortunately, this almost always means they are - <quote>winmodems</quote> whose - functionality is implemented in software, for which only &windows; - drivers are normally available (though a few drivers are beginning - to show up for other operating systems; for example, if your modem has a Lucent LT chipset it might be supported by the <filename role="package">comms/ltmdm</filename> port). If that is the case, you - need to buy an external modem: the most compact option is - probably a PC Card (PCMCIA) modem, discussed below, but - serial or USB modems may be cheaper. Generally, regular - modems (non-winmodems) should work fine. - </para> - - </sect1> - - <sect1> - <title>PCMCIA (PC Card) devices</title> - - <para> Most laptops come with PCMCIA (also called PC Card) - slots; these are supported fine under FreeBSD. Look through - your boot-up messages (using &man.dmesg.8;) and see whether these were - detected correctly (they should appear as - <devicename>pccard0</devicename>, - <devicename>pccard1</devicename> etc on devices like - <devicename>pcic0</devicename>).</para> - - <para>&os; 4.X supports 16-bit PCMCIA cards, and - &os; 5.X supports both 16-bit and - 32-bit (<quote>CardBus</quote>) cards. A database of supported - cards is in the file <filename>/etc/defaults/pccard.conf</filename>. - Look through it, and preferably buy cards listed there. Cards not - listed may also work as <quote>generic</quote> devices: in - particular most modems (16-bit) should work fine, provided they - are not winmodems (these do exist even as PC Cards, so watch out). - If your card is recognised as a generic modem, note that the - default <filename>pccard.conf</filename> file specifies a delay time of 10 seconds - (to avoid freezes on certain modems); this may well be - over-cautious for your modem, so you may want to play with it, - reducing it or removing it totally.</para> - - <para>Some parts of <filename>pccard.conf</filename> may need - editing. Check the irq line, and be sure to remove any number - already being used: in particular, if you have an on board sound - card, remove irq 5 (otherwise you may experience hangs when you - insert a card). Check also the available memory slots; if your - card is not being detected, try changing it to one of the other - allowed values (listed in the manual page &man.pccardc.8;). - </para> - - <para>If it is not running already, start the &man.pccardd.8; daemon. - (To enable it at boot time, add - <programlisting>pccard_enable="YES"</programlisting> to - <filename>/etc/rc.conf</filename>.) Now your cards should be - detected when you insert and remove them, and you should get - log messages about new devices being enabled.</para> - - <para>There have been major changes to the pccard code - (including ISA routing of interrupts, for machines where - &os; is not able to use the PCI BIOS) before the &os; 4.4 - release. If you have problems, try upgrading your system.</para> - - </sect1> - - <sect1> - - <title>Power management</title> - - <para>Unfortunately, this is not very reliably supported under - FreeBSD. If you are lucky, some functions may work reliably; - or they may not work at all.</para> - - <para>To make things a little more complex, there are two existing - standards for power management: APM and ACPI, the latter - superseding the former and including more features, but also - introducing more problems.</para> - - <para>Some laptops support both APM and ACPI (to a certain - degree), others just support one of them, so chances are that - you have to experiment with both of them to have reliable power - management on your laptop.</para> - - <note> - <para>You cannot have APM and ACPI enabled at the same time, - even if your laptop has support for both of them.</para> - </note> - - <sect2> - <title>APM</title> - - <para>The APM (Advanced Power Management) BIOS provides support - for various power management features like standby, suspend, - hibernation, CPU clock slow down etc. and is available - under &os; 4.X and &os; 5.X.</para> - - <para>To enable APM support, you can compile a kernel with power - management support (<literal>device apm0</literal> on - &os; 4.X and <literal>device apm</literal> on - &os; 5.X). A kernel module for APM is available under - &os; 5.X, to simply load the APM kernel module at boot - add the line <literal>apm_load="YES"</literal> to - <filename>/boot/loader.conf</filename>.</para> - - <para>On &os; 5.X, you also have to set - <literal>hint.apm.0.disabled="0"</literal> in - <filename>/boot/device.hints</filename>.</para> - - <para>You can start APM at boot time by having - <literal>apm_enable="YES"</literal> in - <filename>/etc/rc.conf</filename>. You may also want start - the &man.apmd.8; daemon by adding - <literal>apmd_enable="YES"</literal> to - <filename>/etc/rc.conf</filename>, which takes care of - various APM events that are posted to the BIOS, so you can - have your laptop suspend/resume by pressing some function - key on the keyboard or by closing/opening the lid.</para> - - <para>The APM commands are listed in the &man.apm.8; manual page. - For instance, <command>apm -b</command> gives you battery - status (or 255 if not supported), <command>apm -Z</command> - puts the laptop on standby, <command>apm -z</command> (or - <command>zzz</command>) suspends it. To shutdown and power - off the machine, use <command>shutdown -p</command>. Again, - some or all of these functions may not work very well or at - all.</para> - - <para>You may find that laptop suspension/standby works in - console mode but not under X (that is, the screen does not - come on again); if you are running &os; 5.X, one solution - for this might be to put <literal>options - SC_NO_SUSPEND_VTYSWITCH</literal> - in your kernel configuration file and recompile your kernel. - Another workaround is to switch to a virtual console (using - <keycombo - action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo> - or another function key) and then execute &man.apm.8;. - You can automate this with &man.vidcontrol.1;, if you are - running &man.apmd.8;. Simply edit - <filename>/etc/apmd.conf</filename> and change it to - this:</para> - - <programlisting>apm_event SUSPENDREQ { - exec "vidcontrol -s 1 < /dev/console"; - exec "/etc/rc.suspend"; -} - -apm_event USERSUSPENDREQ { - exec "vidcontrol -s 1 < /dev/console"; - exec "sync && sync && sync"; - exec "sleep 1"; - exec "apm -z"; -} - -apm_event NORMRESUME, STANDBYRESUME { - exec "/etc/rc.resume"; - exec "vidcontrol -s 9 < /dev/console"; -}</programlisting> - </sect2> - - <sect2> - <title>ACPI</title> - - <para>ACPI (Advanced Configuration and Power Management - Interface) provides not only power management but also - platform hardware discovery (superseding PnP and PCI BIOS). - ACPI is only available under &os; 5.X and is enabled by - default, so you do not have to do anything special to get it - running. You can control ACPI behaviour with - &man.acpiconf.8;.</para> - - <para>Unfortunately, vendors often ship their laptops with - broken ACPI implementations, thus having ACPI enabled - sometimes causes more problems than being useful, up to the - point that you cannot even boot &os; on some machines with - ACPI enabled.</para> - - <para>If ACPI is causing problems, you might check if your - laptop vendor has released a new BIOS version that fixes some - bugs. Since the &os; ACPI implementation is still very - evolving code, you might also want to upgrade your system; - chances are that your problems are fixed.</para> - - <para>If you want to disable ACPI simply add - <literal>hint.acpi.0.disabled="1"</literal> to - <filename>/boot/device.hints</filename>. You can disable - ACPI temporarily at the boot loader prompt by issueing - <literal>unset acpi_load</literal> if you are having problems - booting an ACPI enabled machine. &os; 5.1-RELEASE and - later come with a boot-time menu that controls how &os; is - booted. One of the proposed options is to turn off ACPI. So - to disable ACPI just select <guimenuitem>2. Boot &os; with ACPI - disabled</guimenuitem> in the menu.</para> - </sect2> - - <sect2> - <title>Display Power Management</title> - - <para>The X window system (<application>&xfree86;</application>) also includes display power - management (look at the &man.xset.1; manual page, and search for - <quote>dpms</quote> there). You may want to investigate this. However, this, - too, works inconsistently on laptops: it - often turns off the display but does not turn off the - backlight.</para> - </sect2> - - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/mailing-list-faq/Makefile b/en_US.ISO8859-1/articles/mailing-list-faq/Makefile deleted file mode 100644 index 09f7ccb2f7..0000000000 --- a/en_US.ISO8859-1/articles/mailing-list-faq/Makefile +++ /dev/null @@ -1,26 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Frequently Asked Questions About The FreeBSD Mailing Lists - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -WITH_ARTICLE_TOC?=YES - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml b/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml deleted file mode 100644 index a79cf3a1f4..0000000000 --- a/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml +++ /dev/null @@ -1,539 +0,0 @@ -<!-- $FreeBSD$ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Frequently Asked Questions About The &os; Mailing Lists</title> - - <authorgroup> - <author> - <surname>The &os; Documentation Project</surname> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <copyright> - <year>2004</year> - <holder>The &os; Documentation Project</holder> - </copyright> - - <abstract> - <para>This is the FAQ for the &os; mailing lists. If you are - interested in helping with this project, send email to the &a.doc;. - The latest version of this document is always available from the - <ulink - url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/mailing-list-faq/index.html">&os; - World Wide Web server</ulink>. It may also be downloaded as - one large <ulink url="article.html">HTML</ulink> file with HTTP - or as plain text, PostScript, PDF, etc. from the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">&os; FTP - server</ulink>. You may also want to <ulink - url="&url.base;/search/index.html">Search the - FAQ</ulink>.</para> - </abstract> - </articleinfo> - - <sect1 id="introduction"> - <title>Introduction</title> - - <para>As is usual with FAQs, this document aims to cover the - most frequently asked questions concerning the &os; mailing - lists (and of course answer them!). Although originally intended - to reduce bandwidth and avoid the same old questions being asked - over and over again, FAQs have become recognized as valuable - information resources.</para> - - <para>This document attempts to represent a community consensus, and - as such it can never really be <emphasis>authoritative</emphasis>. - However, if you find technical errors within this document, or - have suggestions about items that should be added, plase either - submit a PR, or email the &a.doc;. Thanks.</para> - - <qandaset> - <qandaentry> - <question id="purpose"> - <para>What is the purpose of the &os; mailing lists?</para> - </question> - - <answer> - <para>The &os; mailing lists serve as the primary - communication channels for the &os; community, covering many - different topic areas and communities of interest.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="audience"> - <para>Who is the audience for the &os; mailing lists?</para> - </question> - - <answer> - <para>This depends on charter of each individual list. Some - lists are more oriented to developers; some are more oriented - towards the &os; community as a whole. Please see <ulink - url="http://lists.FreeBSD.org/mailman/listinfo">this list</ulink> - for the current summary.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="participation-who"> - <para>Are the &os; mailing lists open for anyone to participate?</para> - </question> - - <answer> - <para>Again, this depends on charter of each individual list. - Please read the charter of a mailing list before you post to it, - and respect it when you post. This will help everyone to have - a better experience with the lists.</para> - - <para>If after reading the above lists, you still do not know - which mailing list to post a question to, you will probably - want to post to freebsd-questions (but see below, first).</para> - - <para>Also note that the mailing lists have traditionally - been open to postings from non-subscribers. This has - been a deliberate choice, to help make joining the &os; - community an easier process, and to encourage open sharing - of ideas. However, due to past abuse by some individuals, - certain lists now have a policy where postings from - non-subscribers must be manually screened to ensure that - they are appropriate.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="subscribe"> - <para>How can I subscribe?</para> - </question> - - <answer> - <para>You can use <ulink - url="http://lists.FreeBSD.org/mailman/listinfo"> - the Mailman web interface</ulink> to subscribe to any - of the public lists.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="unsubscribe"> - <para>How can I unsubscribe?</para> - </question> - - <answer> - <para>You can use the same interface as above; or, - you can follow the instructions that are at the - bottom of every mailing list message that is sent.</para> - - <para>Please do not send unsubscribe messages directly - to the public lists themselves. First, this will not - accomplish your goal, and second, it will irritate the - existing subscribers, and you will probably get flamed. - This is a classical mistake when using mailing lists; - please try to avoid it.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="archives"> - <para>Are archives available?</para> - </question> - - <answer> - <para>Yes. Threaded archives are available - <ulink url="http://docs.FreeBSD.org/mail/">here</ulink>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="digest"> - <para>Are mailing lists available in a digest format?</para> - </question> - - <answer> - <para>Yes. See <ulink - url="http://lists.FreeBSD.org/mailman/listinfo"> - the Mailman web interface</ulink>.</para> - </answer> - </qandaentry> - </qandaset> - </sect1> - - <sect1 id="etiquette"> - <title>Mailing List Etiquette</title> - - <para>Participation in the mailing lists, like participation - in any community, requires a common basis for communication. - Please make only appropriate postings, and follow common - rules of etiquette.</para> - - <qandaset> - <qandaentry> - <question id="before-posting"> - <para>What should I do before I post?</para> - </question> - - <answer> - <para>You have already taken the most important step by - reading this document. However, if you are new to &os;, - you may first need to familiarize yourself with the - software, and all the social history around it, by - reading the numerous - <ulink url="&url.base;/docs.html#books">books</ulink> - and - <ulink url="&url.base;/docs.html#articles">articles</ulink> - that are available. Items of particular interest - include the <ulink - url="&url.books.faq;/index.html"> - &os; Frequently Asked Questions (FAQ)</ulink> document, - the <ulink - url="&url.books.handbook;/index.html"> - &os; Handbook</ulink>, - and the articles <ulink - url="&url.articles.freebsd-questions;/article.html"> - How to get best results from the FreeBSD-questions mailing list</ulink>, - <ulink - url="&url.articles.explaining-bsd;/article.html"> - Explaining BSD</ulink>, - and <ulink - url="&url.articles.new-users;/article.html"> - &os; First Steps</ulink>.</para> - - <para>It is always considered bad form to ask a question that is - already answered in the above documents. This is not because - the volunteers who work on this project are particularly mean - people, but after a certain number of times answering the same - questions over and over again, frustration begins to set in. - This is particularly true if there is an existing answer to the - question that is already available. Always keep in mind that - almost all of the work done on &os; is done by volunteers, - and that we are only human.</para> - </answer> - - </qandaentry> - - <qandaentry> - <question id="inappropriate"> - <para>What constitutes an inappropriate posting?</para> - </question> - - <answer> - <itemizedlist> - <listitem> - <para>Postings must be in accordance with the charter - of the mailing list.</para> - </listitem> - - <listitem> - <para>Personal attacks are discouraged. As good - net.citizens, we should try to hold ourselves to high - standards of behavior.</para> - </listitem> - - <listitem> - <para>Spam is not allowed, ever. The mailing lists are - actively processed to ban offenders to this rule.</para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - - <qandaentry> - <question id="etiquette-posting"> - <para>What is considered proper etiquette when posting - to the mailing lists?</para> - </question> - - <answer> - <itemizedlist> - <listitem> - <para>Please wrap lines at 75 characters, since not - everyone uses fancy GUI mail reading programs.</para> - </listitem> - - <listitem> - <para>Please respect that fact that bandwidth is not - infinite. Not everyone reads email through high-speed - connections, so if your posting involves something like - the content of <filename>config.log</filename> or an - extensive stack trace, please consider putting that - information up on a website somewhere and just provide - a URL to it. Remember, too, that these postings will - be archived indefinitely, so huge postings will simply - inflate the size of the archives long after their - purpose has expired.</para> - </listitem> - - <listitem> - <para>Format your message so that it is legible, and - PLEASE DO NOT SHOUT!!!!!. Do not underestimate the - effect that a poorly formatted mail message has, and not - just on the &os; mailing lists. Your mail message is - all that people see of you, and if it is poorly formatted, - badly spelled, full of errors, and/or has lots of exclamation - points, it will give people a poor impression of you.</para> - </listitem> - - <listitem> - <para>Please use an appropriate human language for a - particular mailing list. Many non-English mailing - lists are - <ulink url="&url.base;/support.html#mailing-list-languages"> - available</ulink>.</para> - - <para>For the ones that are not, we do appreciate that many - people do not speak English as their first language, - and we try to make allowances for that. It is considered - particularly poor form to criticize non-native speakers - for spelling or grammatical errors. &os; has an - excellent track record in this regard; please, help us - to uphold that tradition.</para> - </listitem> - - <listitem> - <para>Please use a standards-compliant Mail User Agent (MUA). - A lot of badly formatted messages come from - <ulink url="http://www.lemis.com/email.html">bad mailers - or badly configured mailers</ulink>. The following mailers - are known to send out badly formatted messages without you - finding out about them:</para> - - <itemizedlist> - <listitem> - <para>cc:Mail</para> - </listitem> - - <listitem> - <para>&eudora; (older versions)</para> - </listitem> - - <listitem> - <para>exmh</para> - </listitem> - - <listitem> - <para>µsoft; Exchange</para> - </listitem> - - <listitem> - <para>µsoft; Internet Mail</para> - </listitem> - - <listitem> - <para>µsoft; &outlook;</para> - </listitem> - - <listitem> - <para>&netscape; (older versions)</para> - </listitem> - </itemizedlist> - - <para>As you can see, the mailers in the Microsoft world - are frequent offenders. If at all possible, use a &unix; - mailer. If you must use a mailer under Microsoft - environments, make sure it is set up correctly. Try not - to use <acronym>MIME</acronym>: a lot of people use mailers - which do not get on very well with - <acronym>MIME</acronym>.</para> - </listitem> - - <listitem> - <para>Make sure your time and time zone are set correctly. - This may seem a little silly, since your message still - gets there, but many of the people on these mailing lists - get several hundred messages a day. They frequently sort - the incoming messages by subject and by date, and if your - message does not come before the first answer, they may - assume that they missed it and not bother to look.</para> - </listitem> - - <listitem> - <para>A lot of the information you need to supply is the - output of programs, such as &man.dmesg.8;, or console - messages, which usually appear in - <filename>/var/log/messages</filename>. Do not try to copy - this information by typing it in again; not only it is a - real pain, but you are bound to make a mistake. To send log - file contents, either make a copy of the file and use an - editor to trim the information to what is relevant, or cut - and paste into your message. For the output of programs - like <command>dmesg</command>, redirect the output to a - file and include that. For example,</para> - - <screen>&prompt.user; <userinput>dmesg > /tmp/dmesg.out</userinput></screen> - - <para>This redirects the information to the file - <filename>/tmp/dmesg.out</filename>.</para> - </listitem> - - <listitem> - <para>When using cut-and-paste, please be aware that some - such operations badly mangle their messages. This is of - particular concern when posting contents of - <filename>Makefiles</filename>, where <literal>tab</literal> - is a significant character. This is a very common, - and very annoying, problem with submissions to the - <ulink url="&url.base;/support.html#gnats"> - GNATS Problem Reports database</ulink>. - <filename>Makefiles</filename> with tabs changed to either - spaces, or the annoying <literal>=3B</literal> escape - sequence, create a great deal of aggravation for - committers.</para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - - <qandaentry> - <question id="etiquette-replying"> - <para>What are the special etiquette consideration when replying - to an existing posting on the mailing lists?</para> - </question> - - <answer> - <itemizedlist> - <listitem> - <para>Please include relevant text from the original message. - Trim it to the minimum, but do not overdo it. It should - still be possible for somebody who did not read the original - message to understand what you are talking about.</para> - - <para> This is especially important for postings of the type - "yes, I see this too", where the initial posting was dozens - or hundreds of lines.</para> - </listitem> - - <listitem> - <para>Use some technique to identify which text came from - the original message, and which text you add. A common - convention is to prepend - <quote><literal>> </literal></quote> to the original - message. Leaving white space after the - <quote><literal>> </literal></quote> and leaving empty - lines between your text and the original text both make - the result more readable.</para> - </listitem> - - <listitem> - <para>Please ensure that the attributions of the text - you are quoting is correct. People can become offended - if you attribute words to them that they themselves did - not write.</para> - </listitem> - - <listitem> - <para>Please do not <literal>top post</literal>. By this, we - mean that if you are replying to a message, please put your - replies after the text that you copy in your reply.</para> - <!-- note: the question and answer are intentionally - reversed for humorous effect --> - <itemizedlist> - <listitem> - <para>A: Because it reverses the logical flow of - conversation.</para> - </listitem> - <listitem> - <para>Q: Why is top posting frowned upon?</para> - </listitem> - </itemizedlist> - <para>(Thanks to Randy Bush for the joke.)</para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - </qandaset> - </sect1> - - <sect1 id="recurring"> - <title>Recurring Topics On The Mailing Lists</title> - - <para>Participation in the mailing lists, like participation - in any community, requires a common basis for communication. - Many of the mailing lists presuppose a knowledge of the - Project's history. In particular, there are certain topics - that seem to regularly occur to newcomers to the community. - It is the responsibility of each poster to ensure that - their postings do not fall into one of these categories. - By doing so, you will help the mailing lists to stay on-topic, - and probably save yourself being flamed in the process.</para> - - <para>The best method to avoid this is to familiarize yourself - with the <ulink url="http://docs.FreeBSD.org/mail/"> - mailing list archives</ulink>, - to help yourself understand the background of - what has gone before. In this, the <ulink - url="http://www.FreeBSD.org/search/search.html#mailinglists"> - mailing list search interface</ulink> - is invaluable. (If that method does not yield useful results, - please supplement it with a search with your favorite major - search engine).</para> - - <para>By familiarizing yourself with the archives, not only will - you learn what topics have been discussed before, but also how - discussion tends to proceed on that list, who the participants - are, and who the target audience is. These are always good things - to know before you post to any mailing list, not just a &os; - mailing list.</para> - - <para>There is no doubt that the archives are quite extensive, and - some questions recur more often than others, sometimes as followups - where the subject line no longer accurately reflects the new content. - Nevertheless, the burden is on you, the poster, to do your homework - to help avoid these recurring topics, and especially the dreaded - <literal>bikeshed</literal>s.</para> - </sect1> - - <sect1 id="bikeshed"> - <title>What Is A "Bikeshed"?</title> - <para>Literally, a <literal>bikeshed</literal> is a small outdoor - shelter into which one may store one's two-wheeled form of - transportation. However, in &os; parlance, the word is a - derogatory term that refers to any oft-recurring discussion - about a particular subject; in particular, it is most often used - to refer to a topic which has never reached a consensus within - the &os; community, and instead remains controversial. (The - genesis of this term is explained in more detail <ulink - url="&url.books.faq;/misc.html#BIKESHED-PAINTING"> - in this document</ulink>). You simply must have a working - knowledge of this concept before posting to any &os; mailing - list.</para> - - <para>More generally, a bikeshed is a topic that will tend to - generate immediate meta-discussions and flames if you have - not read up on their past history.</para> - - <para>Please help us to keep the mailing lists as useful for as - many people as possible by avoiding bikesheds whenever you can. - Thanks.</para> - </sect1> - - <sect1 id="acknowledgments"> - <title>Acknowledgments</title> - - <variablelist> - <varlistentry> - <term>&a.grog;</term> - <listitem> - <para>Original author of most of the material on mailing - list etiquette, taken from the article on <ulink - url="&url.articles.freebsd-questions;/article.html"> - How to get best results from the FreeBSD-questions mailing list</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.linimon;</term> - <listitem> - <para>Creation of the rough draft of this FAQ.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - -</article> diff --git a/en_US.ISO8859-1/articles/mh/Makefile b/en_US.ISO8859-1/articles/mh/Makefile deleted file mode 100644 index 45a8cf393a..0000000000 --- a/en_US.ISO8859-1/articles/mh/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -# -# $FreeBSD$ -# -# Article: An MH Primer - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/mh/article.sgml b/en_US.ISO8859-1/articles/mh/article.sgml deleted file mode 100644 index a8a25c4000..0000000000 --- a/en_US.ISO8859-1/articles/mh/article.sgml +++ /dev/null @@ -1,815 +0,0 @@ -<!-- $FreeBSD$ --> -<!-- FreeBSD Documentation Project --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> -<article> - <articleinfo> - <title>An <application>MH</application> Primer</title> - - <authorgroup> - <author> - <firstname>Matt</firstname> - - <surname>Midboe</surname> - - <affiliation> - <address> - <email>matt@garply.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>v1.0, 16 January 1996</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.opengroup; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This document contains an introduction to using - <application>MH</application> on FreeBSD</para> - </abstract> - </articleinfo> - - <sect1 id="mhintro"> - <title>Introduction</title> - - <para><application>MH</application> started back in 1977 at the - RAND Corporation, where the initial philosophies behind - <application>MH</application> were - developed. <application>MH</application> is not so much a - monolithic email program but a philosophy about how best to - develop tools for reading email. The - <application>MH</application> developers have done a great job - adhering to the <acronym>KISS</acronym> principle: Keep It - Simple Stupid. Rather than have one large program for reading, - sending and handling email they have written specialized - programs for each part of your email life. One might liken - <application>MH</application> to the specialization that one - finds in insects and nature. Each tool in - <application>MH</application> does one thing, and does it very - well.</para> - - <para>Beyond just the various tools that one uses to handle their - email <application>MH</application> has done an excellent job - keeping the configuration of each of these tools consistent and - uniform. In fact, if you are not quite sure how something is - supposed to work or what the arguments for some command are - supposed to be, then you can generally guess and be right. Each - <application>MH</application> command is consistent about how it - handles reading the configuration files and how it takes - arguments on the command line. One useful thing to remember is - that you can always add a <option>-help</option> to the command - to have it display the options for that command.</para> - - <para>The first thing that you need to do is to make sure that you - have installed the <application>MH</application> package on your - FreeBSD machine. If you installed from CDROM you should be able - to execute the following to load <application>MH</application>: - - <informalexample> - <screen>&prompt.root; <userinput>pkg_add /cdrom/packages/mh-6.8.3.tgz</userinput></screen> - </informalexample> - - You will notice that it created a <filename>/usr/local/lib/mh</filename> - directory for you as well as adding several binaries to the - <filename>/usr/local/bin</filename> directory. If you would prefer to - compile it yourself then you can anonymous ftp it from <ulink - url="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</ulink> or <ulink - url="ftp://louie.udel.edu/">louie.udel.edu</ulink>.</para> - - <para>This primer is not a full comprehensive explanation of how - <application>MH</application> works. This is just intended to - get you started on the road to happier, faster mail reading. You - should read the manual pages for the various commands. You might - also want to read the <ulink - url="news:comp.mail.mh">comp.mail.mh</ulink> newsgroup. Also you - can read the <ulink - url="http://www.faqs.org/faqs/mail/mh-faq/">FAQ for - <application>MH</application></ulink>. The best resource for - <application>MH</application> is <ulink - url="http://www.ics.uci.edu/~mh/book/">Jerry Peek's - <application>MH</application> & nmh: Email for Users & - Programmers</ulink>.</para> - </sect1> - - <sect1> - <title>Reading Mail</title> - - <para>This section covers how to use <command>inc</command>, - <command>show</command>, <command>scan</command>, - <command>next</command>, <command>prev</command>, - <command>rmm</command>, <command>rmf</command>, and - <command>msgchk</command>. One of the best things about - <application>MH</application> is the consistent interface - between programs. One thing to keep in mind when using these - commands is how to specify message lists. In the case of - <command>inc</command> this does not really make any sense but - with commands like <command>show</command> it is useful to - know. </para> - - <para>A message list can consist of something like <parameter>23 - 20 16</parameter> which will act on messages 23, 20 and - 16. This is fairly simple but you can do more useful things - like <parameter>23-30</parameter> which will act on all the - messages between 23 and 30. You can also specify something - like <parameter>cur:10</parameter> which will act on the - current message and the next 9 messages. The - <parameter>cur</parameter>, <parameter>last</parameter>, and - <parameter>first</parameter> messages are special messages - that refer to the current, last or first message in the - folder.</para> - - <sect2 id="inc"> - <title><command>inc</command>, - <command>msgchk</command>—read in your new email or - check it</title> - - <para>If you just type in <userinput>inc</userinput> and hit - <keycap>return</keycap> you will be well on your way to - getting started with <application>MH</application>. The first - time you run <command>inc</command> it will set up your account - to use all the <application>MH</application> defaults and ask - you about creating a <filename>Mail</filename> directory under - your HOME directory. If you have mail waiting to be downloaded - you will see something that looks like:</para> - - <informalexample> - <screen> 29 01/15 Doug White Re: Another Failed to boot problem<<On Mon, 15 J - 30 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa</screen> - </informalexample> - - <para>This is the same thing you will see from a - <command>scan</command> (see <xref linkend="scan">). If you just run - <command>inc</command> with no arguments it will look on your - computer for email that is supposed to be coming to - you.</para> - - <para>A lot of people like to use POP for grabbing their email. - <application>MH</application> can do POP to grab your - email. You will need to give <command>inc</command> a few - command line arguments.</para> - - <informalexample> - <screen>&prompt.user; <userinput>inc -host mail.pop.org -user <replaceable>username</replaceable> -norpop</userinput></screen> - </informalexample> - - <para>That tells <command>inc</command> to go to - <parameter>mail.pop.org</parameter> to download your email, - and that your username on their system is - <replaceable>username</replaceable>. The - <option>-norpop</option> option tells <command>inc</command> - to use plain POP3 for downloading your - email. <application>MH</application> has support for a few - different dialects of POP. More than likely you will never - ever need to use them though. While you can do more complex - things with <command>inc</command> such as audit files and - scan format files this will get you going.</para> - - <para>The <command>msgchk</command> command is used to get information - on whether or not you have new email. <command>msgchk</command> takes - the same <option>-host</option> and <option>-user</option> - options that <command>inc</command> takes.</para> - </sect2> - - <sect2 id="show"> - <title><command>show</command>, <command>next</command> and - <command>prev</command>—displaying and moving through - email</title> - - <para><command>show</command> is to show a letter in your current - folder. Like <command>inc</command>, <command>show</command> is a fairly - straightforward command. If you just type <userinput>show</userinput> - and hit <keycap>return</keycap> then it displays the current - message. You can also give specific message numbers to - show:</para> - - <informalexample> - <screen>&prompt.user; <userinput>show 32 45 56</userinput></screen> - </informalexample> - - <para>This would display message numbers 32, 45 and 56 right - after each other. Unless you change the default behavior - <command>show</command> basically just does a <command>more</command> on the - email message.</para> - - <para><command>next</command> is used to move onto the next message and - <command>prev</command> will go to the previous message. Both - commands have an implied <command>show</command> command so that when - you go to the next message it automatically displays - it.</para> - </sect2> - - <sect2 id="scan"> - <title><command>scan</command>—shows you a scan of your - messages</title> - - <para><command>scan</command> will display a brief listing of the - messages in your current folder. This is an example of what - the <command>scan</command> command will give you.</para> - - <informalexample> - <screen> 30+ 01/16 Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of - 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea - 32 01/16 Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev - 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa</screen> - </informalexample> - - <para>Like just about everything in <application>MH</application> this display is very - configurable. This is the typical default display. It gives - you the message number, the date on the email, the sender, the - subject line, and a sentence fragment from the very beginning - of the email if it can fit it. The <literal>+</literal> means that - message is the current message, so if you do a - <command>show</command> it will display that message.</para> - - <para>One useful option for scan is the - <option>-reverse</option> option. This will list your messages - with the highest message number first and lowest message - number last. Another useful option with <command>scan</command> is to - have it read from a file. If you want to scan your incoming - mailbox on FreeBSD without having to <command>inc</command> it you - can do <command>scan -file - /var/mail/<replaceable>username</replaceable></command>. This can be used - with any file that is in the <database>mbox</database> format.</para> - </sect2> - - <sect2 id="rmm"> - <title><command>rmm</command> and <command>rmf</command>—remove the - current message or folder</title> - - <para><command>rmm</command> is used to remove a mail - message. The default is typically to not actually remove the - message but to rename the file to one that is ignored by the - <application>MH</application> commands. You will periodically - need to go through and physically delete the - <quote>removed</quote> messages.</para> - - <para>The <command>rmf</command> command is used to remove folders. - This does not just rename the files but actually removes the - from the hard drive so you should be careful when you use this - command.</para> - </sect2> - - <sect2 id="samplereading"> - <title>A typical session of reading with MH</title> - - <para>The first thing that you will want to do is - <command>inc</command> your new mail. So at a shell prompt just type - in <command>inc</command> and hit <keycap>return</keycap>.</para> - - <informalexample> - <screen>&prompt.user; <userinput>inc</userinput> -Incorporating new mail into inbox... - - 36+ 01/19 Stephen L. Lange Request...<<Please remove me as contact for pind - 37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -&prompt.user;</screen> - </informalexample> - - <para>This shows you the new email that has been added to your - mailbox. So the next thing to do is <command>show</command> the email - and move around.</para> - - <informalexample> - <screen>&prompt.user; <userinput>show</userinput> -Received: by sashimi.wwa.com (Smail3.1.29.1 #2) - id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST -Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST) -From: "Stephen L. Lange" <stvlange@wwa.com> -To: matt@garply.com -Subject: Request... -Message-Id: <Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII - - -Please remove me as contact for pindat.com - -&prompt.user; <userinput>rmm</userinput> -&prompt.user; <userinput>next</userinput> -Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8 -.6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT -Message-Id: <199601191756.RAA24416@whydos.lkg.dec.com> -X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro -tocol -To: hsu@clinet.fi -Cc: hackers@FreeBSD.org -Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet - boards) -In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100." - <199601182318.AA11772@Sysiphos> -X-Mailer: exmh version 1.5omega 10/6/94 -Date: Fri, 19 Jan 1996 17:56:40 +0000 -From: Matt Thomas <matt@lkg.dec.com> -Sender: owner-hackers@FreeBSD.org -Precedence: bulk - - -This is due to a typo in pcireg.h (to -which I am probably the guilty party).</screen> - </informalexample> - - <para>The <command>rmm</command> removed the current message and the - <command>next</command> command moved me on to the next message. Now - if I wanted to look at ten most recent messages so I could - read one of them here is what I would do:</para> - - <informalexample> - <screen>&prompt.user; <userinput>scan last:10</userinput> - 26 01/16 maddy Re: Testing some stuff<<yeah, well, Trinity has - 27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19 - 28 01/17 Evans A Criswell Re: Hey dude<<>From matt@tempest.garply.com Tue - 29 01/16 Karl Heuer need configure/make volunteers<<The FSF is looki - 30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)< - 31 01/18 Bill Lenherr Re: Linux NIS Solaris<<--- On Thu, 18 Jan 1996 1 - 34 01/19 John Fieber Re: Stuff for the email section?<<On Fri, 19 Jan - 35 01/19 support@foo.garpl [garply.com #1138] parlor<<Hello. This is the Ne - 37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl - 38 01/19 Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In -&prompt.user;</screen> - </informalexample> - - <para>Then if I wanted to read message number 27 I would do a - <userinput>show 27</userinput> and it would be displayed. As - you can probably tell from this sample session - <application>MH</application> is pretty easy to use and - looking through emails and displaying them is fairly intuitive - and easy.</para> - </sect2> - </sect1> - - <sect1> - <title>Folders and Mail Searching</title> - - <para>Anybody who gets lots of email definitely wants to be able - to prioritize, stamp, brief, de-brief, and number their emails - in a variety of different ways. <application>MH</application> - can do this better than just about anything. One thing that we - have not really talked about is the concept of folders. You have - undoubtedly come across the folders concept using other email - programs. <application>MH</application> has folders too. - <application>MH</application> can even do sub-folders of a - folder. One thing you should keep in mind with - <application>MH</application> is that when you ran - <command>inc</command> for the first time and it asked you if it - could create a <filename>Mail</filename> directory it began - storing everything in that directory. If you look at that - directory you will find a directory named - <filename>inbox</filename>. The <filename>inbox</filename> - directory houses all of your incoming mail that has not been - thrown anywhere else.</para> - - <para>Whenever you create a new folder a new directory is going to - be created underneath your <application>MH</application> - <filename>Mail</filename> directory, and messages in that folder - are going to be stored in that directory. When a new email - message comes, it is thrown into your <filename>inbox</filename> - directory with a file name that is equivalent to the message - number. So even if you did not have any of the - <application>MH</application> tools to read your email you could - still use standard &unix; commands to munge around in those - directories and just more your files. It is this simplicity that - really gives you a lot of power with what you can do with your - email.</para> - - <para>Just as you can use message lists like <parameter>23 16 - 42</parameter> with most <application>MH</application> - commands there is a folder option you can specify with just - about every <application>MH</application> command. If you do a - <command>scan +freebsd</command> it will scan your - <filename>freebsd</filename> folder, and your current folder - will be changed to <filename>freebsd</filename>. If you do a - <command>show +freebsd 23 16 42</command>, - <command>show</command> is going to switch to your - <filename>freebsd</filename> folder and display messages 23, - 16 and 42. So remember that - <option>+<replaceable>folder</replaceable></option> - syntax. You will need to make sure you use it to make commands - process different folders. Remember you default folder for - mail is <filename>inbox</filename> so doing a <command>folder - +inbox</command> should always get you back to your mail. Of - course, in <application>MH</application>'s infinite - flexibility this can be changed but most places have probably - left it as <command>inbox</command>.</para> - - <sect2> - <title><command>pick</command>—search email that matches certain - criteria</title> - - <para><command>pick</command> is one of the more complex commands in - the <application>MH</application> system. So you might want to read the - <citerefentry><refentrytitle>pick</refentrytitle><manvolnum>1</manvolnum></citerefentry> man - page for a more thorough understanding. At its simplest level - you can do something like</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -search pci</userinput> -15 -42 -55 -56 -57</screen> - </informalexample> - - <para>This will tell <command>pick</command> to look through every - single line in every message in your current folder and tell - you which message numbers it found the word <literal>pci</literal> - in. You can then <command>show</command> those messages and read them - if you wish or <command>rmm</command> them. You would have to specify - something like <command>show 15 42 55-57</command> to display them - though. A slightly more useful thing to do is this:</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -search pci -seq pick</userinput> -5 hits -&prompt.user; <userinput>show pick</userinput></screen> - </informalexample> - - <para>This will show you the same messages you just did not have - to work as hard to do it. The <option>-seq</option> option is - really an abbreviation of <option>-sequence</option> and - <command>pick</command> is just a sequence which contains the - message numbers that matched. You can use sequences with just - about any <application>MH</application> command. So you could - have done an <command>rmm pick</command> and all those - messages would be removed instead. You sequence can be named - anything. If you run pick again it will overwrite the old - sequence if you use the same name.</para> - - <para>Doing a <command>pick -search</command> can be a bit more - time consuming than just searching for message from someone, - or to someone. So <command>pick</command> allows you to use the - following predefined search criteria:</para> - - <variablelist> - <varlistentry> - <term><option>-to</option></term> - - <listitem> - <para>search based upon who the message is to</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-cc</option></term> - - <listitem> - <para>search based on who is in the <literal>Cc:</literal> list</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-from</option></term> - - <listitem> - <para>search for who sent the message</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-subject</option></term> - - <listitem> - <para>search for emails with this subject</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-date</option></term> - - <listitem> - <para>find emails with a matching date</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--<replaceable>component</replaceable></option></term> - - <listitem> - <para>search for any other component in the header. (i.e. - <option>--reply-to</option> to find all emails with a certain - reply-to in the header)</para> - </listitem> - </varlistentry> - </variablelist> - - <para>This allows you to do things like - - <informalexample> - <screen>&prompt.user; <userinput>pick -to freebsd-hackers@FreeBSD.org -seq hackers</userinput></screen> - </informalexample> - - to get a list of all the email send to the FreeBSD hackers - mailing list. <command>pick</command> also allows you to group these - criteria in different ways using the following options:</para> - - <itemizedlist> - <listitem> - <para>… <option>-and</option> …</para> - </listitem> - - <listitem> - <para>… <option>-or</option> …</para> - </listitem> - - <listitem> - <para><option>-not</option> …</para> - </listitem> - - <listitem> - <para><option>-lbrace</option> … - <option>-rbrace</option></para> - </listitem> - </itemizedlist> - - <para>These commands allow you to do things like</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -to freebsd-hackers -or -cc freebsd-hackers</userinput></screen> - </informalexample> - - <para>That will grab all the email in your <filename - role="directory">inbox</filename> that was sent to - freebsd-hackers or cc'd to that list. The brace options allow - you to group search criteria together. This is sometimes very - necessary as in the following example</para> - - <informalexample> - <screen>&prompt.user; <userinput>pick -lbrace -to freebsd-hackers -and - -not -cc freebsd-questions -rbrace -and -subject pci</userinput></screen> - </informalexample> - - <para>Basically this says <quote>pick (to freebsd-hackers and - not cc'd on freebsd-questions) and the subject is - pci</quote>. It should look through your folder and find - all messages sent to the freebsd-hackers list that are not cc'd - to the freebsd-questions list and contain <quote>pci</quote> in - the subject line. Ordinarily you might have to worry about - something called operator precedence. Remember in math how you - evaluate from left to right and you do multiplication and - division first and addition and subtraction second? - <application>MH</application> has the same type of rules for - <command>pick</command>. It is fairly complex so you might - want to study the manual page. This document is just to help - you get acquainted with <application>MH</application>.</para> - </sect2> - - <sect2> - <title><command>folder</command>, <command>folders</command>, - <command>refile</command>—three useful programs for folder - maintenance</title> - - <para>There are three programs which are primarily just for - manipulating your folders. The <command>folder</command> - program is used to switch between folders, pack them, and list - them. At its simplest level you can do a <command>folder - +<replaceable>newfolder</replaceable></command> and you will - be switched into <replaceable>newfolder</replaceable>. From - there on out all your <application>MH</application> commands - like <command>comp</command>, <command>repl</command>, - <command>scan</command>, and <command>show</command> will act - on that <command>newfolder</command> folder.</para> - - <para>Sometimes when you are reading and deleting messages you - will develop <quote>holes</quote> in your folders. If you do a - <command>scan</command> you might just see messages 34, 35, 36, 43, - 55, 56, 57, 80. If you do a <command>folder -pack</command> - this will renumber all your messages so that there are no - holes. It does not actually delete any messages though. So you - may need to periodically go through and physically delete - <command>rmm</command>'d messages.</para> - - <para>If you need statistics on your folders you can do a - <command>folders</command> or <command>folder -all</command> to list - all your folders, how many messages they have, what the - current message is in each one and so on. This line of stats - it displays for all your folders is the same one you get when - you change to a folder with <command>folder +foldername</command>. A - <command>folders</command> command looks like this:</para> - - <informalexample> - <screen> Folder # of messages ( range ); cur msg (other files) - announce has 1 message ( 1- 1). - drafts has no messages. - f-hackers has 43 messages ( 1- 43). - f-questions has 16 messages ( 1- 16). - inbox+ has 35 messages ( 1- 38); cur= 37. - lists has 8 messages ( 1- 8). - netfuture has 1 message ( 1- 1). - out has 31 messages ( 1- 31). - personal has 6 messages ( 1- 6). - todo has 58 messages ( 1- 58); cur= 1. - - TOTAL= 199 messages in 13 folders.</screen> - </informalexample> - - <para>The <command>refile</command> command is what you use to move - messages between folders. When you do something like - <command>refile 23 +netfuture</command> message number 23 is moved - into the <filename>netfuture</filename> folder. You could also do - something like <command>refile 23 +netfuture/latest</command> which - would put message number 23 in a subfolder called - <filename>latest</filename> under the <filename>netfuture</filename> folder. - If you want to keep a message in the current folder and link - it you can do a <command>refile -link 23 +netfuture</command> - which would keep 23 in your current <filename>inbox</filename> but - also list in your <filename>netfuture</filename> folder. You are - probably beginning to realize some of the really powerful - things you can do with <application>MH</application>.</para> - </sect2> - </sect1> - - <sect1> - <title>Sending Mail</title> - - <para>Email is a two way street for most people so you want to be - able to send something back. The way - <application>MH</application> handles sending mail can be a bit - difficult to follow at first, but it allows for incredible - flexibility. The first thing <application>MH</application> does - is to copy a components file into your outgoing email. A - components file is basically a skeleton email letter with stuff - like the <literal>To:</literal> and <literal>Subject:</literal> - headers already in it. You are then sent into your editor where - you fill in the header information and then type the body of - your message below the dashed lines in the message. When you - leave the editor, the <command>whatnow</command> program is run. - When you are at the <prompt>What now?</prompt> prompt you can - tell it to <command>send</command>, <command>list</command>, - <command>edit</command>, <command>push</command>, and - <command>quit</command>. Most of these commands are - self-explanatory. So the message sending process involves - copying a component file, editing your email, and then telling - the <command>whatnow</command> program what to do with your - email.</para> - - <sect2> - <title><command>comp</command>, <command>forw</command>, - <command>reply</command>—compose, forward or reply to a message - to someone</title> - - <para>The <command>comp</command> program has a few useful command line - options. The most important one to know right now is the - <option>-editor</option> option. When <application>MH</application> is installed the - default editor is usually a program called - <command>prompter</command> which comes with <application>MH</application>. It is not a very - exciting editor and basically just gets the job done. So when - you go to compose a message to someone you might want to use - <command>comp -editor /usr/bin/vi</command> or <command>comp -editor - /usr/local/bin/pico</command> instead. Once you have run - <emphasis>comp</emphasis> you are in your editor and you see - something that looks like this:</para> - - <informalexample> - <screen>To: -cc: -Subject: ---------</screen> - </informalexample> - - <para>You need to put the person you are sending the mail to - after the <literal>To:</literal> line. It works the same way for the - other headers also, so you would need to put your subject - after the <literal>Subject:</literal> line. Then you would just put - the body of your message after the dashed lines. It may seem a - bit simplistic since a lot of email programs have special - requesters that ask you for this information but there really - is no point to that. Plus this really gives you excellent - flexibility.</para> - - <informalexample> - <screen>To:<userinput>freebsd-rave@FreeBSD.org</userinput> -cc: -Subject:<userinput>And on the 8th day God created the FreeBSD core team</userinput> --------- -<userinput>Wow this is an amazing operating system. Thanks!</userinput></screen> - </informalexample> - - <para>You can now save this message and exit your editor. You - will see the <prompt>What now?</prompt> prompt and you can type in - <userinput>send</userinput> or <userinput>s</userinput> and hit - <keycap>return</keycap>. Then the FreeBSD core team will receive - their just rewards. As I mentioned earlier, you can also use - other commands at the <prompt>What now?</prompt> prompt. - For example you can use <command>quit</command>, if you do not want - to send the message.</para> - - <para>The <command>forw</command> command is stunningly similar. The - big difference being that the message you are forwarding is - automatically included in the outgoing message. When you run - <command>forw</command> it will forward your current message. You can - always tell it to forward something else by doing something - like <command>forw 23</command> and then message number 23 will be - put in your outgoing message instead of the current message. - Beyond those small differences <command>forw</command> functions - exactly the same as <command>comp</command>. You go through the exact - same message sending process.</para> - - <para>The <command>repl</command> command will reply to the - current message, unless you give it a different message to - reply to. <command>repl</command> will do its best to go ahead - and fill in some of the email headers already. So you will - notice that the <literal>To:</literal> header already has the - address of the recipient in there. Also the - <literal>Subject:</literal> line will already be filled in. - You then go about the normal message composition process and - you are done. One useful command line option to know here is - the <option>-cc</option> option. You can use - <parameter>all</parameter>, <parameter>to</parameter>, - <parameter>cc</parameter>, <parameter>me</parameter> after the - <option>-cc</option> option to have <command>repl</command> - automatically add the various addresses to the - <literal>Cc:</literal> list in the message. You have probably - noticed that the original message is not included. This is - because most <application>MH</application> setups are - configured to do this from the start.</para> - </sect2> - - <sect2> - <title><filename>components</filename>, and - <filename>replcomps</filename>—components files for - <command>comp</command> and <command>repl</command></title> - - <para>The <filename>components</filename> file is usually in - <filename>/usr/local/lib/mh</filename>. You can copy that file - into your <application>MH</application> Mail directory and - edit to contain what you want it to contain. It is a fairly - basic file. You have various email headers at the top, a - dashed line and then nothing. The <command>comp</command> - command just copies this <filename>components</filename> file - and then edits it. You can add any kind of valid RFC822 header - you want. For instance you could have something like this in - your <filename>components</filename> file:</para> - - <informalexample> - <screen>To: -Fcc: out -Subject: -X-Mailer: MH 6.8.3 -X-Home-Page: http://www.FreeBSD.org/ --------</screen> - </informalexample> - - <para><application>MH</application> would then copy this - components file and throw you into your editor. The - <filename>components</filename> file is fairly simple. If you - wanted to have a signature on those messages you would just - put your signature in that <filename>components</filename> - file.</para> - - <para>The <filename>replcomps</filename> file is a bit more complex. The - default <filename>replcomps</filename> looks like this:</para> - - <informalexample> - <screen>%(lit)%(formataddr %<{reply-to}%?{from}%?{sender}%?{return-path}%>)\ -%<(nonnull)%(void(width))%(putaddr To: )\n%>\ -%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\ -%<(nonnull)%(void(width))%(putaddr cc: )\n%>\ -%<{fcc}Fcc: %{fcc}\n%>\ -%<{subject}Subject: Re: %{subject}\n%>\ -%<{date}In-reply-to: Your message of "\ -%<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id} - %{message-id}%>\n%>\ ---------</screen> - </informalexample> - - <para>It is in the same basic format as the - <filename>components</filename> file but it contains quite a few extra - formatting codes. The <literal>%(lit)</literal> command makes room - for the address. The <literal>%(formataddr)</literal> is a function - that returns a proper email address. The next part is - <literal>%<</literal> which means if and the - <literal>{reply-to}</literal> means the reply-to field in the - original message. So that might be translated this way:</para> - - <informalexample> - <screen>%<<emphasis remap=bf>if</emphasis> {reply-to} <emphasis remap=bf>the original message has a reply-to</emphasis> -then give that to formataddr, %? <emphasis remap=bf>else</emphasis> {from} <emphasis remap=bf>take the -from address</emphasis>, %? <emphasis remap=bf>else</emphasis> {sender} <emphasis remap=bf>take the sender address</emphasis>, %? -<emphasis remap=bf>else</emphasis> {return-path} <emphasis remap=bf>take the return-path from the original -message</emphasis>, %> <emphasis remap=bf>endif</emphasis>.</screen> - </informalexample> - - <para>As you can tell <application>MH</application> formatting - can get rather involved. You can probably decipher what most - of the other functions and variables mean. All of the - information on writing these format strings is in the - MH-Format manual page. The really nice thing is that once you - have built your customized <filename>replcomps</filename> file - you will not need to touch it again. No other email program - really gives you the power and flexibility that - <application>MH</application> gives you.</para> - </sect2> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/multi-os/Makefile b/en_US.ISO8859-1/articles/multi-os/Makefile deleted file mode 100644 index 8becfa753e..0000000000 --- a/en_US.ISO8859-1/articles/multi-os/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Installing and Using FreeBSD With Other Operating Systems - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/multi-os/article.sgml b/en_US.ISO8859-1/articles/multi-os/article.sgml deleted file mode 100644 index 926303aec2..0000000000 --- a/en_US.ISO8859-1/articles/multi-os/article.sgml +++ /dev/null @@ -1,752 +0,0 @@ -<!-- $FreeBSD$ --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Installing and Using FreeBSD With Other Operating Systems</title> - - <authorgroup> - <author> - <firstname>Jay</firstname> - - <surname>Richmond</surname> - - <affiliation> - <address> - <email>jayrich@sysc.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>6 August 1996</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.ibm; - &tm-attrib.linux; - &tm-attrib.microsoft; - &tm-attrib.powerquest; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This document discusses how to make FreeBSD coexist nicely - with other popular operating systems such as Linux, &ms-dos;, - &os2;, and &windows; 95. Special thanks to: Annelise Anderson - <email>andrsn@stanford.edu</email>, Randall Hopper - <email>rhh@ct.picker.com</email>, and &a.jkh;.</para> - </abstract> - </articleinfo> - - <sect1> - <title>Overview</title> - - <para>Most people can not fit these operating systems together - comfortably without having a larger hard disk, so special - information on large EIDE drives is included. Because there are - so many combinations of possible operating systems and hard disk - configurations, the <xref linkend="ch5"> section may be of the - most use to you. It contains descriptions of specific working - computer setups that use multiple operating systems.</para> - - <para>This document assumes that you have already made room on - your hard disk for an additional operating system. Any time you - repartition your hard drive, you run the risk of destroying the - data on the original partitions. However, if your hard drive is - completely occupied by DOS, you might find the FIPS utility - (included on the FreeBSD CDROM in the - <filename>\TOOLS</filename> directory or via <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/">ftp</ulink>) - useful. It lets you repartition your hard disk without - destroying the data already on it. There is also a commercial - program available called <application>&partitionmagic;</application>, which lets you size - and delete partitions without consequence.</para> - </sect1> - - <sect1 id="ch2"> - <title>Overview of Boot Managers</title> - - <para>These are just brief descriptions of some of the different - boot managers you may encounter. Depending on your computer - setup, you may find it useful to use more than one of them on - the same system.</para> - - <variablelist> - <varlistentry> - <term>Boot Easy</term> - - <listitem> - <para>This is the default boot manager used with FreeBSD. - It has the ability to boot most anything, including BSD, - &os2; (HPFS), &windows; 95 (FAT and FAT32), and Linux. - Partitions are selected with the function keys.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&os2; Boot Manager</term> - - <listitem> - <para>This will boot FAT, FAT32, HPFS, FFS (FreeBSD), and EXT2 - (Linux). Partitions - are selected using arrow keys. The &os2; Boot Manager is - the only one to use its own separate partition, unlike the - others which use the master boot record (MBR). Therefore, - it must be installed below the 1024th cylinder to avoid - booting problems. It can boot Linux using LILO when it is - part of the boot sector, not the MBR. Go to <ulink - url="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux - HOWTOs</ulink> on the World Wide Web for more - information on booting Linux with the &os2; boot - manager.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>OS-BS</term> - - <listitem> - <para>This is an alternative to Boot Easy. It gives you more - control over the booting process, with the ability to set - the default partition to boot and the booting timeout. - The beta version of this programs allows you to boot by - selecting the OS with your arrow keys. It is included on - the FreeBSD CD in the <filename class="directory">\TOOLS</filename> - directory, and via <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/">ftp</ulink>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>LILO, or LInux LOader</term> - - <listitem> - <para>This is a limited boot manager. It will boot FreeBSD, - though some customization work is required in the LILO - configuration file.</para> - </listitem> - </varlistentry> - </variablelist> - - <note id="fat32"> - <title>About FAT32</title> - - <para>FAT32 is the replacement to the FAT filesystem included in - Microsoft's OEM SR2 Beta release, which started replacing FAT - on computers pre-loaded with &windows; 95 towards the - end of 1996. It converts the normal FAT filesystem and - allows you to use smaller cluster sizes for larger hard - drives. FAT32 also modifies the traditional FAT boot sector - and allocation table, making it incompatible with some boot - managers.</para> - </note> - </sect1> - - <sect1 id="ch3"> - <title>A Typical Installation</title> - - <para>Let's say I have two large EIDE hard drives, and I want to - install FreeBSD, Linux, and &windows; 95 on them.</para> - - <para>Here is how I might do it using these hard disks:</para> - - <itemizedlist> - <listitem> - <para><filename>/dev/wd0</filename> (first physical hard disk)</para> - </listitem> - - <listitem> - <para><filename>/dev/wd1</filename> (second hard disk)</para> - </listitem> - </itemizedlist> - - <para>Both disks have 1416 cylinders.</para> - - <procedure> - <step> - <para>I boot from a &ms-dos; or &windows; 95 boot disk that - contains the <filename>FDISK.EXE</filename> utility and make a small - 50 MB primary partition (35-40 for &windows; 95, plus a - little breathing room) on the first disk. Also create a - larger partition on the second hard disk for my &windows; - applications and data.</para> - </step> - - <step> - <para>I reboot and install &windows; 95 (easier said than done) - on the <filename>C:</filename> partition.</para> - </step> - - <step> - <para>The next thing I do is install Linux. I am not sure - about all the distributions of Linux, but <ulink url="http://www.slackware.com">Slackware</ulink> includes - LILO (see <xref linkend="ch2">). When I am partitioning out - my hard disk with Linux <command>fdisk</command>, I would - put all of Linux on the first drive (maybe 300 MB for a - nice root partition and some swap space).</para> - </step> - - <step> - <para>After I install Linux, and are prompted about installing - LILO, make <emphasis>sure</emphasis> that I install it on the boot sector of my - root Linux partition, not in the MBR (master boot - record).</para> - </step> - - <step> - <para>The remaining hard disk space can go to FreeBSD. I also - make sure that my FreeBSD root slice does not go beyond the - 1024th cylinder. (The 1024th cylinder is 528 MB into the - disk with our hypothetical 720 MB disks). I will use the - rest of the hard drive (about 270 MB) for the - <filename class="directory">/usr</filename> and <filename class="directory">/</filename> slices if I wish. The - rest of the second hard disk (size depends on the amount of - my &windows; application/data partition that I created in step - 1) can go to the <filename class="directory">/usr/src</filename> slice and swap - space.</para> - </step> - - <step> - <para>When viewed with the &windows; 95 <command>fdisk</command> - utility, my hard drives should now look something like this: - - <screen>--------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 1 - -Partition Status Type Volume_Label Mbytes System Usage -C: 1 A PRI DOS 50 FAT** 7% - 2 A Non-DOS (Linux) 300 43% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ---------------------------------------------------------------------- - - Display Partition Information - -Current fixed disk drive: 2 - -Partition Status Type Volume_Label Mbytes System Usage -D: 1 A PRI DOS 420 FAT** 60% - -Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) - -Press Esc to continue - ----------------------------------------------------------------------</screen> - ** May say FAT16 or FAT32 if you are using the OEM SR2 - update. See <xref linkend="ch2">.</para> - </step> - - <step> - <para>Install FreeBSD. I make sure to boot with my first hard - disk set at <quote>NORMAL</quote> in the BIOS. If it is not, - I will have the enter my true disk geometry at boot time (to - get this, boot &windows; 95 and consult Microsoft Diagnostics - (<filename>MSD.EXE</filename>), or check your BIOS) with the - parameter <literal>hd0=1416,16,63</literal> where - <replaceable>1416</replaceable> is the number of cylinders on my hard - disk, <replaceable>16</replaceable> is the number of heads per track, - and <replaceable>63</replaceable> is the number of sectors per track on - the drive.</para> - </step> - - <step> - <para>When partitioning out the hard disk, I make sure to - install Boot Easy on the first disk. I do not worry about - the second disk, nothing is booting off of it.</para> - </step> - - <step> - <para>When I reboot, Boot Easy should recognize my three - bootable partitions as DOS (&windows; 95), Linux, and BSD - (FreeBSD).</para> - </step> - </procedure> - </sect1> - - <sect1 id="ch4"> - <title>Special Considerations</title> - - <para>Most operating systems are very picky about where and how - they are placed on the hard disk. &windows; 95 and DOS need to be - on the first primary partition on the first hard disk. &os2; is - the exception. It can be installed on the first or second disk - in a primary or extended partition. If you are not sure, keep - the beginning of the bootable partitions below the 1024th - cylinder.</para> - - <para>If you install &windows; 95 on an existing BSD system, it will - <quote>destroy</quote> the MBR, and you will have to reinstall your - previous boot manager. Boot Easy can be reinstalled by using - the <filename>BOOTINST.EXE</filename> utility included in the <filename class="directory">\TOOLS</filename> directory on the - CDROM, and via <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/">ftp</ulink>. - You can also re-start the installation process and go to the - partition editor. From there, mark the FreeBSD partition as - bootable, select Boot Manager, and then type W to (W)rite out - the information to the MBR. You can now reboot, and Boot Easy - should then recognize &windows; 95 as DOS.</para> - - <para>Please keep in mind that &os2; can read FAT and HPFS - partitions, but not FFS (FreeBSD) or EXT2 (Linux) partitions. - Likewise, &windows; 95 can only read and write to FAT and FAT32 - (see <xref linkend="ch2">) partitions. FreeBSD can read most - filesystems, but currently cannot read HPFS partitions. Linux - can read HPFS partitions, but can not write to them. Recent - versions of the Linux kernel (2.x) can read and write to &windows; - 95 VFAT partitions (VFAT is what gives &windows; 95 long file - names - it is pretty much the same as FAT). Linux can read and - write to most filesystems. Got that? I hope so.</para> - </sect1> - - <sect1 id="ch5"> - <title>Examples</title> - - <para><emphasis>(section needs work, please send your example to - <email>jayrich@sysc.com</email>)</emphasis>.</para> - - <para>FreeBSD + &windows; 95: If you installed FreeBSD after &windows; 95, - you should see <literal>DOS</literal> on the Boot Easy menu. This is - &windows; 95. If you installed &windows; 95 after FreeBSD, read - <xref linkend="ch4"> above. As long as your hard disk does not - have 1024 cylinders you should not have a problem booting. If - one of your partitions goes beyond the 1024th cylinder however, - and you get messages like <errorname>invalid system disk</errorname> - under DOS (&windows; 95) and FreeBSD will not boot, try looking - for a setting in your BIOS called <quote>> 1024 cylinder - support</quote> or <quote>NORMAL/LBA</quote> mode. DOS may need LBA - (Logical Block Addressing) in order to boot correctly. If the - idea of switching BIOS settings every time you boot up does not - appeal to you, you can boot FreeBSD through DOS via the - <filename>FBSDBOOT.EXE</filename> utility on the CD (It should find your - FreeBSD partition and boot it.)</para> - - <para>FreeBSD + &os2; + &windows; 95: Nothing new here. The &os2; boot manager - can boot all of these operating systems, so that should not be a - problem.</para> - - <para>FreeBSD + Linux: You can also use Boot Easy to boot both - operating systems.</para> - - <para>FreeBSD + Linux + &windows; 95: (see <xref linkend="ch3">)</para> - </sect1> - - <sect1 id="sources"> - <title>Other Sources of Help</title> - - <para>There are many <ulink - url="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux - HOW-TOs</ulink> that deal with multiple operating systems on - the same hard disk.</para> - - <para>The <ulink - url="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+DOS+Win95+OS2.html">Linux+DOS+Win95+OS2 - mini-HOWTO</ulink> offers help on configuring the &os2; boot - manager, and the <ulink - url="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+FreeBSD.html">Linux+FreeBSD - mini-HOWTO</ulink> might be interesting as well. The <ulink - url="http://www.in.net/~jkatz/win95/Linux-HOWTO.html">Linux-HOWTO</ulink> - is also helpful.</para> - - <para>The <ulink - url="http://www.tburke.net/info/ntldr/ntldr_hacking_guide.htm">&windowsnt; - Loader Hacking Guide</ulink> provides good information on - multibooting &windowsnt;, &windows; 95, and DOS with other operating - systems.</para> - - <para>And Hale Landis's <quote>How It Works</quote> document pack contains some - good info on all sorts of disk geometry and booting related - topics. You can find it at - <ulink url="ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip"></ulink>.</para> - - <para>Finally, do not overlook FreeBSD's kernel documentation on - the booting procedure, available in the kernel source - distribution (it unpacks to <ulink - url="file://localhost/usr/src/sys/i386/boot/biosboot/README.386BSD">/usr/src/sys/i386/boot/biosboot/README.386BSD</ulink>.</para> - </sect1> - - <sect1> - <title>Technical Details</title> - - <para><emphasis>(Contributed by Randall Hopper, - <email>rhh@ct.picker.com</email>)</emphasis></para> - - <para>This section attempts to give you enough basic information - about your hard disks and the disk booting process so that you - can troubleshoot most problems you might encounter when getting - set up to boot several operating systems. It starts in pretty - basic terms, so you may want to skim down in this section until - it begins to look unfamiliar and then start reading.</para> - - <sect2> - <title>Disk Primer</title> - - <para>Three fundamental terms are used to describe the location - of data on your hard disk: Cylinders, Heads, and Sectors. - It is not particularly important to know what these terms - relate to except to know that, together, they identify where - data is physically on your disk.</para> - - <para>Your disk has a particular number of cylinders, number of - heads, and number of sectors per cylinder-head (a - cylinder-head also known now as a track). Collectively this - information defines the <quote>physical disk geometry</quote> for your hard - disk. There are typically 512 bytes per sector, and 63 - sectors per track, with the number of cylinders and heads - varying widely from disk to disk. Thus you can figure the - number of bytes of data that will fit on your own disk by - calculating:</para> - - <informalexample> - <para>(# of cylinders) × (# heads) × (63 - sectors/track) × (512 bytes/sect)</para> - </informalexample> - - <para>For example, on my 1.6 Gig Western Digital AC31600 EIDE hard - disk, that is:</para> - - <informalexample> - <para>(3148 cyl) × (16 heads) × (63 - sectors/track) × (512 bytes/sect)</para> - </informalexample> - - <para>which is 1,624,670,208 bytes, or around 1.6 Gig.</para> - - <para>You can find out the physical disk geometry (number of - cylinders, heads, and sectors/track counts) for your hard - disks using ATAID or other programs off the net. Your hard - disk probably came with this information as well. Be careful - though: if you are using BIOS LBA (see <xref - linkend="limits">), you can not use just any program to get - the physical geometry. This is because many programs (e.g. - <filename>MSD.EXE</filename> or FreeBSD fdisk) do not identify the - physical disk geometry; they instead report the - <firstterm>translated geometry</firstterm> (virtual numbers from using - LBA). Stay tuned for what that means.</para> - - <para>One other useful thing about these terms. Given 3 - numbers—a cylinder number, a head number, and a - sector-within-track number—you identify a specific - absolute sector (a 512 byte block of data) on your disk. - Cylinders and Heads are numbered up from 0, and Sectors are - numbered up from 1.</para> - - <para>For those that are interested in more technical details, - information on disk geometry, boot sectors, BIOSes, etc. can - be found all over the net. Query Lycos, Yahoo, etc. for - <literal>boot sector</literal> or <literal>master boot record</literal>. - Among the useful info you will find are Hale Landis's - <citetitle>How It Works</citetitle> document pack. See the <xref - linkend="sources"> section for a few pointers to this - pack.</para> - - <para>Ok, enough terminology. We are talking about booting - here.</para> - </sect2> - - <sect2 id="booting"> - <title>The Booting Process</title> - - <para>On the first sector of your disk (Cyl 0, Head 0, Sector 1) - lives the Master Boot Record (MBR). It contains a map of your - disk. It identifies up to 4 <firstterm>partitions</firstterm>, each of - which is a contiguous chunk of that disk. FreeBSD calls - partitions <firstterm>slices</firstterm> to avoid confusion with its - own partitions, but we will not do that here. Each partition can - contain its own operating system.</para> - - <para>Each partition entry in the MBR has a <firstterm>Partition - ID</firstterm>, a <firstterm>Start Cylinder/Head/Sector</firstterm>, and an - <firstterm>End Cylinder/Head/Sector</firstterm>. The Partition ID - tells what type of partition it is (what OS) and the Start/End - tells where it is. <xref linkend="tbl-pid"> lists a - smattering of some common Partition IDs.</para> - - <table id="tbl-pid"> - <title>Partition IDs</title> - - <tgroup cols="2"> - <thead> - <row> - <entry>ID (hex)</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>01</entry> - <entry>Primary DOS12 (12-bit FAT)</entry> - </row> - - <row> - <entry>04</entry> - <entry>Primary DOS16 (16-bit FAT)</entry> - </row> - - <row> - <entry>05</entry> - <entry>Extended DOS</entry> - </row> - - <row> - <entry>06</entry> - <entry>Primary big DOS (> 32MB)</entry> - </row> - - <row> - <entry>0A</entry> - <entry>&os2;</entry> - </row> - - <row> - <entry>83</entry> - <entry>Linux (EXT2FS)</entry> - </row> - - <row> - <entry>A5</entry> - <entry>FreeBSD, NetBSD, 386BSD (UFS)</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Note that not all partitions are bootable (e.g. Extended - DOS). Some are—some are not. What makes a partition - bootable is the configuration of the <firstterm>Partition Boot - Sector</firstterm> that exists at the beginning of each - partition.</para> - - <para>When you configure your favorite boot manager, it looks up - the entries in the MBR partition tables of all your hard disks - and lets you name the entries in that list. Then when you - boot, the boot manager is invoked by special code in the - Master Boot Sector of the first probed hard disk on your - system. It looks at the MBR partition table entry - corresponding to the partition choice you made, uses the Start - Cylinder/Head/Sector information for that partition, loads up - the Partition Boot Sector for that partition, and gives it - control. That Boot Sector for the partition itself contains - enough information to start loading the operating system on - that partition.</para> - - <para>One thing we just brushed past that is important to know. - All of your hard disks have MBRs. However, the one that is - important is the one on the disk that is first probed by the - BIOS. If you have only IDE hard disks, it is the first IDE disk - (e.g. primary disk on first controller). Similarly for SCSI - only systems. If you have both IDE and SCSI hard disks - though, the IDE disk is typically probed first by the BIOS, so - the first IDE disk is the first probed disk. The boot manager - you will install will be hooked into the MBR on this first - probed hard disk that we have just described.</para> - </sect2> - - <sect2 id="limits"> - <title>Booting Limitations and Warnings</title> - - <para>Now the interesting stuff that you need to watch out - for.</para> - - <sect3> - <title>The dreaded 1024 cylinder limit and how BIOS LBA helps</title> - - <para>The first part of the booting process is all done - through the BIOS, (if that is a new term to you, the BIOS is - a software chip on your system motherboard which provides - startup code for your computer). As such, this first part - of the process is subject to the limitations of the BIOS - interface.</para> - - <para>The BIOS interface used to read the hard disk during - this period (INT 13H, Subfunction 2) allocates 10 bits to - the Cylinder Number, 8 bits to the Head Number, and 6 bits - to the Sector Number. This restricts users of this - interface (i.e. boot managers hooked into your disk's MBR as - well as OS loaders hooked into the Boot Sectors) to the - following limits:</para> - - <itemizedlist> - <listitem> - <para>1024 cylinders, max</para> - </listitem> - - <listitem> - <para>256 heads, max</para> - </listitem> - - <listitem> - <para>64 sectors/track, max (actually 63, <literal>0</literal> - is not available)</para> - </listitem> - </itemizedlist> - - <para>Now big hard disks have lots of cylinders but not a lot - of heads, so invariably with big hard disks the number of - cylinders is greater than 1024. Given this and the BIOS - interface as is, you can not boot off just anywhere on your - hard disk. The boot code (the boot manager and the OS - loader hooked into all bootable partitions' Boot Sectors) - has to reside below cylinder 1024. In fact, if your hard - disk is typical and has 16 heads, this equates to:</para> - - <informalexample> - <para>1024 cyl/disk × 16 heads/disk × 63 - sect/(cyl-head) × 512 bytes/sector</para> - </informalexample> - - <para>which is around the often-mentioned 528MB limit.</para> - - <para>This is where BIOS LBA (Logical Block Addressing) comes - in. BIOS LBA gives the user of the BIOS API calls access to - physical cylinders above 1024 though the BIOS interfaces by - redefining a cylinder. That is, it remaps your cylinders - and heads, making it appear through the BIOS as though the - disk has fewer cylinders and more heads than it actually - does. In other words, it takes advantage of the fact that - hard disks have relatively few heads and lots of cylinders - by shifting the balance between number of cylinders and - number of heads so that both numbers lie below the - above-mentioned limits (1024 cylinders, 256 heads).</para> - - <para>With BIOS LBA, the hard disk size limitation is - virtually removed (well, pushed up to 8 Gigabytes anyway). - If you have an LBA BIOS, you can put FreeBSD or any OS - anywhere you want and not hit the 1024 cylinder - limit.</para> - - <para>To use my 1.6 Gig Western Digital as an example again, - its physical geometry is:</para> - - <informalexample> - <para>(3148 cyl, 16 heads, 63 sectors/track, 512 - bytes/sector)</para> - </informalexample> - - <para>However, my BIOS LBA remaps this to:</para> - - <informalexample> - <para>(787 cyl, 64 heads, 63 sectors/track, 512 - bytes/sector)</para> - </informalexample> - - <para>giving the same effective size disk, but with cylinder - and head counts within the BIOS API's range (Incidentally, I - have both Linux and FreeBSD existing on one of my hard disks - above the 1024th physical cylinder, and both operating - systems boot fine, thanks to BIOS LBA).</para> - </sect3> - - <sect3> - <title>Boot Managers and Disk Allocation</title> - - <para>Another gotcha to watch out when installing boot - managers is allocating space for your boot manager. It is - best to be aware of this issue up front to save yourself - from having to reinstall one or more of your OSs.</para> - - <para>If you followed the discussion in <xref - linkend="booting"> about the Master Boot Sector (where the - MBR is), Partition Boot Sectors, and the booting process, - you may have been wondering just exactly where on your hard - disk that nifty boot manager is going to live. Well, some - boot managers are small enough to fit entirely within the - Master Boot Sector (Cylinder 0, Head 0, Sector 0) along with - the partition table. Others need a bit more room and - actually extend a few sectors past the Master Boot Sector in - the Cylinder 0 Head 0 track, since that is typically - free…typically.</para> - - <para>That is the catch. Some operating systems (FreeBSD - included) let you start their partitions right after the - Master Boot Sector at Cylinder 0, Head 0, Sector 2 if you - want. In fact, if you give FreeBSD's sysinstall a disk with - an empty chunk up front or the whole disk empty, that is - where it will start the FreeBSD partition by default (at least - it did when I fell into this trap). Then when you go to - install your boot manager, if it is one that occupies a few - extra sectors after the MBR, it will overwrite the front of - the first partition's data. In the case of FreeBSD, this - overwrites the disk label, and renders your FreeBSD - partition unbootable.</para> - - <para>The easy way to avoid this problem (and leave yourself - the flexibility to try different boot managers later) is - just to always leave the first full track on your disk - unallocated when you partition your disk. That is, leave - the space from Cylinder 0, Head 0, Sector 2 through Cylinder - 0, Head 0, Sector 63 unallocated, and start your first - partition at Cylinder 0, Head 1, Sector 1. For what it is - worth, when you create a DOS partition at the front of your - disk, DOS leaves this space open by default (this is why - some boot managers assume it is free). So creating a DOS - partition up at the front of your disk avoids this problem - altogether. I like to do this myself, creating 1 Meg DOS - partition up front, because it also avoids my primary DOS - drive letters shifting later when I repartition.</para> - - <para>For reference, the following boot managers use the - Master Boot Sector to store their code and data:</para> - - <itemizedlist> - <listitem> - <para>OS-BS 1.35</para> - </listitem> - - <listitem> - <para>Boot Easy</para> - </listitem> - - <listitem> - <para>LILO</para> - </listitem> - </itemizedlist> - - <para>These boot managers use a few additional sectors after - the Master Boot Sector:</para> - - <itemizedlist> - <listitem> - <para>OS-BS 2.0 Beta 8 (sectors 2-5)</para> - </listitem> - - <listitem> - <para>The &os2; boot manager</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>What if your machine will not boot?</title> - - <para>At some point when installing boot managers, you might - leave the MBR in a state such that your machine will not boot. - This is unlikely, but possible when re-FDISKing underneath - an already-installed boot manager.</para> - - <para>If you have a bootable DOS partition on your disk, you - can boot off a DOS floppy, and run:</para> - - <informalexample> - <screen>A:\> <userinput>FDISK /MBR</userinput></screen> - </informalexample> - - <para>to put the original, simple DOS boot code back into the - system. You can then boot DOS (and DOS only) off the hard - drive. Alternatively, just re-run your boot manager - installation program off a bootable floppy.</para> - </sect3> - </sect2> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/new-users/Makefile b/en_US.ISO8859-1/articles/new-users/Makefile deleted file mode 100644 index 5eaabc4d5a..0000000000 --- a/en_US.ISO8859-1/articles/new-users/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -# -# $FreeBSD$ -# -# Article: For People New to Both FreeBSD and Unix - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/new-users/article.sgml b/en_US.ISO8859-1/articles/new-users/article.sgml deleted file mode 100644 index a256e10f15..0000000000 --- a/en_US.ISO8859-1/articles/new-users/article.sgml +++ /dev/null @@ -1,1059 +0,0 @@ -<!-- $FreeBSD$ --> -<!-- The FreeBSD Documentation Project --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>For People New to Both FreeBSD and &unix;</title> - - <authorgroup> - <author> - <firstname>Annelise</firstname> - - <surname>Anderson</surname> - - <affiliation> - <address><email>andrsn@andrsn.stanford.edu</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>August 15, 1997</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.ibm; - &tm-attrib.microsoft; - &tm-attrib.netscape; - &tm-attrib.opengroup; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>Congratulations on installing FreeBSD! This introduction - is for people new to both FreeBSD <emphasis>and</emphasis> - &unix;—so it starts with basics. It assumes you are using - version 2.0.5 or later of &os; as distributed by - &os;.org, your system (for now) has a single user - (you)—and you are probably pretty good with DOS/&windows; - or &os2;.</para> - </abstract> - </articleinfo> - - <sect1> - <title>Logging in and Getting Out</title> - - <para>Log in (when you see <prompt >login:</prompt>) as a user you - created during installation or as <username>root</username>. - (Your FreeBSD installation will already have an account for - <username>root</username>; who can go anywhere and do anything, including deleting - essential files, so be careful!) The symbols &prompt.user; and - &prompt.root; in the following stand for the prompt (yours may - be different), with &prompt.user; indicating an ordinary user - and &prompt.root; indicating <username>root</username>.</para> - - <para>To log out (and get a new <prompt >login:</prompt> prompt) - type</para> - - <informalexample> - <screen>&prompt.root; <userinput>exit</userinput></screen> - </informalexample> - - <para>as often as necessary. Yes, press <keysym>enter</keysym> - after commands, and remember that &unix; is - case-sensitive—<command>exit</command>, not - <command>EXIT</command>.</para> - - <para>To shut down the machine type</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/shutdown -h now</userinput></screen> - </informalexample> - - <para>Or to reboot type</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/shutdown -r now</userinput></screen> - </informalexample> - - <para>or</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/reboot</userinput></screen> - </informalexample> - - <para>You can also reboot with - <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Delete</keycap></keycombo>. - Give it a little time to do its work. This is equivalent to - <command>/sbin/reboot</command> in recent releases of FreeBSD - and is much, much better than hitting the reset button. You - do not want to have to reinstall this thing, do you?</para> - </sect1> - - <sect1> - <title>Adding A User with Root Privileges</title> - - <para>If you did not create any users when you installed the system - and are thus logged in as <username>root</username>, you should probably create a - user now with</para> - - <informalexample> - <screen>&prompt.root; <userinput>adduser</userinput></screen> - </informalexample> - - <para>The first time you use <command>adduser</command>, it might ask for some - defaults to save. You might want to make the default shell - &man.csh.1; instead of &man.sh.1;, if it suggests - <command>sh</command> as the default. Otherwise just press - enter to accept each default. These defaults are saved in - <filename>/etc/adduser.conf</filename>, an editable file.</para> - - <para>Suppose you create a user <username>jack</username> with - full name <emphasis>Jack Benimble</emphasis>. Give <username>jack</username> a - password if security (even kids around who might pound on the - keyboard) is an issue. When it asks you if you want to invite - <username>jack</username> into other groups, type <groupname>wheel</groupname></para> - - <informalexample> - <screen>Login group is ``jack''. Invite jack into other groups: <userinput>wheel</userinput></screen> - </informalexample> - - <para>This will make it possible to log in as - <username>jack</username> and use the &man.su.1; - command to become <username>root</username>. Then you will not get scolded any more for - logging in as <username>root</username>.</para> - - <para>You can quit <command>adduser</command> any time by typing - <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>, - and at the end you will have a chance to approve your new user or - simply type <keycap>n</keycap> for no. You might want to create - a second new user so that when you edit <username>jack</username>'s login - files, you will have a hot spare in case something goes - wrong.</para> - - <para>Once you have done this, use <command>exit</command> to get - back to a login prompt and log in as <username>jack</username>. - In general, it is a good idea to do as much work as possible as - an ordinary user who does not have the power—and - risk—of <username>root</username>.</para> - - <para>If you already created a user and you want the user to be - able to <command>su</command> to <username>root</username>, you can log in as <username>root</username> - and edit the file <filename>/etc/group</filename>, adding <username>jack</username> - to the first line (the group <groupname>wheel</groupname>). But - first you need to practice &man.vi.1;, the text editor—or - use the simpler text editor, &man.ee.1;, installed on recent - versions of FreeBSD.</para> - - <para>To delete a user, use the <command>rmuser</command> - command.</para> - </sect1> - - <sect1> - <title>Looking Around</title> - - <para>Logged in as an ordinary user, look around and try out some - commands that will access the sources of help and information - within FreeBSD.</para> - - <para>Here are some commands and what they do:</para> - - <variablelist> - <varlistentry> - <term><command>id</command></term> - - <listitem> - <para>Tells you who you are!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>pwd</command></term> - - <listitem> - <para>Shows you where you are—the current working - directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls</command></term> - - <listitem> - <para>Lists the files in the current directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls <option>-F</option></command></term> - - <listitem> - <para>Lists the files in the current directory with a - <literal>*</literal> after executables, a - <literal>/</literal> after directories, and an - <literal>@</literal> after symbolic links.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls <option>-l</option></command></term> - - <listitem> - <para>Lists the files in long format—size, date, - permissions.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls <option>-a</option></command></term> - - <listitem> - <para>Lists hidden <quote>dot</quote> files with the others. - If you are <username>root</username>, the <quote>dot</quote> files show up - without the <option>-a</option> switch.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>cd</command></term> - - <listitem> - <para>Changes directories. <command>cd - <parameter>..</parameter></command> backs up one level; - note the space after <command>cd</command>. <command>cd - <parameter>/usr/local</parameter></command> goes there. - <command>cd <parameter>~</parameter></command> goes to the - home directory of the person logged in—e.g., - <filename>/usr/home/jack</filename>. Try <command>cd - <parameter>/cdrom</parameter></command>, and then - <command>ls</command>, to find out if your CDROM is - mounted and working.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>view - <replaceable>filename</replaceable></command></term> - - <listitem> - <para>Lets you look at a file (named - <replaceable>filename</replaceable>) without changing it. - Try <command>view - <parameter>/etc/fstab</parameter></command>. - Type <command>:q</command> to quit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>cat - <replaceable>filename</replaceable></command></term> - - <listitem> - <para>Displays <replaceable>filename</replaceable> on - screen. If it is too long and you can see only the end of - it, press <keycap>ScrollLock</keycap> and use the - <keycap>up-arrow</keycap> to move backward; you can use - <keycap>ScrollLock</keycap> with manual pages too. Press - <keycap>ScrollLock</keycap> again to quit scrolling. You - might want to try <command>cat</command> on some of the - dot files in your home directory—<command>cat - <parameter>.cshrc</parameter></command>, <command>cat - <parameter>.login</parameter></command>, <command>cat - <parameter>.profile</parameter></command>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>You will notice aliases in <filename>.cshrc</filename> for - some of the <command>ls</command> commands (they are very - convenient). You can create other aliases by editing - <filename>.cshrc</filename>. You can make these aliases - available to all users on the system by putting them in the - system-wide <command>csh</command> configuration file, - <filename>/etc/csh.cshrc</filename>.</para> - </sect1> - - <sect1> - <title>Getting Help and Information</title> - - <para>Here are some useful sources of help. - <replaceable>Text</replaceable> stands for something of your - choice that you type in—usually a command or - filename.</para> - - <variablelist> - <varlistentry> - <term><command>apropos - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Everything containing string - <replaceable>text</replaceable> in the <database>whatis - database</database>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>man - <replaceable>text</replaceable></command></term> - - <listitem> - <para>The manual page for <replaceable>text</replaceable>. The - major source of documentation for &unix; systems. - <command>man <parameter>ls</parameter></command> will tell - you all the ways to use the <command>ls</command> command. - Press <keycap>Enter</keycap> to move through text, - <keycombo><keycap>Ctrl</keycap><keycap>B</keycap></keycombo> - to go back a page, - <keycombo><keycap>Ctrl</keycap><keycap>F</keycap></keycombo> - to go forward, <keycap>q</keycap> or - <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> - to quit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>which - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Tells you where in the user's path the command - <replaceable>text</replaceable> is found.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>locate - <replaceable>text</replaceable></command></term> - - <listitem> - <para>All the paths where the string - <replaceable>text</replaceable> is found.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>whatis - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Tells you what the command - <replaceable>text</replaceable> does and its manual page. - Typing <command>whatis *</command> will tell you about all - the binaries in the current directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>whereis - <replaceable>text</replaceable></command></term> - - <listitem> - <para>Finds the file <replaceable>text</replaceable>, giving - its full path.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>You might want to try using <command>whatis</command> on - some common useful commands like <command>cat</command>, - <command>more</command>, <command>grep</command>, - <command>mv</command>, <command>find</command>, - <command>tar</command>, <command>chmod</command>, - <command>chown</command>, <command>date</command>, and - <command>script</command>. <command>more</command> lets you - read a page at a time as it does in DOS, e.g., <command>ls -l | - more</command> or <command>more - <replaceable>filename</replaceable></command>. The - <literal>*</literal> works as a wildcard—e.g., <command>ls - w*</command> will show you files beginning with - <literal>w</literal>.</para> - - <para>Are some of these not working very well? Both - &man.locate.1; and &man.whatis.1; depend - on a database that is rebuilt weekly. If your machine is not - going to be left on over the weekend (and running FreeBSD), you - might want to run the commands for daily, weekly, and monthly - maintenance now and then. Run them as <username>root</username> and, for now, give each one - time to finish before you start the next one.</para> - - <informalexample> - <screen>&prompt.root; <userinput>periodic daily</userinput> -<lineannotation>output omitted</lineannotation> -&prompt.root; <userinput>periodic weekly</userinput> -<lineannotation>output omitted</lineannotation> -&prompt.root; <userinput>periodic monthly</userinput> -<lineannotation>output omitted</lineannotation></screen> - </informalexample> - - <para>If you get tired of waiting, press - <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to - get another <firstterm>virtual console</firstterm>, and log in - again. After all, it is a multi-user, multi-tasking system. - Nevertheless these commands will probably flash messages on your - screen while they are running; you can type - <command>clear</command> at the prompt to clear the screen. - Once they have run, you might want to look at - <filename>/var/mail/root</filename> and - <filename>/var/log/messages</filename>.</para> - - <para>Running such commands is part of system - administration—and as a single user of a &unix; system, - you are your own system administrator. Virtually everything you - need to be <username>root</username> to do is system administration. Such - responsibilities are not covered very well even in those big fat - books on &unix;, which seem to devote a lot of space to pulling - down menus in windows managers. You might want to get one of - the two leading books on systems administration, either Evi - Nemeth et.al.'s <citetitle>UNIX System Administration - Handbook</citetitle> (Prentice-Hall, 1995, ISBN - 0-13-15051-7)—the second edition with the red cover; or - Æleen Frisch's <citetitle>Essential System - Administration</citetitle> (O'Reilly & Associates, 2002, - ISBN 0-596-00343-9). I used Nemeth.</para> - </sect1> - - <sect1> - <title>Editing Text</title> - - <para>To configure your system, you need to edit text files. Most - of them will be in the <filename>/etc</filename> directory; and - you will need to <command>su</command> to <username>root</username> to be able to - change them. You can use the easy <command>ee</command>, but in - the long run the text editor <command>vi</command> is worth - learning. There is an excellent tutorial on vi in - <filename>/usr/src/contrib/nvi/docs/tutorial</filename>, if you - have the system sources installed.</para> - - <para>Before you edit a file, you should probably back it up. - Suppose you want to edit <filename>/etc/rc.conf</filename>. You - could just use <command>cd /etc</command> to get to the - <filename>/etc</filename> directory and do:</para> - - <informalexample> - <screen>&prompt.root; <userinput>cp rc.conf rc.conf.orig</userinput></screen> - </informalexample> - - <para>This would copy <filename>rc.conf</filename> to - <filename>rc.conf.orig</filename>, and you could later copy - <filename>rc.conf.orig</filename> to - <filename>rc.conf</filename> to recover the original. But even - better would be moving (renaming) and then copying back:</para> - - <informalexample> - <screen>&prompt.root; <userinput>mv rc.conf rc.conf.orig</userinput> -&prompt.root; <userinput>cp rc.conf.orig rc.conf</userinput></screen> - </informalexample> - - <para>because the <command>mv</command> command preserves the - original date and owner of the file. You can now edit - <filename>rc.conf</filename>. If you want the original back, - you would then <userinput>mv rc.conf rc.conf.myedit</userinput> - (assuming you want to preserve your edited version) and - then</para> - - <informalexample> - <screen>&prompt.root; <userinput>mv rc.conf.orig rc.conf</userinput></screen> - </informalexample> - - <para>to put things back the way they were.</para> - - <para>To edit a file, type</para> - - <informalexample> - <screen>&prompt.root; <userinput>vi <replaceable>filename</replaceable></userinput></screen> - </informalexample> - - <para>Move through the text with the arrow keys. - <keycap>Esc</keycap> (the escape key) puts <command>vi</command> - in command mode. Here are some commands:</para> - - <variablelist> - <varlistentry> - <term><command>x</command></term> - - <listitem> - <para>delete letter the cursor is on</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>dd</command></term> - - <listitem> - <para>delete the entire line (even if it wraps on the - screen)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>i</command></term> - - <listitem> - <para>insert text at the cursor</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>a</command></term> - - <listitem> - <para>insert text after the cursor</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Once you type <command>i</command> or <command>a</command>, - you can enter text. <command>Esc</command> puts you back in - command mode where you can type</para> - - <variablelist> - <varlistentry> - <term><command>:w</command></term> - - <listitem> - <para>to write your changes to disk and continue - editing</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>:wq</command></term> - - <listitem> - <para>to write and quit</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>:q!</command></term> - - <listitem> - <para>to quit without saving changes</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>/<replaceable>text</replaceable></command></term> - - <listitem> - <para>to move the cursor to <replaceable>text</replaceable>; - <command>/<keycap>Enter</keycap></command> (the enter key) - to find the next instance of - <replaceable>text</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>G</command></term> - - <listitem> - <para>to go to the end of the file</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command><replaceable>n</replaceable>G</command></term> - - <listitem> - <para>to go to line <replaceable>n</replaceable> in the - file, where <replaceable>n</replaceable> is a - number</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo></term> - - <listitem> - <para>to redraw the screen</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo> and - <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo></term> - - <listitem> - <para>go back and forward a screen, as they do with - <command>more</command> and <command>view</command>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Practice with <command>vi</command> in your home directory - by creating a new file with <command>vi - <replaceable>filename</replaceable></command> and adding and - deleting text, saving the file, and calling it up again. - <command>vi</command> delivers some surprises because it is - really quite complex, and sometimes you will inadvertently issue a - command that will do something you do not expect. (Some people - actually like <command>vi</command>—it is more powerful - than DOS EDIT—find out about the <command>:r</command> - command.) Use <keycap>Esc</keycap> one or more times to be sure - you are in command mode and proceed from there when it gives you - trouble, save often with <command>:w</command>, and use - <command>:q!</command> to get out and start over (from your last - <command>:w</command>) when you need to.</para> - - <para>Now you can <command>cd</command> to - <filename>/etc</filename>, <command>su</command> to <username>root</username>, use - <command>vi</command> to edit the file - <filename>/etc/group</filename>, and add a user to <groupname>wheel</groupname> so the - user has root privileges. Just add a comma and the user's login - name to the end of the first line in the file, press - <keycap>Esc</keycap>, and use <command>:wq</command> to write - the file to disk and quit. Instantly effective. (You did not - put a space after the comma, did you?)</para> - </sect1> - - <sect1> - <title>Printing Files from DOS</title> - - <para>At this point you probably do not have the printer working, - so here is a way to create a file from a manual page, move it to a - floppy, and then print it from DOS. Suppose you want to read - carefully about changing permissions on files (pretty - important). You can use <command>man chmod</command> to read - about it. The command</para> - - <informalexample> - <screen>&prompt.user; <userinput>man chmod | col -b > chmod.txt</userinput></screen> - </informalexample> - - <para>will remove formatting codes and send the manual page to the - <filename>chmod.txt</filename> file instead of showing it on - your screen. Now put a dos-formatted diskette in your floppy - drive <devicename>a</devicename>, <command>su</command> to <username>root</username>, and type</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/mount -t msdos /dev/fd0 /mnt</userinput></screen> - </informalexample> - - <para>to mount the floppy drive on - <filename>/mnt</filename>.</para> - - <para>Now (you no longer need to be <username>root</username>, and you can type - <command>exit</command> to get back to being user jack) you can - go to the directory where you created - <filename>chmod.txt</filename> and copy the file to the floppy - with:</para> - - <informalexample> - <screen>&prompt.user; <userinput>cp chmod.txt /mnt</userinput></screen> - </informalexample> - - <para>and use <command>ls /mnt</command> to get a directory - listing of <filename>/mnt</filename>, which should show the file - <filename>chmod.txt</filename>.</para> - - <para>You might especially want to make a file from - <filename>/sbin/dmesg</filename> by typing</para> - - <informalexample> - <screen>&prompt.user; <userinput>/sbin/dmesg > dmesg.txt</userinput></screen> - </informalexample> - - <para>and copying <filename>dmesg.txt</filename> to the floppy. - <command>/sbin/dmesg</command> is the boot log record, and it is - useful to understand it because it shows what FreeBSD found when - it booted up. If you ask questions on the &a.questions; or on a USENET - group—like <quote>FreeBSD is not finding my tape drive, - what do I do?</quote>—people will want to know what - <command>dmesg</command> has to say.</para> - - <para>You can now unmount the floppy drive (as <username>root</username>) to get the - disk out with</para> - - <informalexample> - <screen>&prompt.root; <userinput>/sbin/umount /mnt</userinput></screen> - </informalexample> - - <para>and reboot to go to DOS. Copy these files to a DOS - directory, call them up with DOS EDIT, &windows; Notepad or - Wordpad, or a word processor, make a minor change so the file - has to be saved, and print as you normally would from DOS or - Windows. Hope it works! manual pages come out best if printed - with the DOS <command>print</command> command. (Copying files - from FreeBSD to a mounted DOS partition is in some cases still a - little risky.)</para> - - <para>Getting the printer printing from FreeBSD involves creating - an appropriate entry in <filename>/etc/printcap</filename> and - creating a matching spool directory in - <filename>/var/spool/output</filename>. If your printer is on - <hardware>lpt0</hardware> (what DOS calls - <hardware>LPT1</hardware>), you may only need to go to - <filename>/var/spool/output</filename> and (as <username>root</username>) create the - directory <filename>lpd</filename> by typing: <command>mkdir - lpd</command>, if it does not already exist. Then the printer - should respond if it is turned on when the system is booted, and - <command>lp</command> or <command>lpr</command> should send a - file to the printer. Whether or not the file actually prints - depends on configuring it, which is covered in the <ulink - url="&url.books.handbook;/index.html">FreeBSD - handbook.</ulink></para> - </sect1> - - <sect1> - <title>Other Useful Commands</title> - - <variablelist> - <varlistentry> - <term><command>df</command></term> - - <listitem> - <para>shows file space and mounted systems.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ps aux</command></term> - - <listitem> - <para>shows processes running. <command>ps ax</command> is a - narrower form.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>rm <replaceable>filename</replaceable></command></term> - - <listitem> - <para>remove <replaceable>filename</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>rm -R <replaceable>dir</replaceable></command></term> - - <listitem> - <para>removes a directory <replaceable>dir</replaceable> and all - subdirectories—careful!</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>ls -R</command></term> - - <listitem> - <para>lists files in the current directory and all - subdirectories; I used a variant, <command>ls -AFR > - where.txt</command>, to get a list of all the files in - <filename>/</filename> and (separately) - <filename>/usr</filename> before I found better ways to - find files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>passwd</command></term> - - <listitem> - <para>to change user's password (or <username>root</username>'s password)</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>man hier</command></term> - - <listitem> - <para>manual page on the &unix; filesystem</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Use <command>find</command> to locate <filename>filename</filename> in - <filename>/usr</filename> or any of its subdirectories - with</para> - - <informalexample> - <screen>&prompt.user; <userinput>find /usr -name "<replaceable>filename</replaceable>"</userinput></screen> - </informalexample> - - <para>You can use <literal>*</literal> as a wildcard in - <parameter>"<replaceable>filename</replaceable>"</parameter> - (which should be in quotes). If you tell - <command>find</command> to search in <filename>/</filename> - instead of <filename>/usr</filename> it will look for the - file(s) on all mounted filesystems, including the CDROM and the - DOS partition.</para> - - <para>An excellent book that explains &unix; commands and utilities - is Abrahams & Larson, <citetitle>Unix for the - Impatient</citetitle> (2nd ed., Addison-Wesley, 1996). - There is also a lot of &unix; information on the Internet.</para> - </sect1> - - <sect1> - <title>Next Steps</title> - - <para>You should now have the tools you need to get around and - edit files, so you can get everything up and running. There is - a great deal of information in the FreeBSD handbook (which is - probably on your hard drive) and <ulink - url="&url.base;/index.html">FreeBSD's web site</ulink>. A - wide variety of packages and ports are on the CDROM as well as - the web site. The handbook tells you more about how to use them - (get the package if it exists, with <command>pkg_add - /cdrom/packages/All/<replaceable>packagename</replaceable></command>, - where <replaceable>packagename</replaceable> is the filename of - the package). The CDROM has lists of the packages and ports - with brief descriptions in - <filename>cdrom/packages/index</filename>, - <filename>cdrom/packages/index.txt</filename>, and - <filename>cdrom/ports/index</filename>, with fuller descriptions - in <filename>/cdrom/ports/*/*/pkg/DESCR</filename>, where the - <literal>*</literal>s represent subdirectories of kinds of - programs and program names respectively.</para> - - <para>If you find the handbook too sophisticated (what with - <command>lndir</command> and all) on installing ports from the - CDROM, here is what usually works:</para> - - <para>Find the port you want, say <command>kermit</command>. - There will be a directory for it on the CDROM. Copy the - subdirectory to <filename>/usr/local</filename> (a good place - for software you add that should be available to all users) - with:</para> - - <informalexample> - <screen>&prompt.root; <userinput>cp -R /cdrom/ports/comm/kermit /usr/local</userinput></screen> - </informalexample> - - <para>This should result in a - <filename>/usr/local/kermit</filename> subdirectory that has all - the files that the <command>kermit</command> subdirectory on the - CDROM has.</para> - - <para>Next, create the directory - <filename>/usr/ports/distfiles</filename> if it does not already - exist using <command>mkdir</command>. Now check - <filename>/cdrom/ports/distfiles</filename> for a file with a - name that indicates it is the port you want. Copy that file to - <filename>/usr/ports/distfiles</filename>; in recent versions - you can skip this step, as FreeBSD will do it for you. In the - case of <command>kermit</command>, there is no distfile.</para> - - <para>Then <command>cd</command> to the subdirectory of - <filename>/usr/local/kermit</filename> that has the file - <filename>Makefile</filename>. Type</para> - - <informalexample> - <screen>&prompt.root; <userinput>make all install</userinput></screen> - </informalexample> - - <para>During this process the port will FTP to get any compressed - files it needs that it did not find on the CDROM or in - <filename>/usr/ports/distfiles</filename>. If you do not have - your network running yet and there was no file for the port in - <filename>/cdrom/ports/distfiles</filename>, you will have to - get the distfile using another machine and copy it to - <filename>/usr/ports/distfiles</filename> from a floppy or your - DOS partition. Read <filename>Makefile</filename> (with - <command>cat</command> or <command>more</command> or - <command>view</command>) to find out where to go (the master - distribution site) to get the file and what its name is. Its - name will be truncated when downloaded to DOS, and after you get - it into <filename>/usr/ports/distfiles</filename> you will have to - rename it (with the <command>mv</command> command) to its - original name so it can be found. (Use binary file transfers!) - Then go back to <filename>/usr/local/kermit</filename>, find the - directory with <filename>Makefile</filename>, and type - <command>make all install</command>.</para> - - <para>The other thing that happens when installing ports or - packages is that some other program is needed. If the - installation stops with a message <errorname>can't find - unzip</errorname> or whatever, you might need to install the - package or port for unzip before you continue.</para> - - <para>Once it is installed type <command>rehash</command> to make - FreeBSD reread the files in the path so it knows what is there. - (If you get a lot of <errorname>path not found</errorname> - messages when you use <command>whereis</command> or which, you - might want to make additions to the list of directories in the - path statement in <filename>.cshrc</filename> in your home - directory. The path statement in &unix; does the same kind of - work it does in DOS, except the current directory is not (by - default) in the path for security reasons; if the command you - want is in the directory you are in, you need to type - <filename>./</filename> before the command to make it work; no - space after the slash.)</para> - - <para>You might want to get the most recent version of &netscape; - from their <ulink url="ftp://ftp.netscape.com/">FTP site</ulink>. - (&netscape; requires the X Window System.) There is now a FreeBSD - version, so look around carefully. Just use <command>gunzip - <replaceable>filename</replaceable></command> and <command>tar - xvf <replaceable>filename</replaceable></command> on it, move - the binary to <filename>/usr/local/bin</filename> or some other - place binaries are kept, <command>rehash</command>, and then put - the following lines in <filename>.cshrc</filename> in each - user's home directory or (easier) in - <filename>/etc/csh.cshrc</filename>, the system-wide - <command>csh</command> start-up file:</para> - - <informalexample> - <programlisting>setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB -setenv XNLSPATH /usr/X11R6/lib/X11/nls</programlisting> - </informalexample> - - <para>This assumes that the file <filename>XKeysymDB</filename> - and the directory <filename>nls</filename> are in - <filename>/usr/X11R6/lib/X11</filename>; if they are not, find - them and put them there.</para> - - <para>If you originally got &netscape; as a port using the CDROM (or - FTP), do not replace <filename>/usr/local/bin/netscape</filename> - with the new netscape binary; this is just a shell script that - sets up the environment variables for you. Instead rename the - new binary to <filename>netscape.bin</filename> and replace the - old binary, which is - <filename>/usr/local/netscape/netscape</filename>.</para> - </sect1> - - <sect1> - <title>Your Working Environment</title> - - <para>Your shell is the most important part of your working - environment. In DOS, the usual shell is command.com. The shell - is what interprets the commands you type on the command line, - and thus communicates with the rest of the operating system. - You can also write shell scripts, which are like DOS batch - files: a series of commands to be run without your - intervention.</para> - - <para>Two shells come installed with FreeBSD: - <command>csh</command> and <command>sh</command>. - <command>csh</command> is good for command-line work, but - scripts should be written with <command>sh</command> (or - <command>bash</command>). You can find out what shell you have - by typing <command>echo $SHELL</command>.</para> - - <para>The <command>csh</command> shell is okay, but - <command>tcsh</command> does everything <command>csh</command> - does and more. It allows you to recall commands with the arrow - keys and edit them. It has tab-key completion of filenames - (<command>csh</command> uses the <keycap>Esc</keycap> key), and - it lets you switch to the directory you were last in with - <command>cd -</command>. It is also much easier to alter your - prompt with <command>tcsh</command>. It makes life a lot - easier.</para> - - <para>Here are the three steps for installing a new shell:</para> - - <procedure> - <step> - <para>Install the shell as a port or a package, just as you - would any other port or package. Use - <command>rehash</command> and <command>which tcsh</command> - (assuming you are installing <command>tcsh</command>) to make - sure it got installed.</para> - </step> - - <step> - <para>As <username>root</username>, edit <filename>/etc/shells</filename>, adding a - line in the file for the new shell, in this case - <filename>/usr/local/bin/tcsh</filename>, and save the file. - (Some ports may do this for you.)</para> - </step> - - <step> - <para>Use the <command>chsh</command> command to change your - shell to <command>tcsh</command> permanently, or type - <command>tcsh</command> at the prompt to change your shell - without logging in again.</para> - </step> - </procedure> - - <note> - <para>It can be dangerous to change <username>root</username>'s shell to something - other than <command>sh</command> or <command>csh</command> on - early versions of FreeBSD and many other versions of &unix;; you - may not have a working shell when the system puts you into - single user mode. The solution is to use <command>su - -m</command> to become <username>root</username>, which will give you the - <command>tcsh</command> as <username>root</username>, because the shell is part of - the environment. You can make this permanent by adding it to - your <filename>.tcshrc</filename> file as an alias with:</para> - <programlisting>alias su su -m</programlisting> - </note> - - <para>When <command>tcsh</command> starts up, it will read the - <filename>/etc/csh.cshrc</filename> and - <filename>/etc/csh.login</filename> files, as does - <command>csh</command>. It will also read the - <filename>.login</filename> file in your home directory and the - <filename>.cshrc</filename> file as well, unless you provide a - <filename>.tcshrc</filename> file. This you can do by simply - copying <filename>.cshrc</filename> to - <filename>.tcshrc</filename>.</para> - - <para>Now that you have installed <command>tcsh</command>, you can - adjust your prompt. You can find the details in the manual page - for <command>tcsh</command>, but here is a line to put in your - <filename>.tcshrc</filename> that will tell you how many - commands you have typed, what time it is, and what directory you - are in. It also produces a <literal>></literal> if you are an - ordinary user and a <literal>#</literal> if you are <username>root</username>, but - tsch will do that in any case:</para> - - <para>set prompt = "%h %t %~ %# "</para> - - <para>This should go in the same place as the existing set prompt - line if there is one, or under "if($?prompt) then" if not. - Comment out the old line; you can always switch back to it if - you prefer it. Do not forget the spaces and quotes. You can get - the <filename>.tcshrc</filename> reread by typing - <command>source .tcshrc</command>.</para> - - <para>You can get a listing of other environmental variables that - have been set by typing <command>env</command> at the prompt. - The result will show you your default editor, pager, and - terminal type, among possibly many others. A useful command if - you log in from a remote location and can not run a program - because the terminal is not capable is <command>setenv TERM - vt100</command>.</para> - </sect1> - - <sect1> - <title>Other</title> - - <para>As <username>root</username>, you can unmount the CDROM with - <command>/sbin/umount /cdrom</command>, take it out of the - drive, insert another one, and mount it with - <command>/sbin/mount_cd9660 /dev/cd0a /cdrom</command> assuming - <hardware>cd0a</hardware> is the device name for your CDROM - drive. The most recent versions of FreeBSD let you mount the - CDROM with just <command>/sbin/mount /cdrom</command>.</para> - - <para>Using the live filesystem—the second of FreeBSD's - CDROM disks—is useful if you have got limited space. What - is on the live filesystem varies from release to release. You - might try playing games from the CDROM. This involves using - <command>lndir</command>, which gets installed with the X Window - System, to tell the program(s) where to find the necessary - files, because they are in the <filename>/cdrom</filename> file - system instead of in <filename>/usr</filename> and its - subdirectories, which is where they are expected to be. Read - <command>man lndir</command>.</para> - </sect1> - - <sect1> - <title>Comments Welcome</title> - - <para>If you use this guide I would be interested in knowing where it - was unclear and what was left out that you think should be - included, and if it was helpful. My thanks to Eugene W. Stark, - professor of computer science at SUNY-Stony Brook, and John - Fieber for helpful comments.</para> - - <para>Annelise Anderson, - <email>andrsn@andrsn.stanford.edu</email></para> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/pam/Makefile b/en_US.ISO8859-1/articles/pam/Makefile deleted file mode 100644 index c7252e978d..0000000000 --- a/en_US.ISO8859-1/articles/pam/Makefile +++ /dev/null @@ -1,33 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Pluggable Authentication Modules - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES -WITH_INLINE_LEGALNOTICE?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -EXTRAS= pam_app.c -EXTRAS+= pam_conv.c -EXTRAS+= pam_module.c -CLEANFILES+= ${EXTRAS} - -SRCS= article.sgml -SRCS+= ${EXTRAS} - -pam_app.c: su.c - sed -e '/^[\/ ]\*/d' ${.ALLSRC} >${.TARGET} - -pam_conv.c: converse.c - sed -e '/^[\/ ]\*/d' ${.ALLSRC} >${.TARGET} - -pam_module.c: pam_unix.c - sed -e '/^[\/ ]\*/d' ${.ALLSRC} >${.TARGET} - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/pam/article.sgml b/en_US.ISO8859-1/articles/pam/article.sgml deleted file mode 100644 index f5d4cb58ab..0000000000 --- a/en_US.ISO8859-1/articles/pam/article.sgml +++ /dev/null @@ -1,1362 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<!-- - - Copyright (c) 2001-2003 Networks Associates Technology, Inc. - - All rights reserved. - - - - This software was developed for the FreeBSD Project by ThinkSec AS and - - Network Associates Laboratories, the Security Research Division of - - Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 - - ("CBOSS"), as part of the DARPA CHATS research program. - - - - Redistribution and use in source and binary forms, with or without - - modification, are permitted provided that the following conditions - - are met: - - 1. Redistributions of source code must retain the above copyright - - notice, this list of conditions and the following disclaimer. - - 2. Redistributions in binary form must reproduce the above copyright - - notice, this list of conditions and the following disclaimer in the - - documentation and/or other materials provided with the distribution. - - 3. The name of the author may not be used to endorse or promote - - products derived from this software without specific prior written - - permission. - - - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND - - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - - ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE - - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - - SUCH DAMAGE. - --> - -<article> - <articleinfo> - <title>Pluggable Authentication Modules</title> - - <pubdate>$FreeBSD$</pubdate> - - <abstract> - <para>This article describes the underlying principles and - mechanisms of the Pluggable Authentication Modules (PAM) - library, and explains how to configure PAM, how to integrate - PAM into applications, and how to write PAM modules.</para> - </abstract> - - <copyright> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <holder>Networks Associates Technology, Inc.</holder> - </copyright> - - <authorgroup> - <author> - <firstname>Dag-Erling</firstname> - <surname>Smørgrav</surname> - <contrib>Contributed by </contrib> - </author> - </authorgroup> - - <legalnotice> - <para>This article was written for the FreeBSD Project by - ThinkSec AS and Network Associates Laboratories, the Security - Research Division of Network Associates, Inc. under - DARPA/SPAWAR contract N66001-01-C-8035 (<quote>CBOSS</quote>), - as part of the DARPA CHATS research program.</para> - </legalnotice> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.linux; - &tm-attrib.opengroup; - &tm-attrib.sun; - &tm-attrib.general; - </legalnotice> - </articleinfo> - - <section id="pam-intro"> - <title id="pam-intro.title">Introduction</title> - - <para>The Pluggable Authentication Modules (PAM) library is a - generalized API for authentication-related services which allows - a system administrator to add new authentication methods simply - by installing new PAM modules, and to modify authentication - policies by editing configuration files.</para> - - <para>PAM was defined and developed in 1995 by Vipin Samar and - Charlie Lai of Sun Microsystems, and has not changed much since. - In 1997, the Open Group published the X/Open Single Sign-on - (XSSO) preliminary specification, which standardized the PAM API - and added extensions for single (or rather integrated) sign-on. - At the time of this writing, this specification has not yet been - adopted as a standard.</para> - - <para>Although this article focuses primarily on FreeBSD 5.x, - which uses OpenPAM, it should be equally applicable to FreeBSD - 4.x, which uses Linux-PAM, and other operating systems such as - Linux and &solaris;.</para> - </section> - - <section id="pam-terms"> - <title id="pam-terms.title">Terms and conventions</title> - - <section id="pam-definitions"> - <title id="pam-definitions.title">Definitions</title> - - <para>The terminology surrounding PAM is rather confused. - Neither Samar and Lai's original paper nor the XSSO - specification made any attempt at formally defining terms for - the various actors and entities involved in PAM, and the terms - that they do use (but do not define) are sometimes misleading - and ambiguous. The first attempt at establishing a consistent - and unambiguous terminology was a whitepaper written by Andrew - G. Morgan (author of Linux-PAM) in 1999. While Morgan's - choice of terminology was a huge leap forward, it is in this - author's opinion by no means perfect. What follows is an - attempt, heavily inspired by Morgan, to define precise and - unambiguous terms for all actors and entities involved in - PAM.</para> - - <glosslist> - <glossentry> - <glossterm>account</glossterm> - <glossdef> - <para>The set of credentials the applicant is requesting - from the arbitrator.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>applicant</glossterm> - <glossdef> - <para>The user or entity requesting authentication.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>arbitrator</glossterm> - <glossdef> - <para>The user or entity who has the privileges necessary - to verify the applicant's credentials and the authority - to grant or deny the request.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>chain</glossterm> - <glossdef> - <para>A sequence of modules that will be invoked in - response to a PAM request. The chain includes - information about the order in which to invoke the - modules, what arguments to pass to them, and how to - interpret the results.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>client</glossterm> - <glossdef> - <para>The application responsible for initiating an - authentication request on behalf of the applicant and - for obtaining the necessary authentication information - from him.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>facility</glossterm> - <glossdef> - <para>One of the four basic groups of functionality - provided by PAM: authentication, account management, - session management and authentication token - update.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>module</glossterm> - <glossdef> - <para>A collection of one or more related functions - implementing a particular authentication facility, - gathered into a single (normally dynamically loadable) - binary file and identified by a single name.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>policy</glossterm> - <glossdef> - <para>The complete set of configuration statements - describing how to handle PAM requests for a particular - service. A policy normally consists of four chains, one - for each facility, though some services do not use all - four facilities.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>server</glossterm> - <glossdef> - <para>The application acting on behalf of the arbitrator - to converse with the client, retrieve authentication - information, verify the applicant's credentials and - grant or deny requests.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>service</glossterm> - <glossdef> - <para>A class of servers providing similar or related - functionality and requiring similar authentication. PAM - policies are defined on a per-service basis, so all - servers that claim the same service name will be subject - to the same policy.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>session</glossterm> - <glossdef> - <para>The context within which service is rendered to the - applicant by the server. One of PAM's four facilities, - session management, is concerned exclusively with - setting up and tearing down this context.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>token</glossterm> - <glossdef> - <para>A chunk of information associated with the account, - such as a password or passphrase, which the applicant - must provide to prove his identity.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>transaction</glossterm> - <glossdef> - <para>A sequence of requests from the same applicant to - the same instance of the same server, beginning with - authentication and session set-up and ending with - session tear-down.</para> - </glossdef> - </glossentry> - </glosslist> - </section> - - <section id="pam-usage-examples"> - <title id="pam-usage-examples.title">Usage examples</title> - - <para>This section aims to illustrate the meanings of some of - the terms defined above by way of a handful of simple - examples.</para> - - <section> - <title>Client and server are one</title> - - <para>This simple example shows <literal>alice</literal> - &man.su.1;'ing to <literal>root</literal>.</para> - -<screen>&prompt.user; <userinput>whoami</userinput> -alice -&prompt.user; <userinput>ls -l `which su`</userinput> --r-sr-xr-x 1 root wheel 10744 Dec 6 19:06 /usr/bin/su -&prompt.user; <userinput>su -</userinput> -Password: <userinput>xi3kiune</userinput> -&prompt.root; whoami -root -</screen> - - <itemizedlist> - <listitem> - <para>The applicant is <literal>alice</literal>.</para> - </listitem> - <listitem> - <para>The account is <literal>root</literal>.</para> - </listitem> - <listitem> - <para>The &man.su.1; process is both client and - server.</para> - </listitem> - <listitem> - <para>The authentication token is - <literal>xi3kiune</literal>.</para> - </listitem> - <listitem> - <para>The arbitrator is <literal>root</literal>, which is - why &man.su.1; is setuid <literal>root</literal>.</para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Client and server are separate</title> - - <para>The example below shows <literal>eve</literal> try to - initiate an &man.ssh.1; connection to - <literal>login.example.com</literal>, ask to log in as - <literal>bob</literal>, and succeed. Bob should have chosen - a better password!</para> - -<screen>&prompt.user; <userinput>whoami</userinput> -eve -&prompt.user; <userinput>ssh bob@login.example.com</userinput> -bob@login.example.com's password: <userinput>god</userinput> -Last login: Thu Oct 11 09:52:57 2001 from 192.168.0.1 -Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 - The Regents of the University of California. All rights reserved. -FreeBSD 4.4-STABLE (LOGIN) #4: Tue Nov 27 18:10:34 PST 2001 - -Welcome to FreeBSD! -&prompt.user;</screen> - - <itemizedlist> - <listitem> - <para>The applicant is <literal>eve</literal>.</para> - </listitem> - <listitem> - <para>The client is Eve's &man.ssh.1; process.</para> - </listitem> - <listitem> - <para>The server is the &man.sshd.8; process on - <literal>login.example.com</literal></para> - </listitem> - <listitem> - <para>The account is <literal>bob</literal>.</para> - </listitem> - <listitem> - <para>The authentication token is - <literal>god</literal>.</para> - </listitem> - <listitem> - <para>Although this is not shown in this example, the - arbitrator is <literal>root</literal>.</para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Sample policy</title> - - <para>The following is FreeBSD's default policy for - <literal>sshd</literal>:</para> - -<programlisting>sshd auth required pam_nologin.so no_warn -sshd auth required pam_unix.so no_warn try_first_pass -sshd account required pam_login_access.so -sshd account required pam_unix.so -sshd session required pam_lastlog.so no_fail -sshd password required pam_permit.so</programlisting> - - <itemizedlist> - <listitem> - <para>This policy applies to the <literal>sshd</literal> - service (which is not necessarily restricted to the - &man.sshd.8; server.)</para> - </listitem> - <listitem> - <para><literal>auth</literal>, <literal>account</literal>, - <literal>session</literal> and - <literal>password</literal> are facilities.</para> - </listitem> - <listitem> - <para><filename>pam_nologin.so</filename>, - <filename>pam_unix.so</filename>, - <filename>pam_login_access.so</filename>, - <filename>pam_lastlog.so</filename> and - <filename>pam_permit.so</filename> are modules. It is - clear from this example that - <filename>pam_unix.so</filename> provides at least two - facilities (authentication and account - management.)</para> - </listitem> - </itemizedlist> - </section> - </section> - -<!-- - <section id="pam-conventions"> - <title id="pam-conventions.title">Conventions</title> - - <para>This section has not yet been written.</para> - </section> ---> - </section> - - <section id="pam-essentials"> - <title id="pam-essentials.title">PAM Essentials</title> - - <section id="pam-facilities-primitives"> - <title id="pam-facilities-primitives.title">Facilities and - primitives</title> - - <para>The PAM API offers six different authentication primitives - grouped in four facilities, which are described below.</para> - - <variablelist> - <varlistentry> - <term><literal>auth</literal></term> - <listitem> - <para><emphasis>Authentication.</emphasis> This facility - concerns itself with authenticating the applicant and - establishing the account credentials. It provides two - primitives:</para> - - <itemizedlist> - <listitem> - <para>&man.pam.authenticate.3; authenticates the - applicant, usually by requesting an authentication - token and comparing it with a value stored in a - database or obtained from an authentication - server.</para> - </listitem> - - <listitem> - <para>&man.pam.setcred.3; establishes account - credentials such as user ID, group membership and - resource limits.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>account</literal></term> - <listitem> - <para><emphasis>Account management.</emphasis> This - facility handles non-authentication-related issues of - account availability, such as access restrictions based - on the time of day or the server's work load. It - provides a single primitive:</para> - - <itemizedlist> - <listitem> - <para>&man.pam.acct.mgmt.3; verifies that the - requested account is available.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>session</literal></term> - <listitem> - <para><emphasis>Session management.</emphasis> This - facility handles tasks associated with session set-up - and tear-down, such as login accounting. It provides - two primitives:</para> - - <itemizedlist> - <listitem> - <para>&man.pam.open.session.3; performs tasks - associated with session set-up: add an entry in the - <filename>utmp</filename> and - <filename>wtmp</filename> databases, start an SSH - agent, etc.</para> - </listitem> - - <listitem> - <para>&man.pam.close.session.3; performs tasks - associated with session tear-down: add an entry in - the <filename>utmp</filename> and - <filename>wtmp</filename> databases, stop the SSH - agent, etc.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>password</literal></term> - <listitem> - <para><emphasis>Password management.</emphasis> This - facility is used to change the authentication token - associated with an account, either because it has - expired or because the user wishes to change it. It - provides a single primitive:</para> - - <itemizedlist> - <listitem> - <para>&man.pam.chauthtok.3; changes the authentication - token, optionally verifying that it is sufficiently - hard to guess, has not been used previously, - etc.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="pam-modules"> - <title id="pam-modules.title">Modules</title> - - <para>Modules are a very central concept in PAM; after all, - they are the <quote>M</quote> in <quote>PAM</quote>. A PAM - module is a self-contained piece of program code that - implements the primitives in one or more facilities for one - particular mechanism; possible mechanisms for the - authentication facility, for instance, include the &unix; - password database, NIS, LDAP and Radius.</para> - - <section id="pam-module-naming"> - <title id="pam-module-naming.title">Module Naming</title> - - <para>FreeBSD implements each mechanism in a single module, - named - <literal>pam_<replaceable>mechanism</replaceable>.so</literal> - (for instance, <literal>pam_unix.so</literal> for the &unix; - mechanism.) Other implementations sometimes have separate - modules for separate facilities, and include the facility - name as well as the mechanism name in the module name. To - name one example, &solaris; has a - <literal>pam_dial_auth.so.1</literal> module which is - commonly used to authenticate dialup users.</para> - </section> - - <section id="pam-module-versioning"> - <title id="pam-module-versioning.title">Module Versioning</title> - - <para>FreeBSD's original PAM implementation, based on - Linux-PAM, did not use version numbers for PAM modules. - This would commonly cause problems with legacy applications, - which might be linked against older versions of the system - libraries, as there was no way to load a matching version of - the required modules.</para> - - <para>OpenPAM, on the other hand, looks for modules that have - the same version number as the PAM library (currently 2), - and only falls back to an unversioned module if no versioned - module could be loaded. Thus legacy modules can be provided - for legacy applications, while allowing new (or newly built) - applications to take advantage of the most recent - modules.</para> - - <para>Although &solaris; PAM modules commonly have a version - number, they're not truly versioned, because the number is a - part of the module name and must be included in the - configuration.</para> - </section> - </section> - - <section id="pam-chains-policies"> - <title id="pam-chains-policies.title">Chains and - policies</title> - - <para>When a server initiates a PAM transaction, the PAM library - tries to load a policy for the service specified in the - &man.pam.start.3; call. The policy specifies how - authentication requests should be processed, and is defined in - a configuration file. This is the other central concept in - PAM: the possibility for the admin to tune the system security - policy (in the wider sense of the word) simply by editing a - text file.</para> - - <para>A policy consists of four chains, one for each of the four - PAM facilities. Each chain is a sequence of configuration - statements, each specifying a module to invoke, some - (optional) parameters to pass to the module, and a control - flag that describes how to interpret the return code from the - module.</para> - - <para>Understanding the control flags is essential to - understanding PAM configuration files. There are four - different control flags:</para> - - <variablelist> - <varlistentry> - <term><literal>binding</literal></term> - <listitem> - <para>If the module succeeds and no earlier module in the - chain has failed, the chain is immediately terminated - and the request is granted. If the module fails, the - rest of the chain is executed, but the request is - ultimately denied.</para> - - <para>This control flag was introduced by Sun in &solaris; 9 - (&sunos; 5.9), and is also supported by OpenPAM.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>required</literal></term> - <listitem> - <para>If the module succeeds, the rest of the chain is - executed, and the request is granted unless some other - module fails. If the module fails, the rest of the - chain is also executed, but the request is ultimately - denied.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>requisite</literal></term> - <listitem> - <para>If the module succeeds, the rest of the chain is - executed, and the request is granted unless some other - module fails. If the module fails, the chain is - immediately terminated and the request is denied.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>sufficient</literal></term> - <listitem> - <para>If the module succeeds and no earlier module in the - chain has failed, the chain is immediately terminated - and the request is granted. If the module fails, the - module is ignored and the rest of the chain is - executed.</para> - - <para>As the semantics of this flag may be somewhat - confusing, especially when it is used for the last - module in a chain, it is recommended that the - <literal>binding</literal> control flag be used instead - if the implementation supports it.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>optional</literal></term> - <listitem> - <para>The module is executed, but its result is ignored. - If all modules in a chain are marked - <literal>optional</literal>, all requests will always be - granted.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>When a server invokes one of the six PAM primitives, PAM - retrieves the chain for the facility the primitive belongs to, - and invokes each of the modules listed in the chain, in the - order they are listed, until it reaches the end, or determines - that no further processing is necessary (either because a - <literal>binding</literal> or - <literal>sufficient</literal> module succeeded, or because a - <literal>requisite</literal> module failed.) The request is - granted if and only if at least one module was invoked, and - all non-optional modules succeeded.</para> - - <para>Note that it is possible, though not very common, to have - the same module listed several times in the same chain. For - instance, a module that looks up user names and passwords in a - directory server could be invoked multiple times with - different parameters specifying different directory servers to - contact. PAM treat different occurrences of the same module - in the same chain as different, unrelated modules.</para> - </section> - - <section id="pam-transactions"> - <title id="pam-transactions.title">Transactions</title> - - <para>The lifecycle of a typical PAM transaction is described - below. Note that if any of these steps fails, the server - should report a suitable error message to the client and abort - the transaction.</para> - - <orderedlist> - <listitem> - <para>If necessary, the server obtains arbitrator - credentials through a mechanism independent of - PAM—most commonly by virtue of having been started - by <literal>root</literal>, or of being setuid - <literal>root</literal>.</para> - </listitem> - - <listitem> - <para>The server calls &man.pam.start.3; to initialize the - PAM library and specify its service name and the target - account, and register a suitable conversation - function.</para> - </listitem> - - <listitem> - <para>The server obtains various information relating to the - transaction (such as the applicant's user name and the - name of the host the client runs on) and submits it to PAM - using &man.pam.set.item.3;.</para> - </listitem> - - <listitem> - <para>The server calls &man.pam.authenticate.3; to - authenticate the applicant.</para> - </listitem> - - <listitem> - <para>The server calls &man.pam.acct.mgmt.3; to verify that the - requested account is available and valid. If the password - is correct but has expired, &man.pam.acct.mgmt.3; will - return <literal>PAM_NEW_AUTHTOK_REQD</literal> instead of - <literal>PAM_SUCCESS</literal>.</para> - </listitem> - - <listitem> - <para>If the previous step returned - <literal>PAM_NEW_AUTHTOK_REQD</literal>, the server now - calls &man.pam.chauthtok.3; to force the client to change - the authentication token for the requested account.</para> - </listitem> - - <listitem> - <para>Now that the applicant has been properly - authenticated, the server calls &man.pam.setcred.3; to - establish the credentials of the requested account. It is - able to do this because it acts on behalf of the - arbitrator, and holds the arbitrator's credentials.</para> - </listitem> - - <listitem> - <para>Once the correct credentials have been established, - the server calls &man.pam.open.session.3; to set up the - session.</para> - </listitem> - - <listitem> - <para>The server now performs whatever service the client - requested—for instance, provide the applicant with a - shell.</para> - </listitem> - - <listitem> - <para>Once the server is done serving the client, it calls - &man.pam.close.session.3; to tear down the session.</para> - </listitem> - - <listitem> - <para>Finally, the server calls &man.pam.end.3; to notify - the PAM library that it is done and that it can release - whatever resources it has allocated in the course of the - transaction.</para> - </listitem> - </orderedlist> - </section> - </section> - - <section id="pam-config"> - <title id="pam-config.title">PAM Configuration</title> - - <section id="pam-config-file"> - <title id="pam-config-file.title">PAM policy files</title> - - <section id="pam-config-pam.conf"> - <title id="pam-config-pam.conf.title">The - <filename>/etc/pam.conf</filename> file</title> - - <para>The traditional PAM policy file is - <filename>/etc/pam.conf</filename>. This file contains all - the PAM policies for your system. Each line of the file - describes one step in a chain, as shown below:</para> - -<programlisting>login auth required pam_nologin.so no_warn</programlisting> - - <para>The fields are, in order: service name, facility name, - control flag, module name, and module arguments. Any - additional fields are interpreted as additional module - arguments.</para> - - <para>A separate chain is constructed for each service / - facility pair, so while the order in which lines for the - same service and facility appear is significant, the order - in which the individual services and facilities are listed - is not. The examples in the original PAM paper grouped - configuration lines by facility, and the &solaris; stock - <filename>pam.conf</filename> still does that, but FreeBSD's - stock configuration groups configuration lines by service. - Either way is fine; either way makes equal sense.</para> - </section> - - <section id="pam-config-pam.d"> - <title id="pam-config-pam.d.title">The - <filename>/etc/pam.d</filename> directory</title> - - <para>OpenPAM and Linux-PAM support an alternate configuration - mechanism, which is the preferred mechanism in FreeBSD. In - this scheme, each policy is contained in a separate file - bearing the name of the service it applies to. These files - are stored in <filename>/etc/pam.d/</filename>.</para> - - <para>These per-service policy files have only four fields - instead of <filename>pam.conf</filename>'s five: the service - name field is omitted. Thus, instead of the sample - <filename>pam.conf</filename> line from the previous - section, one would have the following line in - <filename>/etc/pam.d/login</filename>:</para> - -<programlisting>auth required pam_nologin.so no_warn</programlisting> - - <para>As a consequence of this simplified syntax, it is - possible to use the same policy for multiple services by - linking each service name to a same policy file. For - instance, to use the same policy for the - <literal>su</literal> and <literal>sudo</literal> services, - one could do as follows:</para> - -<screen>&prompt.root; <userinput>cd /etc/pam.d</userinput> -&prompt.root; <userinput>ln -s su sudo</userinput></screen> - - <para>This works because the service name is determined from - the file name rather than specified in the policy file, so - the same file can be used for multiple differently-named - services.</para> - - <para>Since each service's policy is stored in a separate - file, the <filename>pam.d</filename> mechanism also makes it - very easy to install additional policies for third-party - software packages.</para> - </section> - - <section id="pam-config-file-order"> - <title id="pam-config-file-order.title">The policy search - order</title> - - <para>As we have seen above, PAM policies can be found in a - number of places. What happens if policies for the same - service exist in multiple places?</para> - - <para>It is essential to understand that PAM's configuration - system is centered on chains.<!-- XXX --></para> - - </section> - </section> - - <section id="pam-config-breakdown"> - <title id="pam-config-breakdown.title">Breakdown of a - configuration line</title> - - <para>As explained in the <link linkend="pam-config-file" - endterm="pam-config-file.title"></link> section, each line in - <filename>/etc/pam.conf</filename> consists of four or more - fields: the service name, the facility name, the control flag, - the module name, and zero or more module arguments.</para> - - <para>The service name is generally (though not always) the name - of the application the statement applies to. If you are - unsure, refer to the individual application's documentation to - determine what service name it uses.</para> - - <para>Note that if you use <filename>/etc/pam.d/</filename> - instead of <filename>/etc/pam.conf</filename>, the service - name is specified by the name of the policy file, and omitted - from the actual configuration lines, which then start with the - facility name.</para> - - <para>The facility is one of the four facility keywords - described in the <link linkend="pam-facilities-primitives" - endterm="pam-facilities-primitives.title"></link> - section.</para> - - <para>Likewise, the control flag is one of the four keywords - described in the <link linkend="pam-chains-policies" - endterm="pam-chains-policies.title"></link> section, - describing how to interpret the return code from the module. - Linux-PAM supports an alternate syntax that lets you specify - the action to associate with each possible return code, but - this should be avoided as it is non-standard and closely tied - in with the way Linux-PAM dispatches service calls (which - differs greatly from the way &solaris; and OpenPAM do it.) - Unsurprisingly, OpenPAM does not support this syntax.</para> - </section> - - <section id="pam-policies"> - <title id="pam-policies.title">Policies</title> - - <para>To configure PAM correctly, it is essential to understand - how policies are interpreted.</para> - - <para>When an application calls &man.pam.start.3;, the PAM - library loads the policy for the specified service and - constructs four module chains (one for each facility.) If one - or more of these chains are empty, the corresponding chains - from the policy for the <literal>other</literal> service are - substituted.</para> - - <para>When the application later calls one of the six PAM - primitives, the PAM library retrieves the chain for the - corresponding facility and calls the appropriate service - function in each module listed in the chain, in the order in - which they were listed in the configuration. After each call - to a service function, the module type and the error code - returned by the service function are used to determine what - happens next. With a few exceptions, which we discuss below, - the following table applies:</para> - - <table> - <title>PAM chain execution summary</title> - <tgroup cols="4"> - <colspec colwidth="1*" colname="type"> - <colspec colwidth="1*" colname="success"> - <colspec colwidth="1*" colname="ignore"> - <colspec colwidth="1*" colname="other"> - <thead> - <row> - <entry colname="type"></entry> - <entry colname="success"><literal>PAM_SUCCESS</literal></entry> - <entry colname="ignore"><literal>PAM_IGNORE</literal></entry> - <entry colname="other"><literal>other</literal></entry> - </row> - </thead> - <tbody> - <row> - <entry colname="type">binding</entry> - <entry colname="success">if (!fail) break;</entry> - <entry colname="ignore">-</entry> - <entry colname="other">fail = true;</entry> - </row> - <row> - <entry colname="type">required</entry> - <entry colname="success">-</entry> - <entry colname="ignore">-</entry> - <entry colname="other">fail = true;</entry> - </row> - <row> - <entry colname="type">requisite</entry> - <entry colname="success">-</entry> - <entry colname="ignore">-</entry> - <entry colname="other">fail = true; break;</entry> - </row> - <row> - <entry colname="type">sufficient</entry> - <entry colname="success">if (!fail) break;</entry> - <entry colname="ignore">-</entry> - <entry colname="other">-</entry> - </row> - <row> - <entry colname="type">optional</entry> - <entry colname="success">-</entry> - <entry colname="ignore">-</entry> - <entry colname="other">-</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>If <varname>fail</varname> is true at the end of a chain, - or when a <quote>break</quote> is reached, the dispatcher - returns the error code returned by the first module that - failed. Otherwise, it returns - <literal>PAM_SUCCESS</literal>.</para> - - <para>The first exception of note is that the error code - <literal>PAM_NEW_AUTHTOK_REQD</literal> is treated like a - success, except that if no module failed, and at least one - module returned <literal>PAM_NEW_AUTHTOK_REQD</literal>, the - dispatcher will return - <literal>PAM_NEW_AUTHTOK_REQD</literal>.</para> - - <para>The second exception is that &man.pam.setcred.3; treats - <literal>binding</literal> and - <literal>sufficient</literal> modules as if they were - <literal>required</literal>.</para> - - <para>The third and final exception is that - &man.pam.chauthtok.3; runs the entire chain twice (once for - preliminary checks and once to actually set the password), and - in the preliminary phase it treats - <literal>binding</literal> and - <literal>sufficient</literal> modules as if they were - <literal>required</literal>.</para> - </section> - </section> - - <section id="pam-freebsd-modules"> - <title id="pam-freebsd-modules.title">FreeBSD PAM Modules</title> - - <section id="pam-modules-deny"> - <title id="pam-modules-deny.title">&man.pam.deny.8;</title> - - <para>The &man.pam.deny.8; module is one of the simplest modules - available; it responds to any request with - <literal>PAM_AUTH_ERR</literal>. It is useful for quickly - disabling a service (add it to the top of every chain), or for - terminating chains of <literal>sufficient</literal> - modules.</para> - </section> - - <section id="pam-modules-echo"> - <title id="pam-modules-echo.title">&man.pam.echo.8;</title> - - <para>The &man.pam.echo.8; module simply passes its arguments to - the conversation function as a - <literal>PAM_TEXT_INFO</literal> message. It is mostly useful - for debugging, but can also serve to display messages such as - <quote>Unauthorized access will be prosecuted</quote> before - starting the authentication procedure.</para> - </section> - - <section id="pam-modules-exec"> - <title id="pam-modules-exec.title">&man.pam.exec.8;</title> - - <para>The &man.pam.exec.8; module takes its first argument to be - the name of a program to execute, and the remaining arguments - are passed to that program as command-line arguments. One - possible application is to use it to run a program at login - time which mounts the user's home directory.</para> - </section> - - <section id="pam-modules-ftpusers"> - <title id="pam-modules-ftpusers.title">&man.pam.ftpusers.8;</title> - - <para>The &man.pam.ftpusers.8; module</para> - </section> - - <section id="pam-modules-group"> - <title id="pam-modules-group.title">&man.pam.group.8;</title> - - <para>The &man.pam.group.8; module accepts or rejects applicants - on the basis of their membership in a particular file group - (normally <literal>wheel</literal> for &man.su.1;). It is - primarily intended for maintaining the traditional behaviour - of BSD &man.su.1;, but has many other uses, such as excluding - certain groups of users from a particular service.</para> - </section> - - <section id="pam-modules-guest"> - <title id="pam-modules-guest.title">&man.pam.guest.8;</title> - - <para>The &man.pam.guest.8; module allows guest logins using - fixed login names. Various requirements can be placed on the - password, but the default behaviour is to allow any password - as long as the login name is that of a guest account. The - &man.pam.guest.8; module can easily be used to implement - anonymous FTP logins.</para> - </section> - - <section id="pam-modules-krb5"> - <title id="pam-modules-krb5.title">&man.pam.krb5.8;</title> - - <para>The &man.pam.krb5.8; module</para> - </section> - - <section id="pam-modules-ksu"> - <title id="pam-modules-ksu.title">&man.pam.ksu.8;</title> - - <para>The &man.pam.ksu.8; module</para> - </section> - - <section id="pam-modules-lastlog"> - <title id="pam-modules-lastlog.title">&man.pam.lastlog.8;</title> - - <para>The &man.pam.lastlog.8; module</para> - </section> - - <section id="pam-modules-login-access"> - <title id="pam-modules-login-access.title">&man.pam.login.access.8;</title> - - <para>The &man.pam.login.access.8; module provides an - implementation of the account management primitive which - enforces the login restrictions specified in the - &man.login.access.5; table.</para> - </section> - - <section id="pam-modules-nologin"> - <title id="pam-modules-nologin.title">&man.pam.nologin.8;</title> - - <para>The &man.pam.nologin.8; module refuses non-root logins - when <filename>/var/run/nologin</filename> exists. This file - is normally created by &man.shutdown.8; when less than five - minutes remain until the scheduled shutdown time.</para> - </section> - - <section id="pam-modules-opie"> - <title id="pam-modules-opie.title">&man.pam.opie.8;</title> - - <para>The &man.pam.opie.8; module implements the &man.opie.4; - authentication method. The &man.opie.4; system is a - challenge-response mechanism where the response to each - challenge is a direct function of the challenge and a - passphrase, so the response can be easily computed <quote>just - in time</quote> by anyone possessing the passphrase, - eliminating the need for password lists. Moreover, since - &man.opie.4; never reuses a challenge that has been correctly - answered, it is not vulnerable to replay attacks.</para> - </section> - - <section id="pam-modules-opieaccess"> - <title id="pam-modules-opieaccess.title">&man.pam.opieaccess.8;</title> - - <para>The &man.pam.opieaccess.8; module is a companion module to - &man.pam.opie.8;. Its purpose is to enforce the restrictions - codified in &man.opieaccess.5;, which regulate the conditions - under which a user who would normally authenticate herself - using &man.opie.4; is allowed to use alternate methods. This - is most often used to prohibit the use of password - authentication from untrusted hosts.</para> - - <para>In order to be effective, the &man.pam.opieaccess.8; - module must be listed as <literal>requisite</literal> - immediately after a <literal>sufficient</literal> entry for - &man.pam.opie.8;, and before any other modules, in the - <literal>auth</literal> chain.</para> - </section> - - <section id="pam-modules-passwdqc"> - <title id="pam-modules-passwdqc.title">&man.pam.passwdqc.8;</title> - - <para>The &man.pam.passwdqc.8; module</para> - </section> - - <section id="pam-modules-permit"> - <title id="pam-modules-permit.title">&man.pam.permit.8;</title> - - <para>The &man.pam.permit.8; module is one of the simplest - modules available; it responds to any request with - <literal>PAM_SUCCESS</literal>. It is useful as a placeholder - for services where one or more chains would otherwise be - empty.</para> - </section> - - <section id="pam-modules-radius"> - <title id="pam-modules-radius.title">&man.pam.radius.8;</title> - - <para>The &man.pam.radius.8; module</para> - </section> - - <section id="pam-modules-rhosts"> - <title id="pam-modules-rhosts.title">&man.pam.rhosts.8;</title> - - <para>The &man.pam.rhosts.8; module</para> - </section> - - <section id="pam-modules-rootok"> - <title id="pam-modules-rootok.title">&man.pam.rootok.8;</title> - - <para>The &man.pam.rootok.8; module reports success if and only - if the real user id of the process calling it (which is - assumed to be run by the applicant) is 0. This is useful for - non-networked services such as &man.su.1; or &man.passwd.1;, - to which the <literal>root</literal> should have automatic - access.</para> - </section> - - <section id="pam-modules-securetty"> - <title id="pam-modules-securetty.title">&man.pam.securetty.8;</title> - - <para>The &man.pam.securetty.8; module</para> - </section> - - <section id="pam-modules-self"> - <title id="pam-modules-self.title">&man.pam.self.8;</title> - - <para>The &man.pam.self.8; module reports success if and only if - the names of the applicant matches that of the target account. - It is most useful for non-networked services such as - &man.su.1;, where the identity of the applicant can be easily - verified.</para> - </section> - - <section id="pam-modules-ssh"> - <title id="pam-modules-ssh.title">&man.pam.ssh.8;</title> - - <para>The &man.pam.ssh.8; module provides both authentication - and session services. The authentication service allows users - who have passphrase-protected SSH secret keys in their - <filename>~/.ssh</filename> directory to authenticate - themselves by typing their passphrase. The session service - starts &man.ssh-agent.1; and preloads it with the keys that - were decrypted in the authentication phase. This feature is - particularly useful for local logins, whether in X (using - &man.xdm.1; or another PAM-aware X login manager) or at the - console.</para> - </section> - - <section id="pam-modules-tacplus"> - <title id="pam-modules-tacplus.title">&man.pam.tacplus.8;</title> - - <para>The &man.pam.tacplus.8; module</para> - </section> - - <section id="pam-modules-unix"> - <title id="pam-modules-unix.title">&man.pam.unix.8;</title> - - <para>The &man.pam.unix.8; module implements traditional &unix; - password authentication, using &man.getpwnam.3; to obtain the - target account's password and compare it with the one provided - by the applicant. It also provides account management - services (enforcing account and password expiration times) and - password-changing services. This is probably the single most - useful module, as the great majority of admins will want to - maintain historical behaviour for at least some - services.</para> - </section> - </section> - - <section id="pam-appl-prog"> - <title id="pam-appl-prog.title">PAM Application Programming</title> - - <para><!--XXX-->This section has not yet been written.</para> - - <!-- - - Note that while the original PAM paper includes a sample PAM - application that calls pam_open_session() before pam_setcred(), - the Linux-PAM documentation states that pam_setcred() must be - called first, which makes more sense. - - Also note that the example in the paper calls setgid(), - initgroups() and setuid() itself rather than rely on - pam_setcred() to do it. - - --> - - </section> - - <section id="pam-module-prog"> - <title id="pam-module-prog.title">PAM Module Programming</title> - - <para><!--XXX-->This section has not yet been written.</para> - </section> - - <appendix id="pam-sample-appl"> - <title id="pam-sample-appl.title">Sample PAM Application</title> - - <para>The following is a minimal implementation of &man.su.1; - using PAM. Note that it uses the OpenPAM-specific - &man.openpam.ttyconv.3; conversation function, which is - prototyped in <filename - class="headerfile">security/openpam.h</filename>. If you wish - build this application on a system with a different PAM library, - you will have to provide your own conversation function. A - robust conversation function is surprisingly difficult to - implement; the one presented in the <link - linkend="pam-sample-conv" - endterm="pam-sample-conv.title"></link> appendix is a good - starting point, but should not be used in real-world - applications.</para> - -<programlisting><inlinegraphic fileref="pam_app.c" - format="linespecific"></programlisting> - </appendix> - - <appendix id="pam-sample-module"> - <title id="pam-sample-module.title">Sample PAM Module</title> - - <para>The following is a minimal implementation of - &man.pam.unix.8;, offering only authentication services. It - should build and run with most PAM implementations, but takes - advantage of OpenPAM extensions if available: note the use of - &man.pam.get.authtok.3;, which enormously simplifies prompting - the user for a password.</para> - -<programlisting><inlinegraphic fileref="pam_module.c" - format="linespecific"></programlisting> - </appendix> - - <appendix id="pam-sample-conv"> - <title id="pam-sample-conv.title">Sample PAM Conversation - Function</title> - - <para>The conversation function presented below is a greatly - simplified version of OpenPAM's &man.openpam.ttyconv.3;. It is - fully functional, and should give the reader a good idea of how - a conversation function should behave, but it is far too simple - for real-world use. Even if you're not using OpenPAM, feel free - to download the source code and adapt &man.openpam.ttyconv.3; to - your uses; we believe it to be as robust as a tty-oriented - conversation function can reasonably get.</para> - -<programlisting><inlinegraphic fileref="pam_conv.c" - format="linespecific"></programlisting> - </appendix> - - <bibliography id="pam-further"> - <title id="pam-further.title">Further Reading</title> - - <abstract> - <para>This is a list of documents relevant to PAM and related - issues. It is by no means complete.</para> - </abstract> - - <bibliodiv> - <title>Papers</title> - - <biblioentry> - <title><ulink - url="http://www.sun.com/software/solaris/pam/pam.external.pdf"> - Making Login Services Independent of Authentication - Technologies</ulink></title> - <authorgroup> - <author> - <surname>Samar</surname> - <firstname>Vipin</firstname> - </author> - <author> - <surname>Lai</surname> - <firstname>Charlie</firstname> - </author> - </authorgroup> - <orgname>Sun Microsystems</orgname> - </biblioentry> - - <biblioentry> - <title><ulink - url="http://www.opengroup.org/pubs/catalog/p702.htm">X/Open - Single Sign-on Preliminary Specification</ulink></title> - <orgname>The Open Group</orgname> - <isbn>1-85912-144-6</isbn> - <pubdate>June 1997</pubdate> - </biblioentry> - - <biblioentry> - <title><ulink - url="http://www.kernel.org/pub/linux/libs/pam/pre/doc/current-draft.txt"> - Pluggable Authentication Modules</ulink></title> - <author> - <surname>Morgan</surname> - <firstname>Andrew</firstname> - <othername role="mi">G.</othername> - </author> - <pubdate>October 6, 1999</pubdate> - </biblioentry> - </bibliodiv> - - <bibliodiv> - <title>User Manuals</title> - - <biblioentry> - <title><ulink - url="http://www.sun.com/software/solaris/pam/pam.admin.pdf">PAM - Administration</ulink></title> - <orgname>Sun Microsystems</orgname> - </biblioentry> - </bibliodiv> - - <bibliodiv> - <title>Related Web pages</title> - - <biblioentry> - <title><ulink url="http://openpam.sourceforge.net/">OpenPAM homepage</ulink></title> - <author> - <surname>Smørgrav</surname> - <firstname>Dag-Erling</firstname> - </author> - <orgname>ThinkSec AS</orgname> - </biblioentry> - - <biblioentry> - <title><ulink url="http://www.kernel.org/pub/linux/libs/pam/">Linux-PAM homepage</ulink></title> - <author> - <surname>Morgan</surname> - <firstname>Andrew</firstname> - <othername role="mi">G.</othername> - </author> - </biblioentry> - - <biblioentry> - <title><ulink url="http://wwws.sun.com/software/solaris/pam/">Solaris PAM homepage</ulink></title> - <orgname>Sun Microsystems</orgname> - </biblioentry> - </bibliodiv> - </bibliography> -</article> diff --git a/en_US.ISO8859-1/articles/pam/converse.c b/en_US.ISO8859-1/articles/pam/converse.c deleted file mode 100644 index 2f8297dc0f..0000000000 --- a/en_US.ISO8859-1/articles/pam/converse.c +++ /dev/null @@ -1,102 +0,0 @@ -/*- - * Copyright (c) 2002 Networks Associates Technology, Inc. - * All rights reserved. - * - * This software was developed for the FreeBSD Project by ThinkSec AS and - * Network Associates Laboratories, the Security Research Division of - * Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 - * ("CBOSS"), as part of the DARPA CHATS research program. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * 3. The name of the author may not be used to endorse or promote - * products derived from this software without specific prior written - * permission. - * - * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE - * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * - * $FreeBSD$ - */ - -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <unistd.h> - -#include <security/pam_appl.h> - -int -converse(int n, const struct pam_message **msg, - struct pam_response **resp, void *data) -{ - struct pam_response *aresp; - char buf[PAM_MAX_RESP_SIZE]; - int i; - - data = data; - if (n <= 0 || n > PAM_MAX_NUM_MSG) - return (PAM_CONV_ERR); - if ((aresp = calloc(n, sizeof *aresp)) == NULL) - return (PAM_BUF_ERR); - for (i = 0; i < n; ++i) { - aresp[i].resp_retcode = 0; - aresp[i].resp = NULL; - switch (msg[i]->msg_style) { - case PAM_PROMPT_ECHO_OFF: - aresp[i].resp = strdup(getpass(msg[i]->msg)); - if (aresp[i].resp == NULL) - goto fail; - break; - case PAM_PROMPT_ECHO_ON: - fputs(msg[i]->msg, stderr); - if (fgets(buf, sizeof buf, stdin) == NULL) - goto fail; - aresp[i].resp = strdup(buf); - if (aresp[i].resp == NULL) - goto fail; - break; - case PAM_ERROR_MSG: - fputs(msg[i]->msg, stderr); - if (strlen(msg[i]->msg) > 0 && - msg[i]->msg[strlen(msg[i]->msg) - 1] != '\n') - fputc('\n', stderr); - break; - case PAM_TEXT_INFO: - fputs(msg[i]->msg, stdout); - if (strlen(msg[i]->msg) > 0 && - msg[i]->msg[strlen(msg[i]->msg) - 1] != '\n') - fputc('\n', stdout); - break; - default: - goto fail; - } - } - *resp = aresp; - return (PAM_SUCCESS); - fail: - for (i = 0; i < n; ++i) { - if (aresp[i].resp != NULL) { - memset(aresp[i].resp, 0, strlen(aresp[i].resp)); - free(aresp[i].resp); - } - } - memset(aresp, 0, n * sizeof *aresp); - *resp = NULL; - return (PAM_CONV_ERR); -} diff --git a/en_US.ISO8859-1/articles/pam/pam_unix.c b/en_US.ISO8859-1/articles/pam/pam_unix.c deleted file mode 100644 index 37d170a1df..0000000000 --- a/en_US.ISO8859-1/articles/pam/pam_unix.c +++ /dev/null @@ -1,165 +0,0 @@ -/*- - * Copyright (c) 2002 Networks Associates Technology, Inc. - * All rights reserved. - * - * This software was developed for the FreeBSD Project by ThinkSec AS and - * Network Associates Laboratories, the Security Research Division of - * Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 - * ("CBOSS"), as part of the DARPA CHATS research program. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * 3. The name of the author may not be used to endorse or promote - * products derived from this software without specific prior written - * permission. - * - * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE - * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * - * $P4: //depot/projects/openpam/modules/pam_unix/pam_unix.c#3 $ - * $FreeBSD$ - */ - -#include <sys/param.h> - -#include <pwd.h> -#include <stdlib.h> -#include <stdio.h> -#include <string.h> -#include <unistd.h> - -#include <security/pam_modules.h> -#include <security/pam_appl.h> - -#ifndef _OPENPAM -static char password_prompt[] = "Password:"; -#endif - -#ifndef PAM_EXTERN -#define PAM_EXTERN -#endif - -PAM_EXTERN int -pam_sm_authenticate(pam_handle_t *pamh, int flags, - int argc, const char *argv[]) -{ -#ifndef _OPENPAM - struct pam_conv *conv; - struct pam_message msg; - const struct pam_message *msgp; - struct pam_response *resp; -#endif - struct passwd *pwd; - const char *user; - char *crypt_password, *password; - int pam_err, retry; - - /* identify user */ - if ((pam_err = pam_get_user(pamh, &user, NULL)) != PAM_SUCCESS) - return (pam_err); - if ((pwd = getpwnam(user)) == NULL) - return (PAM_USER_UNKNOWN); - - /* get password */ -#ifndef _OPENPAM - pam_err = pam_get_item(pamh, PAM_CONV, (const void **)&conv); - if (pam_err != PAM_SUCCESS) - return (PAM_SYSTEM_ERR); - msg.msg_style = PAM_PROMPT_ECHO_OFF; - msg.msg = password_prompt; - msgp = &msg; -#endif - for (retry = 0; retry < 3; ++retry) { -#ifdef _OPENPAM - pam_err = pam_get_authtok(pamh, PAM_AUTHTOK, - (const char **)&password, NULL); -#else - resp = NULL; - pam_err = (*conv->conv)(1, &msgp, &resp, conv->appdata_ptr); - if (resp != NULL) { - if (pam_err == PAM_SUCCESS) - password = resp->resp; - else - free(resp->resp); - free(resp); - } -#endif - if (pam_err == PAM_SUCCESS) - break; - } - if (pam_err == PAM_CONV_ERR) - return (pam_err); - if (pam_err != PAM_SUCCESS) - return (PAM_AUTH_ERR); - - /* compare passwords */ - if ((!pwd->pw_passwd[0] && (flags & PAM_DISALLOW_NULL_AUTHTOK)) || - (crypt_password = crypt(password, pwd->pw_passwd)) == NULL || - strcmp(crypt_password, pwd->pw_passwd) != 0) - pam_err = PAM_AUTH_ERR; - else - pam_err = PAM_SUCCESS; -#ifndef _OPENPAM - free(password); -#endif - return (pam_err); -} - -PAM_EXTERN int -pam_sm_setcred(pam_handle_t *pamh, int flags, - int argc, const char *argv[]) -{ - - return (PAM_SUCCESS); -} - -PAM_EXTERN int -pam_sm_acct_mgmt(pam_handle_t *pamh, int flags, - int argc, const char *argv[]) -{ - - return (PAM_SUCCESS); -} - -PAM_EXTERN int -pam_sm_open_session(pam_handle_t *pamh, int flags, - int argc, const char *argv[]) -{ - - return (PAM_SUCCESS); -} - -PAM_EXTERN int -pam_sm_close_session(pam_handle_t *pamh, int flags, - int argc, const char *argv[]) -{ - - return (PAM_SUCCESS); -} - -PAM_EXTERN int -pam_sm_chauthtok(pam_handle_t *pamh, int flags, - int argc, const char *argv[]) -{ - - return (PAM_SERVICE_ERR); -} - -#ifdef PAM_MODULE_ENTRY -PAM_MODULE_ENTRY("pam_unix"); -#endif diff --git a/en_US.ISO8859-1/articles/pam/su.c b/en_US.ISO8859-1/articles/pam/su.c deleted file mode 100644 index ace48def3f..0000000000 --- a/en_US.ISO8859-1/articles/pam/su.c +++ /dev/null @@ -1,186 +0,0 @@ -/*- - * Copyright (c) 2002,2003 Networks Associates Technology, Inc. - * All rights reserved. - * - * This software was developed for the FreeBSD Project by ThinkSec AS and - * Network Associates Laboratories, the Security Research Division of - * Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 - * ("CBOSS"), as part of the DARPA CHATS research program. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * 3. The name of the author may not be used to endorse or promote - * products derived from this software without specific prior written - * permission. - * - * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE - * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * - * $P4: //depot/projects/openpam/bin/su/su.c#10 $ - * $FreeBSD$ - */ - -#include <sys/param.h> -#include <sys/wait.h> - -#include <err.h> -#include <pwd.h> -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <syslog.h> -#include <unistd.h> - -#include <security/pam_appl.h> -#include <security/openpam.h> /* for openpam_ttyconv() */ - -extern char **environ; - -static pam_handle_t *pamh; -static struct pam_conv pamc; - -static void -usage(void) -{ - - fprintf(stderr, "Usage: su [login [args]]\n"); - exit(1); -} - -int -main(int argc, char *argv[]) -{ - char hostname[MAXHOSTNAMELEN]; - const char *user, *tty; - char **args, **pam_envlist, **pam_env; - struct passwd *pwd; - int o, pam_err, status; - pid_t pid; - - while ((o = getopt(argc, argv, "h")) != -1) - switch (o) { - case 'h': - default: - usage(); - } - - argc -= optind; - argv += optind; - - if (argc > 0) { - user = *argv; - --argc; - ++argv; - } else { - user = "root"; - } - - /* initialize PAM */ - pamc.conv = &openpam_ttyconv; - pam_start("su", user, &pamc, &pamh); - - /* set some items */ - gethostname(hostname, sizeof(hostname)); - if ((pam_err = pam_set_item(pamh, PAM_RHOST, hostname)) != PAM_SUCCESS) - goto pamerr; - user = getlogin(); - if ((pam_err = pam_set_item(pamh, PAM_RUSER, user)) != PAM_SUCCESS) - goto pamerr; - tty = ttyname(STDERR_FILENO); - if ((pam_err = pam_set_item(pamh, PAM_TTY, tty)) != PAM_SUCCESS) - goto pamerr; - - /* authenticate the applicant */ - if ((pam_err = pam_authenticate(pamh, 0)) != PAM_SUCCESS) - goto pamerr; - if ((pam_err = pam_acct_mgmt(pamh, 0)) == PAM_NEW_AUTHTOK_REQD) - pam_err = pam_chauthtok(pamh, PAM_CHANGE_EXPIRED_AUTHTOK); - if (pam_err != PAM_SUCCESS) - goto pamerr; - - /* establish the requested credentials */ - if ((pam_err = pam_setcred(pamh, PAM_ESTABLISH_CRED)) != PAM_SUCCESS) - goto pamerr; - - /* authentication succeeded; open a session */ - if ((pam_err = pam_open_session(pamh, 0)) != PAM_SUCCESS) - goto pamerr; - - /* get mapped user name; PAM may have changed it */ - pam_err = pam_get_item(pamh, PAM_USER, (const void **)&user); - if (pam_err != PAM_SUCCESS || (pwd = getpwnam(user)) == NULL) - goto pamerr; - - /* export PAM environment */ - if ((pam_envlist = pam_getenvlist(pamh)) != NULL) { - for (pam_env = pam_envlist; *pam_env != NULL; ++pam_env) { - putenv(*pam_env); - free(*pam_env); - } - free(pam_envlist); - } - - /* build argument list */ - if ((args = calloc(argc + 2, sizeof *args)) == NULL) { - warn("calloc()"); - goto err; - } - *args = pwd->pw_shell; - memcpy(args + 1, argv, argc * sizeof *args); - - /* fork and exec */ - switch ((pid = fork())) { - case -1: - warn("fork()"); - goto err; - case 0: - /* child: give up privs and start a shell */ - - /* set uid and groups */ - if (initgroups(pwd->pw_name, pwd->pw_gid) == -1) { - warn("initgroups()"); - _exit(1); - } - if (setgid(pwd->pw_gid) == -1) { - warn("setgid()"); - _exit(1); - } - if (setuid(pwd->pw_uid) == -1) { - warn("setuid()"); - _exit(1); - } - execve(*args, args, environ); - warn("execve()"); - _exit(1); - default: - /* parent: wait for child to exit */ - waitpid(pid, &status, 0); - - /* close the session and release PAM resources */ - pam_err = pam_close_session(pamh, 0); - pam_end(pamh, pam_err); - - exit(WEXITSTATUS(status)); - } - -pamerr: - fprintf(stderr, "Sorry\n"); -err: - pam_end(pamh, pam_err); - exit(1); -} diff --git a/en_US.ISO8859-1/articles/portbuild/Makefile b/en_US.ISO8859-1/articles/portbuild/Makefile deleted file mode 100644 index f61284a9be..0000000000 --- a/en_US.ISO8859-1/articles/portbuild/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Portbuild Procedure -# - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/portbuild/article.sgml b/en_US.ISO8859-1/articles/portbuild/article.sgml deleted file mode 100644 index b5fcd98093..0000000000 --- a/en_US.ISO8859-1/articles/portbuild/article.sgml +++ /dev/null @@ -1,747 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Package Building Procedures</title> - - <authorgroup> - <corpauthor>The &os; Ports Management Team</corpauthor> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <copyright> - <year>2003</year> - <year>2004</year> - <holder role="mailto:portmgr@FreeBSD.org">The &os; Ports - Management Team</holder> - </copyright> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.intel; - &tm-attrib.sparc; - &tm-attrib.general; - </legalnotice> - </articleinfo> - - <sect1 id="intro"> - <title>Introduction and Conventions</title> - - <para>In order to provide pre-compiled binaries of third-party - applications for &os;, the ports collection is regularly - built on one of the <quote>Package Building Clusters.</quote> - Currently, there are two such clusters: - <hostid role="fqdn">pointyhat.FreeBSD.org</hostid> and - <hostid role="fqdn">dosirak.kr.FreeBSD.org</hostid>.</para> - - <para>Most of the package building magic occurs under the - <filename>/var/portbuild</filename> directory. Unless - otherwise specified, all paths will be relative to - this location. <replaceable>${arch}</replaceable> will - be used to specify one of the package architectures - (&i386;, alpha, &sparc64;, ia64, and amd64), and - <replaceable>${branch}</replaceable> will be used - to specify the build branch (4, 5, 4-exp). - </para> - </sect1> - - <sect1 id="management"> - <title>Build Client Management</title> - - <para>The &i386;, alpha, amd64, and two &sparc64; clients currently - netboot from <hostid>pointyhat</hostid>; the other sparc64 client - and ia64 clients are self-hosted. In all cases they set themselves - up at boot-time to prepare to build packages.</para> - - <para>In the latest round of portbuild updates, - <replaceable>disconnected</replaceable> cluster node support has - been added. A disconnected node is - one that does not mount the cluster master via NFS. It could be - a remote node, for example. The cluster master rsync's the - interesting data (ports, src, and doc trees, bindist tarballs, - scripts, etc.) to disconnected nodes during the node-setup - phase. Then, the disconnected portbuild directory is - nullfs-mounted for chroot builds.</para> - - <para>The - <username>ports-<replaceable>${arch}</replaceable></username> - user can &man.ssh.1; as <username>root</username> onto - each of the <replaceable>${arch}</replaceable> nodes.</para> - - <para>The <command>scripts/allgohans</command> script can - be used to run a command on all of the - <replaceable>${arch}</replaceable> clients.</para> - - <para>The <command>scripts/checkmachines</command> script - is used to monitor the load on all the nodes of the - build cluster, and schedule which nodes build which ports. - This script is not very robust, and has a tendency to die. - It is best to start up this script on the build master - (either <hostid>pointyhat</hostid> or <hostid>dosirak</hostid>) - after boot time using a &man.while.1; loop. - </para> - </sect1> - - <sect1 id="setup"> - <title>Chroot Build Environment Setup</title> - - <para>Package builds are performed in a - <literal>chroot</literal> populated by the - <filename>portbuild</filename> script using the - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/tarballs/bindist.tar</filename> - file. This tarball is created by the - <command>mkbindist</command> script which reads the - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/mkbindist.conf</filename> - file to decide how to create the tarball.</para> - - <para>The script should be run as <username>root</username> - with the following command:</para> - - <screen>/var/portbuild&prompt.root; <userinput>scripts/mkbindist <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable></userinput></screen> - - <para>If <literal>ftp=1</literal> in - <filename>mkbindist.conf</filename> then a pre-built release - will be downloaded via FTP from the location specified by - ftp://<replaceable>${ftpserver}</replaceable>/<replaceable>${ftpurl}</replaceable>/<replaceable>${rel}</replaceable>. - If <literal>ftp=0</literal> and - <literal>buildworld=1</literal> then - <command>mkbindist</command> will call - <command>makeworld</command> to build a new world - [<literal>XXX</literal> This is currently broken].</para> - - <para>If both <literal>ftp=0</literal> and - <literal>buildworld=0</literal> then - <command>mkbindist</command> will use the pre-existing - contents of <replaceable>${worlddir}</replaceable> to - create <filename>bindist.tar</filename>. In practice - this means that you must have already installed a world - in ${worlddir}, which is typically installed with the - <command>makeworld</command> script:</para> - - <screen>/var/portbuild&prompt.root; <userinput>scripts/makeworld <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> [-nocvs]</userinput></screen> - - <para>This command builds a world from the - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/src</filename> - tree and installs it into - <replaceable>${worlddir}</replaceable>. The tree will - be updated first unless <literal>-nocvs</literal> is - specified.</para> - - <para>The <filename>bindist.tar</filename> file is extracted - onto each client at client boot time, and at the start of - each pass of the <command>dopackages</command> - script. - </para> - </sect1> - - <sect1 id="starting"> - <title>Starting the Build</title> - - <para>The <filename>scripts/dopackages*</filename> scripts - are used to perform the builds. Most useful are:</para> - - <itemizedlist> - <listitem> - <para><command>dopackages.5</command> - Perform a - 5.X build - </para> - </listitem> - - <listitem> - <para><command>dopackages.4</command> - Perform a - 4.X build - </para> - </listitem> - - <listitem> - <para><command>dopackages.4-exp</command> - Perform - a 4.X build with experimental patches - (4-exp branch) - </para> - </listitem> - </itemizedlist> - - <para>These are wrappers around <command>dopackages</command>, - and are all symlinked to <command>dopackages.wrapper</command>. - New branch wrapper scripts can be created by symlinking - <command>dopackages.${branch}</command> to - <command>dopackages.wrapper</command>. These scripts - take a number of arguments. For example:</para> - - <screen><command>dopackages.5 <replaceable>${arch}</replaceable> <literal>[-options]</literal></command></screen> - - <para><literal>[-options]</literal> may be zero or more of the - following:</para> - - <itemizedlist> - <listitem> - <para><literal>-nofinish</literal> - Do not perform - post-processing once the build is complete. Useful - if you expect that the build will need to be restarted - once it finishes. This option should always be used - for normal build operations. - </para> - </listitem> - - <listitem> - <para><literal>-finish</literal> - Perform - post-processing only. - </para> - </listitem> - - <listitem> - <para><literal>-restart</literal> - Restart an interrupted - (or non-<literal>finish</literal>ed) build from the - beginning. Ports that failed on the previous build will - be rebuilt. - </para> - </listitem> - - <listitem> - <para><literal>-continue</literal> - Restart an interrupted - (or non-<literal>finish</literal>ed) build. Will not - rebuild ports that failed on the previous build. - </para> - </listitem> - - <listitem> - <para><literal>-incremental</literal> - Compare the - interesting fields of the new - <literal>INDEX</literal> with the previous one, - remove packages and log files for the old ports that - have changed, and rebuild the rest. This - cuts down on build times substantially since - unchanged ports do not get rebuilt everytime. - [XXX This is a work-in-progress, and does not yet - work as advertised.] - </para> - </listitem> - - <listitem> - <para><literal>-cdrom</literal> - This package build is - intended to end up on a CD-ROM, so - <literal>NO_CDROM</literal> packages and distfiles - should be deleted in post-processing. - </para> - </listitem> - - <listitem> - <para><literal>-nobuild</literal> - Perform all - the preprocessing steps, but do not actually do - the package build. - </para> - </listitem> - - <listitem> - <para><literal>-noindex</literal> - Do not rebuild - <filename>INDEX</filename> during preprocessing. - </para> - </listitem> - - <listitem> - <para><literal>-noduds</literal> - Do not rebuild the - <filename>duds</filename> file (ports that are never - built, e.g. those marked <literal>IGNORE</literal>, - <literal>NO_PACKAGE</literal>, etc.) during - preprocessing. - </para> - </listitem> - - <listitem> - <para><literal>-trybroken</literal> - Try to build - <literal>BROKEN</literal> ports (off by default - because the &i386; cluster is fast enough now - that when doing incremental builds, more time - was spent rebuilding things that were going to - fail anyway. Conversely, the other clusters - are slow enough that it would be a waste of time - to try and build <literal>BROKEN</literal> ports. - </para> - </listitem> - - <listitem> - <para><literal>-nocvs</literal> - Do not - <command>cvs update</command> the - <literal>src</literal> tree during preprocessing. - </para> - </listitem> - - <listitem> - <para><literal>-noportscvs</literal> - Do not - <command>cvs update</command> the - <literal>ports</literal> tree during preprocessing. - </para> - </listitem> - - <listitem> - <para><literal>-nodoccvs</literal> - Do not - <command>cvs update</command> the - <literal>doc</literal> tree during preprocessing. - </para> - </listitem> - - <listitem> - <para><literal>-norestr</literal> - Do not attempt to build - <literal>RESTRICTED</literal> ports. - </para> - </listitem> - - <listitem> - <para><literal>-plistcheck</literal> - Make it fatal for - ports to leave behind files after deinstallation. - </para> - </listitem> - - <listitem> - <para><literal>-distfiles</literal> - Collect distfiles - that pass <command>make checksum</command> for later - uploading to <hostid>ftp-master</hostid>. Use this - sparingly because it takes up a lot of disk space. - You should remove the distfiles once they have been - transfered to <hostid>ftp-master</hostid>. - </para> - </listitem> - - <listitem> - <para><literal>-fetch-original</literal> - Fetch the - distfile from the original <literal>MASTER_SITES</literal> - rather than <hostid>ftp-master</hostid>. - </para> - </listitem> - </itemizedlist> - - <para>Make sure the <replaceable>${arch}</replaceable> build - is run as the ports-<replaceable>${arch}</replaceable> user - or it will complain loudly.</para> - - <note><para>The actual package build itself occurs in two - identical phases. The reason for this is that sometimes - transient problems (e.g. NFS failures, FTP sites being - unreachable, etc.) may halt the build. Doing things - in two phases is a workaround for these types of - problems.</para></note> - - <para>Be careful that <filename>ports/Makefile</filename> - does not specify any empty subdirectories. This is especially - important if you are doing a 4-exp build. If the build - process encounters an empty subdirectory, both package build - phases will stop short, and an error similar to the following - will be written to - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/make.[0|1]</filename>: - </para> - - <screen><literal>don't know how to make dns-all(continuing)</literal></screen> - - <para>To correct this problem, simply comment out or remove - the <literal>SUBDIR</literal> entries that point to empty - subdirectories. After doing this, you can restart the build - by running the proper <command>dopackages</command> command - with the <literal>-restart</literal> option. - </para> - </sect1> - - <sect1 id="anatomy"> - <title>Anatomy of a Build</title> - - <para>A full build without any <literal>-no</literal> - options performs the following operations in the - specified order:</para> - - <orderedlist> - <listitem> - <para>A CVS checkout of the current <literal>ports</literal> - tree [*] - </para> - </listitem> - - <listitem> - <para>A CVS checkout of the running branch's - <literal>doc</literal> tree [*] - </para> - </listitem> - - <listitem> - <para>A CVS checkout of the running branch's - <literal>src</literal> tree [*] - </para> - </listitem> - - <listitem> - <para>Checks which ports do not have a - <literal>SUBDIR</literal> entry in their respective - category's <filename>Makefile</filename> [*] - </para> - </listitem> - - <listitem> - <para>Creates the <filename>duds</filename> file, which - is a list of ports not to build [*] [+] - </para> - </listitem> - - <listitem> - <para>Generates a fresh <filename>INDEX</filename> - file [*] [+] - </para> - </listitem> - - <listitem> - <para>Sets up the nodes that will be used in the - build [*] [+] - </para> - </listitem> - - <listitem> - <para>Builds a list of restricted ports [*] [+]</para> - </listitem> - - <listitem> - <para>Builds packages (phase 1) [++]</para> - </listitem> - - <listitem> - <para>Performs another node setup [+]</para> - </listitem> - - <listitem> - <para>Builds packages (phase 2) [++]</para> - </listitem> - </orderedlist> - - <para>[*] Status of these steps can be found in - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/build.log</filename> - as well as on stderr of the tty running the - <command>dopackages</command> command.</para> - - <para>[+] If any of these steps fail, the build will stop - cold in its tracks.</para> - - <para>[++] Status of these steps can be found in - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/make.[0|1]</filename>, - where <filename>make.0</filename> is the log file used by - phase 1 of the package build and <filename>make.1</filename> - is the log file used by phase 2. Individual ports will write - their build logs to - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/logs</filename> - and their error logs to - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/errors</filename>. - </para> - </sect1> - - <sect1 id="interrupting"> - <title>Interrupting a Build</title> - - <para>Sending a <literal>HUP</literal> signal to the - <command>dopackages*</command> shell processes or to any - <command>make</command> process invoked by those scripts - is usually sufficient to interrupt the build. The - package builds dispatched by <command>make</command> to - the client machines will clean themselves up after a - few minutes (check with <command>ps x</command> until they - all go away). The following command usually does the trick:</para> - - <screen>&prompt.user; <userinput>killall -HUP sh ssh make</userinput></screen> - - <para>Remove the - <filename><replaceable>${arch}</replaceable>/lock</filename> - file before trying to restart the build. - </para> - </sect1> - - <sect1 id="monitoring"> - <title>Monitoring the Build</title> - - <para>The - <command>scripts/stats <replaceable>${branch}</replaceable></command> - command counts the number of packages currently built.</para> - - <para>Running <command>cat /var/portbuild/*/loads/*</command> - shows the client loads and number of concurrent builds in - progress.</para> - - <para>Running <command>tail -f <replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/build.log</command> - shows the overall build progress.</para> - - <para>If a build is failing, and it is not immediately obvious - from the port build log as to why, you can preserve the - <literal>WRKDIR</literal> for further analysis. To do this, - touch a file called <filename>.keep</filename> in the port's - directory. The next time the cluster tries to build this port, - it will tar, compress, and copy the <literal>WRKDIR</literal> - to - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/wrkdirs</filename>. - </para> - - <para>Keep an eye on &man.df.1; output. If the - <filename>/var/portbuild</filename> file system becomes full - then <trademark>Bad Things</trademark> happen. - </para> - </sect1> - - <sect1 id="release"> - <title>Release Builds</title> - - <para>When building packages for a release, it may be - necessary to manually update the <literal>ports</literal> - and <literal>src</literal> trees to the release tag and use - <literal>-nocvs</literal> and - <literal>-noportscvs</literal>.</para> - - <para>To build package sets intended for use on a CD-ROM, - use the <literal>-cdrom</literal> option to - <command>dopackages</command>.</para> - - <para>Assuming disk space is available on the cluster, use - <literal>-distfiles</literal> to collect distfiles.</para> - - <note><para>You must run the initial build with - <literal>-distfiles</literal> to collect - all the fetched distfiles.</para></note> - - <para>After the initial build completes, restart the build - with - <literal>-restart -distfiles -fetch-original</literal> - to collect updated distfiles as well. Then, once the - build is post-processed, take an inventory of the list - of files fetched:</para> - - <screen>&prompt.user; <userinput>cd <replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable></userinput> -&prompt.user; <userinput>find distfiles > distfiles-<replaceable>${release}</replaceable></userinput></screen> - - <para>This inventory file typically lives in - <filename>i386/<replaceable>${branch}</replaceable></filename> - on the cluster master.</para> - - <para>This is useful to aid in periodically cleaning out - the distfiles from <hostid>ftp-master</hostid>. When space - gets tight, distfiles from recent releases can be kept while - others can be thrown away.</para> - - <para>Once the distfiles have been uploaded (see below), - the final release package set must be created. Just to be - on the safe side, run the - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/cdrom.sh</filename> - script by hand to make sure all the CD-ROM restricted packages - and distfiles have been pruned. Then, copy the - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/packages</filename> - directory to - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/packages-<replaceable>${release}</replaceable></filename>. - Once the packages are safely moved off, contact the &a.re; - and inform them of the release package location.</para> - - <para>Remember to coordinate with the &a.re; about the timing - and status of the release builds. - </para> - </sect1> - - <sect1 id="uploading"> - <title>Uploading Packages</title> - - <para>Once a build has completed, packages and/or distfiles - can be transferred to <hostid>ftp-master</hostid> for - propagation to the FTP mirror network. If the build was - run with <literal>-nofinish</literal>, then make sure to - follow up with - <command>dopackages -finish</command> to post-process the - packages (removes <literal>RESTRICTED</literal> and - <literal>NO_CDROM</literal> packages where appropriate, - prunes packages not listed in <filename>INDEX</filename>, - removes from <filename>INDEX</filename> - references to packages not built, and generates a - <filename>CHECKSUM.MD5</filename> - summary); and distfiles (moves them from the temporary - <filename>distfiles/.pbtmp</filename> directory into - <filename>distfiles/</filename> and removes - <literal>RESTRICTED</literal> and <literal>NO_CDROM</literal> - distfiles).</para> - - <para>It is usually a good idea to run the - <command>restricted.sh</command> and/or - <command>cdrom.sh</command> scripts by hand after - <command>dopackages</command> finishes just to be safe. - Run the <command>restricted.sh</command> script before - uploading to <hostid>ftp-master</hostid>, then run - <command>cdrom.sh</command> before preparing - the final package set for a release.</para> - - <para>Packages can be copied to the staging area on - <hostid>ftp-master</hostid> with something like the following:</para> - - <screen>&prompt.root; <userinput>cd /var/portbuild/<replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable></userinput> -&prompt.root; <userinput>tar cfv - packages/ | ssh portmgr@ftp-master tar xfC - w/ports/<replaceable>${arch}</replaceable>/tmp/<replaceable>${branch}</replaceable></userinput></screen> - - <para>Then log into <hostid>ftp-master</hostid>, verify that - the package set was transferred successfully, remove the - package set that the new package set is to replace (in - <filename>~/w/ports/<replaceable>${arch}</replaceable></filename>), - and move the new set into place.</para> - - <note><para>Some of the directories on - <hostid>ftp-master</hostid> are, in fact, symlinks. Be sure - you move the new packages directory over the - <emphasis>real</emphasis> destination directory, and not - one of the symlinks that points to it.</para></note> - - <para>Distfiles can be transferred via - <command>rsync</command>:</para> - - <screen>&prompt.root; <userinput>cd /var/portbuild/<replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable></userinput> -&prompt.root; <userinput>rsync -r -v -l -p -c -n distfiles/ portmgr@ftp-master:w/ports/distfiles/ | tee log</userinput></screen> - - <para><emphasis>ALWAYS</emphasis> use <literal>-n</literal> - first with <command>rsync</command> and check the output - to make sure it is sane. If it looks good, re-run the - <command>rsync</command> without the <literal>-n</literal> - option. - </para> - </sect1> - - <sect1 id="expbuilds"> - <title>Experimental Patches Builds</title> - - <para>Experimental patches builds are run from time to time to - new features or bugfixes to the ports infrastructure (i.e. - <literal>bsd.port.mk</literal>), or to test large sweeping - upgrades. The current experimental patches branch is - <literal>4-exp</literal> on the &i386; - architecture.</para> - - <para>In general, an experimental patches build is run the same - way as any other build. However, before running the - <literal>dopackages</literal> script, you must apply the required - patches to the ports tree. It is always a good idea to save - original copies of all changed files, as well as a list of what - you are changing. You can then look back on this list when doing - the final commit.</para> - - <para>In order to have a good control case with which to compare - failures, you should first do a package build of the branch on - which the experimental patches branch is based for the &i386; - architecture (currently this is <literal>4</literal>). Then, when - preparing for the experimental patches build, checkout a ports - tree and a src tree with the same date as was used for the control - build. This will ensure an apples-to-apples comparison - later.</para> - - <note><para>One build cluster can do the control build while the other - does the experimental patches build. This can be a great - time-saver.</para></note> - - <para>Once the build finishes, compare the control build failures - to those of the experimental patches build. Use the following - commands to facilitate this (this assumes the <literal>4</literal> - branch is the control branch, and the <literal>4-exp</literal> - branch is the experimental patches branch):</para> - - <screen>&prompt.user; <userinput>cd /var/portbuild/i386/4-exp/errors</userinput> -&prompt.user; <userinput>find . -name \*.log\* | sort > /tmp/4-exp-errs</userinput> -&prompt.user; <userinput>cd /var/portbuild/i386/4/errors</userinput> -&prompt.user; <userinput>find . -name \*.log\* | sort > /tmp/4-errs</userinput></screen> - - <note><para>If it has been a long time since one of the builds - finished, the logs may have been automatically compressed with - bzip2. In that case, you must use <literal>sort | sed - 's,\.bz2,,g'</literal> instead.</para></note> - - <screen>&prompt.user; <userinput>comm -3 /tmp/4-errs /tmp/4-exp-errs | less</userinput></screen> - - <para>This last command will produce a two-column report. The - first column is ports that failed on the control build but not in - the experimental patches build; the second column is vice versa. - Reasons that the port might be in the first column - include:</para> - - <itemizedlist> - <listitem> - <para>Port was fixed since the control build was run, or was - upgraded to a newer version that is also broken (thus the - newer version should appear in the second column) - </para> - </listitem> - - <listitem> - <para>Port is fixed by the patches in the experimental patches - build - </para> - </listitem> - - <listitem> - <para>Port did not build under the experimental patches build - due to a dependency failure - </para> - </listitem> - </itemizedlist> - - <para>Reasons for a port appearing in the second column - include:</para> - - <itemizedlist> - <listitem> - <para>Port was broken by the experimental patches [1]</para> - </listitem> - - <listitem> - <para>Port was upgraded since the control build and has become - broken [2] - </para> - </listitem> - - <listitem> - <para>Port was broken due to a transient error (e.g. FTP site - down, package client error, etc.) - </para> - </listitem> - </itemizedlist> - - <para>Both columns should be investigated and the reason for the - errors understood before committing the experimental patches set. - To differentiate between [1] and [2] above, you can do a rebuild - of the affected packages under the control branch:</para> - - <screen>&prompt.user; <userinput>cd /var/portbuild/i386/4/ports</userinput></screen> - - <note><para>Be sure to cvs update this tree to the same date as - the experimental patches tree.</para></note> - - <para>The following command will set up the control branch for - the partial build:</para> - - <screen>&prompt.user; <userinput>/var/portbuild/scripts/dopackages.4 -noportscvs -nobuild -nocvs -nofinish</userinput></screen> - - <para>The builds must be performed from the - <literal>packages/All</literal> directory. This directory should - initially be empty except for the Makefile symlink. If this - symlink does not exist, it must be created:</para> - - <screen>&prompt.user; <userinput>cd /var/portbuild/i386/4/packages/All</userinput> -&prompt.user; <userinput>ln -sf ../../Makefile .</userinput> -&prompt.user; <userinput>make -k -j<#> <list of packages to build></userinput></screen> - - <note><para><#> is the concurrency of the build to - attempt. It is usually the sum of the weights listed in - <filename>/var/portbuild/i386/mlist</filename> unless you have a - reason to run a heavier or lighter build.</para> - - <para>The list of packages to build should be a list of package - names (including versions) as they appear in - <filename>INDEX</filename>. The <literal>PKGSUFFIX</literal> - (i.e. .tgz or .tbz) is optional.</para></note> - - <para>This will build only those packages listed as well as all - of their dependencies. You can check the progress of this - partial build the same way you would a regular build. Once all - the errors have been resolved, you can commit the package set. - After committing, it is customary to send a <literal>HEADS - UP</literal> email to <ulink - url="mailto:ports@FreeBSD.org">ports@FreeBSD.org</ulink> and - copy <ulink - url="mailto:ports-developers@FreeBSD.org">ports-developers@FreeBSD.org</ulink> - informing people of the changes. A summary of all changes - should also be committed to - <filename>/usr/ports/CHANGES</filename>.</para> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/pr-guidelines/Makefile b/en_US.ISO8859-1/articles/pr-guidelines/Makefile deleted file mode 100644 index 9aa329f736..0000000000 --- a/en_US.ISO8859-1/articles/pr-guidelines/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Problem Report Handling Guidelines - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml deleted file mode 100644 index 4e5b78a033..0000000000 --- a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml +++ /dev/null @@ -1,530 +0,0 @@ -<!-- - Problem Report Handling Guidelines - The FreeBSD Project - http://www.FreeBSD.org ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -<!ENTITY man.edit-pr.1 "<citerefentry/<refentrytitle/edit-pr/<manvolnum/1//"> -<!ENTITY man.query-pr.1 "<citerefentry/<refentrytitle/query-pr/<manvolnum/1//"> -]> - -<article> - <!-- :START of Article Metadata --> - <articleinfo> - <title>Problem Report Handling Guidelines</title> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.opengroup; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>These guidelines describe recommended handling practices - for FreeBSD Problem Reports (PRs). Whilst developed for the - FreeBSD PR Database Maintenance Team - <email>freebsd-bugbusters@FreeBSD.org</email>, these - guidelines should be followed by anyone working with FreeBSD - PRs.</para> - </abstract> - - <authorgroup> - <author> - <firstname>Dag-Erling</firstname> - <surname>Smørgrav</surname> - </author> - - <author> - <firstname>Hiten</firstname> - <surname>Pandya</surname> - </author> - </authorgroup> - </articleinfo> - <!-- :END of Article Metadata--> - - <section id="intro"> - <title>Introduction</title> - - <para>GNATS is a defect management (bug reporting) system used by - the FreeBSD Project. As accurate tracking of outstanding - software defects is important to FreeBSD's quality, the - correct use of GNATS is essential to the forward progress of the - Project.</para> - - <para>Access to GNATS is available to FreeBSD developers, as well as - to the wider community. In order to maintain consistency within - the database and provide a consistent user experience, guidelines - have been established covering common aspects of bug management - such as presenting followup, handling close requests, and so - forth.</para> - </section> - - <section id="pr-lifecycle"> - <title>Problem Report Life-cycle</title> - - <itemizedlist> - <listitem> - <para>The Reporter submits a PR with &man.send-pr.1; and - receives a confirmation message.</para> - </listitem> - - <listitem> - <para>Joe Random Committer takes interest in the PR and - assigns it to himself, or Jane Random BugBuster decides that - Joe is best suited to handle it and assigns it to - him.</para> - </listitem> - - <listitem> - <para>Joe has a brief exchange with the originator (making - sure it all goes into the audit trail) and determines the - cause of the problem. He then makes sure the cause is - documented in the audit trail, and sets the PRs state to - <quote>analyzed</quote>.</para> - </listitem> - - <listitem> - <para>Joe pulls an all-nighter and whips up a patch that he - thinks fixes the problem, and submits it in a follow-up, - asking the originator to test it. He then sets the PRs - state to <quote>feedback</quote>.</para> - </listitem> - - <listitem> - <para>A couple of iterations later, both Joe and the - originator are satisfied with the patch, and Joe commits it - to <literal>-CURRENT</literal> (or directly to - <literal>-STABLE</literal> if the problem does not exist in - <literal>-CURRENT</literal>), making sure to reference the - Problem Report in his commit log (and credit the originator - if he submitted all or part of the patch) and, if - appropriate, start an MFC countdown.</para> - </listitem> - - <listitem> - <para>If the patch does not need MFCing, Joe then closes the - PR.</para> - </listitem> - - <listitem> - <para>If the patch needs MFCing, Joe leaves the Problem Report - in <quote>patched</quote> state until the patch has been - MFCed, then closes it.</para> - </listitem> - </itemizedlist> - - <note> - <para>Many PRs are submitted with very little information about - the problem, and some are either very complex to solve, or - just scratch the surface of a larger problem; in these cases, it - is very important to obtain all the necessary information - needed to solve the problem. If the problem contained within - cannot be solved, or has occurred again, it is necessary to - re-open the PR.</para> - </note> - <note> - <para>The <quote>email address</quote> used on the PR might not - be able to receive mail. In this case, followup to the PR as - usual and ask the originator (in the followup) to provide a - working email address. This is normally the case when - &man.send-pr.1; is used from a system with the mail system - disabled or not installed.</para> - </note> - </section> - - <section id="pr-states"> - <title>Problem Report State</title> - - <para>It is important to update the state of a PR when certain - actions are taken. The state should accurately reflect the - current state of work on the PR.</para> - - <example> - <title>A small example on when to change PR state</title> - - <para>When a PR has been worked on and the developer(s) - responsible feel comfortable about the fix, they will submit a - followup to the PR and change its state to - <quote>feedback</quote>. At this point, the originator should - evaluate the fix in their context and respond indicating - whether the defect has indeed been remedied.</para> - </example> - - <para>A Problem Report may be in one of the following - states:</para> - - <glosslist> - <glossentry> - <glossterm>open</glossterm> - <glossdef> - <para>Initial state; the problem has been pointed out and it - needs reviewing.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>analyzed</glossterm> - <glossdef> - <para>The problem has been reviewed and a - solution is being sought.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>feedback</glossterm> - <glossdef> - <para>Further work requires additional information from the - originator or the community; possibly information - regarding the proposed solution.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>patched</glossterm> - <glossdef> - <para>A patch has been committed, but something (MFC, or - maybe confirmation from originator) is still pending.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>suspended</glossterm> - <glossdef> - <para>The problem is not being worked on, due to lack of - information or resources. This is a prime candidate for - somebody who is looking for a project to take on. If the - problem cannot be solved at all, it will be closed, rather - than suspended. The documentation project uses - <quote>suspended</quote> for <quote>wish-list</quote> - items that entail a significant amount of work which no one - currently has time for.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>closed</glossterm> - <glossdef> - <para>A problem report is closed when any changes have been - integrated, documented, and tested, or when fixing the - problem is abandoned.</para> - </glossdef> - </glossentry> - </glosslist> - - <note> - <para>The <quote>patched</quote> state is directly related to - feedback, so you may go directly to <quote>closed</quote> state if - the originator cannot test the patch, and it works in your own testing.</para> - </note> - </section> - - <section id="pr-types"> - <title>Types of Problem Reports</title> - - <para>While handling problem reports, either as a developer who has - direct access to the GNATS database or as a contributor who - browses the database and submits followups with patches, comments, - suggestions or change requests, you will come across several - different types of PRs.</para> - - <itemizedlist> - <listitem> - <para><link linkend="pr-assigned">PRs already assigned to someone.</link></para> - </listitem> - <listitem> - <para><link linkend="pr-dups">Duplicates of existing PRs.</link></para> - </listitem> - <listitem> - <para><link linkend="pr-stale">Stale PRs</link></para> - </listitem> - <listitem> - <para><link linkend="pr-misfiled">Misfiled PRs</link></para> - </listitem> - </itemizedlist> - - <para>The following sections describe what each different type of - PRs is used for, when a PR belongs to one of these types, and what - treatment each different type receives.</para> - - <section id="pr-assigned"> - <title>Assigned PRs</title> - - <para>If a PR has the <literal>responsible</literal> field set - to the username of a FreeBSD developer, it means that the PR - has been handed over to that particular person for further - work.</para> - - <para>Assigned PRs should not be touched by anyone but the - assignee. If you have comments, submit a followup. If for - some reason you think the PR should change state or be - reassigned, send a message to the assignee. If the assignee - does not respond within two weeks, unassign the PR and do as - you please.</para> - </section> - - <section id="pr-dups"> - <title>Duplicate PRs</title> - - <para>If you find more than one PR that describe the same issue, - choose the one that contains the largest amount of useful - information and close the others, stating clearly the number - of the superseding PR. If several PRs contain non-overlapping - useful information, submit all the missing information to one - in a followup, including references to the others; then close - the other PRs (which are now completely superseded).</para> - </section> - - <section id="pr-stale"> - <title>Stale PRs</title> - - <para>A PR is considered stale if it has not been modified in more - than six months. Apply the following procedure to deal with - stale PRs:</para> - - <itemizedlist> - <listitem> - <para>If the PR contains sufficient detail, try to reproduce - the problem in <literal>-CURRENT</literal> and - <literal>-STABLE</literal>. If you succeed, submit a - followup detailing your findings and try to find someone - to assign it to. Set the state to <quote>analyzed</quote> - if appropriate.</para> - </listitem> - - <listitem> - <para>If the PR describes an issue which you know is the - result of a usage error (incorrect configuration or - otherwise), submit a followup explaining what the - originator did wrong, then close the PR with the reason - <quote>User error</quote> or <quote>Configuration - error</quote>.</para> - </listitem> - - <listitem> - <para>If the PR describes an error which you know has been - corrected in both <literal>-CURRENT</literal> and - <literal>-STABLE</literal>, close it with a message - stating when it was fixed in each branch.</para> - </listitem> - - <listitem> - <para>If the PR describes an error which you know has been - corrected in <literal>-CURRENT</literal>, but not in - <literal>-STABLE</literal>, try to find out when the person - who corrected it is planning to MFC it, or try to find - someone else (maybe yourself?) to do it. Set the state to - <quote>feedback</quote> and assign it to whomever will do - the MFC.</para> - </listitem> - - <listitem> - <para>In other cases, ask the originator to confirm if - the problem still exists in newer versions. If the - originator does not reply within a month, close the PR - with the notation <quote>Feedback timeout</quote>.</para> - </listitem> - </itemizedlist> - </section> - - <section id="pr-misfiled"> - <title>Misfiled PRs</title> - - <para>GNATS is picky about the format of a submitted bug report. - This is why a lot of PRs end up being <quote>misfiled</quote> if - the submitter forgets to fill in a field or puts the wrong sort of - data in some of the PR fields. This section aims to provide most - of the necessary details for FreeBSD developers that can help them to - close or refile these PRs.</para> - - <para>When GNATS cannot deduce what to do with a problem report - that reaches the database, it sets the responsible of the PR to - <literal>gnats-admin</literal> and files it under the - <literal>pending</literal> category. This is now a - <quote>misfiled</quote> PR and will not appear in bug report - listings, unless someone explicitly asks for a list of all the - misfiled PRs. If you have access to the FreeBSD cluster - machines, you can use <command>query-pr</command> to view a - listing of PRs that have been misfiled:</para> - - <screen>&prompt.user; <userinput>query-pr -x -q -r gnats-admin</userinput> - 52458 gnats-ad open serious medium Re: declaration clash f - 52510 gnats-ad open serious medium Re: lots of sockets in - 52557 gnats-ad open serious medium - 52570 gnats-ad open serious medium Jigdo maintainer update</screen> - - <para>Commonly PRs like the ones shown above are misfiled for one - of the following reasons:</para> - - <itemizedlist> - <listitem> - <para>A followup to an existing PR, sent through email, has - the wrong format on its <literal>Subject:</literal> - header.</para> - </listitem> - - <listitem> - <para>When completing the &man.send-pr.1; template, the submitter - forgot to set the category or class of the PR to a proper - value.</para> - </listitem> - - <listitem> - <para>It is not a real PR, but some random message sent to - <email>bug-followup@FreeBSD.org</email> or - <email>freebsd-gnats-submit@FreeBSD.org</email>.</para> - </listitem> - </itemizedlist> - - <section id="pr-misfiled-followups"> - <title>Followups misfiled as new PRs</title> - - <para>The first category of misfiled PRs, the one with the wrong - subject header, is actually the one that requires the greatest - amount of work from developers. These are not real PRs, - describing separate problem reports. When a reply is received - for an existing PR at one of the addresses that GNATS - <quote>listens</quote> to for incoming messages, the subject - of the reply should always be of the form:</para> - - <programlisting>Subject: Re: category/number: old synopsis text</programlisting> - - <para>Most mailers will add the - <quote><literal>Re: </literal></quote> part when you - reply to the original mail message of a PR. The - <quote><literal>category/number: </literal></quote> part - is a GNATS-specific convention that you have to manually - insert to the subject of your followup reports.</para> - - <para>Any FreeBSD developer, who has direct access to the GNATS - database, can periodically check for PRs of this sort and move - interesting bits of the misfiled PR into the audit trail of - the original PR (by posting a proper followup to a bug report - to the address <email>bug-followup@FreeBSD.org</email>). Then - the misfiled PR can be closed with a message similar - to:</para> - - <programlisting>Your problem report was misfiled. Please use the format -"Subject: category/number: original text" when following -up to older, existing PRs. I've added the relevant bits -from the body of this PR to kern/12345</programlisting> - - <para>Searching with <command>query-pr</command> for the - original PR, of which a misfiled followup is a reply, is as - easy as running:</para> - - <screen>&prompt.user; query-pr -q -y "some text"</screen> - - <para>After you locate the original PR and the misfiled - followups, use the <option>-F</option> option of - <command>query-pr</command> to save the full text of all the - relevant PRs in a &unix; mailbox file, i.e.:</para> - - <screen>&prompt.user; <userinput>query-pr -F 52458 52474 > mbox</userinput></screen> - - <para>Now you can use any mail user agent to view all the PRs - you saved in <filename>mbox</filename>. Copy the text of all - the misfiled PRs in a followup to the original PR and make - sure you include the proper <literal>Subject:</literal> - header. Then close the misfiled PRs. When you close the misfiled - PRs remember that the submitter receives a mail notification that - his PR changed state to <quote>closed</quote>. Make sure you - provide enough details in the log about the reason of this state - change. Typically something like the following is ok:</para> - - <programlisting>Followup to ports/45364 misfiled as a new PR. -This was misfiled because the subject didn't have the format: - - Re: ports/45364: ...</programlisting> - - <para>This way the submitter of the misfiled PR will know what to - avoid the next time a followup to an existing PR is sent.</para> - </section> - - <section id="pr-misfiled-format"> - <title>PRs misfiled because of missing fields</title> - - <para>The second type of misfiled PRs is usually the result of a - submitter forgetting to fill all the necessary fields when - writing the original PR.</para> - - <para>Missing or bogus <quote>category</quote> or - <quote>class</quote> fields can result in a misfiled report. - Developers can use &man.edit-pr.1; to change the category or - class of these misfiled PRs to a more appropriate value and - save the PR.</para> - - <para>Another common cause of misfiled PRs because of formatting - issues is quoting, changes or removal of the - <command>send-pr</command> template, either by the user who - edits the template or by mailers which do strange things to - plain text messages. This doesn't happen a lot of the time, - but it can be fixed with <command>edit-pr</command> too; it - does require a bit of work from the developer who refiles the - PR, but it is relatively easy to do most of the time.</para> - </section> - - <section id="pr-misfiled-notpr"> - <title>Misfiled PRs that are not really problem reports</title> - - <para>Sometimes a user wants to submit a report for a problem - and sends a simple email message to GNATS. The GNATS scripts - will recognize bug reports that are formatted using the - &man.send-pr.1; template. They cannot parse any sort of email - though. This is why submissions of bug reports that are sent - to <email>freebsd-gnats-submit@FreeBSD.org</email> have to - follow the template of <command>send-pr</command>, but email - reports can be sent to &a.bugs;.</para> - - <para>Developers that come across PRs that look like they should have - been posted to &a.bugs.name; or some other list should close the - PR, informing the submitter in their state-change log why this - is not really a PR and where the message should be posted.</para> - - <para>The email addresses that GNATS listens to for incoming PRs - have been published as part of the FreeBSD documentation, have - been announced and listed on the web-site. This means that - spammers found them. Every day several messages with - advertisements would reach GNATS which promptly files them all - under the <quote>pending</quote> category until someone looks - at them. Closing one of these with &man.edit-pr.1; is very - annoying though, because GNATS replies to the submitter and - the sender's address of spam mail is never valid these days. - Bounces will come back for each PR that is closed.</para> - - <para>Currently, with the installation of some antispam filters - that check all submissions to the GNATS database, the amount - of spam that reaches the <quote>pending</quote> state is very - small.</para> - - <para>All developers who have access to the FreeBSD.org cluster - machines are encouraged to check for misfiled PRs and immediately - close those that are spam mail. Whenever you close one of - these PRs it is also a good idea to set its category to - <quote><literal>junk</literal></quote>. Junk PRs are not - backed up, so filing spam mail under this category makes it - obvious that we do not care to keep it around or waste disk - space for it.</para> - </section> - </section> - </section> - - <section id="references"> - <title>Further Reading</title> - - <para>This is a list of resources relevant to the proper writing - and processing of problem reports. It is by no means complete.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="&url.articles.problem-reports;/article.html">How to - Write FreeBSD Problem Reports</ulink>—guidelines - for PR originators.</para> - </listitem> - </itemizedlist> - </section> -</article> diff --git a/en_US.ISO8859-1/articles/problem-reports/Makefile b/en_US.ISO8859-1/articles/problem-reports/Makefile deleted file mode 100644 index 081f20e0f8..0000000000 --- a/en_US.ISO8859-1/articles/problem-reports/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Writing FreeBSD Problem Reports - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/problem-reports/article.sgml b/en_US.ISO8859-1/articles/problem-reports/article.sgml deleted file mode 100644 index d17652e365..0000000000 --- a/en_US.ISO8859-1/articles/problem-reports/article.sgml +++ /dev/null @@ -1,879 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Writing &os; Problem Reports</title> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.cvsup; - &tm-attrib.ibm; - &tm-attrib.intel; - &tm-attrib.sparc; - &tm-attrib.sun; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This article describes how to best formulate and submit a - problem report to the &os; Project.</para> - </abstract> - - <authorgroup> - <author> - <firstname>Dag-Erling</firstname> - <surname>Smørgrav</surname> - <contrib>Contributed by </contrib> - </author> - </authorgroup> - </articleinfo> - - <indexterm><primary>problem reports</primary></indexterm> - - <section id="pr-intro"> - <title>Introduction</title> - - <para>One of the most frustrating experiences one can have as a - software user is to submit a problem report only to have it - summarily closed with a terse and unhelpful explanation like - <quote>not a bug</quote> or <quote>bogus PR</quote>. Similarly, - one of the most frustrating experiences as a software developer - is to be flooded with problem reports that are not really - problem reports but requests for support, or that contain little - or no information about what the problem is and how to reproduce - it.</para> - - <para>This document attempts to describe how to write good problem - reports. What, you ask, is a good problem report? Well, to go - straight to the bottom line, a good problem report is one that - can be analyzed and dealt with swiftly, to the mutual - satisfaction of both user and developer.</para> - - <para>Although the primary focus of this article is on &os; - problem reports, most of it should apply quite well to other - software projects.</para> - - <para>Note that this article is organized thematically, not - chronologically, so you should read through the entire document - before submitting a problem report, rather than treat it as a - step-by-step tutorial.</para> - </section> - - <section id="pr-when"> - <title>When to submit a problem report</title> - - <para>There are many types of problems, and not all of them should - engender a problem report. Of course, nobody is perfect, and - there will be times when you are convinced you have found a bug - in a program when in fact you have misunderstood the syntax for - a command or made a typographical error in a configuration file - (though that in - itself may sometimes be indicative of poor documentation or poor - error handling in the application). There are still many cases - where submitting a problem report is clearly - <emphasis>not</emphasis> the right - course of action, and will only serve to frustrate you and the - developers. Conversely, there are cases where it might be - appropriate to submit a problem report about something else than - a bug—an enhancement or a feature request, for - instance.</para> - - <para>So how do you determine what is a bug and what is not? As a - simple rule of thumb your problem is <emphasis>not</emphasis> a - bug if it can be expressed as a question (usually of the form - <quote>How do I do X?</quote> or <quote>Where can I find - Y?</quote>). It is not always quite so black and white, but the - question rule covers a large majority of cases. If you are looking - for an answer, consider posing your question to the - &a.questions;.</para> - - <para>Some cases where it may be appropriate to submit a problem - report about something that is not a bug are:</para> - - <itemizedlist> - <listitem> - <para>Requests for feature enhancements. It is generally a - good idea to air these on the mailing lists before - submitting a problem report.</para> - </listitem> - - <listitem> - <para>Notification of updates to externally maintained - software (mainly ports, but also externally maintained base - system components such as BIND or various GNU - utilities).</para> - </listitem> - </itemizedlist> - - <para>Another thing is that if the system on which you experienced - the bug is not fairly up-to-date, you should seriously consider - upgrading and trying to reproduce the problem on an up-to-date - system before submitting a problem report. There are few things - that will annoy a developer more than receiving a problem report - about a bug she has already fixed.</para> - - <para>Finally, a bug that can not be reproduced can rarely be - fixed. If the bug only occurred once and you can not reproduce - it, and it does not seem to happen to anybody else, chances are - none of the developers will be able to reproduce it or figure - out what is wrong. That does not mean it did not happen, but it - does mean that the chances of your problem report ever leading - to a bug fix are very slim. To make matters worse, often - these kinds of bugs are actually caused by failing hard drives - or overheating processors — you should always try to rule - out these causes, whenever possible, before submitting a PR.</para> - </section> - - <section id="pr-prep"> - <title>Preparations</title> - - <para>A good rule to follow is to always do a background search - before submitting a problem report. Maybe your problem has - already been reported; maybe it is being discussed on the - mailing lists, or recently was; it may even already be fixed in - a newer version than what you are running. You should therefore - check all the obvious places before submitting your problem - report. For &os;, this means:</para> - - <itemizedlist> - <listitem> - <para>The &os; - <ulink url="&url.books.faq;/index.html">Frequently Asked - Questions</ulink> (FAQ) list. - The FAQ attempts to provide answers for a wide range of questions, - such as those concerning - <ulink url="&url.books.faq;/hardware.html">hardware - compatibility</ulink>, - <ulink url="&url.books.faq;/applications.html">user - applications</ulink>, - and <ulink url="&url.books.faq;/kernelconfig.html">kernel - configuration</ulink>.</para> - </listitem> - - <listitem> - <para>The - <ulink - url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">mailing - lists</ulink>—if you are not subscribed, use - <ulink - url="http://www.FreeBSD.org/search/search.html#mailinglists">the - searchable archives</ulink> on the &os; web site. If your - problem has not been discussed on the lists, you might try - posting a message about it and waiting a few days to see if - someone can spot something you have overlooked.</para> - </listitem> - - <listitem> - <para>Optionally, the entire web—use your favorite - search engine to locate any references to your problem. You - may even get hits from archived mailing lists or newsgroups - you did not know of or had not thought to search - through.</para> - </listitem> - - <listitem> - <para>Next, the searchable - <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> - &os; PR database</ulink> (GNATS). Unless your problem - is recent or obscure, there is a fair chance it has already - been reported.</para> - </listitem> - - <listitem> - <para>Most importantly, you should attempt to see if existing - documentation in the source base addresses your problem.</para> - - <para>For the base &os; code, you should - carefully study the contents of the - <filename>/usr/src/UPDATING</filename> file on your system - or its latest version at - <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING"></ulink>. - (This is vital information - if you are upgrading from one version to - another—especially if you are upgrading to the - &os.current; branch).</para> - - <para>However, if the problem is in something that was installed - as a part of the &os; Ports Collection, you should refer to - <filename>/usr/ports/UPDATING</filename> (for individual ports) - or <filename>/usr/ports/CHANGES</filename> (for changes - that affect the entire Ports Collection). - <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING"></ulink> - and - <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES"></ulink> - are also available via CVSweb.</para> - </listitem> - </itemizedlist> - - <para>Next, you need to make sure your problem report goes to the - right people.</para> - - <para>The first catch here is that if the problem is a bug in - third-party software (a port or a package you have installed), you - should report the bug to the original author, not to the &os; - Project. There are two exceptions to this rule: the first is if - the bug does not occur on other platforms, in which case the - problem may lie in how the software was ported to &os;; the - second is if the original author has already fixed the bug and - released a patch or a new version of his software, and the - &os; port has not been updated yet.</para> - - <para>The second catch is that &os;'s bug tracking system sorts - problem reports according to the category the originator - selected. Therefore, if you select the wrong category when you - submit your problem report, there is a good chance that it will - go unnoticed for a while, until someone re-categorizes it.</para> - </section> - - <section id="pr-writing"> - <title>Writing the problem report</title> - - <para>Now that you have decided that your issue merits a problem - report, and that it is a &os; problem, it is time to write - the actual problem report. Before we get into the mechanics - of the program used to generate and submit PRs, here are some - tips and tricks to help make sure that your PR will be most - effective.</para> - - <section> - <title>Tips and tricks for writing a good problem report</title> - - <itemizedlist> - <listitem> - <para><emphasis>Do not leave the <quote>Synopsis</quote> - line empty.</emphasis> The PRs go both onto a mailing list - that goes all over the world (where the <quote>Synopsis</quote> - is used - for the <literal>Subject:</literal> line), but also into a - database. Anyone who comes along later and browses the - database by synopsis, and finds a PR with a blank subject - line, tends just to skip over it. Remember that PRs stay - in this database until they are closed by someone; an - anonymous one will usually just disappear in the - noise.</para> - </listitem> - - <listitem> - <para><emphasis>Avoid using a weak <quote>Synopsis</quote> - line.</emphasis> You should not assume that anyone reading - your PR has any context for your submission, so the more - you provide, the better. For instance, what part of the - system does the problem apply to? Do you only see the - problem while installing, or while running? To - illustrate, instead of <literal>Synopsis: portupgrade is - broken</literal>, see how much more informative this - seems: <literal>Synopsis: port sysutils/portupgrade - coredumps on -current</literal>. (In the case of ports, - it is especially helpful to have both the category and - portname in the <quote>Synopsis</quote> line.)</para> - </listitem> - - <listitem> - <para><emphasis>If you have a patch, say so.</emphasis> - A PR with a patch included is much more likely to be - looked at than one without. If you are including one, - put the string <literal>[patch]</literal> at the - beginning of the <quote>Synopsis</quote>. (Although it is - not mandatory to use that exact string, by convention, - that is the one that is used.)</para> - </listitem> - - <listitem> - <para><emphasis>If you are a maintainer, say so.</emphasis> - If you are maintaining a part of the source code (for - instance, a port), you might consider adding the string - <literal>[maintainer update]</literal> at the beginning of - your synopsis line, and you definitely should set the - <quote>Class</quote> of - your PR to <literal>maintainer-update</literal>. This way - any committer that handles your PR will not have to check.</para> - </listitem> - - <listitem> - <para><emphasis>Be specific.</emphasis> - The more information you supply about what problem you - are having, the better your chance of getting a response.</para> - - <itemizedlist> - <listitem> - <para>Include the version of &os; you are running (there - is a place to put that, see below) and on which architecture. - You should include whether you are running from a release - (e.g. from a CDROM or download), or from - a system maintained by &man.cvsup.1; (and, if so, how - recently you updated). If you are tracking the - &os.current; branch, that is the very first thing someone - will ask, because fixes (especially for high-profile - problems) tend to get committed very quickly, and - &os.current; users are expected to keep up.</para> - </listitem> - - <listitem> - <para>Include which global options you have specified in - your <filename>make.conf</filename>. Note: specifying - <literal>-O2</literal> and above to &man.gcc.1; is - known to be buggy in many situations. While the - &os; developers will accept patches, they are - generally unwilling to investigate such issues due - to simple lack of time and volunteers, and may - instead respond that this just is not supported.</para> - </listitem> - - <listitem> - <para>If this is a kernel problem, then be prepared to - supply the following information. (You do not - have to include these by default, which only tends to - fill up the database, but you should include excerpts - that you think might be relevant):</para> - - <itemizedlist> - <listitem> - <para>your kernel configuration (including which - hardware devices you have installed)</para> - </listitem> - <listitem> - <para>whether or not you have debugging options enabled - (such as <literal>WITNESS</literal>), and if so, - whether the problem persists when you change the - sense of that option</para> - </listitem> - <listitem> - <para>a backtrace, if one was generated</para> - </listitem> - <listitem> - <para>the fact that you have read - <filename>src/UPDATING</filename> and that your problem - is not listed there (someone is guaranteed to ask)</para> - </listitem> - <listitem> - <para>whether or not you can run any other kernel as - a fallback (this is to rule out hardware-related - issues such as failing disks and overheating CPUs, - which can masquerade as kernel problems)</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>If this is a ports problem, then be prepared to - supply the following information. (You do not - have to include these by default, which only tends to - fill up the database, but you should include excerpts - that you think might be relevant):</para> - - <itemizedlist> - <listitem> - <para>which ports you have installed</para> - </listitem> - <listitem> - <para>any environment variables that override the - defaults in <filename>bsd.port.mk</filename>, such - as <makevar>PORTSDIR</makevar></para> - </listitem> - <listitem> - <para>the fact that you have read - <filename>ports/UPDATING</filename> and that your problem - is not listed there (someone is guaranteed to ask)</para> - </listitem> - </itemizedlist> - </listitem> - - </itemizedlist> - - </listitem> - - <listitem> - <para><emphasis>Avoid vague requests for features.</emphasis> - PRs of the form <quote>someone should really implement something - that does so-and-so</quote> are less likely to get results than - very specific requests. Remember, the source is available - to everyone, so if you want a feature, the best way to - ensure it being included is to get to work! Also consider - the fact that many things like this would make a better - topic for discussion on <literal>freebsd-questions</literal> - than an entry in the PR database, as discussed above.</para> - </listitem> - - <listitem> - <para><emphasis>Make sure no one else has already submitted - a similar PR.</emphasis> Although this has already been - mentioned above, it bears repeating here. It only take a - minute or two to use the web-based search engine at - <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"></ulink>. - (Of course, everyone is guilty of forgetting to do this - now and then.)</para> </listitem> - - <listitem> - <para><emphasis>Avoid controversial requests.</emphasis> - If your PR addresses an area that has been controversial - in the past, you should probably be prepared to not only - offer patches, but also justification for why the patches - are <quote>The Right Thing To Do</quote>. As noted above, - a careful search of the mailing lists using the archives - at <ulink url="http://www.FreeBSD.org/search/search.html#mailinglists"></ulink> - is always good preparation.</para> - </listitem> - - <listitem> - <para><emphasis>Be polite.</emphasis> - Almost anyone who would potentially work on your PR is a - volunteer. No one likes to be told that they have to do - something when they are already doing it for some - motivation other than monetary gain. This is a good thing - to keep in mind at all times on Open Source - projects.</para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Before you begin</title> - - <para>Before running the &man.send-pr.1; program, make sure your - <envar>VISUAL</envar> (or <envar>EDITOR</envar> if - <envar>VISUAL</envar> is not set) environment variable is set - to something sensible.</para> - - <para>You should also make sure that mail delivery works fine. - &man.send-pr.1; uses mail messages for the submission and - tracking of problem reports. If you cannot post mail messages - from the machine you're running &man.send-pr.1; on, your - problem report will not reach the GNATS database. For details - on the setup of mail on &os;, see the <quote>Electronic - Mail</quote> chapter of the &os; Handbook at - <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html"></ulink>.</para> - </section> - - <section> - <title>Attaching patches or files</title> - - <para>The &man.send-pr.1; program has provisions for attaching - files to a problem report. You can attach as many files as - you want provided that each has a unique base name (i.e. the - name of the file proper, without the path). Just use the - <option>-a</option> command-line option to specify the names - of the files you wish to attach:</para> - -<screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/errors</userinput></screen> - - <para>Do not worry about binary files, they will be automatically - encoded so as not to upset your mail agent.</para> - - <para>If you attach a patch, make sure you use the - <option>-c</option> or <option>-u</option> option to - &man.diff.1; to create a context or unified diff (unified is - preferred), and make - sure to specify the exact CVS revision numbers of the files - you modified so the developers who read your report will be - able to apply them easily. For problems with the kernel or the - base utilities, a patch against &os.current; (the HEAD - CVS branch) is preferred since all new code should be applied - and tested there first. After appropriate or substantial testing - has been done, the code will be merged/migrated to the &os.stable; - branch.</para> - - <para>If you attach a patch inline, instead of as an attachment, - note that the most common problem by far is the tendency of some - email programs to render tabs as spaces, which will completely - ruin anything intended to be part of a Makefile.</para> - - <para>Also note that while including small patches in a PR is - generally all right—particularly when they fix the problem - described in the PR—large patches and especially new code - which may require substantial review before committing should - be placed on a web or ftp server, and the URL should be - included in the PR instead of the patch. Patches in email - tend to get mangled, especially when GNATS is involved, and - the larger the patch, the harder it will be for interested - parties to unmangle it. Also, posting a patch on the web - allows you to modify it without having to resubmit the entire - patch in a followup to the original PR.</para> - - <para>You should also take note that unless you explicitly - specify otherwise in your PR or in the patch itself, any - patches you submit will be assumed to be licensed under the - same terms as the original file you modified.</para> - </section> - - <section> - <title>Filling out the template</title> - - <para>When you run &man.send-pr.1;, you are presented with a - template. The template consists of a list of fields, some of - which are pre-filled, and some of which have comments explaining - their purpose or listing acceptable values. Do not worry - about the comments; they will be removed automatically if you - do not modify them or remove them yourself.</para> - - <para>At the top of the template, below the - <literal>SEND-PR:</literal> lines, are the email headers. You - do not normally need to modify these, unless you are sending - the problem report from a machine or account that can send but - not receive mail, in which case you will want to set the - <literal>From:</literal> and <literal>Reply-To:</literal> to - your real email address. You may also want to send yourself - (or someone else) a carbon copy of the problem report by - adding one or more email addresses to the - <literal>Cc:</literal> header.</para> - - <para>Next comes a series of single-line fields:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Submitter-Id:</emphasis> Do not change this. - The default value of <literal>current-users</literal> is - correct, even if you run &os.stable;.</para> - </listitem> - - <listitem> - <para><emphasis>Originator:</emphasis> This is normally - prefilled with the <literal>gecos</literal> field of the - currently logged-in - user. Please specify your real name, optionally followed - by your email address in angle brackets.</para> - </listitem> - - <listitem> - <para><emphasis>Organization:</emphasis> Whatever you feel - like. This field is not used for anything - significant.</para> - </listitem> - - <listitem> - <para><emphasis>Confidential:</emphasis> This is prefilled - to <literal>no</literal>. Changing it makes no sense as - there is no such thing as a confidential &os; problem - report—the PR database is distributed worldwide by - <application>CVSup</application>.</para> - </listitem> - - <listitem> - <para><emphasis>Synopsis:</emphasis> Fill this out with a - short and accurate description of the problem. The - synopsis is used as the subject of the problem report - email, and is used in problem report listings and - summaries; problem reports with obscure synopses tend to - get ignored.</para> - - <para>As noted above, if your problem report includes a patch, - please have the synopsis start with <literal>[patch]</literal>; - if you are a maintainer, you may consider adding - <literal>[maintainer update]</literal> and set the - <quote>Class</quote> of your PR to - <literal>maintainer-update</literal>.</para> - </listitem> - - <listitem> - <para><emphasis>Severity:</emphasis> One of - <literal>non-critical</literal>, - <literal>serious</literal> or - <literal>critical</literal>. Do not overreact; refrain - from labeling your problem <literal>critical</literal> - unless it really is (e.g. <username>root</username> exploit, easily - reproducible panic) or <literal>serious</literal> unless - it is something that will affect many users (problems with - particular device drivers or system utilities). &os; - developers will not neccesarily work on your problem faster - if you inflate its importance since there are so many other - people who have done exactly that — in fact, some - developers pay little attention to this field, and the next, - because of this.</para> - </listitem> - - <listitem> - <para><emphasis>Priority:</emphasis> One of - <literal>low</literal>, <literal>medium</literal> or - <literal>high</literal>. <literal>high</literal> should - be reserved for problems that will affect practically - every user of &os; and <literal>medium</literal> for - something that will affect many users.</para> - </listitem> - - <listitem> - <para><emphasis>Category:</emphasis> Choose one of the - following (taken from - <filename>/usr/gnats/gnats-adm/categories</filename>):</para> - <itemizedlist> - <listitem> - <para><literal>advocacy:</literal> problems relating to - &os;'s public image. Rarely used.</para> - </listitem> - - <listitem> - <para><literal>alpha:</literal> problems specific to the - Alpha platform.</para> - </listitem> - - <listitem> - <para><literal>amd64:</literal> problems specific to the - AMD64 platform.</para> - </listitem> - - <listitem> - <para><literal>bin:</literal> problems with userland - programs in the base system.</para> - </listitem> - - <listitem> - <para><literal>conf:</literal> problems with - configuration files, default values etc.</para> - </listitem> - - <listitem> - <para><literal>docs:</literal> problems with manual pages - or on-line documentation.</para> - </listitem> - - <listitem> - <para><literal>gnu:</literal> problems with GNU software - such as &man.gcc.1; or &man.grep.1;.</para> - </listitem> - - <listitem> - <para><literal>i386:</literal> problems specific to the - &i386; platform.</para> - </listitem> - - <listitem> - <para><literal>ia64:</literal> problems specific to the - ia64 platform.</para> - </listitem> - - <listitem> - <para><literal>java:</literal> problems related to &java;. - </para> - </listitem> - - <listitem> - <para><literal>kern:</literal> problems with - the kernel or (non-platform-specific) device drivers.</para> - </listitem> - - <listitem> - <para><literal>misc:</literal> anything that does not fit - in any of the other categories. (Note that it is - easy for things to get lost in this category).</para> - </listitem> - - <listitem> - <para><literal>ports:</literal> problems relating to the - ports tree.</para> - </listitem> - - <listitem> - <para><literal>powerpc:</literal> problems specific to the - &powerpc; platform.</para> - </listitem> - - <listitem> - <para><literal>sparc64:</literal> problems specific to the - &sparc64; platform.</para> - </listitem> - - <listitem> - <para><literal>standards:</literal> Standards conformance - issues.</para> - </listitem> - - <listitem> - <para><literal>threads:</literal> problems related to the - &os; threads implementation (especially on &os.current;).</para> - </listitem> - - <listitem> - <para><literal>www:</literal> Changes or enhancements to - the &os; website.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Class:</emphasis> Choose one of the - following:</para> - - <itemizedlist> - <listitem> - <para><literal>sw-bug:</literal> software bugs.</para> - </listitem> - - <listitem> - <para><literal>doc-bug:</literal> errors in - documentation.</para> - </listitem> - - <listitem> - <para><literal>change-request:</literal> requests for - additional features or changes in existing - features.</para> - </listitem> - - <listitem> - <para><literal>update:</literal> updates to ports or - other contributed software.</para> - </listitem> - - <listitem> - <para><literal>maintainer-update:</literal> updates to - ports for which you are the maintainer.</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para><emphasis>Release:</emphasis> The version of &os; - that you are running. This is filled out automatically by - &man.send-pr.1; and need only be changed if you are - sending a problem report from a different system than the - one that exhibits the problem.</para> - </listitem> - </itemizedlist> - - <para>Finally, there is a series of multi-line fields:</para> - - <itemizedlist> - <listitem> - <para><emphasis>Environment:</emphasis> This should - describe, as accurately as possible, the environment in - which the problem has been observed. This includes the - operating system version, the version of the specific - program or file that contains the problem, and any other - relevant items such as system configuration, other - installed software that influences the problem, - etc.—quite simply everything a developer needs to - know to reconstruct the environment in which the problem - occurs.</para> - </listitem> - - <listitem> - <para><emphasis>Description:</emphasis> A complete and - accurate description of the problem you are experiencing. - Try to avoid speculating about the causes of the problem - unless you are certain that you are on the right track, as - it may mislead a developer into making incorrect - assumptions about the problem.</para> - </listitem> - - <listitem> - <para><emphasis>How-To-Repeat:</emphasis> A summary of the - actions you need to take to reproduce the problem.</para> - </listitem> - - <listitem> - <para><emphasis>Fix:</emphasis> Preferably a patch, or at - least a workaround (which not only helps other people with - the same problem work around it, but may also help a - developer understand the cause for the problem), but if - you do not have any firm ideas for either, it is better to - leave this field blank than to speculate.</para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Sending off the problem report</title> - - <para>Once you are done filling out the template, have saved it, - and exit your editor, &man.send-pr.1; will prompt you with - <prompt>s)end, e)dit or a)bort?</prompt>. You can then hit - <userinput>s</userinput> to go ahead and submit the problem report, - <userinput>e</userinput> to restart the editor and make - further modifications, or <userinput>a</userinput> to abort. - If you choose the latter, your problem report will remain on - disk (&man.send-pr.1; will tell you the filename before it - terminates), so you can edit it at your leisure, or maybe - transfer it to a system with better net connectivity, before - sending it with the <option>-f</option> to - &man.send-pr.1;:</para> - -<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput></screen> - - <para>This will read the specified file, validate the contents, - strip comments and send it off.</para> - </section> - - </section> - - <section id="pr-followup"> - <title>Follow-up</title> - - <para>Once your problem report has been filed, you will receive a - confirmation by email which will include the tracking number - that was assigned to your problem report and a URL you can use - to check its status. With a little luck, someone will take an - interest in your problem and try to address it, or, as the case - may be, explain why it is not a problem. You will be - automatically notified of any change of status, and you will - receive copies of any comments or patches someone may attach to - your problem report's audit trail.</para> - - <para>If someone requests additional information from you, or you - remember or discover something you did not mention in the - initial report, please use one of two methods to submit your - followup:</para> - - <itemizedlist> - <listitem> - <para>The easiest way is to use the followup link on - the individual PR's web page, which you can reach from the - <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> - PR search page</ulink>. Clicking on this link will bring up an - an email window with the correct To: and Subject: lines filled in - (if your browser is configured to do this).</para> - </listitem> - - <listitem> - <para>Alternatively, you can just mail it to - <email>bug-followup@FreeBSD.org</email>, making sure that the - tracking number is included in the subject so the bug tracking - system will know what problem report to attach it to.</para> - - <note> - <para>If you do <emphasis>not</emphasis> include the tracking - number, GNATS will become confused and create an entirely - new PR which it then assigns to the GNATS administrator, - and then your followup will become lost until someone - comes in to clean up the mess, which could be days or - weeks afterwards.</para> - - <para>Wrong way: <programlisting>Subject: that PR I sent</programlisting> - Right way: <programlisting>Subject: Re: ports/12345: compilation problem with foo/bar</programlisting></para> - </note> - </listitem> - - </itemizedlist> - - <para>If the problem report remains open after the problem has - gone away, just send a follow-up (in the manner prescribed - above) saying that the problem report can be closed, and, if - possible, explaining how or when the problem was fixed.</para> - </section> - - <section id="pr-further"> - <title>Further Reading</title> - - <para>This is a list of resources relevant to the proper writing - and processing of problem reports. It is by no means complete.</para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"> - How to Report Bugs Effectively</ulink>—an excellent - essay by Simon G. Tatham on composing useful (non-&os;-specific) - problem reports.</para> - </listitem> - <listitem> - <para><ulink - url="&url.articles.pr-guidelines;/article.html">Problem - Report Handling Guidelines</ulink>—valuable insight - into how problem reports are handled by the &os; - developers.</para> - </listitem> - </itemizedlist> - </section> -</article> diff --git a/en_US.ISO8859-1/articles/pxe/Makefile b/en_US.ISO8859-1/articles/pxe/Makefile deleted file mode 100644 index 6f545e20a8..0000000000 --- a/en_US.ISO8859-1/articles/pxe/Makefile +++ /dev/null @@ -1,28 +0,0 @@ -# -# $FreeBSD$ -# -# Article: FreeBSD PXE Jumpstart Guide - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -EXTRAS= dhcpd.conf -EXTRAS+= install.cfg -EXTRAS+= loader.rc -EXTRAS+= pkgmaker.sh -EXTRAS+= post -EXTRAS+= pre - -SRCS= article.sgml - -afterinstall: -.for entry in ${EXTRAS} - ${INSTALL_DOCS} ${.CURDIR}/${entry} ${DESTDIR} -.endfor - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/pxe/article.sgml b/en_US.ISO8859-1/articles/pxe/article.sgml deleted file mode 100644 index efc50a8ecc..0000000000 --- a/en_US.ISO8859-1/articles/pxe/article.sgml +++ /dev/null @@ -1,285 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>FreeBSD Jumpstart Guide</title> - - <authorgroup> - <author> - <firstname>Alfred</firstname> - <surname>Perlstein</surname> - - <affiliation> - <address><email>alfred@FreeBSD.org</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.intel; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This article details the method used to allow machines to install - FreeBSD using the &intel; PXE method of booting a machine over a network. - </para> - </abstract> - </articleinfo> - - <sect1 id="introduction"> - <title>Introduction</title> - - <warning> - <para>This procedure will make the <quote>Server</quote> both insecure and dangerous, - it is best to just keep the <quote>Server</quote> on its own hub and not in any way - accessible by any machines other than the <quote>Clients</quote>.</para> - </warning> - - <para>Terminology:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - - <tbody> - <row> - <entry>Server</entry> - <entry>The machine offering netboot and install options.</entry> - </row> - - <row> - <entry>Client</entry> - <entry>The machine that will have FreeBSD installed on it.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Requires: - Clients supporting the &intel; PXE netboot option, an Ethernet connection. - </para> - - <para>Please let me know if you come across anything you have problems with - or suggestions for additional documentation.</para> - - <para>If you would like someone to train/implement a specific netinstall system - for you, please send email so that we can discuss terms.</para> - - <para>I would also like to thank &a.ps; and &a.jhb; for doing most of the - programming work on pxeboot, the interface to the &intel; PXE (netboot) - system.</para> - </sect1> - - <sect1 id="server-config"> - <title>Server Configuration</title> - - <procedure> - <step> - <para>Install DHCP: Install <filename role="package">net/isc-dhcp3-server</filename> you can use this config file - <ulink url="dhcpd.conf"> - <filename>dhcpd.conf</filename></ulink>, stick it in <filename>/usr/local/etc/</filename>.</para> - </step> - - <step> - <para>Enable tftp:</para> - - <procedure> - <step> - <para>Make a directory <filename>/usr/tftpboot</filename></para> - </step> - - <step> - <para>Add this line to your - <filename>/etc/inetd.conf</filename>:</para> - -<programlisting>tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /usr/tftpboot</programlisting> - </step> - </procedure> - - </step> - - <step> - <para>Enable NFS:</para> - - <procedure> - <step> - <para>Add this to <filename>/etc/rc.conf</filename>:</para> - - <programlisting>nfs_server_enable="YES"</programlisting> - </step> - - <step> - <para>Add this to <filename>/etc/exports</filename>:</para> - - <programlisting>/usr -alldirs -ro</programlisting> - </step> - </procedure> - </step> - - <step> - <para>Reboot to enable the new services or start them - manually.</para> - </step> - </procedure> - </sect1> - - <sect1 id="bootstrap-config"> - <title>Bootstrap Setup</title> - - <procedure> - <step> - <para>Download bootfiles: Download the - <ulink - url="&snapshots.stable;/floppies/kern.flp"> - kern.flp</ulink> and - <ulink - url="&snapshots.stable;/floppies/mfsroot.flp"> - mfsroot.flp</ulink> floppy images.</para> - </step> - - <step> - <para>Set up tftp/pxe-boot directory:</para> - - <procedure> - <step> - <para>Put pxeboot in the boot directory:</para> - - <screen>&prompt.root; <userinput>rm -rf /usr/obj/*</userinput> -&prompt.root; <userinput>cd /usr/src/sys/boot</userinput> -&prompt.root; <userinput>make</userinput> -&prompt.root; <userinput>cp /usr/src/sys/boot/i386/pxeldr/pxeboot /usr/tftpboot</userinput></screen> - </step> - - <step> - <para>Using the vndevice mount the <filename>kern.flp</filename> - file and copy its contents to - <filename>/usr/tftpboot</filename>:</para> - - <screen>&prompt.root; <userinput>vnconfig vn0 kern.flp</userinput> # associate a vndevice with the file -&prompt.root; <userinput>mount /dev/vn0 /mnt</userinput> # mount it -&prompt.root; <userinput>cp -R /mnt /usr/tftpboot</userinput> # copy the contents to /usr/tftpboot -&prompt.root; <userinput>umount /mnt</userinput> # unmount it -&prompt.root; <userinput>vnconfig -u vn0</userinput> # disassociate the vndevice from the file</screen> - </step> - </procedure> - </step> - - <step> - <para>Compile a custom kernel for the clients (particularly to avoid - the device config screen at boot) and stick it in - <filename>/usr/tftpboot</filename>.</para> - </step> - - <step> - <para>Make a special <filename>loader.rc</filename> to and install it - in <filename>/usr/tftpboot/boot/loader.rc</filename> so that it - does not prompt for the second disk, here is - <ulink url="loader.rc">mine</ulink>.</para> - </step> - - <step> - <para>Extract the installer and helper utilities from the mfsroot disk - and uncompress them, put them in <filename>/usr/tftpboot</filename> - as well:</para> - - <screen>&prompt.root; <userinput>vnconfig vn0 mfsroot.flp</userinput> # associate a vndevice with the file -&prompt.root; <userinput>mount /dev/vn0 /mnt</userinput> # mount it -&prompt.root; <userinput>cp /mnt/mfsroot.gz /usr/tftpboot</userinput> # copy the contents to /usr/tftpboot -&prompt.root; <userinput>umount /mnt</userinput> # unmount it -&prompt.root; <userinput>vnconfig -u vn0</userinput> # disassociate the vndevice from the file -&prompt.root; <userinput>cd /usr/tftpboot</userinput> # get into the pxeboot directory -&prompt.root; <userinput>gunzip mfsroot.gz</userinput> # uncompress the mfsroot</screen> - </step> - - <step> - <para>Make your sysinstall script <filename>install.cfg</filename>, you - can use - <ulink url="install.cfg">mine</ulink> - as a template, but you must edit it.</para> - </step> - - <step> - <para>Copy the sysinstall script into the extracted and uncompressed - mfsroot image:</para> - - <screen>&prompt.root; <userinput>cd /usr/tftpboot</userinput> -&prompt.root; <userinput>vnconfig vn0 mfsroot</userinput> -&prompt.root; <userinput>mount /dev/vn0 /mnt</userinput> -&prompt.root; <userinput>cp install.cfg /mnt</userinput> -&prompt.root; <userinput>umount /mnt</userinput> -&prompt.root; <userinput>vnconfig -u vn0</userinput></screen> - </step> - </procedure> - </sect1> - - <sect1 id="install-setup"> - <title>Install Setup</title> - - <procedure> - <step> - <para>Put the install files in an NFS accessible location on the - Server. Make a directory corresponding the 'nfs' directive in the - <filename> install.cfg</filename> file and mirror the FreeBSD - install files there, you will want it to look somewhat like - this:</para> - - <screen>ABOUT.TXT TROUBLE.TXT compat20 floppies ports -ERRATA.TXT UPGRADE.TXT compat21 games proflibs -HARDWARE.TXT XF86336 compat22 info src -INSTALL.TXT bin compat3x kern.flp -LAYOUT.TXT catpages crypto manpages -README.TXT cdrom.inf dict mfsroot.flp -RELNOTES.TXT compat1x doc packages</screen> - </step> - - <step> - <para>Copy the compressed packages into the packages/All directory - under <filename>nfs</filename>.</para> - </step> - - <step> - <para>Make sure you have an <filename>INDEX</filename> file prepared - in the packages directory. You can make your own - <filename>INDEX</filename> entries like so:</para> - - <programlisting>alfred-1.0||/|Alfred install bootstrap||alfred@FreeBSD.org||||</programlisting> - - <para>Then you can install custom packages, particularly your own - custom post-install package.</para> - </step> - </procedure> - </sect1> - - <sect1 id="custom-postinst-package"> - <title>Custom Post-Install Package</title> - - <para>You can use the script <ulink url="pkgmaker.sh"><filename>pkgmaker.sh - </filename></ulink> to create a - custom package for post install, the idea is to have it install and - configure any special things you may need done. - <filename>pkgmaker</filename> is run in the directory above the package - you wish to create with the single argument of the package (ie mypkg) - which will then create a mypkg.tgz for you to include in your sysinstall - package.</para> - - <para>Inside your custom package dir you will want a file called - <filename>PLIST</filename> which contains all the files that you wish to - install and be incorporated into your package.</para> - - <para>You will also want files called - <ulink url="pre"><filename>pre</filename></ulink> and - <ulink url="post"><filename>post</filename></ulink> - in the directory, these are shell scripts - that you want to execute before and after your package is - installed.</para> - - <para>Since this package is in your <filename>install.cfg</filename> file - it should be run and do the final configuration for you.</para> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/pxe/dhcpd.conf b/en_US.ISO8859-1/articles/pxe/dhcpd.conf deleted file mode 100644 index c0f552817e..0000000000 --- a/en_US.ISO8859-1/articles/pxe/dhcpd.conf +++ /dev/null @@ -1,23 +0,0 @@ - -# $Wintelcom: src/freebsd/pxe/doc/dhcpd.conf,v 1.2 2000/09/24 09:18:14 bright Exp $ -# $FreeBSD$ - -option subnet-mask 255.255.255.0; -option routers 10.8.253.254; -filename "pxeboot"; - -ddns-update-style none; - -option domain-name "google.com"; -option broadcast-address 10.8.253.255; -option domain-name-servers 10.8.0.7; -server-name "DHCPserver"; -server-identifier 10.8.253.201; - -default-lease-time 7200; -max-lease-time 7200; - -subnet 10.8.253.0 netmask 255.255.255.0 { - next-server 10.8.253.201; - range 10.8.253.29 10.8.253.200; -} diff --git a/en_US.ISO8859-1/articles/pxe/install.cfg b/en_US.ISO8859-1/articles/pxe/install.cfg deleted file mode 100644 index d543c53c3b..0000000000 --- a/en_US.ISO8859-1/articles/pxe/install.cfg +++ /dev/null @@ -1,209 +0,0 @@ - -# $Wintelcom: src/freebsd/pxe/doc/install.cfg,v 1.1 2000/07/14 12:42:05 bright Exp $ -# $FreeBSD$ - -# This is the installation configuration file for our rackmounted FreeBSD -# cluster machines - -# Turn on extra debugging. -debug=YES - -# Ok, this ought to turn off ALL prompting, don't complain to me that you -# lost a machine because you netbooted it on the same subnet as this -# box -nonInteractive=YES -noWarn=YES -tryDHCP=YES - -################################ -# My host specific data -hostname=booter -domainname=mydomain.com -# DHCP does this for us -#nameserver=10.0.0.1 -#defaultrouter=10.0.0.1 -#ipaddr=DHCP -#netmask=255.255.255.0 -################################ - -################################ -# Which installation device to use -nfs=x.x.x.x:/usr/releng4 -netDev=fxp0 -tryDHCP=YES -mediaSetNFS -################################ - -################################ -# Select which distributions we want. -dists= bin doc games manpages catpages proflibs dict info des compat1x compat20 compat21 compat22 compat3x crypto -distSetCustom -################################ - -################################ -# Now set the parameters for the partition editor on sd0. -disk=ad0 -partition=all -bootManager=standard -diskPartitionEditor -#diskPartitionWrite -################################ - -################################ -# All sizes are expressed in 512 byte blocks! -# -# A 96MB root partition, followed by a 0.5G swap partition, followed by -# a 1G /var, and a /usr using all the remaining space on the disk -# -ad0s1-1=ufs 1999999 / -ad0s1-2=swap 6485760 none -ad0s1-3=ufs 2097152 /var -ad0s1-4=ufs 0 /usr -# Let's do it! -diskLabelEditor -#diskLabelCommit - -# OK, everything is set. Do it! -installCommit - -package=XFree86-3.3.6 -packageAdd - -#package=XFree86-aoutlibs-3.3.3 -#packageAdd - -package=XFree86-contrib-3.3.6 -packageAdd - -package=arpwatch-2.1.a4 -packageAdd - -package=bash-2.04 -packageAdd - -package=bison-1.28 -packageAdd - -package=bzip2-1.0.0 -packageAdd - -package=ctags-3.5.2 -packageAdd - -package=dvips2ascii-1.3 -packageAdd - -package=electricfence-2.0.5 -packageAdd - -package=emacs-20.6 -packageAdd - -package=enscript-letter-1.6.1 -packageAdd - -package=fping-1.20 -packageAdd - -package=gawk-3.0.4 -packageAdd - -package=gdbm-1.8.0 -packageAdd - -package=gettext-0.10.35 -packageAdd - -package=gmake-3.79 -packageAdd - -package=ispell-3.1.20c -packageAdd - -package=less-352 -packageAdd - -package=libgnugetopt-1.1 -packageAdd - -package=libtool-1.3.4 -packageAdd - -package=linux_base-6.1 -packageAdd - -package=linux_devtools-6.1 -packageAdd - -package=lmbench-1.1 -packageAdd - -package=m4-1.4 -packageAdd - -package=mprof-3.0 -packageAdd - -package=mtr-0.42 -packageAdd - -package=nmap-2.53 -packageAdd - -package=pine-4.21 -packageAdd - -package=portscanner-1.0 -packageAdd - -package=portsentry-1.0 -packageAdd - -package=python-1.5.2 -packageAdd - -package=rpm-2.5.6 -packageAdd - -package=rsaref-2.0 -packageAdd - -package=rsync-2.4.3 -packageAdd - -package=screen-3.9.5 -packageAdd - -package=stlport-3.01 -packageAdd - -package=tcsh-6.09.00 -packageAdd - -package=tk-8.0.5 -packageAdd - -package=vim-lite-5.6.70 -packageAdd - -package=wget-1.5.3 -packageAdd - -package=word2x-0.005 -packageAdd - -package=zip-2.3 -packageAdd - -package=zsh-3.0.7 -packageAdd - -# -# this last package is special. It is used to configure the machine. -# it installs several files (like /root/.rhosts) and its installation -# script tweaks several options in /etc/rc.conf -# -package=mypkg-1.0 -packageAdd - -shutdown diff --git a/en_US.ISO8859-1/articles/pxe/loader.rc b/en_US.ISO8859-1/articles/pxe/loader.rc deleted file mode 100644 index 95130eb4df..0000000000 --- a/en_US.ISO8859-1/articles/pxe/loader.rc +++ /dev/null @@ -1,11 +0,0 @@ -\ $Wintelcom: src/freebsd/pxe/doc/loader.rc,v 1.1 2000/07/15 07:20:37 bright Exp $ -\ $FreeBSD$ -echo Loading Kernel... -load /kernel -echo Loading mfsroot... -load -t mfs_root /mfsroot -echo booting... -echo \007\007 -echo initializing h0h0magic... -set vfs.root.mountfrom="ufs:/dev/md0c" -boot diff --git a/en_US.ISO8859-1/articles/pxe/pkgmaker.sh b/en_US.ISO8859-1/articles/pxe/pkgmaker.sh deleted file mode 100644 index 0ff380b477..0000000000 --- a/en_US.ISO8859-1/articles/pxe/pkgmaker.sh +++ /dev/null @@ -1,9 +0,0 @@ -#!/bin/sh - -# $Wintelcom: src/freebsd/pxe/doc/pkgmaker.sh,v 1.1 2000/07/14 12:42:05 bright Exp $ -# $FreeBSD$ - -PKGNAME=${1} -PKGDIR=`pwd`/${PKGNAME}/ - -pkg_create -i ${PKGDIR}pre -I ${PKGDIR}post -f ${PKGDIR}PLIST -s ${PKGDIR} -p / -d ${PKGDIR}DESCR -c ${PKGDIR}COMMENT ${PKGNAME}.tgz diff --git a/en_US.ISO8859-1/articles/pxe/post b/en_US.ISO8859-1/articles/pxe/post deleted file mode 100644 index b465f55008..0000000000 --- a/en_US.ISO8859-1/articles/pxe/post +++ /dev/null @@ -1,36 +0,0 @@ -#!/bin/sh - -# $Wintelcom: src/freebsd/pxe/doc/post,v 1.1 2000/07/14 12:42:05 bright Exp $ -# $FreeBSD$ - -echo post-install - -set PATH=/bin:/usr/local/bin:/sbin:/usr/sbin:/usr/bin:/usr/bin/X11 -export PATH - -# do timezone -cp /usr/share/zoneinfo/America/Los_Angeles /etc/localtime - -conf="/etc/rc.conf.local" - -rm $conf - -echo 'sendmail_enable="NO"' >> $conf -echo 'dumpdev="/dev/ad0s1b"' >> $conf -echo 'sshd_enable="YES"' >> $conf -echo 'linux_enable="YES"' >> $conf - -# set up IP address and hostname -if=`ifconfig fxp1 inet | grep '[ ]*inet' | sed 's/[ ]*//'` -echo "ifconfig_fxp1=\"${if}\"" >> $conf -name=`echo $if | sed 's/[ ][ ]*/ /g' | cut -f2 -d" " | cut -f4 -d.` -echo "hostname=\"suyy${name}\"" >> $conf - -echo "network_interfaces=\"fxp0 fxp1 lo0\"" >> $conf - -# set up gateway, parse netstat output -gw=`netstat -rn | grep '^default' | sed 's/[ ][ ]*/ /g' | cut -f2 -d" "` -echo "defaultrouter=\"${gw}\"" >> $conf - -pwd_mkdb -p /etc/master.passwd -exit 0 diff --git a/en_US.ISO8859-1/articles/pxe/pre b/en_US.ISO8859-1/articles/pxe/pre deleted file mode 100644 index afeb6ab73d..0000000000 --- a/en_US.ISO8859-1/articles/pxe/pre +++ /dev/null @@ -1,7 +0,0 @@ -#!/bin/sh - -# $Wintelcom: src/freebsd/pxe/doc/pre,v 1.1 2000/07/14 12:42:05 bright Exp $ -# $FreeBSD$ - -echo pre-install -exit 0 diff --git a/en_US.ISO8859-1/articles/relaydelay/Makefile b/en_US.ISO8859-1/articles/relaydelay/Makefile deleted file mode 100644 index 68d6d001fc..0000000000 --- a/en_US.ISO8859-1/articles/relaydelay/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Using greylisting with FreeBSD - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/relaydelay/article.sgml b/en_US.ISO8859-1/articles/relaydelay/article.sgml deleted file mode 100644 index 3ed75ec5f6..0000000000 --- a/en_US.ISO8859-1/articles/relaydelay/article.sgml +++ /dev/null @@ -1,288 +0,0 @@ -<!-- - $FreeBSD$ ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -<!ENTITY % not.published "IGNORE"> -]> - -<article> - <articleinfo> - <title>Using Greylist with &os;</title> - - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <affiliation> - <address><email>trhodes@FreeBSD.org</email></address> - </affiliation> - </author> - - <copyright> - <year>2004</year> - <holder>The &os; Documentation Project</holder> - </copyright> - - <abstract> - <para>An article written for the sole purpose of explaining - the relaydelay system on a &os; mail server. A relaydelay - or greylisting server cuts down on spam simply by issuing - a <errorname>TEMPFAIL</errorname> error message to - every incoming email. The purpose behind this idea - is that most spammers use their personal computers with - software to do their spamming. A real mail server should - queue the message and try to send it later. Thus the - spammer most likely moves on to the next host in place - of trying to send the email again. This is an excellent - idea; at least until the spammers begin to use software - that offers to try again. But how does this work exactly? - Well, when an email is received the message - <acronym>ID</acronym> is stored in a database and the - <errorname>TEMPFAIL</errorname> is returned along with the - email. If the email is resent, the message - <acronym>ID</acronym> will be checked against the message - <acronym>ID</acronym>s currently stored in the database. - If it exists in the database then the email is permitted to reach its - intended recipient. Otherwise, the <acronym>ID</acronym> - will be stored and a <errorname>TEMPFAIL</errorname> will - be issued. This cycle will repeat with every email which - comes into the server. From my personal experience, this - really does cut out 90% of the spam.</para> - </abstract> - </articleinfo> - - <sect1> - <title>Basic Configuration</title> - - <para>&os; 4.X includes <command>perl</command> in the base - system, but we need the threaded <command>perl</command>. - Users of &os; 5.X may start the process after reading the forthcoming - note.</para> - - <para>Remove the base <command>perl</command> and all - traces of <command>perl</command> from the system with - the following command:</para> - - <!-- XXX This looks like too much; "Half of my home directory is - missing!" Won't use.perl do? --> - <screen>&prompt.root <userinput>find / -name '*perl*' | xargs rm -rf</userinput></screen> - - <note> - <para>This will require all ports which require - <command>perl</command> to be rebuilt and reinstalled; - <filename role="port">sysutils/portupgrade</filename> - is perfect for this. At least it will point out which - ports have been removed and which will need to be - reinstalled.</para> - </note> - - <para>Install <filename role="port">lang/perl5.8</filename> - with the <makevar>USE_THREADS=yes</makevar> variable - set. The current version of <command>perl</command> - may need to be removed first; errors will be reported - by the install process if this is necessary.</para> - - <note> - <para>&os; 4.X users will need to run the - <command>use.perl</command> command in the - <filename>work</filename> work directory. The - permissions may need to be altered to make the - file executable first, I just set it to 755 - with <command>chmod</command>. From this point - on, all users of &os; 4.X should uncomment the - <makevar>NOPERL</makevar> option in their local - <filename>make.conf</filename> file. Otherwise - the base <command>perl</command> will be reinstalled - during the next upgrade.</para> - </note> - - <para>Now for the database server; - <application>MySQL</application> is perfect for this - sort of work. Install the - <filename role="port">databases/mysql40-server</filename> - along with - <filename role="port">databases/p5-DBD-mysql40</filename>. - The previous port should imply the installation of - <filename role="port">databases/p5-DBI-137</filename> - so that knocks off another step.</para> - - <para>Install the <command>perl</command> based portable - server plugin, <filename role="port">net/p5-Net-Daemon</filename> - port. Most of these port installations should have - been straight forward. The next step will be more - involved.</para> - - <para>Now install the - <filename role="port">mail/p5-Sendmail-Milter</filename> - port. As of this writing the <filename>Makefile</filename> - contains a line beginning with <makevar>BROKEN</makevar>, - just remove it or comment it out. It is only marked - this way because &os; neither has nor installs - a threaded <command>perl</command> package by default. Once that - line is removed it should build and install perfectly - fine.</para> - - <para>Create a directory to hold temporary configuration - files:</para> - - <screen>&prompt.root; <userinput>mkdir /tmp/relaydelay</userinput> -&prompt.root; <userinput>cd /tmp/relaydelay</userinput></screen> - - <para>Now that we have a temporary directory to work in, the - following <acronym>URL</acronym>s should be sent to the - <command>fetch</command> command:</para> - - <screen>&prompt.root; <userinput>fetch http://projects.puremagic.com/greylisting/releases/relaydelay-0.04.tgz</userinput> -&prompt.root; <userinput>fetch http://lists.puremagic.com/pipermail/greylist-users/attachments/20030904/b8dafed9/relaydelay-0.04.bin</userinput></screen> - -<!-- NOTE TO TOM RHODES: HAVING THE SOFTWARE LINKED HERE IS A BAD IDEA IN - CASE SOME ASSHOLE UPDATES IT. I SHOULD PROBABLY ARCHIVE THE OTHER URL - SCRIPTS AND OTHER SHIT AS WELL. --> - - <para>The source code should now be unpacked:</para> - - <screen>&prompt.root; <userinput>gunzip -c relaydelay-0.04.tgz | tar xvf -</userinput></screen> - - <para>There should now be several files into the temporary directory - by this point. The appropriate information can now be passed to - the database server by importing it from the - <filename>mysql.sql</filename> file:</para> - - <screen>&prompt.root; <userinput>mysql < relaydelay-0.04/mysql.sql</userinput></screen> - - <para>And patch the other files with the - <filename>relaydelay.bin</filename> by running:</para> - - <screen>&prompt.root; <userinput>patch -d /tmp/relaydelay/relaydelay-0.04 < relaydelay.bin</userinput></screen> - - <para>Edit the <filename>relaydelay.conf</filename> and the - <filename>db_maintenance.pl</filename> file to append the - correct username and password for the - <application>MySQL</application> database. If the database was - built and installed like the above then no users or passwords - exist. This should be altered before putting this into - production, that is covered in the database documentation and - is beyond the scope of this document.</para> - - <para>Change the working directory to the - <filename role="directory">relaydelay-0.04</filename> - directory:</para> - - <screen>&prompt.root; <userinput>cd relaydelay-0.04</userinput></screen> - - <para>Copy or move the configuration files to their respective - directories:</para> - - <screen>&prompt.root; <userinput>mv db_maintenance.pl relaydelay.pl /usr/local/sbin</userinput> -&prompt.root; <userinput>mv relaydelay.conf /etc/mail</userinput> -&prompt.root; <userinput>mv relaydelay.sh /usr/local/etc/rc.d/</userinput></screen> - - <para>Test the current configuration by running:</para> - - <screen>&prompt.root; <userinput>sh /usr/local/etc/rc.d/relaydelay.sh start</userinput></screen> - - <note> - <para>This file will not exist if the previous &man.mv.1; commands - were neglected.</para> - </note> - - <para>If everything worked correctly a new file, - <filename>relaydelay.log</filename>, should exist in - <filename role="directory">/var/log</filename>. It should - contain something similar to the following text:</para> - - <programlisting>Loaded Config File: /etc/mail/relaydelay.conf -Using connection 'local:/var/run/relaydelay.sock' for filter relaydelay -DBI Connecting to DBI:mysql:database=relaydelay:host=localhost:port=3306 -Spawned relaydelay daemon process 38277. -Starting Sendmail::Milter 0.18 engine.</programlisting> - - <para>If this does not appear then something went wrong, review - the screen output or look for anything new in the - <filename>messages</filename> log file.</para> - - <para>Glue everything together by adding the following line to - <filename>/etc/mail/sendmail.mc</filename> or the customized - site specific <filename>mc</filename> file:</para> - - <programlisting>INPUT_MAIL_FILTER(`relaydelay', `S=local:/var/run/relaydelay.sock, T=S:1m;R:2m;E:3m')dnl</programlisting> - - <para>Rebuild and reinstall the files in the - <filename>/etc/mail</filename> directory and restart - <command>sendmail</command>. A quick <command>make</command> - <maketarget>restart</maketarget> should do the trick.</para> - - <para>Obtain the <command>perl</command> script located at - <ulink url="http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html"> - http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html</ulink> - and save it in the - <filename role="directory">relaydelay-0.04</filename> - directory. In the following examples this script is - referred to as <filename>addlist.pl</filename>.</para> - - <para>Edit the <filename>whitelist_ip.txt</filename> file and - modify it to include <acronym>IP</acronym> addresses of servers - which should have the explicit abilities to bypass the - <application>relaydelay</application> filters. i.e., domains - from which email will not be issued a - <errorname>TEMPFAIL</errorname> when received.</para> - - <para>Some examples could include:</para> - - <programlisting>192.168. # My internal network. -66.218.66 # Yahoo groups has unique senders.</programlisting> - - <para>The <filename>blacklist_ip.txt</filename> file should - be treated similarly but with reversed rules. List within - this file <acronym>IP</acronym>s which should be denied without - being issued a <errorname>TEMPFAIL</errorname>. This list of - domains will never have the opportunity to prove that they are - legitimate email servers.</para> - - <para>These files should now be imported into the database with - the <filename>addlist.pl</filename> script obtained a few - lines ago:</para> - - <screen>&prompt.root; <userinput>perl addlist.pl -whitelist 9999-12-31 23:59:59 < whitelist_ip.txt</userinput> -&prompt.root; <userinput>perl addlist.pl -blacklist 9999-12-31 23:59:59 < blacklist_ip.txt</userinput></screen> - - <para>To have <application>relaydelay</application> start with - every system boot, add the - <option>relaydelay_enable="YES"</option> to the - <filename>/etc/rc.conf</filename> file.</para> - - <para>The <filename>/var/log/relaydelay.log</filename> log file - should slowly fill up with success stories. Lines like the - following should appear after a short time, depending on how - busy the mail server is.</para> - - <programlisting>=== 2004-05-24 21:03:22 === -Stored Sender: <someasshole@flawed-example.com> -Passed Recipient: <local_user@pittgoth.com> - Relay: example.net [XXX.XX.XXX.XX] - If_Addr: MY_IP_ADDRESS - RelayIP: XX.XX.XX.XX - RelayName: example.net - RelayIdent: - PossiblyForged: 0 - From: someasshole@flawed-example.com - To: local_user - InMailer: esmtp - OutMailer: local - QueueID: i4P13Lo6000701111 - Email is known but block has not expired. Issuing a tempfail. rowid: 51 - IN ABORT CALLBACK - PrivData: 0<someasshole@flawed-example.com></programlisting> - - <para>The following line may now be added to - <filename>/etc/newsyslog.conf</filename> to cause for - <filename>relaydelay.log</filename> rotation at every - 100 <acronym>Kb</acronym>:</para> - - <screen>/var/log/relaydelay.log 644 3 100 * Z</screen> - - <!-- XXX What text does this note belong with? --> - <note> - <para>At some point there was an error about improper - <command>perl</command> variables in the - <filename>/etc/mail/relaydelay.conf</filename>. If those - two variables are commented out then configuration may - proceed as normal. Just remember to uncomment them before - starting the <command>relaydelay</command> process.</para> - </note> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/releng-packages/Makefile b/en_US.ISO8859-1/articles/releng-packages/Makefile deleted file mode 100644 index d47d0b2e9a..0000000000 --- a/en_US.ISO8859-1/articles/releng-packages/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -# -# $FreeBSD$ -# -# Article: FreeBSD Release Engineering of Third Party Software Packages - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -CSS_SHEET_ADDITIONS= extra.css - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/releng-packages/article.sgml b/en_US.ISO8859-1/articles/releng-packages/article.sgml deleted file mode 100644 index 0648814b6d..0000000000 --- a/en_US.ISO8859-1/articles/releng-packages/article.sgml +++ /dev/null @@ -1,367 +0,0 @@ -<!-- - The FreeBSD Documentation Project ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <title>FreeBSD Release Engineering for Third Party Software - Packages</title> - <articleinfo> - <authorgroup> - <author> - <firstname>Steve</firstname> - <surname>Price</surname> - <affiliation> - <address><email>steve@FreeBSD.org</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.intel; - &tm-attrib.xfree86; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This paper describes the approach used by the FreeBSD - release engineering team to produce a high quality package set - suitable for official FreeBSD release media. This document is - a work in progress, but eventually it will cover the process - used to build a clean package set on the FreeBSD.org <quote>Ports - Cluster</quote>, how to configure any other set of machines as a - ports cluster, how to split up the packages for the release - media, and how to verify that a package set is - consistent.</para> - </abstract> - - </articleinfo> - - <!-- Introduction - - <sect1 id="introduction"> - <title>Introduction</title> - - <para><emphasis>Coming Soon</emphasis></para> - - </sect1> - ---> - <sect1 id="portbuild"> - <title>Building packages from the Ports Collection</title> - - <para>The <ulink url="http://www.FreeBSD.org/ports">FreeBSD Ports - collection</ulink> is a collection of over &os.numports; - third-party software packages available for FreeBSD. The &a.portmgr; - is responsible for maintaining a consistent ports tree that can be used - to create the binary packages that accompany a given FreeBSD - release.</para> - - <sect2> - <title>The Ports Cluster</title> - - <para>In order to provide a consistent set of third-party - packages for FreeBSD releases, every port is built in a - separate chroot environment, starting with an empty - <filename>/usr/local</filename> and - <filename>/usr/X11R6</filename>. The requisite dependencies - are installed as packages before the build proceeds. This - enforces <emphasis>consistency</emphasis> in the package build - process. By starting the package build in a pristine - environment, we can assure that the package metadata (such as - required dependencies) is accurate. This way, we will never - generate packages that might work on some systems and not on - others depending on what software was previously - installed.</para> - - <para>The <quote>Ports Cluster</quote> for the x86 architecture - currently consists of a master node (Dual &pentium; III 733MHz) - and 8 slave nodes (&pentium; III 800MHz) to do the actual - package builds. With this configuration, a complete package - build takes over 24 hours. These machines are co-located with - the other FreeBSD Project equipment at Yahoo's corner of - Exodus in Santa Clara, CA.</para> - - <para>The <quote>Ports Cluster</quote> for the Alpha - architecture consists of 7 PWS 500A machines donated by Compaq - and also co-located with Yahoo's facilities.</para> - </sect2> - </sect1> - - <sect1> - <title>The Package Split</title> - - <para>For FreeBSD 4.4 over 4.1 gigabytes of packages were created. - This causes a problem for CDROM distributions because we would - like to ship as many packages as possible without making the - user insert another disc to satisfy dependencies. The solution - is to create <quote>clusters</quote> of like packages with - similar dependencies and group these onto specific discs. This - section describes the software and methodology used to create - those package sets for the official FreeBSD release - discs.</para> - - <para>The scripts and other files needed to produce a package - split can be found in the CVS tree in - <filename>ports/Tools/scripts/release</filename>. - Copy this directory to a machine that has enough free disk - space to hold 2 to 3 times the size of the package set that you - wish to split.</para> - - <para>The following scripts are present in this directory:</para> - - <variablelist> - <varlistentry> - <term><filename>config</filename></term> - - <listitem><para>This file contains the free space on each disc - and whether packages, distfiles, or both are allowed on any - given disc. The first column is the disc name. It must be - of the form <literal>disc[0-9a-z]</literal>. Currently it is set up - to allow for 10 discs (4 for the release set and 6 for the toolkit). - There is an implied extra disc called <quote>scratch</quote> where - all of the remaining distfiles/packages land if they do not fit - elsewhere. The second column can be either a 1 or 0, where 1 - says that it is okay to place packages on this disc. The - third column works the same way, but it controls - whether distfiles are placed on this disc. The last column - denotes the number of bytes of free space on a - disc.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>doit.sh</filename></term> - - <listitem><para>This is the workhorse. Once you have all the - files in place and things properly configured this script - directs the process of splitting packages. Beware it is - interactive so you need to keep an eye on it as it runs. - More details on what happens in this script will - follow.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>checkdeps.pl</filename></term> - - <listitem><para>Makes sure all packages dependencies are - satisfied given an <filename>INDEX</filename> file and a directory - of packages.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>oneshot.pl</filename></term> - - <listitem><para>This is where all the magic (and I use that - term loosely as it is mostly just a brute force approach) - happens. Given a list of required packages for each disc - and a set of packages/distfiles this is the script that - places a package or distfile on a disc along with all of its - dependencies.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>print-cdrom-packages.sh</filename></term> - - <listitem><para>This file is a copy of - <filename>src/release/scripts/print-cdrom-packages.sh</filename> - from the release you are working on.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>scrubindex.pl</filename></term> - - <listitem><para>This script removes lines from an - <filename>INDEX</filename> file for packages that are not present. - It also removes the &xfree86; dependencies. NOTE: you will need to - tweak the value of the <varname>xdep</varname> variable to make sure - the version number is correct.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>setup.sh</filename></term> - - <listitem><para>This is a helper script that I use on the - bento cluster to grab a copy of the ports tree and the - matching set of the packages/distfiles.</para></listitem> - </varlistentry> - </variablelist> - - <para>Here is a checklist of things you will need to check or - configure before going any further.</para> - - <orderedlist> - <listitem><para>Edit <filename>config</filename> to denote the - number of discs you have, their sizes, and whether you want - them want to contain packages, distfiles, both, or - neither.</para></listitem> - - <listitem><para>Make sure you remove the <varname>gen</varname> - directory if there is an old one laying around. This directory - contains working files that will only be valid for the current - split.</para></listitem> - - <listitem><para>On your first pass through a split it is best to - fake the copying of packages and distfiles. This will save - both time and diskspace while you do a couple of trial runs to - make sure things fit, etc. In the - <filename>oneshot.pl</filename> set the <varname>fake</varname> - variable to 1 and instead of actually copying the files it will - &man.touch.1; them. Be sure you turn this off or set - <varname>fake</varname> to 0 before you give the resultant discs to - the person that will be mastering the discs otherwise they will get a - directory full of zero-sized files.</para></listitem> - - <listitem><para>Make sure you have a recent copy of the - <filename>print-cdrom-packages.sh</filename> and that it is - from the correct release.</para></listitem> - - <listitem><para>Check to make sure the &xfree86; dependency in - <filename>scrubindex.pl</filename> has the correct - version number. You will also need to make sure this value is - correct in <filename>doit.sh</filename> as - well.</para></listitem> - </orderedlist> - - <para>Next you will need to get a copy of the ports tree, packages, - and distfiles from a recent build on the package cluster. See - the <filename>setup.sh</filename> for a working example - but essentially here is what needs to be done.</para> - - <orderedlist> - - <listitem><para>Grab a copy of <filename>ports.tar.gz</filename> - and extract it into the <filename>ports</filename> directory alongside - <filename>doit.sh</filename> and the - <filename>scripts</filename> directory.</para></listitem> - - <listitem><para>Remove the packages/distfiles directories or - symlinks. Bento has these as symlinks and you will have mixed - results if you do not get rid of them before - proceeding.</para></listitem> - - <listitem><para>Create a new ports/packages directory and copy - the package set from the package building - cluster.</para></listitem> - - <listitem><para>Create a new ports/distfiles directory and copy - the distfiles from the package building cluster. NOTE: if you - do not want any distfiles simply create the directory and leave - it empty. This directory must be present even if it does not - contain anything.</para></listitem> - </orderedlist> - - <para>Now we are finally ready for the fun task of actually - splitting the packages. You start the processing by running - <command>./doit.sh</command>. Here is what it does the first - time you run it.</para> - - <orderedlist> - <listitem><para>Create a list of the restricted (can not be on the - master FTP site) ports.</para></listitem> - - <listitem><para>Asks you if you would like to remove the restricted - ports. Most of the time you will want to answer (y)es - here.</para></listitem> - - <listitem><para>Create a list of the packages/distfiles that - can not be put on the discs.</para></listitem> - - <listitem><para>Asks you if you would like to remove the - non-cdromable packages/distfiles. Most of the time you will - want to answer (y)es here.</para></listitem> - - <listitem><para>Copies the <filename>INDEX</filename> from the - <filename>ports</filename> directory to the <filename>gen</filename> - directory. In doing so it removes the lines for ports - where the packages do not exist. It also checks to make sure - that all of the required dependency packages are - present.</para></listitem> - - <listitem><para>Create a list of packages that are required on - each disc.</para></listitem> - - <listitem><para>Asks you if you would like to populate the discs. - After populating each disc it will check for missing - dependencies, scrub the <filename>INDEX</filename> file, and create the - <filename>CHECKSUM.MD5</filename> file.</para></listitem> - - <listitem><para>Check to make sure the required packages made it - on each disc and gives you a summary of the sizes of each - disc.</para></listitem> - </orderedlist> - - <para>After going through this the first time if you are lucky - enough that all of the required packages built and fit on each - disc. All you need to do is set <varname>fake</varname> to 0 in - <filename>oneshot.pl</filename> and re-run - <command>./doit.sh</command>. The second and subsequent times - around it will skip steps 1-5 above. If you want to re-run any - of those steps refer to <filename>doit.sh</filename> for which files - need to be removed to not short-circuit those steps. If you want to - repeat all of these steps then the easiest way is to <command>rm -rf - gen</command>.</para> - - <para>Upon successful completion the packages/distfiles will be in - the <filename>disc*</filename> directories and the leftover will - be in the <filename>scratch</filename> directory.</para> - - <para>What to do if things go wrong? Here is some common gotchas - and workarounds.</para> - - <variablelist> - <varlistentry> - <term>Missing required packages</term> - - <listitem><para>This is a pretty common occurrence. You will - either need to wait for a new set of packages where the - missing packages were built or get someone to re-start the - package build for you. <emphasis>Do not</emphasis> attempt to build - the missing packages on your own machine and add them into the fray. - While you might be able to get away with this if you are - extremely careful the vast majority of the time you will miss - some little detail and the simple process of adding a - package could make hundreds of others come up mysteriously - broken.</para></listitem> - </varlistentry> - - <varlistentry> - <term>Required packages will not fit</term> - - <listitem><para>This happens on occasion too and is relatively - easy to fix. Simply edit - <filename>print-cdrom-packages.sh</filename> to move - packages around until they fit. Yes this is an iterative - process and one of the reasons why you should enable - <varname>fake</varname> in <filename>oneshot.pl</filename> until you - have gotten things the way you want them. Re-run - <command>./doit.sh</command> after you made your - adjustments.</para></listitem> - </varlistentry> - - <varlistentry> - <term>Required packages not on the right (or any) disc</term> - - <listitem><para>This usually means you did not add them to - <filename>print-cdrom-packages.sh</filename> or you put them - on the wrong disc. This script is the gospel by which this - whole process determines where a package must be. If you - want to force a package to land on a particular disc this is - the only way to ensure that it will - happen.</para></listitem> - </varlistentry> - </variablelist> - - <para>If you get completely stuck and can not figure out why things - are borked or how to fix them then email &a.steve; for - assistance.</para> - - </sect1> - -</article> diff --git a/en_US.ISO8859-1/articles/releng-packages/extra.css b/en_US.ISO8859-1/articles/releng-packages/extra.css deleted file mode 100644 index 7cf2be1d7d..0000000000 --- a/en_US.ISO8859-1/articles/releng-packages/extra.css +++ /dev/null @@ -1,16 +0,0 @@ -/* - * Netscape 4 does not recognice the @import directive of CSS, so we - * can't add an additional stylesheet layer on top of the default one. - * Instead, we use this hack to copy this file to the end of - * docbook.css. - * - * $FreeBSD$ - */ - -/* @import "docbook.css"; */ - -/* Customization that looks good for this particular article. */ - -DIV.TITLEPAGE { - text-align: center; -} diff --git a/en_US.ISO8859-1/articles/releng/Makefile b/en_US.ISO8859-1/articles/releng/Makefile deleted file mode 100644 index ae3d3c2f4f..0000000000 --- a/en_US.ISO8859-1/articles/releng/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -# -# $FreeBSD$ -# -# Article: FreeBSD Release Engineering - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml -IMAGES_EN= branches-head.pic -IMAGES_EN+= branches-releng3.pic -IMAGES_EN+= branches-releng4.pic - -CSS_SHEET_ADDITIONS= extra.css - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/releng/article.sgml b/en_US.ISO8859-1/articles/releng/article.sgml deleted file mode 100644 index ce4010c119..0000000000 --- a/en_US.ISO8859-1/articles/releng/article.sgml +++ /dev/null @@ -1,1046 +0,0 @@ -<!-- - The FreeBSD Documentation Project ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -<!ENTITY art.re.pkgs '<ulink url="&url.articles.releng-packages;/article.html">The Release Engineering of Third Party Packages</ulink>'> -]> - -<article> - <title>FreeBSD Release Engineering</title> - <articleinfo> - - <!-- This paper was presented at BSDCon Europe in Brighton, UK on - November 11, 2001 --> - <confgroup> - <confdates>November 2001</confdates> - <conftitle>BSDCon Europe</conftitle> - </confgroup> - - <authorgroup> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - <authorblurb> - <para>I've been involved in the development of FreeBSD based products - since 1997 at Walnut Creek CDROM, BSDi, and now Wind River Systems. - FreeBSD 4.4 was the first official release of FreeBSD that I played - a significant part in.</para> - </authorblurb> - <affiliation> - <address><email>murray@FreeBSD.org</email> - <otheraddr><ulink url="http://www.FreeBSD.org/~murray/"></ulink></otheraddr> - </address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.cvsup; - &tm-attrib.intel; - &tm-attrib.xfree86; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This paper describes the approach used by the FreeBSD - release engineering team to make production quality releases - of the FreeBSD Operating System. It details the methodology - used for the official FreeBSD releases and describes the tools - available for those interested in producing customized FreeBSD - releases for corporate rollouts or commercial - productization.</para> - </abstract> - - </articleinfo> - -<!-- Introduction --> -<sect1 id="introduction"> - <title>Introduction</title> - - <para>The development of FreeBSD is a very open process. FreeBSD is - comprised of contributions from thousands of people around the - world. The FreeBSD Project provides anonymous - <acronym>CVS</acronym>[1] access to the general public so that - others can have access to log messages, diffs (patches) between - development branches, and other productivity enhancements that - formal source code management provides. This has been a huge help - in attracting more talented developers to FreeBSD. However, I - think everyone would agree that chaos would soon manifest if write - access was opened up to everyone on the Internet. Therefore only - a <quote>select</quote> group of nearly 300 people are given write - access to the <acronym>CVS</acronym> repository. These - <emphasis>committers[6]</emphasis> are responsible for the bulk of - FreeBSD development. An elected <emphasis>core-team[7]</emphasis> - of very senior developers provides some level of direction over - the project.</para> - - <para>The rapid pace of <systemitem - class="osname">FreeBSD</systemitem> development leaves little time - for polishing the development system into a production quality - release. To solve this dilemma, development continues on two - parallel tracks. The main development branch is the - <emphasis>HEAD</emphasis> or <emphasis>trunk</emphasis> of our CVS - tree, known as <quote>FreeBSD-CURRENT</quote> or - <quote>-CURRENT</quote> for short.</para> - - <para>A more stable branch is maintained, known as - <quote>FreeBSD-STABLE</quote> or <quote>-STABLE</quote> for short. - Both branches live in a master CVS repository in California and - are replicated via <application - class="software">CVSup</application>[2] to mirrors all over the - world. FreeBSD-CURRENT[8] is the <quote>bleeding-edge</quote> of - FreeBSD development where all new changes first enter the system. - FreeBSD-STABLE is the development branch from which major releases - are made. Changes go into this branch at a different pace, and - with general assumption that they have first gone into - FreeBSD-CURRENT and have been thoroughly tested by our user - community.</para> - - <para>In the interim period between releases, nightly snapshots are - built automatically by the FreeBSD Project build machines and made - available for download from <systemitem - class="resource">ftp://stable.FreeBSD.org/</systemitem>. The - widespread availability of binary release snapshots, and the - tendency of our user community to keep up with -STABLE development - with CVSup and <quote><command>make</command> - <maketarget>world</maketarget></quote>[8] helps to keep - FreeBSD-STABLE in a very reliable condition even before the - quality assurance activities ramp up pending a major - release.</para> - - <para>Bug reports and feature requests are continuously submitted by - users throughout the release cycle. Problems reports are entered into our - <application class="software">GNATS</application>[9] database - through email, the &man.send-pr.1; application, or via the web - interface provided at <ulink - url="http://www.FreeBSD.org/send-pr.html"></ulink>. - In addition to the multitude of different technical mailing lists - about FreeBSD, the &a.qa; provides a forum for discussing the finer - points of <quote>release-polishing</quote>.</para> - - <para>To service our most conservative users, individual release - branches were introduced with FreeBSD 4.3. - These release branches are created shortly before a final release - is made. After the release goes out, only the most critical - security fixes and additions are merged onto the release branch. - In addition to source updates via CVS, binary patchkits are - available to keep systems on the - <emphasis>RELENG_<replaceable>X</replaceable>_<replaceable>Y</replaceable></emphasis> - branches updated.</para> - - <para><xref linkend="release-proc"> discusses the - different phases of the release engineering process leading up to - the actual system build and <xref linkend="release-build"> - describes the actual build process. <xref - linkend="extensibility"> describes how the base - release may be extended by third parties and <xref - linkend="lessons-learned"> details some of the - lessons learned through the release of FreeBSD 4.4. Finally, - <xref linkend="future"> presents future directions - of development.</para> -</sect1> - -<!-- Release Process --> -<sect1 id="release-proc"> - <title>Release Process</title> - - <para>New releases of FreeBSD are released from the -STABLE branch - at approximately four month intervals. The FreeBSD release - process begins to ramp up 45 days before the anticipated release - date when the release engineer sends an email to the development - mailing lists to remind developers that they only have 15 days to - integrate new changes before the code freeze. During this time, - many developers perform what have become known as <quote>MFC - sweeps</quote>. <acronym>MFC</acronym> stands for <quote>Merge - From CURRENT</quote> and it describes the process of merging a - tested change from our -CURRENT development branch to our -STABLE - branch.</para> - - <sect2> - <title>Code Review</title> - - <para>Thirty days before the anticipated release, the source - repository enters a <quote>code slush</quote>. During this - time, all commits to the -STABLE branch must be approved by the - &a.re;. The kinds of changes that are allowed during this 15 day - period include:</para> - - <itemizedlist> - <listitem> - <para>Bug fixes.</para> - </listitem> - - <listitem> - <para>Documentation updates.</para> - </listitem> - - <listitem> - <para>Security-related fixes of any kind.</para> - </listitem> - - <listitem> - <para>Minor changes to device drivers, such as adding new Device - IDs.</para> - </listitem> - - <listitem> - <para>Any additional change that the release engineering team feels - is justified, given the potential risk.</para> - </listitem> - </itemizedlist> - - <para>After the first 15 days of the code slush, a - <emphasis>release candidate</emphasis> is released for - widespread testing and the code enters a <quote>code - freeze</quote> where it becomes much harder to justify new - changes to the system unless a serious bug-fix or security issue - is involved. During the code freeze, at least one release - candidate is released per week, until the final release is - ready. During the days leading to the final release, the - release engineering team is in constant communication with the - security-officer team, the documentation maintainers, and the - port maintainers, to ensure that all of the - different components required for a successful release are - available.</para> - </sect2> - - <sect2> - <title>Final Release Checklist</title> - - <para>When several release candidates have been made available for - widespread testing and all major issues have been resolved, the - final release <quote>polishing</quote> can begin.</para> - - <sect3> - <title>Creating the Release Branch</title> - - <para>As described in the introduction, the - <literal>RELENG_<replaceable>X</replaceable>_<replaceable>Y</replaceable></literal> - release branch is a relatively new addition to our release - engineering - methodology. The first step in creating this branch is to - ensure that you are working with the newest version of the - <literal>RELENG_<replaceable>X</replaceable></literal> sources - that you want to branch <emphasis>from</emphasis>.</para> - - <screen>/usr/src&prompt.root; <userinput>cvs update -rRELENG_4 -P -d</userinput></screen> - - <para>The next step is to create a branch point - <emphasis>tag</emphasis>, so that diffs against the start of - the branch are easier with CVS:</para> - - <screen>/usr/src&prompt.root; <userinput>cvs rtag -rRELENG_4 RELENG_4_8_BP src</userinput></screen> - - <para>And then a new branch tag is created with:</para> - - <screen>/usr/src&prompt.root; <userinput>cvs rtag -b -rRELENG_4_8_BP RELENG_4_8 src</userinput></screen> - - <note> - <para><emphasis>The - <literal>RELENG_<replaceable>*</replaceable></literal> tags - are restricted for use by the CVS-meisters and release - engineers.</emphasis></para> - </note> - - <sidebar> - <para>A <quote><emphasis>tag</emphasis></quote> is CVS - vernacular for a label that identifies the source at a specific point - in time. By tagging the tree, we ensure that future release builders - will always be able to use the same source we used to create the - official FreeBSD Project releases.</para> - </sidebar> - - <mediaobject> - <imageobject> - <imagedata fileref="branches-head" align="center"> - </imageobject> - - <textobject> - <phrase>FreeBSD Development Branch</phrase> - </textobject> - </mediaobject> - - <mediaobject> - <imageobject> - <imagedata fileref="branches-releng3" align="center"> - </imageobject> - - <textobject> - <phrase>FreeBSD 3.x STABLE Branch</phrase> - </textobject> - </mediaobject> - - <mediaobject> - <imageobject> - <imagedata fileref="branches-releng4" align="center"> - </imageobject> - - <textobject> - <phrase>FreeBSD 4.x STABLE Branch</phrase> - </textobject> - </mediaobject> - - </sect3> - - <sect3 id="versionbump"> - <title>Bumping up the Version Number</title> - - <para>Before the final release can be tagged, built, and - released, the following files need to be modified to reflect - the correct version of FreeBSD:</para> - - <itemizedlist> - <listitem> - <para><filename>doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml - </filename></para> - </listitem> - - <listitem> - <para><filename>doc/en_US.ISO8859-1/books/porters-handbook/book.sgml - </filename></para> - </listitem> - - <listitem> - <para><filename>doc/share/sgml/freebsd.ent</filename></para> - </listitem> - - <listitem> - <para><filename>src/Makefile.inc1</filename></para> - </listitem> - - <listitem> - <para><filename>src/UPDATING</filename></para> - </listitem> - - <listitem> - <para><filename>src/gnu/usr.bin/groff/tmac/mdoc.local</filename></para> - </listitem> - - <listitem> - <para><filename>src/release/Makefile</filename></para> - </listitem> - - <listitem> - <para><filename>src/release/doc/en_US.ISO8859-1/share/sgml/release.dsl</filename></para> - </listitem> - - <listitem> - <para><filename>src/release/doc/share/examples/Makefile.relnotesng</filename></para> - </listitem> - - <listitem> - <para><filename>src/release/doc/share/sgml/release.ent</filename></para> - </listitem> - - <listitem> - <para><filename>src/share/examples/cvsup/standard-supfile</filename></para> - </listitem> - - <listitem> - <para><filename>src/sys/conf/newvers.sh</filename></para> - </listitem> - - <listitem> - <para><filename>src/sys/sys/param.h</filename></para> - </listitem> - - <listitem> - <para><filename>src/usr.sbin/pkg_install/add/main.c</filename></para> - </listitem> - - <listitem> - <para><filename>www/en/docs.sgml</filename></para> - </listitem> - - <listitem> - <para><filename>www/en/cgi/ports.cgi</filename></para> - </listitem> - - <listitem> - <para><filename>ports/Tools/scripts/release/config</filename></para> - </listitem> - - </itemizedlist> - - <para>The release notes and errata files also need to be adjusted for the - new release (on the release branch) and truncated appropriately - (on the stable/current branch):</para> - - <itemizedlist> - <listitem> - <para><filename>src/release/doc/en_US.ISO8859-1/relnotes/common/new.sgml - </filename></para> - </listitem> - - <listitem> - <para><filename>src/release/doc/en_US.ISO8859-1/errata/article.sgml - </filename></para> - </listitem> - </itemizedlist> - - <para><application>Sysinstall</application> should be updated to note - the number of available ports and the amount of disk space required - for the Ports Collection. This information is currently kept in - <filename>src/release/sysinstall/dist.c</filename>.</para> - - <para>After the release has been built, a number of file should - be updated to announce the release to the world.</para> - - <itemizedlist> - <listitem> - <para><filename>www/share/sgml/includes.release.sgml</filename></para> - </listitem> - - <listitem> - <para><filename>www/share/sgml/includes.release.xsl</filename></para> - </listitem> - - <listitem> - <para><filename>www/en/releases/*</filename></para> - </listitem> - - <listitem> - <para><filename>www/en/releng/index.sgml</filename></para> - </listitem> - - <listitem> - <para><filename>www/en/news/news.xml</filename></para> - </listitem> - - <listitem> - <para><filename>src/share/misc/bsd-family-tree</filename></para> - </listitem> - - </itemizedlist> - - </sect3> - - <sect3> - <title>Creating Release Tags</title> - - <para>When the final release is ready, the following command - will create the <literal>RELENG_4_8_0_RELEASE</literal> - tag.</para> - - <screen> - /usr/src&prompt.root; <userinput>cvs rtag -rRELENG_4_8 RELENG_4_8_0_RELEASE src</userinput> - </screen> - - <para>The Documentation and Ports managers are responsible for - tagging the respective trees with the <literal>RELEASE_4_8_0</literal> - tag.</para> - - <para>Occasionally, a last minute fix may be required - <emphasis>after</emphasis> the final tags have been created. - In practice this isn't a problem, since <acronym>CVS</acronym> - allows tags to be manipulated with <command>cvs - tag -d <replaceable>tagname filename</replaceable></command>. - It is very important that any last minute changes be tagged - appropriately as part of the release. FreeBSD releases must - always be reproduceable. Local hacks in the release - engineer's environment are not acceptable.</para> - </sect3> - </sect2> -</sect1> - -<!-- Release Building --> -<sect1 id="release-build"> - <title>Release Building</title> - - <para>FreeBSD <quote>releases</quote> can be built by anyone with a - fast machine and access to a source repository. (That should be - everyone, since we offer anonymous CVS! See The Handbook for - details.) The <emphasis>only</emphasis> special requirement is - that the &man.vn.4; device must be available. (On -CURRENT, this - device has been replaced by the new &man.md.4; - memory disk driver.) If the - device is not loaded into your kernel, then the kernel module - should be automatically loaded when &man.vnconfig.8; is executed - during the boot media creation phase. All of the tools necessary - to build a release are available from the CVS repository in - <filename>src/release</filename>. These tools aim to provide a - consistent way to build FreeBSD releases. A complete release can - actually be built with only a single command, including the - creation of <acronym>ISO</acronym> images suitable for burning to - CDROM, installation floppies, and an FTP install directory. This - command is aptly named <command>make - release</command>.</para> - - <sect2> - <title><command>make release</command></title> - - <para>To successfully build a release, you must first populate - <filename>/usr/obj</filename> by running <command>make - world</command> or simply - <command>make - buildworld</command>. The release - target requires several variables be set properly to build a - release:</para> - - <itemizedlist> - <listitem> - <para><makevar>CHROOTDIR</makevar> - The directory to be used as the - chroot environment for the entire release build.</para> - </listitem> - - <listitem> - <para><makevar>BUILDNAME</makevar> - The name of the release to be - built.</para> - </listitem> - - <listitem> - <para><makevar>CVSROOT</makevar> - The location of a CVS Repository. - </para> - </listitem> - - <listitem> - <para><makevar>RELEASETAG</makevar> - The CVS tag corresponding to the - release you would like to build.</para> - </listitem> - </itemizedlist> - - <para>If you do not already have access to a local CVS - repository, then you may mirror one with <ulink - url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/synching.html#CVSUP">CVSup</ulink>. - The supplied supfile, - <filename>/usr/share/examples/cvsup/cvs-supfile</filename>, is - a useful starting point for mirroring the CVS - repository.</para> - - <para>If <makevar>RELEASETAG</makevar> is omitted, then the - release will be built from the <literal>HEAD</literal> (a.k.a. -CURRENT) branch. - Releases built from this branch are normally referred to as - <quote>-CURRENT snapshots</quote>.</para> - - <para>There are many other variables available to customize the - release build. Most of these variables are documented at the - top of <filename>src/release/Makefile</filename>. The exact - command used to build the official FreeBSD 4.7 (x86) release - was:</para> - - <screen><command>make <literal>release CHROOTDIR=/local3/release \ - BUILDNAME=4.7-RELEASE \ - CVSROOT=/host/cvs/usr/home/ncvs \ - RELEASETAG=RELENG_4_7_0_RELEASE</literal> - </command> - </screen> - - <para>The release <filename>Makefile</filename> can be broken down into several distinct - steps.</para> - - <itemizedlist> - <listitem> - <para>Creation of a sanitized system environment in a separate - directory hierarchy with <quote><command>make - <literal>installworld</literal></command></quote>. - </para> - </listitem> - - <listitem> - <para>Checkout from CVS of a clean version of the system source, - documentation, and ports into the release build hierarchy.</para> - </listitem> - - <listitem> - <para>Population of <filename>/etc</filename> and - <filename>/dev</filename> in the chrooted - environment.</para> - </listitem> - - <listitem> - <para>chroot into the release build hierarchy, to make it harder for - the outside environment to taint this build.</para> - </listitem> - - <listitem> - <para><command>make world</command> - in the chrooted environment.</para> - </listitem> - - <listitem> - <para>Build of Kerberos-related binaries.</para> - </listitem> - - <listitem> - <para>Build <filename>GENERIC</filename> kernel.</para> - </listitem> - - <listitem> - <para>Creation of a staging directory tree where the binary - distributions will be built and packaged.</para> - </listitem> - - <listitem> - <para>Build and installation of the documentation toolchain needed to - convert the documentation source (SGML) into HTML and text documents - that will accompany the release.</para> - </listitem> - - <listitem> - <para>Build and installation of the actual documentation - (user manuals, tutorials, release notes, hardware compatibility lists, - and so on.)</para> - </listitem> - - <listitem> - <para>Build of the <quote>crunched</quote> binaries used for - installation floppies.</para> - </listitem> - - <listitem> - <para>Package up distribution tarballs of the binaries and sources. - </para> - </listitem> - - <listitem> - <para>Create the boot media and a <quote>fixit</quote> floppy.</para> - </listitem> - - <listitem> - <para>Create FTP installation hierarchy.</para> - </listitem> - - <listitem> - <para><emphasis>(optionally)</emphasis> Create ISO images for - CDROM/DVD media.</para> - </listitem> - </itemizedlist> - - <para>For more information about the release build infrastructure, - please see &man.release.7;.</para> - - </sect2> - - <sect2> - <title>Building <application>&xfree86;</application></title> - - <para><application>&xfree86;</application> is an important component for many desktop users. - Prior to FreeBSD 4.6-RELEASE, releases used &xfree86; - 3.<replaceable>X</replaceable> by default. - The easiest way to build these versions is to use the - <filename>src/release/scripts/X11/build_x.sh</filename> script. - This script requires that &xfree86; and Tcl/Tk already be - installed on the build host. After compiling the necessary X - servers, the script will package all of the files into tarballs - that &man.sysinstall.8; expects to find in the - <filename>XF86336</filename> directory of the installation - media.</para> - - <para>Beginning with FreeBSD 4.6-RELEASE, &man.sysinstall.8; - installs &xfree86; 4.<replaceable>X</replaceable> by default, as a - set of <quote>normal</quote> packages. These can either be the - packages generated by the package-building cluster or packages - built from an appropriately tagged ports tree.</para> - - <note><para>It is important to remove any site-specific settings - from <filename>/etc/make.conf</filename>. For example, it would - be unwise to distribute binaries that were built on a system - with <varname>CPUTYPE</varname> set to a specific - processor.</para></note> - - </sect2> - - <sect2> - <title>Contributed Software (<quote>ports</quote>)</title> - - <para>The <ulink url="http://www.FreeBSD.org/ports">FreeBSD Ports - collection</ulink> is a collection of over &os.numports; - third-party software packages available for FreeBSD. The &a.portmgr; - is responsible for maintaining a consistent ports tree that can be used - to create the binary packages that accompany official FreeBSD - releases.</para> - - <para>The release engineering activities for our collection of - third-party packages is beyond the scope of this document. A - separate article, &art.re.pkgs;, covers this topic - in depth.</para> - - </sect2> - - <sect2> - <title>Release ISOs</title> - - <para>Starting with FreeBSD 4.4, the FreeBSD Project decided to - release all four ISO images that were previously sold on the - <emphasis>BSDi/Wind River Systems/FreeBSD Mall</emphasis> - <quote>official</quote> CDROM distributions. Each of the four - discs must contain a <filename>README.TXT</filename> file that - explains the contents of the disc, a - <filename>CDROM.INF</filename> file that provides meta-data for - the disc so that &man.sysinstall.8; can validate and use the - contents, and a <filename>filename.txt</filename> file that - provides a manifest for the disc. This - <emphasis>manifest</emphasis> can be created with a simple - command:</para> - - <screen>/stage/cdrom&prompt.root; <userinput>find . -type f | sed -e 's/^\.\///' | sort > filename.txt</userinput></screen> - - <para>The specific requirements of each CD are outlined below.</para> - - <sect3> - <title>Disc 1</title> - - <para>The first disc is almost completely created by - <command>make - release</command>. The only changes - that should be made to the <filename>disc1</filename> directory are the addition of - a <filename>tools</filename> directory, <application - class="software">&xfree86;</application>, and as many popular - third party software packages as will fit on the disc. The - <filename>tools</filename> directory contains software that allow users to create - installation floppies from other operating systems. This disc - should be made bootable so that users of modern PCs do not - need to create installation floppy disks.</para> - - <para>If an alternate version of &xfree86; is to be provided, then - &man.sysinstall.8; must be updated to reflect the new location - and installation instructions. The relevant code is contained - in <filename>src/release/sysinstall</filename> on -STABLE or - <filename>src/usr.sbin/sysinstall</filename> on - -CURRENT. Specifically, the files <filename>dist.c</filename>, - <filename>menus.c</filename>, and - <filename>config.c</filename> will need to be updated.</para> - </sect3> - - <sect3> - <title>Disc 2</title> - - <para>The second disc is also largely created by <command>make - release</command>. This disc contains a <quote>live - filesystem</quote> that can be used from &man.sysinstall.8; to - troubleshoot a FreeBSD installation. This disc should be - bootable and should also contain a compressed copy of the CVS - repository in the <filename>CVSROOT</filename> directory and - commercial software demos in the <filename>commerce</filename> - directory.</para> - </sect3> - - <sect3> - <title>Discs 3 and 4</title> - - <para>The remaining two discs contain additional software - packages for FreeBSD. The packages should be clustered so that - a package and all of its <emphasis>dependencies</emphasis> are - included on the same disc. More information about the - creation of these discs is provided in the &art.re.pkgs; - article.</para> - </sect3> - </sect2> -</sect1> - -<!-- Distribution --> -<sect1 id="distribution"> - <title>Distribution</title> - - <sect2 id="dist-ftp"> - <title>FTP Sites</title> - - <para>When the release has been thoroughly tested and packaged for - distribution, the master FTP site must be updated. The official - FreeBSD public FTP sites are all mirrors of a master server that - is open only to other FTP sites. This site is known as - <hostid>ftp-master</hostid>. When the release is ready, the - following files must be modified on <hostid>ftp-master</hostid>:</para> - - <variablelist> - <varlistentry> - <term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>X.Y</replaceable>-RELEASE/</filename></term> - <listitem> - <para>The installable FTP directory as output from <command>make - release</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>/pub/FreeBSD/ports/<replaceable>arch</replaceable>/packages-<replaceable>X.Y</replaceable>-release/</filename></term> - <listitem><para>The complete package build for this - release.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>X.Y</replaceable>-RELEASE/tools</filename></term> - <listitem><para>A symlink to - <filename>../../../tools</filename>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>X.Y</replaceable>-RELEASE/packages</filename></term> - <listitem><para>A symlink to - <filename>../../../ports/<replaceable>arch</replaceable>/packages-<replaceable>X.Y</replaceable>-release</filename>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/ISO-IMAGES/<replaceable>X.Y</replaceable>/<replaceable>X.Y</replaceable>-RELEASE-<replaceable>arch</replaceable>-*.iso</filename></term> - <listitem><para>The ISO images. The <quote>*</quote> is - <filename>disc1</filename>, <filename>disc2</filename>, etc. - Only if there is a <filename>disc1</filename> and there is an - alternative first installation CD (for example a - stripped-down install with no windowing system) there may - be a <filename>mini</filename> as well.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>For more information about the distribution mirror - architecture of the FreeBSD FTP sites, please see the <ulink - url="&url.articles.hubs;/">Mirroring FreeBSD</ulink> article.</para> - - <para>It may take many hours to two days after updating - <hostid>ftp-master</hostid> before a majority of the Tier-1 FTP - sites have the new software depending on whether or not a package - set got loaded at the same time. It is imperative that the release - engineers coordinate with the &a.mirror-announce; before announcing the general - availability of new software on the FTP sites. Ideally - the release package set should be loaded at least four - days prior to release day. The release bits should be - loaded between 24 and 48 hours before the planned release - time with <quote>other</quote> file permissions turned off. - This will allow the mirror sites to download it but the - general public will not be able to download it from the mirror - sites. Mail should be sent to &a.mirror-announce; at the time - the release bits get posted saying the release has been staged - and giving the time that the mirror sites should begin allowing - access. Be sure to include a time zone with the - time, for example make it relative to GMT.</para> - </sect2> - - <sect2 id="dist-cdrom"> - <title>CD-ROM Replication</title> - - <para>Coming soon: Tips for sending FreeBSD ISOs to a replicator - and quality assurance measures to be taken.</para> - </sect2> - -</sect1> - -<!-- Extensibility --> -<sect1 id="extensibility"> - <title>Extensibility</title> - - <para>Although FreeBSD forms a complete operating system, there is - nothing that forces you to use the system exactly as we have - packaged it up for distribution. We have tried to design the - system to be as extensible as possible so that it can serve as a - platform that other commercial products can be built on top - of. The only <quote>rule</quote> we have about this is that if you - are going to distribute FreeBSD with non-trivial changes, we - encourage you to document your enhancements! The FreeBSD community - can only help support users of the software we provide. We - certainly encourage innovation in the form of advanced - installation and administration tools, for example, but we can't - be expected to answer questions about it.</para> - - <sect2> - <title>Creating Customized Boot floppies</title> - - <para>Many sites have complex requirements that may require - additional kernel modules or userland tools be added to the - installation floppies. The <quote>quick and dirty</quote> way - to accomplish this would be to modify the staging directory of - an existing <command>make release</command> build hierarchy:</para> - - <itemizedlist> - <listitem> - <para>Apply patches or add additional files inside the chroot - release build directory.</para> - </listitem> - - <listitem> - <para><command>rm - ${CHROOTDIR}/usr/obj/usr/src/release/release.[59]</command></para> - </listitem> - - <listitem> - <para>rebuild &man.sysinstall.8;, the kernel, or whatever - parts of the system your change affected.</para> - </listitem> - - <listitem> - <para><command>chroot ${CHROOTDIR} ./mk floppies - </command></para> - </listitem> - - </itemizedlist> - - <para>New release floppies will be located in - <filename>${CHROOTDIR}/R/stage/floppies</filename>.</para> - - <para>Alternatively, the - <filename>boot.flp</filename> make - target can be called, or the filesystem - creating script, - <filename>src/release/scripts/doFS.sh</filename>, may be invoked - directly.</para> - - <para>Local patches may also be supplied to the release build by - defining the <makevar>LOCAL_PATCH</makevar> variable in <command>make - release</command>. - </para> - </sect2> - - <sect2> - <title>Scripting <command>sysinstall</command></title> - - <para>The FreeBSD system installation and configuration tool, - &man.sysinstall.8;, can be scripted to provide automated installs - for large sites. This functionality can be used in conjunction - with &intel; PXE[13] to bootstrap systems from the network, or - via custom boot floppies with a sysinstall script. An example - sysinstall script is available in the CVS tree as - <filename>src/release/sysinstall/install.cfg</filename>.</para> - </sect2> -</sect1> - -<!-- Lessons Learned --> -<sect1 id="lessons-learned"> - <title>Lessons Learned from FreeBSD 4.4</title> - - <para>The release engineering process for 4.4 formally began on - August 1st, 2001. After that date all commits to the - <literal>RELENG_4</literal> branch of FreeBSD had to be explicitly - approved by the &a.re;. The first - release candidate for the x86 architecture was released on August - 16, followed by 4 more release candidates leading up to the final - release on September 18th. The security officer was very involved - in the last week of the process as several security issues were - found in the earlier release candidates. A total of over - <emphasis>500</emphasis> emails were sent to the &a.re; in - little over a month.</para> - - <para>Our user community has made it very clear that the security - and stability of a FreeBSD release should not be sacrificed for - any self-imposed deadlines or target release dates. The FreeBSD - Project has grown tremendously over its lifetime and the need for - standardized release engineering procedures has never been more - apparent. This will become even more important as FreeBSD is - ported to new platforms.</para> -</sect1> - -<!-- Future Directions --> -<sect1 id="future"> - <title>Future Directions</title> - - <para>It is imperative for our release engineering activities to - scale with our growing userbase. Along these lines we are working - very hard to document the procedures involved in producing FreeBSD - releases.</para> - - <itemizedlist> - <listitem> - <para><emphasis>Parallelism</emphasis> - Certain portions of the - release build are actually <quote>embarrassingly - parallel</quote>. Most of the tasks are very I/O intensive, - so having multiple high-speed disk drives is actually more important than - using multiple processors in speeding up the <command>make - release</command> process. If multiple disks are used for - different hierarchies in the &man.chroot.2; - environment, then the CVS checkout of the <filename>ports</filename> and <filename>doc</filename> trees - can be happening simultaneously as the <command>make - world</command> on another disk. Using a - <acronym>RAID</acronym> solution (hardware or software) can - significantly decrease the overall build time.</para> - </listitem> - - <listitem> - <para><emphasis>Cross-building releases</emphasis> - Building - IA-64 or Alpha release on x86 hardware? <command>make - TARGET=ia64 release</command>. - </para> - </listitem> - - <listitem> - <para><emphasis>Regression Testing</emphasis> - We need better - automated correctness testing for FreeBSD.</para> - </listitem> - - <listitem> - <para><emphasis>Installation Tools</emphasis> - Our installation - program has long since outlived its intended life span. - Several projects are under development to provide a more - advanced installation mechanism. One of the most promising is - the libh project[5] which aims to provide an intelligent new - package framework and GUI installation program.</para> - </listitem> - </itemizedlist> - -</sect1> - -<!-- Acknowledgements --> -<sect1 id="ackno"> -<title>Acknowledgements</title> - - <para>I would like to thank Jordan Hubbard for giving me the - opportunity to take on some of the release engineering - responsibilities for FreeBSD 4.4 and also for all of his work - throughout the years making FreeBSD what it is today. Of course - the release wouldn't have been possible without all of the - release-related work done by &a.asami;, &a.steve;, &a.bmah;, &a.nik;, - &a.obrien;, &a.kris;, &a.jhb; and the rest of the FreeBSD development - community. I would also like to thank &a.rgrimes;, &a.phk;, and others - who worked on the release engineering tools in the very early days - of FreeBSD. This article was influenced by release engineering - documents from the CSRG[14], the NetBSD Project[11], and John - Baldwin's proposed release engineering process notes[12].</para> -</sect1> - -<!-- Reference / Biblio Section --> -<sect1 id="biblio"> - <title>References</title> - <para>[1] CVS - Concurrent Versions System - <ulink url="http://www.cvshome.org"></ulink></para> - - <para>[2] CVSup - The CVS-Optimized General Purpose Network File Distribution - System <ulink url="http://www.polstra.com/projects/freeware/CVSup"></ulink> - </para> - - <para>[3] <ulink url="http://bento.FreeBSD.org"></ulink></para> - - <para>[4] FreeBSD Ports Collection - <ulink url="http://www.FreeBSD.org/ports"></ulink></para> - - <para>[5] The libh Project - <ulink url="http://www.FreeBSD.org/projects/libh.html"></ulink></para> - - <para>[6] FreeBSD Committers <ulink - url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributors/staff-committers.html"></ulink> - </para> - - <para>[7] FreeBSD Core-Team - <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributors/staff-core.html"></ulink></para> - - <para>[8] FreeBSD Handbook - <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook"></ulink> - </para> - - <para>[9] GNATS: The GNU Bug Tracking System - <ulink url="http://www.gnu.org/software/gnats"></ulink> - </para> - - <para>[10] FreeBSD PR Statistics - <ulink url="http://www.FreeBSD.org/prstats/index.html"></ulink></para> - - <para>[11] NetBSD Developer Documentation: Release Engineering - <ulink url="http://www.NetBSD.org/developers/releng/index.html"></ulink> - </para> - - <para>[12] John Baldwin's FreeBSD Release Engineering Proposal - <ulink url="http://people.FreeBSD.org/~jhb/docs/releng.txt"></ulink> - </para> - - <para>[13] PXE Jumpstart Guide - <ulink - url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/pxe/index.html"></ulink> - </para> - - <para>[14] Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic: - <ulink url="http://docs.FreeBSD.org/44doc/papers/releng.html"> -<emphasis>The Release Engineering of 4.3BSD</emphasis></ulink> - </para> -</sect1> -</article> diff --git a/en_US.ISO8859-1/articles/releng/extra.css b/en_US.ISO8859-1/articles/releng/extra.css deleted file mode 100644 index 8d13ebf887..0000000000 --- a/en_US.ISO8859-1/articles/releng/extra.css +++ /dev/null @@ -1,16 +0,0 @@ -/* - * Netscape 4 does not recognize the @import directive of CSS, so we - * can't add an additional stylesheet layer on top of the default one. - * Instead, we use this hack to copy this file to the end of - * docbook.css. - * - * $FreeBSD$ - */ - -/* @import "docbook.css"; */ - -/* Customization that looks good for this particular article. */ - -DIV.TITLEPAGE { - text-align: center; -} diff --git a/en_US.ISO8859-1/articles/serial-uart/Makefile b/en_US.ISO8859-1/articles/serial-uart/Makefile deleted file mode 100644 index b0465bf0c0..0000000000 --- a/en_US.ISO8859-1/articles/serial-uart/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Serial and UART Tutorial - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/serial-uart/article.sgml b/en_US.ISO8859-1/articles/serial-uart/article.sgml deleted file mode 100644 index c0de19c776..0000000000 --- a/en_US.ISO8859-1/articles/serial-uart/article.sgml +++ /dev/null @@ -1,2439 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Serial and UART Tutorial</title> - - <authorgroup> - <author> - <firstname>Frank</firstname> - <surname>Durda</surname> - - <affiliation> - <address><email>uhclem@FreeBSD.org</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.microsoft; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This article talks about using serial hardware with FreeBSD.</para> - </abstract> - </articleinfo> - - <sect1 id="uart"> - <title>The UART: What it is and how it works</title> - - <para><emphasis>Copyright © 1996 &a.uhclem;, All Rights - Reserved. 13 January 1996.</emphasis></para> - - <para>The Universal Asynchronous Receiver/Transmitter (UART) - controller is the key component of the serial communications - subsystem of a computer. The UART takes bytes of data and - transmits the individual bits in a sequential fashion. At the - destination, a second UART re-assembles the bits into complete - bytes.</para> - - <para>Serial transmission is commonly used with modems and for - non-networked communication between computers, terminals and - other devices.</para> - - <para>There are two primary forms of serial transmission: - Synchronous and Asynchronous. Depending on the modes that are - supported by the hardware, the name of the communication - sub-system will usually include a <literal>A</literal> if it - supports Asynchronous communications, and a - <literal>S</literal> if it supports Synchronous - communications. Both forms are described below.</para> - - <para>Some common acronyms are:</para> - - <blockquote> - <para>UART Universal Asynchronous Receiver/Transmitter</para> - </blockquote> - - <blockquote> - <para>USART Universal Synchronous-Asynchronous - Receiver/Transmitter</para> - </blockquote> - - <sect2> - <title>Synchronous Serial Transmission</title> - - <para>Synchronous serial transmission requires that the sender - and receiver share a clock with one another, or that the - sender provide a strobe or other timing signal so that the - receiver knows when to <quote>read</quote> the next bit of - the data. In most forms of serial Synchronous - communication, if there is no data available at a given - instant to transmit, a fill character must be sent instead - so that data is always being transmitted. Synchronous - communication is usually more efficient because only data - bits are transmitted between sender and receiver, and - synchronous communication can be more costly if extra wiring - and circuits are required to share a clock signal between - the sender and receiver.</para> - - <para>A form of Synchronous transmission is used with printers - and fixed disk devices in that the data is sent on one set - of wires while a clock or strobe is sent on a different - wire. Printers and fixed disk devices are not normally - serial devices because most fixed disk interface standards - send an entire word of data for each clock or strobe signal - by using a separate wire for each bit of the word. In the - PC industry, these are known as Parallel devices.</para> - - <para>The standard serial communications hardware in the PC - does not support Synchronous operations. This mode is - described here for comparison purposes only.</para> - </sect2> - - <sect2> - <title>Asynchronous Serial Transmission</title> - - <para>Asynchronous transmission allows data to be transmitted - without the sender having to send a clock signal to the - receiver. Instead, the sender and receiver must agree on - timing parameters in advance and special bits are added to - each word which are used to synchronize the sending and - receiving units.</para> - - <para>When a word is given to the UART for Asynchronous - transmissions, a bit called the "Start Bit" is added to the - beginning of each word that is to be transmitted. The Start - Bit is used to alert the receiver that a word of data is - about to be sent, and to force the clock in the receiver - into synchronization with the clock in the transmitter. - These two clocks must be accurate enough to not have the - frequency drift by more than 10% during the transmission of - the remaining bits in the word. (This requirement was set - in the days of mechanical teleprinters and is easily met by - modern electronic equipment.)</para> - - <para>After the Start Bit, the individual bits of the word of - data are sent, with the Least Significant Bit (LSB) being - sent first. Each bit in the transmission is transmitted for - exactly the same amount of time as all of the other bits, - and the receiver <quote>looks</quote> at the wire at - approximately halfway through the period assigned to each - bit to determine if the bit is a <literal>1</literal> or a - <literal>0</literal>. For example, if it takes two seconds - to send each bit, the receiver will examine the signal to - determine if it is a <literal>1</literal> or a - <literal>0</literal> after one second has passed, then it - will wait two seconds and then examine the value of the next - bit, and so on.</para> - - <para>The sender does not know when the receiver has - <quote>looked</quote> at the value of the bit. The sender - only knows when the clock says to begin transmitting the - next bit of the word.</para> - - <para>When the entire data word has been sent, the transmitter - may add a Parity Bit that the transmitter generates. The - Parity Bit may be used by the receiver to perform simple - error checking. Then at least one Stop Bit is sent by the - transmitter.</para> - - <para>When the receiver has received all of the bits in the - data word, it may check for the Parity Bits (both sender and - receiver must agree on whether a Parity Bit is to be used), - and then the receiver looks for a Stop Bit. If the Stop Bit - does not appear when it is supposed to, the UART considers - the entire word to be garbled and will report a Framing - Error to the host processor when the data word is read. The - usual cause of a Framing Error is that the sender and - receiver clocks were not running at the same speed, or that - the signal was interrupted.</para> - - <para>Regardless of whether the data was received correctly or - not, the UART automatically discards the Start, Parity and - Stop bits. If the sender and receiver are configured - identically, these bits are not passed to the host.</para> - - <para>If another word is ready for transmission, the Start Bit - for the new word can be sent as soon as the Stop Bit for the - previous word has been sent.</para> - - <para>Because asynchronous data is <quote>self - synchronizing</quote>, if there is no data to transmit, the - transmission line can be idle.</para> - </sect2> - - <sect2> - <title>Other UART Functions</title> - - <para>In addition to the basic job of converting data from - parallel to serial for transmission and from serial to - parallel on reception, a UART will usually provide - additional circuits for signals that can be used to indicate - the state of the transmission media, and to regulate the - flow of data in the event that the remote device is not - prepared to accept more data. For example, when the device - connected to the UART is a modem, the modem may report the - presence of a carrier on the phone line while the computer - may be able to instruct the modem to reset itself or to not - take calls by raising or lowering one more of these - extra signals. The function of each of these additional - signals is defined in the EIA RS232-C standard.</para> - </sect2> - - <sect2> - <title>The RS232-C and V.24 Standards</title> - - <para>In most computer systems, the UART is connected to - circuitry that generates signals that comply with the EIA - RS232-C specification. There is also a CCITT standard named - V.24 that mirrors the specifications included in - RS232-C.</para> - - <sect3> - <title>RS232-C Bit Assignments (Marks and Spaces)</title> - - <para>In RS232-C, a value of <literal>1</literal> is called - a <literal>Mark</literal> and a value of - <literal>0</literal> is called a <literal>Space</literal>. - When a communication line is idle, the line is said to be - <quote>Marking</quote>, or transmitting continuous - <literal>1</literal> values.</para> - - <para>The Start bit always has a value of - <literal>0</literal> (a Space). The Stop Bit always has a - value of <literal>1</literal> (a Mark). This means that - there will always be a Mark (1) to Space (0) transition on - the line at the start of every word, even when multiple - word are transmitted back to back. This guarantees that - sender and receiver can resynchronize their clocks - regardless of the content of the data bits that are being - transmitted.</para> - - <para>The idle time between Stop and Start bits does not - have to be an exact multiple (including zero) of the bit - rate of the communication link, but most UARTs are - designed this way for simplicity.</para> - - <para>In RS232-C, the "Marking" signal (a - <literal>1</literal>) is represented by a voltage between - -2 VDC and -12 VDC, and a "Spacing" signal (a - <literal>0</literal>) is represented by a voltage between - 0 and +12 VDC. The transmitter is supposed to send +12 - VDC or -12 VDC, and the receiver is supposed to allow for - some voltage loss in long cables. Some transmitters in - low power devices (like portable computers) sometimes use - only +5 VDC and -5 VDC, but these values are still - acceptable to a RS232-C receiver, provided that the cable - lengths are short.</para> - </sect3> - - <sect3> - <title>RS232-C Break Signal</title> - - <para>RS232-C also specifies a signal called a - <literal>Break</literal>, which is caused by sending - continuous Spacing values (no Start or Stop bits). When - there is no electricity present on the data circuit, the - line is considered to be sending - <literal>Break</literal>.</para> - - <para>The <literal>Break</literal> signal must be of a - duration longer than the time it takes to send a complete - byte plus Start, Stop and Parity bits. Most UARTs can - distinguish between a Framing Error and a Break, but if - the UART cannot do this, the Framing Error detection can - be used to identify Breaks.</para> - - <para>In the days of teleprinters, when numerous printers - around the country were wired in series (such as news - services), any unit could cause a <literal>Break</literal> - by temporarily opening the entire circuit so that no - current flowed. This was used to allow a location with - urgent news to interrupt some other location that was - currently sending information.</para> - - <para>In modern systems there are two types of Break - signals. If the Break is longer than 1.6 seconds, it is - considered a "Modem Break", and some modems can be - programmed to terminate the conversation and go on-hook or - enter the modems' command mode when the modem detects this - signal. If the Break is smaller than 1.6 seconds, it - signifies a Data Break and it is up to the remote computer - to respond to this signal. Sometimes this form of Break - is used as an Attention or Interrupt signal and sometimes - is accepted as a substitute for the ASCII CONTROL-C - character.</para> - - <para>Marks and Spaces are also equivalent to - <quote>Holes</quote> and <quote>No Holes</quote> in paper - tape systems.</para> - - <note> - <para>Breaks cannot be generated from paper tape or from - any other byte value, since bytes are always sent with - Start and Stop bit. The UART is usually capable of - generating the continuous Spacing signal in response to - a special command from the host processor.</para> - </note> - </sect3> - - <sect3> - <title>RS232-C DTE and DCE Devices</title> - - <para>The RS232-C specification defines two types of - equipment: the Data Terminal Equipment (DTE) and the Data - Carrier Equipment (DCE). Usually, the DTE device is the - terminal (or computer), and the DCE is a modem. Across - the phone line at the other end of a conversation, the - receiving modem is also a DCE device and the computer that - is connected to that modem is a DTE device. The DCE - device receives signals on the pins that the DTE device - transmits on, and vice versa.</para> - - <para>When two devices that are both DTE or both DCE must be - connected together without a modem or a similar media - translater between them, a NULL modem must be used. The - NULL modem electrically re-arranges the cabling so that - the transmitter output is connected to the receiver input - on the other device, and vice versa. Similar translations - are performed on all of the control signals so that each - device will see what it thinks are DCE (or DTE) signals - from the other device.</para> - - <para>The number of signals generated by the DTE and DCE - devices are not symmetrical. The DTE device generates - fewer signals for the DCE device than the DTE device - receives from the DCE.</para> - </sect3> - - <sect3> - <title>RS232-C Pin Assignments</title> - - <para>The EIA RS232-C specification (and the ITU equivalent, - V.24) calls for a twenty-five pin connector (usually a - DB25) and defines the purpose of most of the pins in that - connector.</para> - - <para>In the IBM Personal Computer and similar systems, a - subset of RS232-C signals are provided via nine pin - connectors (DB9). The signals that are not included on - the PC connector deal mainly with synchronous operation, - and this transmission mode is not supported by the UART - that IBM selected for use in the IBM PC.</para> - - <para>Depending on the computer manufacturer, a DB25, a DB9, - or both types of connector may be used for RS232-C - communications. (The IBM PC also uses a DB25 connector - for the parallel printer interface which causes some - confusion.)</para> - - <para>Below is a table of the RS232-C signal assignments in - the DB25 and DB9 connectors.</para> - - <informaltable frame="none"> - <tgroup cols="7"> - <thead> - <row> - <entry>DB25 RS232-C Pin</entry> <entry>DB9 IBM PC - Pin</entry> <entry>EIA Circuit Symbol</entry> - <entry>CCITT Circuit Symbol</entry> <entry>Common - Name</entry> <entry>Signal Source</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>-</entry> - <entry>AA</entry> - <entry>101</entry> - <entry>PG/FG</entry> - <entry>-</entry> - <entry>Frame/Protective Ground</entry> - </row> - - <row> - <entry>2</entry> - <entry>3</entry> - <entry>BA</entry> - <entry>103</entry> - <entry>TD</entry> - <entry>DTE</entry> - <entry>Transmit Data</entry> - </row> - - <row> - <entry>3</entry> - <entry>2</entry> - <entry>BB</entry> - <entry>104</entry> - <entry>RD</entry> - <entry>DCE</entry> - <entry>Receive Data</entry> - </row> - - <row> - <entry>4</entry> - <entry>7</entry> - <entry>CA</entry> - <entry>105</entry> - <entry>RTS</entry> - <entry>DTE</entry> - <entry>Request to Send</entry> - </row> - - <row> - <entry>5</entry> - <entry>8</entry> - <entry>CB</entry> - <entry>106</entry> - <entry>CTS</entry> - <entry>DCE</entry> - <entry>Clear to Send</entry> - </row> - - <row> - <entry>6</entry> - <entry>6</entry> - <entry>CC</entry> - <entry>107</entry> - <entry>DSR</entry> - <entry>DCE</entry> - <entry>Data Set Ready</entry> - </row> - - <row> - <entry>7</entry> - <entry>5</entry> - <entry>AV</entry> - <entry>102</entry> - <entry>SG/GND</entry> - <entry>-</entry> - <entry>Signal Ground</entry> - </row> - - <row> - <entry>8</entry> - <entry>1</entry> - <entry>CF</entry> - <entry>109</entry> - <entry>DCD/CD</entry> - <entry>DCE</entry> - <entry>Data Carrier Detect</entry> - </row> - - <row> - <entry>9</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>Reserved for Test</entry> - </row> - - <row> - <entry>10</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>Reserved for Test</entry> - </row> - - <row> - <entry>11</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>Reserved for Test</entry> - </row> - - <row> - <entry>12</entry> - <entry>-</entry> - <entry>CI</entry> - <entry>122</entry> - <entry>SRLSD</entry> - <entry>DCE</entry> - <entry>Sec. Recv. Line Signal Detector</entry> - </row> - - <row> - <entry>13</entry> - <entry>-</entry> - <entry>SCB</entry> - <entry>121</entry> - <entry>SCTS</entry> - <entry>DCE</entry> - <entry>Secondary Clear to Send</entry> - </row> - - <row> - <entry>14</entry> - <entry>-</entry> - <entry>SBA</entry> - <entry>118</entry> - <entry>STD</entry> - <entry>DTE</entry> - <entry>Secondary Transmit Data</entry> - </row> - - <row> - <entry>15</entry> - <entry>-</entry> - <entry>DB</entry> - <entry>114</entry> - <entry>TSET</entry> - <entry>DCE</entry> - <entry>Trans. Sig. Element Timing</entry> - </row> - - <row> - <entry>16</entry> - <entry>-</entry> - <entry>SBB</entry> - <entry>119</entry> - <entry>SRD</entry> - <entry>DCE</entry> - <entry>Secondary Received Data</entry> - </row> - - <row> - <entry>17</entry> - <entry>-</entry> - <entry>DD</entry> - <entry>115</entry> - <entry>RSET</entry> - <entry>DCE</entry> - <entry>Receiver Signal Element Timing</entry> - </row> - - <row> - <entry>18</entry> - <entry>-</entry> - <entry>-</entry> - <entry>141</entry> - <entry>LOOP</entry> - <entry>DTE</entry> - <entry>Local Loopback</entry> - </row> - - <row> - <entry>19</entry> - <entry>-</entry> - <entry>SCA</entry> - <entry>120</entry> - <entry>SRS</entry> - <entry>DTE</entry> - <entry>Secondary Request to Send</entry> - </row> - - <row> - <entry>20</entry> - <entry>4</entry> - <entry>CD</entry> - <entry>108.2</entry> - <entry>DTR</entry> - <entry>DTE</entry> - <entry>Data Terminal Ready</entry> - </row> - - <row> - <entry>21</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>RDL</entry> - <entry>DTE</entry> - <entry>Remote Digital Loopback</entry> - </row> - - <row> - <entry>22</entry> - <entry>9</entry> - <entry>CE</entry> - <entry>125</entry> - <entry>RI</entry> - <entry>DCE</entry> - <entry>Ring Indicator</entry> - </row> - - <row> - <entry>23</entry> - <entry>-</entry> - <entry>CH</entry> - <entry>111</entry> - <entry>DSRS</entry> - <entry>DTE</entry> - <entry>Data Signal Rate Selector</entry> - </row> - - <row> - <entry>24</entry> - <entry>-</entry> - <entry>DA</entry> - <entry>113</entry> - <entry>TSET</entry> - <entry>DTE</entry> - <entry>Trans. Sig. Element Timing</entry> - </row> - - <row> - <entry>25</entry> - <entry>-</entry> - <entry>-</entry> - <entry>142</entry> - <entry>-</entry> - <entry>DCE</entry> - <entry>Test Mode</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - </sect2> - - <sect2> - <title>Bits, Baud and Symbols</title> - - <para>Baud is a measurement of transmission speed in - asynchronous communication. Because of advances in modem - communication technology, this term is frequently misused - when describing the data rates in newer devices.</para> - - <para>Traditionally, a Baud Rate represents the number of bits - that are actually being sent over the media, not the amount - of data that is actually moved from one DTE device to the - other. The Baud count includes the overhead bits Start, Stop - and Parity that are generated by the sending UART and - removed by the receiving UART. This means that seven-bit - words of data actually take 10 bits to be completely - transmitted. Therefore, a modem capable of moving 300 bits - per second from one place to another can normally only move - 30 7-bit words if Parity is used and one Start and Stop bit - are present.</para> - - <para>If 8-bit data words are used and Parity bits are also - used, the data rate falls to 27.27 words per second, because - it now takes 11 bits to send the eight-bit words, and the - modem still only sends 300 bits per second.</para> - - <para>The formula for converting bytes per second into a baud - rate and vice versa was simple until error-correcting modems - came along. These modems receive the serial stream of bits - from the UART in the host computer (even when internal - modems are used the data is still frequently serialized) and - converts the bits back into bytes. These bytes are then - combined into packets and sent over the phone line using a - Synchronous transmission method. This means that the Stop, - Start, and Parity bits added by the UART in the DTE (the - computer) were removed by the modem before transmission by - the sending modem. When these bytes are received by the - remote modem, the remote modem adds Start, Stop and Parity - bits to the words, converts them to a serial format and then - sends them to the receiving UART in the remote computer, who - then strips the Start, Stop and Parity bits.</para> - - <para>The reason all these extra conversions are done is so - that the two modems can perform error correction, which - means that the receiving modem is able to ask the sending - modem to resend a block of data that was not received with - the correct checksum. This checking is handled by the - modems, and the DTE devices are usually unaware that the - process is occurring.</para> - - <para>By striping the Start, Stop and Parity bits, the - additional bits of data that the two modems must share - between themselves to perform error-correction are mostly - concealed from the effective transmission rate seen by the - sending and receiving DTE equipment. For example, if a - modem sends ten 7-bit words to another modem without - including the Start, Stop and Parity bits, the sending modem - will be able to add 30 bits of its own information that the - receiving modem can use to do error-correction without - impacting the transmission speed of the real data.</para> - - <para>The use of the term Baud is further confused by modems - that perform compression. A single 8-bit word passed over - the telephone line might represent a dozen words that were - transmitted to the sending modem. The receiving modem will - expand the data back to its original content and pass that - data to the receiving DTE.</para> - - <para>Modern modems also include buffers that allow the rate - that bits move across the phone line (DCE to DCE) to be a - different speed than the speed that the bits move between - the DTE and DCE on both ends of the conversation. Normally - the speed between the DTE and DCE is higher than the DCE to - DCE speed because of the use of compression by the - modems.</para> - - <para>Because the number of bits needed to describe a byte - varied during the trip between the two machines plus the - differing bits-per-seconds speeds that are used present on - the DTE-DCE and DCE-DCE links, the usage of the term Baud to - describe the overall communication speed causes problems and - can misrepresent the true transmission speed. So Bits Per - Second (bps) is the correct term to use to describe the - transmission rate seen at the DCE to DCE interface and Baud - or Bits Per Second are acceptable terms to use when a - connection is made between two systems with a wired - connection, or if a modem is in use that is not performing - error-correction or compression.</para> - - <para>Modern high speed modems (2400, 9600, 14,400, and - 19,200bps) in reality still operate at or below 2400 baud, - or more accurately, 2400 Symbols per second. High speed - modem are able to encode more bits of data into each Symbol - using a technique called Constellation Stuffing, which is - why the effective bits per second rate of the modem is - higher, but the modem continues to operate within the - limited audio bandwidth that the telephone system provides. - Modems operating at 28,800 and higher speeds have variable - Symbol rates, but the technique is the same.</para> - </sect2> - - <sect2> - <title>The IBM Personal Computer UART</title> - - <para>Starting with the original IBM Personal Computer, IBM - selected the National Semiconductor INS8250 UART for use in - the IBM PC Parallel/Serial Adapter. Subsequent generations - of compatible computers from IBM and other vendors continued - to use the INS8250 or improved versions of the National - Semiconductor UART family.</para> - - <sect3> - <title>National Semiconductor UART Family Tree</title> - - <para>There have been several versions and subsequent - generations of the INS8250 UART. Each major version is - described below.</para> - - <!-- This should really be a graphic --> - <programlisting>INS8250 -> INS8250B - \ - \ - \-> INS8250A -> INS82C50A - \ - \ - \-> NS16450 -> NS16C450 - \ - \ - \-> NS16550 -> NS16550A -> PC16550D</programlisting> - - <variablelist> - <varlistentry> - <term>INS8250</term> - - <listitem> - <para>This part was used in the original IBM PC and - IBM PC/XT. The original name for this part was the - INS8250 ACE (Asynchronous Communications Element) - and it is made from NMOS technology.</para> - - <para>The 8250 uses eight I/O ports and has a one-byte - send and a one-byte receive buffer. This original - UART has several race conditions and other - flaws. The original IBM BIOS includes code to work - around these flaws, but this made the BIOS dependent - on the flaws being present, so subsequent parts like - the 8250A, 16450 or 16550 could not be used in the - original IBM PC or IBM PC/XT.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>INS8250-B</term> - - <listitem> - <para>This is the slower speed of the INS8250 made - from NMOS technology. It contains the same problems - as the original INS8250.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>INS8250A</term> - - <listitem> - <para>An improved version of the INS8250 using XMOS - technology with various functional flaws - corrected. The INS8250A was used initially in PC - clone computers by vendors who used - <quote>clean</quote> BIOS designs. Because of the - corrections in the chip, this part could not be used - with a BIOS compatible with the INS8250 or - INS8250B.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>INS82C50A</term> - - <listitem> - <para>This is a CMOS version (low power consumption) - of the INS8250A and has similar functional - characteristics.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16450</term> - - <listitem> - <para>Same as NS8250A with improvements so it can be - used with faster CPU bus designs. IBM used this - part in the IBM AT and updated the IBM BIOS to no - longer rely on the bugs in the INS8250.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16C450</term> - - <listitem> - <para>This is a CMOS version (low power consumption) - of the NS16450.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16550</term> - - <listitem> - <para>Same as NS16450 with a 16-byte send and receive - buffer but the buffer design was flawed and could - not be reliably be used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16550A</term> - - <listitem> - <para>Same as NS16550 with the buffer flaws - corrected. The 16550A and its successors have become - the most popular UART design in the PC industry, - mainly due to its ability to reliably handle higher - data rates on operating systems with sluggish - interrupt response times.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NS16C552</term> - - <listitem> - <para>This component consists of two NS16C550A CMOS - UARTs in a single package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>PC16550D</term> - - <listitem> - <para>Same as NS16550A with subtle flaws - corrected. This is revision D of the 16550 family - and is the latest design available from National - Semiconductor.</para> - </listitem> - </varlistentry> - </variablelist> - </sect3> - - <sect3> - <title>The NS16550AF and the PC16550D are the same thing</title> - - <para>National reorganized their part numbering system a few - years ago, and the NS16550AFN no longer exists by that - name. (If you have a NS16550AFN, look at the date code on - the part, which is a four digit number that usually starts - with a nine. The first two digits of the number are the - year, and the last two digits are the week in that year - when the part was packaged. If you have a NS16550AFN, it - is probably a few years old.)</para> - - <para>The new numbers are like PC16550DV, with minor - differences in the suffix letters depending on the package - material and its shape. (A description of the numbering - system can be found below.)</para> - - <para>It is important to understand that in some stores, you - may pay $15(US) for a NS16550AFN made in 1990 and in - the next bin are the new PC16550DN parts with minor fixes - that National has made since the AFN part was in - production, the PC16550DN was probably made in the past - six months and it costs half (as low as $5(US) in - volume) as much as the NS16550AFN because they are readily - available.</para> - - <para>As the supply of NS16550AFN chips continues to shrink, - the price will probably continue to increase until more - people discover and accept that the PC16550DN really has - the same function as the old part number.</para> - </sect3> - - <sect3> - <title>National Semiconductor Part Numbering System</title> - - <para>The older NS<replaceable>nnnnnrqp</replaceable> part - numbers are now of the format - PC<replaceable>nnnnnrgp</replaceable>.</para> - - <para>The <replaceable>r</replaceable> is the revision - field. The current revision of the 16550 from National - Semiconductor is <literal>D</literal>.</para> - - <para>The <replaceable>p</replaceable> is the package-type - field. The types are:</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <tbody> - <row> - <entry>"F"</entry> - <entry>QFP</entry> - <entry>(quad flat pack) L lead type</entry> - </row> - - <row> - <entry>"N"</entry> - <entry>DIP</entry> - <entry>(dual inline package) through hole straight lead - type</entry> - </row> - - <row> - <entry>"V"</entry> - <entry>LPCC</entry> - <entry>(lead plastic chip carrier) J lead type</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>The <replaceable>g</replaceable> is the product grade - field. If an <literal>I</literal> precedes the - package-type letter, it indicates an - <quote>industrial</quote> grade part, which has higher - specs than a standard part but not as high as Military - Specification (Milspec) component. This is an optional - field.</para> - - <para>So what we used to call a NS16550AFN (DIP Package) is - now called a PC16550DN or PC16550DIN.</para> - </sect3> - </sect2> - - <sect2> - <title>Other Vendors and Similar UARTs</title> - - <para>Over the years, the 8250, 8250A, 16450 and 16550 have - been licensed or copied by other chip vendors. In the case - of the 8250, 8250A and 16450, the exact circuit (the - <quote>megacell</quote>) was licensed to many vendors, - including Western Digital and Intel. Other vendors - reverse-engineered the part or produced emulations that had - similar behavior.</para> - - <para>In internal modems, the modem designer will frequently - emulate the 8250A/16450 with the modem microprocessor, and - the emulated UART will frequently have a hidden buffer - consisting of several hundred bytes. Because of the size of - the buffer, these emulations can be as reliable as a 16550A - in their ability to handle high speed data. However, most - operating systems will still report that the UART is only a - 8250A or 16450, and may not make effective use of the extra - buffering present in the emulated UART unless special - drivers are used.</para> - - <para>Some modem makers are driven by market forces to abandon - a design that has hundreds of bytes of buffer and instead - use a 16550A UART so that the product will compare favorably - in market comparisons even though the effective performance - may be lowered by this action.</para> - - <para>A common misconception is that all parts with - <quote>16550A</quote> written on them are identical in - performance. There are differences, and in some cases, - outright flaws in most of these 16550A clones.</para> - - <para>When the NS16550 was developed, the National - Semiconductor obtained several patents on the design and - they also limited licensing, making it harder for other - vendors to provide a chip with similar features. Because of - the patents, reverse-engineered designs and emulations had - to avoid infringing the claims covered by the patents. - Subsequently, these copies almost never perform exactly the - same as the NS16550A or PC16550D, which are the parts most - computer and modem makers want to buy but are sometimes - unwilling to pay the price required to get the genuine - part.</para> - - <para>Some of the differences in the clone 16550A parts are - unimportant, while others can prevent the device from being - used at all with a given operating system or driver. These - differences may show up when using other drivers, or when - particular combinations of events occur that were not well - tested or considered in the &windows; driver. This is because - most modem vendors and 16550-clone makers use the Microsoft - drivers from &windows; for Workgroups 3.11 and the µsoft; - &ms-dos; utility as the primary tests for compatibility with - the NS16550A. This over-simplistic criteria means that if a - different operating system is used, problems could appear - due to subtle differences between the clones and genuine - components.</para> - - <para>National Semiconductor has made available a program - named <application>COMTEST</application> that performs - compatibility tests independent of any OS drivers. It - should be remembered that the purpose of this type of - program is to demonstrate the flaws in the products of the - competition, so the program will report major as well as - extremely subtle differences in behavior in the part being - tested.</para> - - <para>In a series of tests performed by the author of this - document in 1994, components made by National Semiconductor, - TI, StarTech, and CMD as well as megacells and emulations - embedded in internal modems were tested with COMTEST. A - difference count for some of these components is listed - below. Because these tests were performed in 1994, they may - not reflect the current performance of the given product - from a vendor.</para> - - <para>It should be noted that COMTEST normally aborts when an - excessive number or certain types of problems have been - detected. As part of this testing, COMTEST was modified so - that it would not abort no matter how many differences were - encountered.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>Vendor</entry> - <entry>Part Number</entry> - <entry>Errors (aka "differences" reported)</entry> - </row> - </thead> - - <tbody> - <row> - <entry>National</entry> - <entry>(PC16550DV)</entry> - <entry>0</entry> - </row> - - <row> - <entry>National</entry> - <entry>(NS16550AFN)</entry> - <entry>0</entry> - </row> - - <row> - <entry>National</entry> - <entry>(NS16C552V)</entry> - <entry>0</entry> - </row> - - <row> - <entry>TI</entry> - <entry>(TL16550AFN)</entry> - <entry>3</entry> - </row> - - <row> - <entry>CMD</entry> - <entry>(16C550PE)</entry> - <entry>19</entry> - </row> - - <row> - <entry>StarTech</entry> - <entry>(ST16C550J)</entry> - <entry>23</entry> - </row> - - <row> - <entry>Rockwell</entry> - <entry>Reference modem with internal 16550 or an - emulation (RC144DPi/C3000-25)</entry> - <entry>117</entry> - </row> - - <row> - <entry>Sierra</entry> - <entry>Modem with an internal 16550 - (SC11951/SC11351)</entry> - <entry>91</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <note> - <para>To date, the author of this document has not found any - non-National parts that report zero differences using the - COMTEST program. It should also be noted that National - has had five versions of the 16550 over the years and the - newest parts behave a bit differently than the classic - NS16550AFN that is considered the benchmark for - functionality. COMTEST appears to turn a blind eye to the - differences within the National product line and reports - no errors on the National parts (except for the original - 16550) even when there are official erratas that describe - bugs in the A, B and C revisions of the parts, so this - bias in COMTEST must be taken into account.</para> - </note> - - <para>It is important to understand that a simple count of - differences from COMTEST does not reveal a lot about what - differences are important and which are not. For example, - about half of the differences reported in the two modems - listed above that have internal UARTs were caused by the - clone UARTs not supporting five- and six-bit character - modes. The real 16550, 16450, and 8250 UARTs all support - these modes and COMTEST checks the functionality of these - modes so over fifty differences are reported. However, - almost no modern modem supports five- or six-bit characters, - particularly those with error-correction and compression - capabilities. This means that the differences related to - five- and six-bit character modes can be discounted.</para> - - <para>Many of the differences COMTEST reports have to do with - timing. In many of the clone designs, when the host reads - from one port, the status bits in some other port may not - update in the same amount of time (some faster, some slower) - as a <emphasis>real</emphasis> NS16550AFN and COMTEST looks - for these differences. This means that the number of - differences can be misleading in that one device may only - have one or two differences but they are extremely serious, - and some other device that updates the status registers - faster or slower than the reference part (that would - probably never affect the operation of a properly written - driver) could have dozens of differences reported.</para> - - <para>COMTEST can be used as a screening tool to alert the - administrator to the presence of potentially incompatible - components that might cause problems or have to be handled - as a special case.</para> - - <para>If you run COMTEST on a 16550 that is in a modem or a - modem is attached to the serial port, you need to first - issue a ATE0&W command to the modem so that the modem - will not echo any of the test characters. If you forget to - do this, COMTEST will report at least this one - difference:</para> - - <screen>Error (6)...Timeout interrupt failed: IIR = c1 LSR = 61</screen> - </sect2> - - <sect2> - <title>8250/16450/16550 Registers</title> - - <para>The 8250/16450/16550 UART occupies eight contiguous I/O - port addresses. In the IBM PC, there are two defined - locations for these eight ports and they are known - collectively as <devicename>COM1</devicename> and <devicename>COM2</devicename>. The makers of PC-clones and - add-on cards have created two additional areas known as <devicename>COM3</devicename> - and <devicename>COM4</devicename>, but these extra COM ports conflict with other - hardware on some systems. The most common conflict is with - video adapters that provide IBM 8514 emulation.</para> - - <para><devicename>COM1</devicename> is located from 0x3f8 to 0x3ff and normally uses - IRQ 4. <devicename>COM2</devicename> is located from 0x2f8 to 0x2ff and normally uses - IRQ 3. <devicename>COM3</devicename> is located from 0x3e8 to 0x3ef and has no - standardized IRQ. <devicename>COM4</devicename> is located from 0x2e8 to 0x2ef and has - no standardized IRQ.</para> - - <para>A description of the I/O ports of the 8250/16450/16550 - UART is provided below.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>I/O Port</entry> - <entry>Access Allowed</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>+0x00</entry> - <entry>write (DLAB==0)</entry> - <entry><para>Transmit Holding Register - (THR).</para><para>Information written to this port are - treated as data words and will be transmitted by the - UART.</para></entry> - </row> - - <row> - <entry>+0x00</entry> - <entry>read (DLAB==0)</entry> - <entry><para>Receive Buffer Register (RBR).</para><para>Any - data words received by the UART form the serial link are - accessed by the host by reading this - port.</para></entry> - </row> - - <row> - <entry>+0x00</entry> - <entry>write/read (DLAB==1)</entry> - <entry><para>Divisor Latch LSB (DLL)</para><para>This value - will be divided from the master input clock (in the IBM - PC, the master clock is 1.8432MHz) and the resulting - clock will determine the baud rate of the UART. This - register holds bits 0 thru 7 of the - divisor.</para></entry> - </row> - - <row> - <entry>+0x01</entry> - <entry>write/read (DLAB==1)</entry> - <entry><para>Divisor Latch MSB (DLH)</para><para>This value - will be divided from the master input clock (in the IBM - PC, the master clock is 1.8432MHz) and the resulting - clock will determine the baud rate of the UART. This - register holds bits 8 thru 15 of the - divisor.</para></entry> - </row> - - <row> - <entry>+0x01</entry> - <entry>write/read (DLAB==0)</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2"><para>Interrupt Enable Register - (IER)</para><para>The 8250/16450/16550 UART - classifies events into one of four categories. - Each category can be configured to generate an - interrupt when any of the events occurs. The - 8250/16450/16550 UART generates a single external - interrupt signal regardless of how many events in - the enabled categories have occurred. It is up to - the host processor to respond to the interrupt and - then poll the enabled interrupt categories - (usually all categories have interrupts enabled) - to determine the true cause(s) of the - interrupt.</para></entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>Enable Modem Status Interrupt (EDSSI). Setting - this bit to "1" allows the UART to generate an - interrupt when a change occurs on one or more of the - status lines.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>Enable Receiver Line Status Interrupt (ELSI) - Setting this bit to "1" causes the UART to generate - an interrupt when the an error (or a BREAK signal) - has been detected in the incoming data.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Enable Transmitter Holding Register Empty - Interrupt (ETBEI) Setting this bit to "1" causes the - UART to generate an interrupt when the UART has room - for one or more additional characters that are to be - transmitted.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Enable Received Data Available Interrupt - (ERBFI) Setting this bit to "1" causes the UART to - generate an interrupt when the UART has received - enough characters to exceed the trigger level of the - FIFO, or the FIFO timer has expired (stale data), or - a single character has been received when the FIFO - is disabled.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x02</entry> - <entry>write</entry> - <entrytbl cols="4"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <colspec colnum="3" colname="col3"> - <colspec colnum="4" colname="col4"> - <spanspec namest="col1" nameend="col4" spanname="1to4"> - <spanspec namest="col2" nameend="col4" spanname="2to4"> - - <tbody> - <row> - <entry spanname="1to4">FIFO Control Register (FCR) - (This port does not exist on the 8250 and 16450 - UART.)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry spanname="2to4">Receiver Trigger Bit #1</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry spanname="2to4"><para>Receiver Trigger Bit - #0</para><para>These two bits control at what - point the receiver is to generate an interrupt - when the FIFO is active.</para></entry> - </row> - - <row> - <entry colname="col2">7</entry> - <entry colname="col3">6</entry> - <entry colname="col4">How many words are received - before an interrupt is generated</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4">1</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4">4</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">0</entry> - <entry colname="col4">8</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">1</entry> - <entry colname="col4">14</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry spanname="2to4">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry spanname="2to4">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry spanname="2to4">DMA Mode Select. If Bit 0 is - set to "1" (FIFOs enabled), setting this bit changes - the operation of the -RXRDY and -TXRDY signals from - Mode 0 to Mode 1.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry spanname="2to4">Transmit FIFO Reset. When a - "1" is written to this bit, the contents of the FIFO - are discarded. Any word currently being transmitted - will be sent intact. This function is useful in - aborting transfers.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry spanname="2to4">Receiver FIFO Reset. When a - "1" is written to this bit, the contents of the FIFO - are discarded. Any word currently being assembled - in the shift register will be received - intact.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry spanname="2to4">16550 FIFO Enable. When set, - both the transmit and receive FIFOs are enabled. - Any contents in the holding register, shift - registers or FIFOs are lost when FIFOs are enabled - or disabled.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x02</entry> - <entry>read</entry> - <entrytbl cols="6"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <colspec colnum="3" colname="col3"> - <colspec colnum="4" colname="col4"> - <colspec colnum="5" colname="col5"> - <colspec colnum="6" colname="col6"> - <spanspec namest="col1" nameend="col6" spanname="1to6"> - <spanspec namest="col2" nameend="col6" spanname="2to6"> - - <tbody> - <row> - <entry spanname="1to6">Interrupt Identification - Register</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry spanname="2to6">FIFOs enabled. On the - 8250/16450 UART, this bit is zero.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry spanname="2to6">FIFOs enabled. On the - 8250/16450 UART, this bit is zero.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry spanname="2to6">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry spanname="2to6">Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry spanname="2to6">Interrupt ID Bit #2. On the - 8250/16450 UART, this bit is zero.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry spanname="2to6">Interrupt ID Bit #1</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry spanname="2to6">Interrupt ID Bit #0.These - three bits combine to report the category of - event that caused the interrupt that is in - progress. These categories have priorities, - so if multiple categories of events occur at - the same time, the UART will report the more - important events first and the host must - resolve the events in the order they are - reported. All events that caused the current - interrupt must be resolved before any new - interrupts will be generated. (This is a - limitation of the PC architecture.)</entry> - </row> - - <row> - <entry colname="col2">2</entry> - <entry colname="col3">1</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Priority</entry> - <entry colname="col6">Description</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4">1</entry> - <entry colname="col5">First</entry> - <entry colname="col6">Received Error (OE, PE, BI, or - FE)</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Second</entry> - <entry colname="col6">Received Data Available</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">1</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Second</entry> - <entry colname="col6">Trigger level identification - (Stale data in receive buffer)</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4">1</entry> - <entry colname="col5">Third</entry> - <entry colname="col6">Transmitter has room for more - words (THRE)</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4">0</entry> - <entry colname="col5">Fourth</entry> - <entry colname="col6">Modem Status Change (-CTS, -DSR, - -RI, or -DCD)</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry spanname="2to6">Interrupt Pending Bit. If this - bit is set to "0", then at least one interrupt is - pending.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x03</entry> - <entry>write/read</entry> - <entrytbl cols="5"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <colspec colnum="3" colname="col3"> - <colspec colnum="4" colname="col4"> - <colspec colnum="5" colname="col5"> - <spanspec namest="col1" nameend="col5" spanname="1to5"> - <spanspec namest="col2" nameend="col5" spanname="2to5"> - <spanspec namest="col4" nameend="col5" spanname="4to5"> - - <tbody> - <row> - <entry spanname="1to5">Line Control Register - (LCR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry spanname="2to5">Divisor Latch Access Bit - (DLAB). When set, access to the data - transmit/receive register (THR/RBR) and the - Interrupt Enable Register (IER) is disabled. Any - access to these ports is now redirected to the - Divisor Latch Registers. Setting this bit, loading - the Divisor Registers, and clearing DLAB should be - done with interrupts disabled.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry spanname="2to5">Set Break. When set to "1", - the transmitter begins to transmit continuous - Spacing until this bit is set to "0". This - overrides any bits of characters that are being - transmitted.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry spanname="2to5">Stick Parity. When parity is - enabled, setting this bit causes parity to always be - "1" or "0", based on the value of Bit 4.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry spanname="2to5">Even Parity Select (EPS). When - parity is enabled and Bit 5 is "0", setting this bit - causes even parity to be transmitted and expected. - Otherwise, odd parity is used.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry spanname="2to5">Parity Enable (PEN). When set - to "1", a parity bit is inserted between the last - bit of the data and the Stop Bit. The UART will - also expect parity to be present in the received - data.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry spanname="2to5">Number of Stop Bits (STB). If - set to "1" and using 5-bit data words, 1.5 Stop Bits - are transmitted and expected in each data word. For - 6, 7 and 8-bit data words, 2 Stop Bits are - transmitted and expected. When this bit is set to - "0", one Stop Bit is used on each data word.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry spanname="2to5">Word Length Select Bit #1 - (WLSB1)</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry spanname="2to5">Word Length Select Bit #0 - (WLSB0)</entry> - </row> - - <row> - <entry colname="col2" spanname="2to5">Together these - bits specify the number of bits in each data - word.</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">0</entry> - <entry colname="col4" spanname="4to5">Word - Length</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">0</entry> - <entry colname="col4" spanname="4to5">5 Data - Bits</entry> - </row> - - <row> - <entry colname="col2">0</entry> - <entry colname="col3">1</entry> - <entry colname="col4" spanname="4to5">6 Data - Bits</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">0</entry> - <entry colname="col4" spanname="4to5">7 Data - Bits</entry> - </row> - - <row> - <entry colname="col2">1</entry> - <entry colname="col3">1</entry> - <entry colname="col4" spanname="4to5">8 Data - Bits</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x04</entry> - <entry>write/read</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2">Modem Control Register - (MCR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Reserved, always 0.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Loop-Back Enable. When set to "1", the UART - transmitter and receiver are internally connected - together to allow diagnostic operations. In - addition, the UART modem control outputs are - connected to the UART modem control inputs. CTS is - connected to RTS, DTR is connected to DSR, OUT1 is - connected to RI, and OUT 2 is connected to - DCD.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>OUT 2. An auxiliary output that the host - processor may set high or low. In the IBM PC serial - adapter (and most clones), OUT 2 is used to - tri-state (disable) the interrupt signal from the - 8250/16450/16550 UART.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>OUT 1. An auxiliary output that the host - processor may set high or low. This output is not - used on the IBM PC serial adapter.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Request to Send (RTS). When set to "1", the - output of the UART -RTS line is Low - (Active).</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Data Terminal Ready (DTR). When set to "1", - the output of the UART -DTR line is Low - (Active).</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x05</entry> - <entry>write/read</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2">Line Status Register - (LSR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Error in Receiver FIFO. On the 8250/16450 - UART, this bit is zero. This bit is set to "1" when - any of the bytes in the FIFO have one or more of the - following error conditions: PE, FE, or BI.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Transmitter Empty (TEMT). When set to "1", - there are no words remaining in the transmit FIFO - or the transmit shift register. The transmitter is - completely idle.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Transmitter Holding Register Empty (THRE). - When set to "1", the FIFO (or holding register) now - has room for at least one additional word to - transmit. The transmitter may still be transmitting - when this bit is set to "1".</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Break Interrupt (BI). The receiver has - detected a Break signal.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>Framing Error (FE). A Start Bit was detected - but the Stop Bit did not appear at the expected - time. The received word is probably - garbled.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>Parity Error (PE). The parity bit was - incorrect for the word received.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Overrun Error (OE). A new word was received - and there was no room in the receive buffer. The - newly-arrived word in the shift register is - discarded. On 8250/16450 UARTs, the word in the - holding register is discarded and the newly- arrived - word is put in the holding register.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Data Ready (DR) One or more words are in the - receive FIFO that the host may read. A word must be - completely received and moved from the shift - register into the FIFO (or holding register for - 8250/16450 designs) before this bit is set.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x06</entry> - <entry>write/read</entry> - <entrytbl cols="2"> - <colspec colnum="1" colname="col1"> - <colspec colnum="2" colname="col2"> - <spanspec namest="col1" nameend="col2" spanname="1to2"> - - <tbody> - <row> - <entry spanname="1to2">Modem Status Register - (MSR)</entry> - </row> - - <row> - <entry>Bit 7</entry> - <entry>Data Carrier Detect (DCD). Reflects the state - of the DCD line on the UART.</entry> - </row> - - <row> - <entry>Bit 6</entry> - <entry>Ring Indicator (RI). Reflects the state of the - RI line on the UART.</entry> - </row> - - <row> - <entry>Bit 5</entry> - <entry>Data Set Ready (DSR). Reflects the state of - the DSR line on the UART.</entry> - </row> - - <row> - <entry>Bit 4</entry> - <entry>Clear To Send (CTS). Reflects the state of the - CTS line on the UART.</entry> - </row> - - <row> - <entry>Bit 3</entry> - <entry>Delta Data Carrier Detect (DDCD). Set to "1" - if the -DCD line has changed state one more - time since the last time the MSR was read by the - host.</entry> - </row> - - <row> - <entry>Bit 2</entry> - <entry>Trailing Edge Ring Indicator (TERI). Set to - "1" if the -RI line has had a low to high transition - since the last time the MSR was read by the - host.</entry> - </row> - - <row> - <entry>Bit 1</entry> - <entry>Delta Data Set Ready (DDSR). Set to "1" if the - -DSR line has changed state one more time - since the last time the MSR was read by the - host.</entry> - </row> - - <row> - <entry>Bit 0</entry> - <entry>Delta Clear To Send (DCTS). Set to "1" if the - -CTS line has changed state one more time - since the last time the MSR was read by the - host.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row> - <entry>+0x07</entry> - <entry>write/read</entry> - <entry>Scratch Register (SCR). This register performs no - function in the UART. Any value can be written by the - host to this location and read by the host later - on.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - - <sect2> - <title>Beyond the 16550A UART</title> - - <para>Although National Semiconductor has not offered any - components compatible with the 16550 that provide additional - features, various other vendors have. Some of these - components are described below. It should be understood - that to effectively utilize these improvements, drivers may - have to be provided by the chip vendor since most of the - popular operating systems do not support features beyond - those provided by the 16550.</para> - - <variablelist> - <varlistentry> - <term>ST16650</term> - - <listitem> - <para>By default this part is similar to the NS16550A, but an - extended 32-byte send and receive buffer can be optionally - enabled. Made by StarTech.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>TIL16660</term> - - <listitem> - <para>By default this part behaves similar to the NS16550A, - but an extended 64-byte send and receive buffer can be - optionally enabled. Made by Texas Instruments.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Hayes ESP</term> - - <listitem> - <para>This proprietary plug-in card contains a 2048-byte send - and receive buffer, and supports data rates to - 230.4Kbit/sec. Made by Hayes.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In addition to these <quote>dumb</quote> UARTs, many vendors - produce intelligent serial communication boards. This type of - design usually provides a microprocessor that interfaces with - several UARTs, processes and buffers the data, and then alerts the - main PC processor when necessary. Because the UARTs are not - directly accessed by the PC processor in this type of - communication system, it is not necessary for the vendor to use - UARTs that are compatible with the 8250, 16450, or the 16550 UART. - This leaves the designer free to components that may have better - performance characteristics.</para> - </sect2> - </sect1> - - <sect1 id="sio"> - <title>Configuring the <devicename>sio</devicename> driver</title> - - <para>The <devicename>sio</devicename> driver provides support - for NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C - (CCITT V.24) communications interfaces. Several multiport - cards are supported as well. See the &man.sio.4; manual page - for detailed technical documentation.</para> - - <sect2> - <title>Digi International (DigiBoard) PC/8</title> - - <para><emphasis>Contributed by &a.awebster;. 26 August - 1995.</emphasis></para> - - <para>Here is a config snippet from a machine with a Digi - International PC/8 with 16550. It has 8 modems connected to - these 8 lines, and they work just great. Do not forget to - add <literal>options COM_MULTIPORT</literal> or it will not - work very well!</para> - - <programlisting>device sio4 at isa? port 0x100 flags 0xb05 -device sio5 at isa? port 0x108 flags 0xb05 -device sio6 at isa? port 0x110 flags 0xb05 -device sio7 at isa? port 0x118 flags 0xb05 -device sio8 at isa? port 0x120 flags 0xb05 -device sio9 at isa? port 0x128 flags 0xb05 -device sio10 at isa? port 0x130 flags 0xb05 -device sio11 at isa? port 0x138 flags 0xb05 irq 9</programlisting> - - <para>The trick in setting this up is that the MSB of the - flags represent the last SIO port, in this case 11 so flags - are 0xb05.</para> - </sect2> - - <sect2> - <title>Boca 16</title> - - <para><emphasis>Contributed by &a.whiteside;. 26 August - 1995.</emphasis></para> - - <para>The procedures to make a Boca 16 port board with FreeBSD - are pretty straightforward, but you will need a couple - things to make it work:</para> - - <orderedlist> - <listitem> - <para>You either need the kernel sources installed so you - can recompile the necessary options or you will need - someone else to compile it for you. The 2.0.5 default - kernel does <emphasis>not</emphasis> come with - multiport support enabled and you will need to add a - device entry for each port anyways.</para> - </listitem> - - <listitem> - <para>Two, you will need to know the interrupt and IO - setting for your Boca Board so you can set these options - properly in the kernel.</para> - </listitem> - </orderedlist> - - <para>One important note — the actual UART chips for the - Boca 16 are in the connector box, not on the internal board - itself. So if you have it unplugged, probes of those ports - will fail. I have never tested booting with the box - unplugged and plugging it back in, and I suggest you do not - either.</para> - - <para>If you do not already have a custom kernel - configuration file set up, refer to <ulink - url="&url.books.handbook;/kernelconfig.html">Kernel - Configuration</ulink> chapter of the FreeBSD Handbook for - general procedures. The following are the specifics for the - Boca 16 board and assume you are using the kernel name - MYKERNEL and editing with vi.</para> - - <procedure> - <step> - <para>Add the line - - <programlisting>options COM_MULTIPORT</programlisting> - - to the config file.</para> - </step> - - <step> - <para>Where the current <literal>device - sio<replaceable>n</replaceable></literal> lines are, you - will need to add 16 more devices. The - following example is for a Boca Board with an interrupt - of 3, and a base IO address 100h. The IO address for - Each port is +8 hexadecimal from the previous port, thus - the 100h, 108h, 110h... addresses.</para> - - <programlisting>device sio1 at isa? port 0x100 flags 0x1005 -device sio2 at isa? port 0x108 flags 0x1005 -device sio3 at isa? port 0x110 flags 0x1005 -device sio4 at isa? port 0x118 flags 0x1005 -… -device sio15 at isa? port 0x170 flags 0x1005 -device sio16 at isa? port 0x178 flags 0x1005 irq 3</programlisting> - - <para>The flags entry <emphasis>must</emphasis> be changed - from this example unless you are using the exact same - sio assignments. Flags are set according to - 0x<replaceable>M</replaceable><replaceable>YY</replaceable> - where <replaceable>M</replaceable> indicates the minor - number of the master port (the last port on a Boca 16) - and <replaceable>YY</replaceable> indicates if FIFO is - enabled or disabled(enabled), IRQ sharing is used(yes) - and if there is an AST/4 compatible IRQ control - register(no). In this example, <programlisting> flags - 0x1005</programlisting> indicates that the master port - is sio16. If I added another board and assigned sio17 - through sio28, the flags for all 16 ports on - <emphasis>that</emphasis> board would be 0x1C05, where - 1C indicates the minor number of the master port. Do - not change the 05 setting.</para> - </step> - - <step> - <para>Save and complete the kernel configuration, - recompile, install and reboot. Presuming you have - successfully installed the recompiled kernel and have it - set to the correct address and IRQ, your boot message - should indicate the successful probe of the Boca ports - as follows: (obviously the sio numbers, IO and IRQ could - be different)</para> - - <screen>sio1 at 0x100-0x107 flags 0x1005 on isa -sio1: type 16550A (multiport) -sio2 at 0x108-0x10f flags 0x1005 on isa -sio2: type 16550A (multiport) -sio3 at 0x110-0x117 flags 0x1005 on isa -sio3: type 16550A (multiport) -sio4 at 0x118-0x11f flags 0x1005 on isa -sio4: type 16550A (multiport) -sio5 at 0x120-0x127 flags 0x1005 on isa -sio5: type 16550A (multiport) -sio6 at 0x128-0x12f flags 0x1005 on isa -sio6: type 16550A (multiport) -sio7 at 0x130-0x137 flags 0x1005 on isa -sio7: type 16550A (multiport) -sio8 at 0x138-0x13f flags 0x1005 on isa -sio8: type 16550A (multiport) -sio9 at 0x140-0x147 flags 0x1005 on isa -sio9: type 16550A (multiport) -sio10 at 0x148-0x14f flags 0x1005 on isa -sio10: type 16550A (multiport) -sio11 at 0x150-0x157 flags 0x1005 on isa -sio11: type 16550A (multiport) -sio12 at 0x158-0x15f flags 0x1005 on isa -sio12: type 16550A (multiport) -sio13 at 0x160-0x167 flags 0x1005 on isa -sio13: type 16550A (multiport) -sio14 at 0x168-0x16f flags 0x1005 on isa -sio14: type 16550A (multiport) -sio15 at 0x170-0x177 flags 0x1005 on isa -sio15: type 16550A (multiport) -sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa -sio16: type 16550A (multiport master)</screen> - - <para>If the messages go by too fast to see, - - <screen>&prompt.root; <userinput>dmesg | more</userinput></screen> - will show you the boot messages.</para> - </step> - - <step> - <para>Next, appropriate entries in - <filename>/dev</filename> for the devices must be made - using the <filename>/dev/MAKEDEV</filename> - script. This step can be omitted if you are running - FreeBSD 5.X with a kernel that has &man.devfs.5; - support compiled in.</para> - - <para>If you do need to create the <filename>/dev</filename> - entries, run the following as <username>root</username>:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV tty1</userinput> -&prompt.root; <userinput>./MAKEDEV cua1</userinput> -<emphasis>(everything in between)</emphasis> -&prompt.root; <userinput>./MAKEDEV ttyg</userinput> -&prompt.root; <userinput>./MAKEDEV cuag</userinput></screen> - - <para>If you do not want or need call-out devices for some - reason, you can dispense with making the - <filename>cua*</filename> devices.</para> - </step> - - <step> - <para>If you want a quick and sloppy way to make sure the - devices are working, you can simply plug a modem into - each port and (as root) - - <screen>&prompt.root; <userinput>echo at > ttyd*</userinput></screen> - for each device you have made. You - <emphasis>should</emphasis> see the RX lights flash for each - working port.</para> - </step> - </procedure> - </sect2> - - <sect2> - <title>Support for Cheap Multi-UART Cards</title> - - <para><emphasis>Contributed by Helge Oldach - <email>hmo@sep.hamburg.com</email>, September - 1999</emphasis></para> - - <para>Ever wondered about FreeBSD support for your 20$ - multi-I/O card with two (or more) COM ports, sharing IRQs? - Here is how:</para> - - <para>Usually the only option to support these kind of boards - is to use a distinct IRQ for each port. For example, if - your CPU board has an on-board <devicename>COM1</devicename> - port (aka <devicename>sio0</devicename>–I/O address - 0x3F8 and IRQ 4) and you have an extension board with two - UARTs, you will commonly need to configure them as - <devicename>COM2</devicename> (aka - <devicename>sio1</devicename>–I/O address 0x2F8 and - IRQ 3), and the third port (aka - <devicename>sio2</devicename>) as I/O 0x3E8 and IRQ 5. - Obviously this is a waste of IRQ resources, as it should be - basically possible to run both extension board ports using a - single IRQ with the <literal>COM_MULTIPORT</literal> - configuration described in the previous sections.</para> - - <para>Such cheap I/O boards commonly have a 4 by 3 jumper - matrix for the COM ports, similar to the following:</para> - -<programlisting> o o o * -Port A | - o * o * -Port B | - o * o o -IRQ 2 3 4 5</programlisting> - - <para>Shown here is port A wired for IRQ 5 and port B wired - for IRQ 3. The IRQ columns on your specific board may - vary—other boards may supply jumpers for IRQs 3, 4, 5, - and 7 instead.</para> - - <para>One could conclude that wiring both ports for IRQ 3 - using a handcrafted wire-made jumper covering all three - connection points in the IRQ 3 column would solve the issue, - but no. You cannot duplicate IRQ 3 because the output - drivers of each UART are wired in a <quote>totem - pole</quote> fashion, so if one of the UARTs drives IRQ 3, - the output signal will not be what you would expect. - Depending on the implementation of the extension board or - your motherboard, the IRQ 3 line will continuously stay up, - or always stay low.</para> - - <para>You need to decouple the IRQ drivers for the two UARTs, - so that the IRQ line of the board only goes up if (and only - if) one of the UARTs asserts a IRQ, and stays low otherwise. - The solution was proposed by Joerg Wunsch - <email>j@ida.interface-business.de</email>: To solder up a - wired-or consisting of two diodes (Germanium or - Schottky-types strongly preferred) and a 1 kOhm resistor. - Here is the schematic, starting from the 4 by 3 jumper field - above:</para> - -<programlisting> Diode - +---------->|-------+ - / | - o * o o | 1 kOhm -Port A +----|######|-------+ - o * o o | | -Port B `-------------------+ ==+== - o * o o | Ground - \ | - +--------->|-------+ -IRQ 2 3 4 5 Diode</programlisting> - - <para>The cathodes of the diodes are connected to a common - point, together with a 1 kOhm pull-down resistor. It is - essential to connect the resistor to ground to avoid - floating of the IRQ line on the bus.</para> - - <para>Now we are ready to configure a kernel. Staying with - this example, we would configure:</para> - - <programlisting># standard on-board COM1 port -device sio0 at isa? port "IO_COM1" flags 0x10 -# patched-up multi-I/O extension board -options COM_MULTIPORT -device sio1 at isa? port "IO_COM2" flags 0x205 -device sio2 at isa? port "IO_COM3" flags 0x205 irq 3</programlisting> - - <para>Note that the <literal>flags</literal> setting for - <devicename>sio1</devicename> and - <devicename>sio2</devicename> is truly essential; refer to - &man.sio.4; for details. (Generally, the - <literal>2</literal> in the "flags" attribute refers to - <devicename>sio</devicename>2 which holds the IRQ, and you - surely want a <literal>5</literal> low nibble.) With kernel - verbose mode turned on this should yield something similar - to this:</para> - - <screen>sio0: irq maps: 0x1 0x11 0x1 0x1 -sio0 at 0x3f8-0x3ff irq 4 flags 0x10 on isa -sio0: type 16550A -sio1: irq maps: 0x1 0x9 0x1 0x1 -sio1 at 0x2f8-0x2ff flags 0x205 on isa -sio1: type 16550A (multiport) -sio2: irq maps: 0x1 0x9 0x1 0x1 -sio2 at 0x3e8-0x3ef irq 3 flags 0x205 on isa -sio2: type 16550A (multiport master)</screen> - - <para>Though <filename>/sys/i386/isa/sio.c</filename> is - somewhat cryptic with its use of the <quote>irq maps</quote> - array above, the basic idea is that you observe - <literal>0x1</literal> in the first, third, and fourth - place. This means that the corresponding IRQ was set upon - output and cleared after, which is just what we would - expect. If your kernel does not display this behavior, most - likely there is something wrong with your wiring.</para> - </sect2> - </sect1> - - <sect1 id="cy"> - <title>Configuring the <devicename>cy</devicename> driver</title> - - <para><emphasis>Contributed by Alex Nash. 6 June - 1996.</emphasis></para> - - <para>The Cyclades multiport cards are based on the - <devicename>cy</devicename> driver instead of the usual - <devicename>sio</devicename> driver used by other multiport - cards. Configuration is a simple matter of:</para> - - <procedure> - <step> - <para>Add the <devicename>cy</devicename> device to your - kernel configuration (note that your irq and iomem - settings may differ).</para> - - <programlisting>device cy0 at isa? irq 10 iomem 0xd4000 iosiz 0x2000</programlisting> - </step> - - <step> - <para>Rebuild and install the new kernel.</para> - </step> - - <step> - <para>Make the device nodes by typing (the following - example assumes an 8-port board)<footnote> - <para>You can omit this part if you are running FreeBSD 5.X - with &man.devfs.5;.</para> - </footnote>:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>for i in 0 1 2 3 4 5 6 7;do ./MAKEDEV cuac$i ttyc$i;done</userinput></screen> - </step> - - <step> - <para>If appropriate, add dialup entries to - <filename>/etc/ttys</filename> by duplicating serial - device (<literal>ttyd</literal>) entries and using - <literal>ttyc</literal> in place of - <literal>ttyd</literal>. For example:</para> - - <programlisting>ttyc0 "/usr/libexec/getty std.38400" unknown on insecure -ttyc1 "/usr/libexec/getty std.38400" unknown on insecure -ttyc2 "/usr/libexec/getty std.38400" unknown on insecure -… -ttyc7 "/usr/libexec/getty std.38400" unknown on insecure</programlisting> - </step> - - <step> - <para>Reboot with the new kernel.</para> - </step> - </procedure> - </sect1> - - <sect1> - <title>Configuring the <devicename>si</devicename> driver</title> - - <para><emphasis>Contributed by &a.nsayer;. 25 March - 1998.</emphasis></para> - - <para>The Specialix SI/XIO and SX multiport cards use the - <devicename>si</devicename> driver. A single machine can have - up to 4 host cards. The following host cards are - supported:</para> - - <itemizedlist> - <listitem><para>ISA SI/XIO host card (2 versions)</para></listitem> - <listitem><para>EISA SI/XIO host card</para></listitem> - <listitem><para>PCI SI/XIO host card</para></listitem> - <listitem><para>ISA SX host card</para></listitem> - <listitem><para>PCI SX host card</para></listitem> - </itemizedlist> - - <para>Although the SX and SI/XIO host cards look markedly - different, their functionality are basically the same. The - host cards do not use I/O locations, but instead require a 32K - chunk of memory. The factory configuration for ISA cards - places this at <literal>0xd0000-0xd7fff</literal>. They also - require an IRQ. PCI cards will, of course, auto-configure - themselves.</para> - - <para>You can attach up to 4 external modules to each host - card. The external modules contain either 4 or 8 serial - ports. They come in the following varieties:</para> - - <itemizedlist> - <listitem><para>SI 4 or 8 port modules. Up to 57600 bps on each port - supported.</para></listitem> - - <listitem><para>XIO 8 port modules. Up to 115200 bps on each port - supported. One type of XIO module has 7 serial and 1 parallel - port.</para></listitem> - - <listitem><para>SXDC 8 port modules. Up to 921600 bps on each port - supported. Like XIO, a module is available with one parallel - port as well.</para></listitem> - </itemizedlist> - - <para>To configure an ISA host card, add the following line to - your kernel configuration file, changing the numbers as - appropriate:</para> - - <programlisting>device si0 at isa? iomem 0xd0000 irq 11</programlisting> - - <para>Valid IRQ numbers are 9, 10, 11, 12 and 15 for SX ISA host - cards and 11, 12 and 15 for SI/XIO ISA host cards.</para> - - <para>To configure an EISA or PCI host card, use this line:</para> - - <programlisting>device si0</programlisting> - - <para>After adding the configuration entry, rebuild and - install your new kernel.</para> - - <note> - <para>The following step, is not necessary if you are using - &man.devfs.5; in FreeBSD 5.<replaceable>X</replaceable>.</para> - </note> - - <para>After rebooting with the new kernel, you need to make the - device nodes in <filename>/dev</filename>. The <filename>MAKEDEV</filename> script - will take care of this for you. Count how many total ports - you have and type:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV ttyA<replaceable>nn</replaceable> cuaA<replaceable>nn</replaceable></userinput></screen> - - <para>(where <replaceable>nn</replaceable> is the number of - ports)</para> - - <para>If you want login prompts to appear on these ports, you - will need to add lines like this to - <filename>/etc/ttys</filename>:</para> - - <programlisting>ttyA01 "/usr/libexec/getty std.9600" vt100 on insecure</programlisting> - - <para>Change the terminal type as appropriate. For modems, - <userinput>dialup</userinput> or - <userinput>unknown</userinput> is fine.</para> - - </sect1> - -</article> diff --git a/en_US.ISO8859-1/articles/solid-state/Makefile b/en_US.ISO8859-1/articles/solid-state/Makefile deleted file mode 100644 index 9dfb36fb9d..0000000000 --- a/en_US.ISO8859-1/articles/solid-state/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -# -# $FreeBSD$ -# -# Article: FreeBSD and Solid State Devices - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/solid-state/article.sgml b/en_US.ISO8859-1/articles/solid-state/article.sgml deleted file mode 100644 index cff6136296..0000000000 --- a/en_US.ISO8859-1/articles/solid-state/article.sgml +++ /dev/null @@ -1,635 +0,0 @@ -<!-- Copyright (c) 2001 The FreeBSD Documentation Project - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "AS - IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, - THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY - DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -<!ENTITY legalnotice SYSTEM "../../share/sgml/legalnotice.sgml"> -]> - -<article> - <articleinfo> - <title>FreeBSD and Solid State Devices</title> - - <authorgroup> - <author> - <firstname>John</firstname> - <surname>Kozubik</surname> - - <affiliation> - <address><email>john@kozubik.com</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - <copyright> - <year>2001</year> - <holder>The FreeBSD Documentation Project</holder> - </copyright> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.m-systems; - &tm-attrib.general; - </legalnotice> - - &legalnotice; - - <abstract> - <para>This article covers the use of solid state disk devices in FreeBSD - to create embedded systems.</para> - - <para>Embedded systems have the advantage of increased stability due to - the lack of integral moving parts (hard drives). Account must be - taken, however, for the generally low disk space available in the - system and the durability of the storage medium.</para> - - <para>Specific topics to be covered include the types and attributes of - solid state media suitable for disk use in FreeBSD, kernel options - that are of interest in such an environment, the - <filename>rc.diskless</filename> mechanisms that automate the - initialization of such systems and the need for read-only filesystems, - and building filesystems from scratch. The article will conclude - with some general strategies for small and read-only FreeBSD - environments.</para> - </abstract> - </articleinfo> - - <sect1 id="intro"> - <title>Solid State Disk Devices</title> - - <para>The scope of this article will be limited to solid state disk - devices made from flash memory. Flash memory is a solid state memory - (no moving parts) that is non-volatile (the memory maintains data even - after all power sources have been disconnected). Flash memory can - withstand tremendous physical shock and is reasonably fast (the flash - memory solutions covered in this article are slightly slower than a EIDE - hard disk for write operations, and much faster for read operations). - One very important aspect of flash memory, the ramifications of which - will be discussed later in this article, is that each sector has a - limited rewrite capacity. You can only write, erase, and write again to - a sector of flash memory a certain number of times before the sector - becomes permanently unusable. Although many flash memory products - automatically map bad blocks, and although some even distribute write - operations evenly throughout the unit, the fact remains that there - exists a limit to the amount of writing that can be done to the device. - Competitive units have between 1,000,000 and 10,000,000 writes per - sector in their specification. This figure varies due to the - temperature of the environment.</para> - - <para>Specifically, we will be discussing ATA compatible compact-flash - units and the M-Systems &diskonchip; flash memory unit. ATA compatible - compact-flash cards are quite popular as storage media for digital - cameras. Of particular interest is the fact that they pin out directly - to the IDE bus and are compatible with the ATA command set. Therefore, - with a very simple and low-cost adaptor, these devices can be attached - directly to an IDE bus in a computer. Once implemented in this manner, - operating systems such as FreeBSD see the device as a normal hard disk - (albeit small). The M-Systems &diskonchip; product is based on the same - underlying flash memory technology as ATA compatible compact-flash - cards, but resides in a DIP form factor and is not ATA compatible. To - use such a device, not only must you install it on a motherboard that - has a &diskonchip; socket, you must also build the `fla` driver into any - FreeBSD kernel you wish to use it with. Further, there is critical, - manufacturer-specific data residing in the boot sector of this device, - so you must take care not to install the FreeBSD (or any other) boot - loader when using this.</para> - - <para>Other solid state disk solutions do exist, but their expense, - obscurity, and relative unease of use places them beyond the scope of - this article.</para> - </sect1> - - <sect1 id="kernel"> - <title>Kernel Options</title> - - <para>A few kernel options are of specific interest to those creating - an embedded FreeBSD system.</para> - - <para>First, all embedded FreeBSD systems that use flash memory as system - disk will be interested in memory disks and memory filesystems. Because - of the limited number of writes that can be done to flash memory, the - disk and the filesystems on the disk will most likely be mounted - read-only. In this environment, filesystems such as - <filename>/tmp</filename> and <filename>/var</filename> are mounted as - memory filesystems to allow the system to create logs and update - counters and temporary files. Memory filesystems are a critical - component to a successful solid state FreeBSD implementation.</para> - - <para>You should make sure the following lines exist in your kernel - configuration file:</para> - - <programlisting>options MFS # Memory Filesystem -options MD_ROOT # md device usable as a potential root device -pseudo-device md # memory disk</programlisting> - - <para>Second, if you will be using the M-Systems &diskonchip; product, you - must also include this line:</para> - - <programlisting>device fla0 at isa?</programlisting> - </sect1> - - <sect1 id="ro-fs"> - <title><filename>rc.diskless</filename> and Read-Only Filesystems</title> - - <para>The post-boot initialization of an embedded FreeBSD system is - controlled by <filename>/etc/rc.diskless2</filename> - (<filename>/etc/rc.diskless1</filename> is for BOOTP diskless boot). - This initialization script is invoked by placing a line in - <filename>/etc/rc.conf</filename> as follows:</para> - - <programlisting>diskless_mount=/etc/rc.diskless2</programlisting> - - <para><filename>rc.diskless2</filename> mounts <filename>/var</filename> - as a memory filesystem, makes a configurable list of directories in - <filename>/var</filename> with the &man.mkdir.1; command, changes modes - on some of those directories, and extracts a list of device entries to - copy to a writable (again, a memory filesystem) - <filename>/dev</filename> partition. In the execution of - <filename>/etc/rc.diskless2</filename>, one other - <filename>rc.conf</filename> variable comes into play - - <literal>varsize</literal>. The <filename>/etc/rc.diskless2</filename> - file creates a <filename>/var</filename> partition based on the value of - this variable in <filename>rc.conf</filename>:</para> - - <programlisting>varsize=8192</programlisting> - - <para>Remember that this value is in sectors. The creation of the - <filename>/dev</filename> partition by - <filename>/etc/rc.diskless2</filename>, however, is governed by a - hard-coded value of 4096 sectors. It is trivial to change this entry in - the <filename>/etc/rc.diskless2</filename> file itself, although you - should not need more space than that for - <filename>/dev</filename>.</para> - - <para>It is important to remember that the - <filename>/etc/rc.diskless2</filename> script assumes that you have - already removed your conventional <filename>/tmp</filename> partition - and replaced it with a symbolic link to <filename>/var/tmp</filename>. - Because <filename>tmp</filename> is one of the directories created in - <filename>/var</filename> by the <filename>/etc/rc.diskless2</filename> - script, and because <filename>/var</filename> is a memory filesystem - (which is mounted read-write), <filename>/tmp</filename> will now be a - directory that is read-write as well.</para> - - <para>The fact that <filename>/var</filename> and - <filename>/dev</filename> are read-write filesystems is an important - distinction, as the <filename>/</filename> partition (and any other - partitions you may have on your flash media) should be mounted - read-only. Remember that in <xref linkend="intro"> we detailed the - limitations of flash memory - specifically the limited write capability. - The importance of not mounting filesystems on flash media read-write, - and the importance of not using a swap file, cannot be overstated. A - swap file on a busy system can burn through a piece of flash media in - less than one year. Heavy logging or temporary file creation and - destruction can do the same. Therefore, in addition to removing the - <literal>swap</literal> and <literal>/proc</literal> entries from your - <filename>/etc/fstab</filename> file, you should also change the Options - field for each filesystem to <literal>ro</literal> as follows:</para> - - <programlisting># Device Mountpoint FStype Options Dump Pass# -/dev/ad0s1a / ufs ro 1 1</programlisting> - - <para>A few applications in the average system will immediately begin to - fail as a result of this change. For instance, ports will not install - from the ports tree because the - <filename>/var/db/port.mkversion</filename> file does not exist. cron - will not run properly as a result of missing cron tabs in the - <filename>/var</filename> created by - <filename>/etc/rc.diskless2</filename>, and syslog and dhcp will - encounter problems as well as a result of the read-only filesystem and - missing items in the <filename>/var</filename> that - <filename>/etc/rc.diskless2</filename> has created. These are only - temporary problems though, and are addressed, along with solutions to - the execution of other common software packages in - <xref linkend="strategies">.</para> - - <para>An important thing to remember is that a filesystem that was mounted - read-only with <filename>/etc/fstab</filename> can be made read-write at - any time by issuing the command:</para> - - <screen>&prompt.root; <userinput>/sbin/mount -uw <replaceable>partition</replaceable></userinput></screen> - - <para>and can be toggled back to read-only with the command:</para> - - <screen>&prompt.root; <userinput>/sbin/mount -ur <replaceable>partition</replaceable></userinput></screen> - </sect1> - - <sect1> - <title>Building a File System From Scratch</title> - - <para>Because ATA compatible compact-flash cards are seen by FreeBSD as - normal IDE hard drives, as is a M-Systems &diskonchip; product (when you - are running a kernel with the fla driver built in) you could - theoretically install FreeBSD from the network using the kern and - mfsroot floppies or from a CD. Other than the fact that you should not - write a boot-loader of any kind to the M-Systems device, no special - instructions are needed.</para> - - <para>However, even a small installation of FreeBSD using normal - installation procedures can produce a system in size of greater than 200 - megabytes. Because most people will be using smaller flash memory - devices (128 megabytes is considered fairly large - 32 or even 16 - megabytes is common) an installation using normal mechanisms is not - possible—there is simply not enough disk space for even the - smallest of conventional installations.</para> - - <para>The easiest way to overcome this space limitation is to install - FreeBSD using conventional means to a normal hard disk. After the - installation is complete, pare down the operating system to a size that - will fit onto your flash media, then tar the entire filesystem. The - following steps will guide you through the process of preparing a piece - of flash memory for your tarred filesystem. Remember, because a normal - installation is not being performed, operations such as partitioning, - labeling, file-system creation, etc. need to be performed by hand. In - addition to the kern and mfsroot floppy disks, you will also need to use - the fixit floppy. If you are using a M-Systems &diskonchip;, the kernel - on your kern floppy must have the <literal>fla</literal> option detailed - in <xref linkend="kernel"> compiled into it. Please see - <xref linkend="kern.flp"> for instructions on creating a new kernel for - <filename>kern.flp</filename>.</para> - - <procedure> - <step> - <title>Partitioning your flash media device</title> - - <para>After booting with the kern and mfsroot floppies, choose - <literal>custom</literal> from the installation menu. In the custom - installation menu, choose <literal>partition</literal>. In the - partition menu, you should delete all existing partitions using the - <keycap>d</keycap> key. After deleting all existing partitions, - create a partition using the <keycap>c</keycap> key and accept the - default value for the size of the partition. When asked for the - type of the partition, make sure the value is set to - <literal>165</literal>. Now write this partition table to the disk - by pressing the <keycap>w</keycap> key (this is a hidden option on - this screen). When presented with a menu to choose a boot manager, - take care to select <literal>None</literal> if you are using an - M-Systems &diskonchip;. If you are using an ATA compatible compact - flash card, you should choose the FreeBSD Boot Manager. Now press - the <keycap>q</keycap> key to quit the partition menu. You will be - shown the boot manager menu once more - repeat the choice you made - earlier.</para> - </step> - - <step> - <title>Creating filesystems on your flash memory device</title> - - <para>Exit the custom installation menu, and from the main - installation menu choose the <literal>fixit</literal> option. After - entering the fixit environment, enter the following commands:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry align="center">ATA compatible</entry> - - <entry align="center">&diskonchip;</entry> - </row> - </thead> - <tbody> - <row> - <entry><para><screen>&prompt.root; <userinput>mknod /dev/ad0a c 116 0</userinput> -&prompt.root; <userinput>mknod /dev/ad0c c 116 2</userinput> -&prompt.root; <userinput>disklabel -e /dev/ad0c</userinput></screen></para></entry> - - <entry><para><screen>&prompt.root; <userinput>mknod /dev/fla0a c 102 0</userinput> -&prompt.root; <userinput>mknod /dev/fla0c c 102 2</userinput> -&prompt.root; <userinput>disklabel -e /dev/fla0c</userinput></screen></para></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>At this point you will have entered the vi editor under the - auspices of the disklabel command. If you are using &diskonchip;, - the first step will be to change the type value near the beginning - of the file from <literal>ESDI</literal> to - <literal>DOC2K</literal>. Next, regardless of whether you are using - &diskonchip; or ATA compatible compact flash media, you need to add - an <literal>a:</literal> line at the end of the file. This - <literal>a:</literal> line should look like:</para> - - <programlisting>a: <replaceable>123456</replaceable> 0 4.2BSD 0 0</programlisting> - - <para>Where <replaceable>123456</replaceable> is a number that is - exactly the same as the number in the existing <literal>c:</literal> - entry for size. Basically you are duplicating the existing - <literal>c:</literal> line as an <literal>a:</literal> line, making - sure that fstype is <literal>4.2BSD</literal>. Save the file and - exit.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry align="center">ATA compatible</entry> - - <entry align="center">&diskonchip;</entry> - </row> - </thead> - <tbody> - <row> - <entry><para><screen>&prompt.root; <userinput>disklabel -B -r /dev/ad0c</userinput> -&prompt.root; <userinput>newfs /dev/ad0a</userinput></screen></para></entry> - - <entry><para><screen>&prompt.root; <userinput>disklabel -B -r /dev/fla0c</userinput> -&prompt.root; <userinput>newfs /dev/fla0a</userinput></screen></para></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </step> - - <step> - <title>Placing your filesystem on the flash media</title> - - <para>Mount the newly prepared flash media:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry align="center">ATA compatible</entry> - - <entry align="center">&diskonchip;</entry> - </row> - </thead> - <tbody> - <row> - <entry><para><screen>&prompt.root; <userinput>mount /dev/ad0a /flash</userinput></screen></para></entry> - - <entry><para><screen>&prompt.root; <userinput>mount /dev/fla0a /flash</userinput></screen></para></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Bring this machine up on the network so we may transfer our tar - file and explode it onto our flash media filesystem. One example of - how to do this is:</para> - - <screen>&prompt.root; <userinput>ifconfig xl0 192.168.0.10 netmask 255.255.255.0</userinput> -&prompt.root; <userinput>route add default 192.168.0.1</userinput></screen> - - <para>Now that the machine is on the network, transfer your tar file. - You may be faced with a bit of a dilemma at this point - if your - flash memory part is 128 megabytes, for instance, and your tar file - is larger than 64 megabytes, you cannot have your tar file on the - flash media at the same time as you explode it - you will run out of - space. One solution to this problem, if you are using FTP, is to - untar the file while it is transferred over FTP. If you perform - your transfer in this manner, you will never have the tar file and - the tar contents on your disk at the same time:</para> - - <screen><prompt>ftp></prompt> <userinput>get tarfile.tar "| tar xvf -"</userinput></screen> - - <para>If your tarfile is gzipped, you can accomplish this as - well:</para> - - <screen><prompt>ftp></prompt> <userinput>get tarfile.tar "| zcat | tar xvf -"</userinput></screen> - - <para>After the contents of your tarred filesystem are on your flash - memory filesystem, you can unmount the flash memory and - reboot:</para> - - <screen>&prompt.root; <userinput>cd /</userinput> -&prompt.root; <userinput>umount /flash</userinput> -&prompt.root; <userinput>exit</userinput></screen> - - <para>Assuming that you configured your filesystem correctly when it - was built on the normal hard disk (with your filesystems mounted - read-only, and with the necessary options compiled into the kernel) - you should now be successfully booting your FreeBSD embedded - system.</para> - </step> - </procedure> - </sect1> - - <sect1 id="kern.flp"> - <title>Building a <filename>kern.flp</filename> Installation Floppy with - the fla Driver</title> - - <note> - <para>This section of the article is relevant only to those using - M-Systems &diskonchip; flash media.</para> - </note> - - <para>It is possible that your <filename>kern.flp</filename> boot floppy - does not have a kernel with the <devicename>fla</devicename> driver - compiled into it necessary for the system to recognize the &diskonchip;. - If you have booted off of the installation floppies and are told that no - disks are present, then you are probably lacking the - <devicename>fla</devicename> driver in your kernel.</para> - - <para>After you have built a kernel with <devicename>fla</devicename> - support that is smaller than 1.4 megabytes, you can create a custom - <filename>kern.flp</filename> floppy image with it by following these - instructions:</para> - - <procedure> - <step> - <para>Obtain an existing kern.flp image file</para> - </step> - - <step> - <para><screen>&prompt.root; <userinput>vnconfig vn0c kern.flp</userinput></screen></para> - </step> - - <step> - <para><screen>&prompt.root; <userinput>mount /dev/vn0c /mnt</userinput></screen></para> - </step> - - <step> - <para>Place your kernel file into <filename>/mnt</filename>, replacing - the existing one</para> - </step> - - <step> - <para><screen>&prompt.root; <userinput>vnconfig -d vn0c</userinput></screen></para> - </step> - </procedure> - - <para>Your <filename>kern.flp</filename> file now has your new kernel on it.</para> - </sect1> - - <sect1 id="strategies"> - <title>System Strategies for Small and Read Only Environments</title> - - <para>In <xref linkend="ro-fs">, it was pointed out that the - <filename>/var</filename> filesystem constructed by - <filename>/etc/rc.diskless2</filename> and the presence of a read-only - root filesystem causes problems with many common software packages used - with FreeBSD. In this article, suggestions for successfully running - cron, syslog, ports installations, and the Apache web server will be - provided.</para> - - <sect2> - <title>cron</title> - - <para>In <filename>/etc/rc.diskless2</filename> there is a variable - named <literal>var_dirs</literal>. This variable consists of a - space-delimited list of directories that will be created inside of - <filename>/var</filename> after it is mounted as a memory filesystem. - <filename>cron</filename> and <filename>cron/tabs</filename> are not - in that list, and without those directories, cron will complain. By - inserting <literal>cron</literal>, <literal>cron/tabs</literal>, and - perhaps even <literal>at</literal>, and <literal>at/jobs</literal> as - elements of that variable, you will facilitate the running of the - &man.cron.8; and &man.at.1; daemons.</para> - - <para>However, this still does not solve the problem of maintaining cron - tabs across reboots. When the system reboots, the - <filename>/var</filename> filesystem that is in memory will disappear - and any cron tabs you may have had in it will also disappear. - Therefore, one solution would be to create cron tabs for the users - that need them, mount your <filename>/</filename> filesystem as - read-write and copy those cron tabs to somewhere safe, like - <filename>/etc/tabs</filename>, then add a line to the end of - <filename>/etc/rc.diskless2</filename> that copies those crontabs into - <filename>/var/cron/tabs</filename> after that directory has been - created during system initialization. You may also need to add a line - that changes modes and permissions on the directories you create and - the files you copy with <filename>/etc/rc.diskless2</filename>.</para> - </sect2> - - <sect2> - <title>syslog</title> - - <para><filename>syslog.conf</filename> specifies the locations of - certain log files that exist in <filename>/var/log</filename>. These - files are not created by <filename>/etc/rc.diskless2</filename> upon - system initialization. Therefore, somewhere in - <filename>/etc/rc.diskless2</filename>, after the section that creates - the directories in <filename>/var</filename>, you will need to add - something like this:</para> - - <screen>&prompt.root; <userinput>touch /var/log/security /var/log/maillog /var/log/cron /var/log/messages</userinput> -&prompt.root; <userinput>chmod 0644 /var/log/*</userinput></screen> - - <para>You will also need to add the log directory to the list of - directories that <filename>/etc/rc.diskless2</filename> - creates.</para> - </sect2> - - <sect2> - <title>ports installation</title> - - <para>Before discussing the changes necessary to successfully use the - ports tree, a reminder is necessary regarding the read-only nature of - your filesystems on the flash media. Since they are read-only, you - will need to temporarily mount them read-write using the mount syntax - shown in <xref linkend="ro-fs">. You should always remount those - filesystems read-only when you are done with any maintenance - - unnecessary writes to the flash media could considerably shorten its - lifespan.</para> - - <para>To make it possible to enter a ports directory and successfully - run <command>make install</command>, it is necessary for the file - <filename>/var/db/port.mkversion</filename> to exist, and that it has - a correct date in it. Further, we must create a packages directory on - a non-memory filesystem that will keep track of our packages across - reboots. Because it is necessary to mount your filesystems as - read-write for the installation of a package anyway, it is sensible to - assume that an area on the flash media can also be used for package - information to be written to.</para> - - <para>First, create a package database directory. This is normally in - <filename>/var/db/pkg</filename>, but we cannot place it there as it - will disappear every time the system is booted.</para> - - <screen>&prompt.root; <userinput>mkdir /etc/pkg</userinput></screen> - - <para>Now, add a line to <filename>/etc/rc.diskless2</filename> that - links the <filename>/etc/pkg</filename> directory to - <filename>/var/db/pkg</filename>. An example:</para> - - <screen>&prompt.root; <userinput>ln -s /etc/pkg /var/db/pkg</userinput></screen> - - <para>Add another line in <filename>/etc/rc.diskless2</filename> that - creates and populates - <filename>/var/db/port.mkversion</filename></para> - - <screen>&prompt.root; <userinput>touch /var/db/port.mkversion</userinput> -&prompt.root; <userinput>chmod 0644 /var/db/port.mkversion</userinput> -&prompt.root; <userinput>echo <replaceable>20010412</replaceable> >> /var/db/port.mkversion</userinput></screen> - - <para>where <replaceable>20010412</replaceable> is a date that is - appropriate for your particular release of FreeBSD</para> - - <para>Now, any time that you mount your filesystems as read-write and - install a package, the <command>make install</command> will work - because it finds a suitable - <filename>/var/db/port.mkversion</filename>, and package information - will be written successfully to <filename>/etc/pkg</filename> (because - the filesystem will, at that time, be mounted read-write) which will - always be available to the operating system as - <filename>/var/db/pkg</filename>.</para> - </sect2> - - <sect2> - <title>Apache Web Server</title> - - <para>Apache keeps pid files and logs in - <filename><replaceable>apache_install</replaceable>/logs</filename>. - Since this directory doubtless exists on a read-only filesystem, this - will not work. It is necessary to add a new directory to the - <filename>/etc/rc.diskless2</filename> list of directories to create - in <filename>/var</filename>, to link - <filename><replaceable>apache_install</replaceable>/logs</filename> to - <filename>/var/log/apache</filename>. It is also necessary to set - permissions and ownership on this new directory.</para> - - <para>First, add the directory <literal>log/apache</literal> to the list - of directories to be created in - <filename>/etc/rc.diskless2</filename>.</para> - - <para>Second, add these commands to - <filename>/etc/rc.diskless2</filename> after the directory creation - section:</para> - - <screen>&prompt.root; <userinput>chmod 0774 /var/log/apache</userinput> -&prompt.root; <userinput>chown nobody:nobody /var/log/apache</userinput></screen> - - <para>Finally, remove the existing - <filename><replaceable>apache_install</replaceable>/logs</filename> - directory, and replace it with a link:</para> - - <screen>&prompt.root; <userinput>rm -rf (apache_install)/logs</userinput> -&prompt.root; <userinput>ln -s /var/log/apache (apache_install)/logs</userinput></screen> - </sect2> - </sect1> -</article> - diff --git a/en_US.ISO8859-1/articles/storage-devices/Makefile b/en_US.ISO8859-1/articles/storage-devices/Makefile deleted file mode 100644 index 0439a4f4a3..0000000000 --- a/en_US.ISO8859-1/articles/storage-devices/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Storage Devices - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/storage-devices/article.sgml b/en_US.ISO8859-1/articles/storage-devices/article.sgml deleted file mode 100644 index 8f8577925f..0000000000 --- a/en_US.ISO8859-1/articles/storage-devices/article.sgml +++ /dev/null @@ -1,2643 +0,0 @@ -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Storage Devices</title> - - <authorgroup> - <author> - <firstname>Wilko</firstname> - <surname>Bulte</surname> - - <affiliation> - <address><email>wilko@FreeBSD.org</email></address> - </affiliation> - </author> - </authorgroup> - - <pubdate>$FreeBSD$</pubdate> - - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>This article talks about storage devices with FreeBSD.</para> - </abstract> - </articleinfo> - - <sect1 id="esdi"> - <title>Using ESDI hard disks</title> - - <para><emphasis>Copyright © 1995, &a.wilko;. 24 September - 1995.</emphasis></para> - - <para>ESDI is an acronym that means Enhanced Small Device - Interface. It is loosely based on the good old ST506/412 - interface originally devised by Seagate Technology, the makers - of the first affordable 5.25" winchester disk.</para> - - <para>The acronym says Enhanced, and rightly so. In the first - place the speed of the interface is higher, 10 or 15 - Mbits/second instead of the 5 Mbits/second of ST412 interfaced - drives. Secondly some higher level commands are added, making - the ESDI interface somewhat <quote>smarter</quote> to the operating system - driver writers. It is by no means as smart as SCSI by the way. - ESDI is standardized by ANSI.</para> - - <para>Capacities of the drives are boosted by putting more sectors - on each track. Typical is 35 sectors per track, high capacity - drives I have seen were up to 54 sectors/track.</para> - - <para>Although ESDI has been largely obsoleted by IDE and SCSI - interfaces, the availability of free or cheap surplus drives - makes them ideal for low (or now) budget systems.</para> - - <sect2> - <title>Concepts of ESDI</title> - - <sect3> - <title>Physical connections</title> - - <para>The ESDI interface uses two cables connected to each drive. - One cable is a 34 pin flat cable edge connector that carries the - command and status signals from the controller to the drive and - vice-versa. The command cable is daisy chained between all the - drives. So, it forms a bus onto which all drives are - connected.</para> - - <para>The second cable is a 20 pin flat cable edge connector that - carries the data to and from the drive. This cable is radially - connected, so each drive has its own direct connection to the - controller.</para> - - <para>To the best of my knowledge PC ESDI controllers are limited to - using a maximum of 2 drives per controller. This is compatibility - feature(?) left over from the WD1003 standard that reserves only a - single bit for device addressing.</para> - </sect3> - - <sect3> - <title>Device addressing</title> - - <para>On each command cable a maximum of 7 devices and 1 controller - can be present. To enable the controller to uniquely identify - which drive it addresses, each ESDI device is equipped with - jumpers or switches to select the devices address.</para> - - <para>On PC type controllers the first drive is set to address 0, - the second disk to address 1. <emphasis>Always make - sure</emphasis> you set each disk to an unique address! So, on a - PC with its two drives/controller maximum the first drive is drive - 0, the second is drive 1.</para> - </sect3> - - <sect3> - <title>Termination</title> - - <para>The daisy chained command cable (the 34 pin cable remember?) - needs to be terminated at the last drive on the chain. For this - purpose ESDI drives come with a termination resistor network that - can be removed or disabled by a jumper when it is not used.</para> - - <para>So, one and <emphasis>only</emphasis> one drive, the one at - the farthest end of the command cable has its terminator - installed/enabled. The controller automatically terminates the - other end of the cable. Please note that this implies that the - controller must be at one end of the cable and - <emphasis>not</emphasis> in the middle.</para> - </sect3> - </sect2> - - <sect2> - <title>Using ESDI disks with FreeBSD</title> - - <para>Why is ESDI such a pain to get working in the first - place?</para> - - <para>People who tried ESDI disks with FreeBSD are known to have - developed a profound sense of frustration. A combination of factors - works against you to produce effects that are hard to understand - when you have never seen them before.</para> - - <para>This has also led to the popular legend ESDI and FreeBSD is a - plain NO-GO. The following sections try to list all the pitfalls - and solutions.</para> - - <sect3> - <title>ESDI speed variants</title> - - <para>As briefly mentioned before, ESDI comes in two speed flavors. - The older drives and controllers use a 10 Mbits/second data - transfer rate. Newer stuff uses 15 Mbits/second.</para> - - <para>It is not hard to imagine that 15 Mbits/second drive cause - problems on controllers laid out for 10 Mbits/second. As always, - consult your controller <emphasis>and</emphasis> drive - documentation to see if things match.</para> - </sect3> - - <sect3> - <title>Stay on track</title> - - <para>Mainstream ESDI drives use 34 to 36 sectors per track. Most - (older) controllers cannot handle more than this number of - sectors. Newer, higher capacity, drives use higher numbers of - sectors per track. For instance, I own a 670 MB drive that has 54 - sectors per track.</para> - - <para>In my case, the controller could not handle this number of - sectors. It proved to work well except that it only used 35 - sectors on each track. This meant losing a lot of disk - space.</para> - - <para>Once again, check the documentation of your hardware for more - info. Going out-of-spec like in the example might or might not - work. Give it a try or get another more capable - controller.</para> - </sect3> - - <sect3> - <title>Hard or soft sectoring</title> - - <para>Most ESDI drives allow hard or soft sectoring to be selected - using a jumper. Hard sectoring means that the drive will produce - a sector pulse on the start of each new sector. The controller - uses this pulse to tell when it should start to write or - read.</para> - - <para>Hard sectoring allows a selection of sector size (normally - 256, 512 or 1024 bytes per formatted sector). FreeBSD uses 512 - byte sectors. The number of sectors per track also varies while - still using the same number of bytes per formatted sector. The - number of <emphasis>unformatted</emphasis> bytes per sector - varies, dependent on your controller it needs more or less - overhead bytes to work correctly. Pushing more sectors on a - track of course gives you more usable space, but might give - problems if your controller needs more bytes than the drive - offers.</para> - - <para>In case of soft sectoring, the controller itself determines - where to start/stop reading or writing. For ESDI hard sectoring - is the default (at least on everything I came across). I never - felt the urge to try soft sectoring.</para> - - <para>In general, experiment with sector settings before you install - FreeBSD because you need to re-run the low-level format after each - change.</para> - </sect3> - - <sect3> - <title>Low level formatting</title> - - <para>ESDI drives need to be low level formatted before they are - usable. A reformat is needed whenever you figgle with the number - of sectors/track jumpers or the physical orientation of the drive - (horizontal, vertical). So, first think, then format. The format - time must not be underestimated, for big disks it can take - hours.</para> - - <para>After a low level format, a surface scan is done to find and - flag bad sectors. Most disks have a manufacturer bad block list - listed on a piece of paper or adhesive sticker. In addition, on - most disks the list is also written onto the disk. Please use the - manufacturer's list. It is much easier to remap a defect now than - after FreeBSD is installed.</para> - - <para>Stay away from low-level formatters that mark all sectors of a - track as bad as soon as they find one bad sector. Not only does - this waste space, it also and more importantly causes you grief - with bad144 (see the section on bad144).</para> - </sect3> - - <sect3> - <title>Translations</title> - - <para>Translations, although not exclusively a ESDI-only problem, - might give you real trouble. Translations come in multiple - flavors. Most of them have in common that they attempt to work - around the limitations posed upon disk geometries by the original - IBM PC/AT design (thanks IBM!).</para> - - <para>First of all there is the (in)famous 1024 cylinder limit. For - a system to be able to boot, the stuff (whatever operating system) - must be in the first 1024 cylinders of a disk. Only 10 bits are - available to encode the cylinder number. For the number of - sectors the limit is 64 (0-63). When you combine the 1024 - cylinder limit with the 16 head limit (also a design feature) you - max out at fairly limited disk sizes.</para> - - <para>To work around this problem, the manufacturers of ESDI PC - controllers added a BIOS prom extension on their boards. This - BIOS extension handles disk I/O for booting (and for some - operating systems <emphasis>all</emphasis> disk I/O) by using - translation. For instance, a big drive might be presented to the - system as having 32 heads and 64 sectors/track. The result is - that the number of cylinders is reduced to something below 1024 - and is therefore usable by the system without problems. It is - noteworthy to know that FreeBSD does not use the BIOS after its - kernel has started. More on this later.</para> - - <para>A second reason for translations is the fact that most older - system BIOSes could only handle drives with 17 sectors per track - (the old ST412 standard). Newer system BIOSes usually have a - user-defined drive type (in most cases this is drive type - 47).</para> - - <warning> - <para>Whatever you do to translations after reading this document, - keep in mind that if you have multiple operating systems on the - same disk, all must use the same translation</para> - </warning> - - <para>While on the subject of translations, I have seen one - controller type (but there are probably more like this) offer the - option to logically split a drive in multiple partitions as a BIOS - option. I had select 1 drive == 1 partition because this - controller wrote this info onto the disk. On power-up it read the - info and presented itself to the system based on the info from the - disk.</para> - </sect3> - - <sect3> - <title>Spare sectoring</title> - - <para>Most ESDI controllers offer the possibility to remap bad - sectors. During/after the low-level format of the disk bad - sectors are marked as such, and a replacement sector is put in - place (logically of course) of the bad one.</para> - - <para>In most cases the remapping is done by using N-1 sectors on - each track for actual data storage, and sector N itself is the - spare sector. N is the total number of sectors physically - available on the track. The idea behind this is that the - operating system sees a <quote>perfect</quote> disk without bad sectors. In - the case of FreeBSD this concept is not usable.</para> - - <para>The problem is that the translation from - <emphasis>bad</emphasis> to <emphasis>good</emphasis> is performed - by the BIOS of the ESDI controller. FreeBSD, being a true 32 bit - operating system, does not use the BIOS after it has been booted. - Instead, it has device drivers that talk directly to the - hardware.</para> - - <para><emphasis>So: do not use spare sectoring, bad block remapping - or whatever it may be called by the controller manufacturer when - you want to use the disk for FreeBSD.</emphasis></para> - </sect3> - - <sect3> - <title>Bad block handling</title> - - <para>The preceding section leaves us with a problem. The - controller's bad block handling is not usable and still FreeBSD's - filesystems assume perfect media without any flaws. To solve this - problem, FreeBSD use the <command>bad144</command> tool. Bad144 - (named after a Digital Equipment standard for bad block handling) - scans a FreeBSD slice for bad blocks. Having found these bad - blocks, it writes a table with the offending block numbers to the - end of the FreeBSD slice.</para> - - <para>When the disk is in operation, the disk accesses are checked - against the table read from the disk. Whenever a block number is - requested that is in the <command>bad144</command> list, a - replacement block (also from the end of the FreeBSD slice) is - used. In this way, the <command>bad144</command> replacement - scheme presents <quote>perfect</quote> media to the FreeBSD filesystems.</para> - - <para>There are a number of potential pitfalls associated with the - use of <command>bad144</command>. First of all, the slice cannot - have more than 126 bad sectors. If your drive has a high number - of bad sectors, you might need to divide it into multiple FreeBSD - slices each containing less than 126 bad sectors. Stay away from - low-level format programs that mark <emphasis>every</emphasis> - sector of a track as bad when they find a flaw on the track. As - you can imagine, the 126 limit is quickly reached when the - low-level format is done this way.</para> - - <para>Second, if the slice contains the root filesystem, the slice - should be within the 1024 cylinder BIOS limit. During the boot - process the bad144 list is read using the BIOS and this only - succeeds when the list is within the 1024 cylinder limit.</para> - - <note> - <para>The restriction is not that only the root - <emphasis>filesystem</emphasis> must be within the 1024 cylinder - limit, but rather the entire <emphasis>slice</emphasis> that - contains the root filesystem.</para> - </note> - </sect3> - - <sect3> - <title>Kernel configuration</title> - - <para>ESDI disks are handled by the same <literal>wd</literal>driver - as IDE and ST412 MFM disks. The <literal>wd</literal> driver - should work for all WD1003 compatible interfaces.</para> - - <para>Most hardware is jumperable for one of two different I/O - address ranges and IRQ lines. This allows you to have two wd - type controllers in one system.</para> - - <para>When your hardware allows non-standard strappings, you can use - these with FreeBSD as long as you enter the correct info into the - kernel config file. An example from the kernel config file (they - live in <filename>/sys/i386/conf</filename> BTW).</para> - - <programlisting># First WD compatible controller -controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr -disk wd0 at wdc0 drive 0 -disk wd1 at wdc0 drive 1 -# Second WD compatible controller -controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr -disk wd2 at wdc1 drive 0 -disk wd3 at wdc1 drive 1</programlisting> - </sect3> - </sect2> - - <sect2> - <title>Particulars on ESDI hardware</title> - - <sect3> - <title>Adaptec 2320 controllers</title> - - <para>I successfully installed FreeBSD onto a ESDI disk controlled - by a ACB-2320. No other operating system was present on the - disk.</para> - - <para>To do so I low level formatted the disk using - <command>NEFMT.EXE</command> (<command>ftp</command>able from - <hostid role="fqdn">www.adaptec.com</hostid>) and answered NO to - the question whether the disk should be formatted with a spare - sector on each track. The BIOS on the ACD-2320 was disabled. I - used the <literal>free configurable</literal> option in the system - BIOS to allow the BIOS to boot it.</para> - - <para>Before using <command>NEFMT.EXE</command> I tried to format - the disk using the ACB-2320 BIOS built-in formatter. This proved - to be a show stopper, because it did not give me an option to - disable spare sectoring. With spare sectoring enabled the FreeBSD - installation process broke down on the <command>bad144</command> - run.</para> - - <para>Please check carefully which - ACB-232<replaceable>xy</replaceable> variant you have. The - <replaceable>x</replaceable> is either <literal>0</literal> or - <literal>2</literal>, indicating a controller without or with a - floppy controller on board.</para> - - <para>The <literal>y</literal> is more interesting. It can either - be a blank, a <literal>A-8</literal> or a <literal>D</literal>. A - blank indicates a plain 10 Mbits/second controller. An - <literal>A-8</literal> indicates a 15 Mbits/second controller - capable of handling 52 sectors/track. A <literal>D</literal> - means a 15 Mbits/second controller that can also handle drives - with > 36 sectors/track (also 52?).</para> - - <para>All variations should be capable of using 1:1 interleaving. - Use 1:1, FreeBSD is fast enough to handle it.</para> - </sect3> - - <sect3> - <title>Western Digital WD1007 controllers</title> - - <para>I successfully installed FreeBSD onto a ESDI disk controlled - by a WD1007 controller. To be precise, it was a WD1007-WA2. - Other variations of the WD1007 do exist.</para> - - <para>To get it to work, I had to disable the sector translation and - the WD1007's onboard BIOS. This implied I could not use the - low-level formatter built into this BIOS. Instead, I grabbed - <command>WDFMT.EXE</command> from <hostid - role="fqdn">www.wdc.com</hostid> Running this formatted my drive - just fine.</para> - </sect3> - - <sect3> - <title>Ultrastor U14F controllers</title> - - <para>According to multiple reports from the net, Ultrastor ESDI - boards work OK with FreeBSD. I lack any further info on - particular settings.</para> - </sect3> - </sect2> - - <sect2 id="esdi-further-reading"> - <title>Further reading</title> - - <para>If you intend to do some serious ESDI hacking, you might want to - have the official standard at hand:</para> - - <para>The latest ANSI X3T10 committee document is: Enhanced Small - Device Interface (ESDI) [X3.170-1990/X3.170a-1991] [X3T10/792D - Rev 11]</para> - - <para>On Usenet the newsgroup <ulink - url="news:comp.periphs">comp.periphs</ulink> is a noteworthy place - to look for more info.</para> - - <para>The World Wide Web (WWW) also proves to be a very handy info - source: For info on Adaptec ESDI controllers see <ulink - url="http://www.adaptec.com/"></ulink>. For - info on Western Digital controllers see - <ulink url="http://www.wdc.com/"></ulink>.</para> - </sect2> - - <sect2> - <title>Thanks to...</title> - - <para>Andrew Gordon for sending me an Adaptec 2320 controller and ESDI - disk for testing.</para> - </sect2> - </sect1> - - <sect1 id="scsi"> - <title>What is SCSI?</title> - - <para><emphasis>Copyright © 1995, &a.wilko;. July 6, - 1996.</emphasis></para> - - <para>SCSI is an acronym for Small Computer Systems Interface. It is an - ANSI standard that has become one of the leading I/O buses in the - computer industry. The foundation of the SCSI standard was laid by - Shugart Associates (the same guys that gave the world the first mini - floppy disks) when they introduced the SASI bus (Shugart Associates - Standard Interface).</para> - - <para>After some time an industry effort was started to come to a more - strict standard allowing devices from different vendors to work - together. This effort was recognized in the ANSI SCSI-1 standard. - The SCSI-1 standard (approximately 1985) is rapidly becoming obsolete. The - current standard is SCSI-2 (see <link - linkend="scsi-further-reading">Further reading</link>), with SCSI-3 - on the drawing boards.</para> - - <para>In addition to a physical interconnection standard, SCSI defines a - logical (command set) standard to which disk devices must adhere. - This standard is called the Common Command Set (CCS) and was developed - more or less in parallel with ANSI SCSI-1. SCSI-2 includes the - (revised) CCS as part of the standard itself. The commands are - dependent on the type of device at hand. It does not make much sense - of course to define a Write command for a scanner.</para> - - <para>The SCSI bus is a parallel bus, which comes in a number of - variants. The oldest and most used is an 8 bit wide bus, with - single-ended signals, carried on 50 wires. (If you do not know what - single-ended means, do not worry, that is what this document is all - about.) Modern designs also use 16 bit wide buses, with differential - signals. This allows transfer speeds of 20Mbytes/second, on cables - lengths of up to 25 meters. SCSI-2 allows a maximum bus width of 32 - bits, using an additional cable. Quickly emerging are Ultra SCSI (also - called Fast-20) and Ultra2 (also called Fast-40). Fast-20 is 20 - million transfers per second (20 Mbytes/sec on a 8 bit bus), Fast-40 - is 40 million transfers per second (40 Mbytes/sec on a 8 bit bus). - Most hard drives sold today are single-ended Ultra SCSI (8 or 16 - bits).</para> - - <para>Of course the SCSI bus not only has data lines, but also a number - of control signals. A very elaborate protocol is part of the standard - to allow multiple devices to share the bus in an efficient manner. In - SCSI-2, the data is always checked using a separate parity line. In - pre-SCSI-2 designs parity was optional.</para> - - <para>In SCSI-3 even faster bus types are introduced, along with a - serial SCSI busses that reduces the cabling overhead and allows a - higher maximum bus length. You might see names like SSA and - fibre channel in this context. None of the serial buses are currently - in widespread use (especially not in the typical FreeBSD environment). - For this reason the serial bus types are not discussed any - further.</para> - - <para>As you could have guessed from the description above, SCSI devices - are intelligent. They have to be to adhere to the SCSI standard - (which is over 2 inches thick BTW). So, for a hard disk drive for - instance you do not specify a head/cylinder/sector to address a - particular block, but simply the number of the block you want. - Elaborate caching schemes, automatic bad block replacement etc are all - made possible by this <quote>intelligent device</quote> approach.</para> - - <para>On a SCSI bus, each possible pair of devices can communicate. - Whether their function allows this is another matter, but the standard - does not restrict it. To avoid signal contention, the 2 devices have - to arbitrate for the bus before using it.</para> - - <para>The philosophy of SCSI is to have a standard that allows - older-standard devices to work with newer-standard ones. So, an old - SCSI-1 device should normally work on a SCSI-2 bus. I say Normally, - because it is not absolutely sure that the implementation of an old - device follows the (old) standard closely enough to be acceptable on a - new bus. Modern devices are usually more well-behaved, because the - standardization has become more strict and is better adhered to by the - device manufacturers.</para> - - <para>Generally speaking, the chances of getting a working set of - devices on a single bus is better when all the devices are SCSI-2 or - newer. This implies that you do not have to dump all your old stuff - when you get that shiny 80GB disk: I own a system on which a pre-SCSI-1 - disk, a SCSI-2 QIC tape unit, a SCSI-1 helical scan tape unit and 2 - SCSI-1 disks work together quite happily. From a performance - standpoint you might want to separate your older and newer (=faster) - devices however. This is especially advantageous if you have an - Ultra160 host adapter where you should separate your U160 devices - from the Fast and Wide SCSI-2 devices.</para> - - <sect2> - <title>Components of SCSI</title> - - <para>As said before, SCSI devices are smart. The idea is to put the - knowledge about intimate hardware details onto the SCSI device - itself. In this way, the host system does not have to worry about - things like how many heads a hard disks has, or how many tracks - there are on a specific tape device. If you are curious, the - standard specifies commands with which you can query your devices on - their hardware particulars. FreeBSD uses this capability during - boot to check out what devices are connected and whether they need - any special treatment.</para> - - <para>The advantage of intelligent devices is obvious: the device - drivers on the host can be made in a much more generic fashion, - there is no longer a need to change (and qualify!) drivers for every - odd new device that is introduced.</para> - - <para>For cabling and connectors there is a golden rule: get good - stuff. With bus speeds going up all the time you will save yourself - a lot of grief by using good material.</para> - - <para>So, gold plated connectors, shielded cabling, sturdy connector - hoods with strain reliefs etc are the way to go. Second golden rule: - do no use cables longer than necessary. I once spent 3 days hunting - down a problem with a flaky machine only to discover that shortening - the SCSI bus by 1 meter solved the problem. And the original bus - length was well within the SCSI specification.</para> - </sect2> - - <sect2> - <title>SCSI bus types</title> - - <para>From an electrical point of view, there are two incompatible bus - types: single-ended and differential. This means that there are two - different main groups of SCSI devices and controllers, which cannot - be mixed on the same bus. It is possible however to use special - converter hardware to transform a single-ended bus into a - differential one (and vice versa). The differences between the bus - types are explained in the next sections.</para> - - <para>In lots of SCSI related documentation there is a sort of jargon - in use to abbreviate the different bus types. A small list:</para> - - <itemizedlist> - <listitem> - <para>FWD: Fast Wide Differential</para> - </listitem> - - <listitem> - <para>FND: Fast Narrow Differential</para> - </listitem> - - <listitem> - <para>SE: Single Ended</para> - </listitem> - - <listitem> - <para>FN: Fast Narrow</para> - </listitem> - - <listitem> - <para>etc.</para> - </listitem> - </itemizedlist> - - - <para>With a minor amount of imagination one can usually imagine what - is meant.</para> - - <para>Wide is a bit ambiguous, it can indicate 16 or 32 bit buses. As - far as I know, the 32 bit variant is not (yet) in use, so wide - normally means 16 bit.</para> - - <para>Fast means that the timing on the bus is somewhat different, so - that on a narrow (8 bit) bus 10 Mbytes/sec are possible instead of 5 - Mbytes/sec for <quote>slow</quote> SCSI. As discussed before, bus speeds of 20 - and 40 million transfers/second are also emerging (Fast-20 == Ultra - SCSI and Fast-40 == Ultra2 SCSI).</para> - - <note> - <para>The data lines > 8 are only used for data transfers and - device addressing. The transfers of commands and status messages - etc are only performed on the lowest 8 data lines. The standard - allows narrow devices to operate on a wide bus. The usable bus - width is negotiated between the devices. You have to watch your - device addressing closely when mixing wide and narrow.</para> - </note> - - <sect3> - <title>Single ended buses</title> - - <para>A single-ended SCSI bus uses signals that are either 5 Volts - or 0 Volts (indeed, TTL levels) and are relative to a COMMON - ground reference. A singled ended 8 bit SCSI bus has - approximately 25 ground lines, who are all tied to a single <quote>rail</quote> - on all devices. A standard single ended bus has a maximum length - of 6 meters. If the same bus is used with fast-SCSI devices, the - maximum length allowed drops to 3 meters. Fast-SCSI means that - instead of 5Mbytes/sec the bus allows 10Mbytes/sec - transfers.</para> - - <para>Fast-20 (Ultra SCSI) and Fast-40 allow for 20 and 40 million - transfers/second respectively. So, F20 is 20 Mbytes/second on a 8 - bit bus, 40 Mbytes/second on a 16 bit bus etc. For F20 the max - bus length is 1.5 meters, for F40 it becomes 0.75 meters. Be - aware that F20 is pushing the limits quite a bit, so you will - quickly find out if your SCSI bus is electrically sound.</para> - - <note> - <para>If some devices on your bus use <quote>fast</quote> to communicate your - bus must adhere to the length restrictions for fast - buses!</para> - </note> - - <para>It is obvious that with the newer fast-SCSI devices the bus - length can become a real bottleneck. This is why the differential - SCSI bus was introduced in the SCSI-2 standard.</para> - - <para>For connector pinning and connector types please refer to the - SCSI-2 standard (see <link linkend="scsi-further-reading">Further - reading</link>) itself, connectors etc are listed there in - painstaking detail.</para> - - <para>Beware of devices using non-standard cabling. For instance - Apple uses a 25pin D-type connecter (like the one on serial ports - and parallel printers). Considering that the official SCSI bus - needs 50 pins you can imagine the use of this connector needs some - <quote>creative cabling</quote>. The reduction of the number of ground wires - they used is a bad idea, you better stick to 50 pins cabling in - accordance with the SCSI standard. For Fast-20 and 40 do not even - think about buses like this.</para> - </sect3> - - <sect3> - <title>Differential buses</title> - - <para>A differential SCSI bus has a maximum length of 25 meters. - Quite a difference from the 3 meters for a single-ended fast-SCSI - bus. The idea behind differential signals is that each bus signal - has its own return wire. So, each signal is carried on a - (preferably twisted) pair of wires. The voltage difference - between these two wires determines whether the signal is asserted - or de-asserted. To a certain extent the voltage difference - between ground and the signal wire pair is not relevant (do not - try 10 kVolts though).</para> - - <para>It is beyond the scope of this document to explain why this - differential idea is so much better. Just accept that - electrically seen the use of differential signals gives a much - better noise margin. You will normally find differential buses in - use for inter-cabinet connections. Because of the lower cost - single ended is mostly used for shorter buses like inside - cabinets.</para> - - <para>There is nothing that stops you from using differential stuff - with FreeBSD, as long as you use a controller that has device - driver support in FreeBSD. As an example, Adaptec marketed the - AHA1740 as a single ended board, whereas the AHA1744 was - differential. The software interface to the host is identical for - both.</para> - </sect3> - - <sect3> - <title>Terminators</title> - - <para>Terminators in SCSI terminology are resistor networks that are - used to get a correct impedance matching. Impedance matching is - important to get clean signals on the bus, without reflections or - ringing. If you once made a long distance telephone call on a bad - line you probably know what reflections are. With 20Mbytes/sec - traveling over your SCSI bus, you do not want signals echoing - back.</para> - - <para>Terminators come in various incarnations, with more or less - sophisticated designs. Of course, there are internal and external - variants. Many SCSI devices come with a number of sockets in - which a number of resistor networks can (must be!) installed. If - you remove terminators from a device, carefully store them. You - will need them when you ever decide to reconfigure your SCSI bus. - There is enough variation in even these simple tiny things to make - finding the exact replacement a frustrating business. There are - also SCSI devices that have a single jumper to enable or disable a - built-in terminator. There are special terminators you can stick - onto a flat cable bus. Others look like external connectors, or a - connector hood without a cable. So, lots of choice as you can - see.</para> - - <para>There is much debate going on if and when you should switch - from simple resistor (passive) terminators to active terminators. - Active terminators contain slightly more elaborate circuit to give - cleaner bus signals. The general consensus seems to be that the - usefulness of active termination increases when you have long - buses and/or fast devices. If you ever have problems with your - SCSI buses you might consider trying an active terminator. Try to - borrow one first, they reputedly are quite expensive.</para> - - <para>Please keep in mind that terminators for differential and - single-ended buses are not identical. You should <emphasis>not - mix</emphasis> the two variants.</para> - - <para>OK, and now where should you install your terminators? This is - by far the most misunderstood part of SCSI. And it is by far the - simplest. The rule is: <emphasis>every single line on the SCSI - bus has 2 (two) terminators, one at each end of the - bus.</emphasis> So, two and not one or three or whatever. Do - yourself a favor and stick to this rule. It will save you endless - grief, because wrong termination has the potential to introduce - highly mysterious bugs. (Note the <quote>potential</quote> here; - the nastiest part is that it may or may not work.)</para> - - <para>A common pitfall is to have an internal (flat) cable in a - machine and also an external cable attached to the controller. It - seems almost everybody forgets to remove the terminators from the - controller. The terminator must now be on the last external - device, and not on the controller! In general, every - reconfiguration of a SCSI bus must pay attention to this.</para> - - <note> - <para>Termination is to be done on a per-line basis. This means - if you have both narrow and wide buses connected to the same - host adapter, you need to enable termination on the higher 8 - bits of the bus on the adapter (as well as the last devices on - each bus, of course).</para> - </note> - - <para>What I did myself is remove all terminators from my SCSI - devices and controllers. I own a couple of external terminators, - for both the Centronics-type external cabling and for the internal - flat cable connectors. This makes reconfiguration much - easier.</para> - - <para>On modern devices, sometimes integrated terminators are used. - These things are special purpose integrated circuits that can be - enabled or disabled with a control pin. It is not necessary to - physically remove them from a device. You may find them on newer - host adapters, sometimes they are software configurable, using - some sort of setup tool. Some will even auto-detect the cables - attached to the connectors and automatically set up the - termination as necessary. At any rate, consult your - documentation!</para> - </sect3> - - <sect3> - <title>Terminator power</title> - - <para>The terminators discussed in the previous chapter need power - to operate properly. On the SCSI bus, a line is dedicated to this - purpose. So, simple huh?</para> - - <para>Not so. Each device can provide its own terminator power to - the terminator sockets it has on-device. But if you have external - terminators, or when the device supplying the terminator power to - the SCSI bus line is switched off you are in trouble.</para> - - <para>The idea is that initiators (these are devices that initiate - actions on the bus, a discussion follows) must supply terminator - power. All SCSI devices are allowed (but not required) to supply - terminator power.</para> - - <para>To allow for un-powered devices on a bus, the terminator power - must be supplied to the bus via a diode. This prevents the - backflow of current to un-powered devices.</para> - - <para>To prevent all kinds of nastiness, the terminator power is - usually fused. As you can imagine, fuses might blow. This can, - but does not have to, lead to a non functional bus. If multiple - devices supply terminator power, a single blown fuse will not put - you out of business. A single supplier with a blown fuse - certainly will. Clever external terminators sometimes have a LED - indication that shows whether terminator power is present.</para> - - <para>In newer designs auto-restoring fuses that <quote>reset</quote> themselves - after some time are sometimes used.</para> - </sect3> - - <sect3> - <title>Device addressing</title> - - <para>Because the SCSI bus is, ehh, a bus there must be a way to - distinguish or address the different devices connected to - it.</para> - - <para>This is done by means of the SCSI or target ID. Each device - has a unique target ID. You can select the ID to which a device - must respond using a set of jumpers, or a dip switch, or something - similar. Some SCSI host adapters let you change the target ID - from the boot menu. (Yet some others will not let you change the - ID from 7.) Consult the documentation of your device for more - information.</para> - - <para>Beware of multiple devices configured to use the same ID. - Chaos normally reigns in this case. A pitfall is that one of the - devices sharing the same ID sometimes even manages to answer to - I/O requests!</para> - - <para>For an 8 bit bus, a maximum of 8 targets is possible. The - maximum is 8 because the selection is done bitwise using the 8 - data lines on the bus. For wide buses this increases to the - number of data lines (usually 16).</para> - - <note> - <para>A narrow SCSI device can not communicate with a SCSI device - with a target ID larger than 7. This means it is generally not - a good idea to move your SCSI host adapter's target ID to - something higher than 7 (or your CDROM will stop - working).</para> - </note> - - <para>The higher the SCSI target ID, the higher the priority the - devices has. When it comes to arbitration between devices that - want to use the bus at the same time, the device that has the - highest SCSI ID will win. This also means that the SCSI host - adapter usually uses target ID 7. Note however that the lower 8 - IDs have higher priorities than the higher 8 IDs on a wide-SCSI - bus. Thus, the order of target IDs is: [7 6 .. 1 0 15 14 .. 9 8] - on a wide-SCSI system. (If you are wondering why the lower 8 - have higher priority, read the previous paragraph for a - hint.)</para> - - <para>For a further subdivision, the standard allows for Logical - Units or LUNs for short. A single target ID may have multiple - LUNs. For example, a tape device including a tape changer may - have LUN 0 for the tape device itself, and LUN 1 for the tape - changer. In this way, the host system can address each of the - functional units of the tape changer as desired.</para> - </sect3> - - <sect3> - <title>Bus layout</title> - - <para>SCSI buses are linear. So, not shaped like Y-junctions, star - topologies, rings, cobwebs or whatever else people might want to - invent. One of the most common mistakes is for people with - wide-SCSI host adapters to connect devices on all three connecters - (external connector, internal wide connector, internal narrow - connector). Do not do that. It may appear to work if you are - really lucky, but I can almost guarantee that your system will - stop functioning at the most unfortunate moment (this is also - known as <quote>Murphy's law</quote>).</para> - - <para>You might notice that the terminator issue discussed earlier - becomes rather hairy if your bus is not linear. Also, if you have - more connectors than devices on your internal SCSI cable, make - sure you attach devices on connectors on both ends instead of - using the connectors in the middle and let one or both ends - dangle. This will screw up the termination of the bus.</para> - - <para>The electrical characteristics, its noise margins and - ultimately the reliability of it all are tightly related to linear - bus rule.</para> - - <para><emphasis>Stick to the linear bus rule!</emphasis></para> - </sect3> - </sect2> - - <sect2> - <title>Using SCSI with FreeBSD</title> - - <sect3> - <title>About translations, BIOSes and magic...</title> - - <para>As stated before, you should first make sure that you have a - electrically sound bus.</para> - - <para>When you want to use a SCSI disk on your PC as boot disk, you - must aware of some quirks related to PC BIOSes. The PC BIOS in - its first incarnation used a low level physical interface to the - hard disk. So, you had to tell the BIOS (using a setup tool or a - BIOS built-in setup) how your disk physically looked like. This - involved stating number of heads, number of cylinders, number of - sectors per track, obscure things like precompensation and reduced - write current cylinder etc.</para> - - <para>One might be inclined to think that since SCSI disks are smart - you can forget about this. Alas, the arcane setup issue is still - present today. The system BIOS needs to know how to access your - SCSI disk with the head/cyl/sector method in order to load the - FreeBSD kernel during boot.</para> - - <para>The SCSI host adapter or SCSI controller you have put in your - AT/EISA/PCI/whatever bus to connect your disk therefore has its - own on-board BIOS. During system startup, the SCSI BIOS takes - over the hard disk interface routines from the system BIOS. To - fool the system BIOS, the system setup is normally set to No hard - disk present. Obvious, is it not?</para> - - <para>The SCSI BIOS itself presents to the system a so called - <emphasis>translated</emphasis> drive. This means that a fake - drive table is constructed that allows the PC to boot the drive. - This translation is often (but not always) done using a pseudo - drive with 64 heads and 32 sectors per track. By varying the - number of cylinders, the SCSI BIOS adapts to the actual drive - size. It is useful to note that 32 * 64 / 2 = the size of your - drive in megabytes. The division by 2 is to get from disk blocks - that are normally 512 bytes in size to Kbytes.</para> - - <para>Right. All is well now?! No, it is not. The system BIOS has - another quirk you might run into. The number of cylinders of a - bootable hard disk cannot be greater than 1024. Using the - translation above, this is a show-stopper for disks greater than 1 - GB. With disk capacities going up all the time this is causing - problems.</para> - - <para>Fortunately, the solution is simple: just use another - translation, e.g. with 128 heads instead of 32. In most cases new - SCSI BIOS versions are available to upgrade older SCSI host - adapters. Some newer adapters have an option, in the form of a - jumper or software setup selection, to switch the translation the - SCSI BIOS uses.</para> - - <para>It is very important that <emphasis>all</emphasis> operating - systems on the disk use the <emphasis>same translation</emphasis> - to get the right idea about where to find the relevant partitions. - So, when installing FreeBSD you must answer any questions about - heads/cylinders etc using the translated values your host adapter - uses.</para> - - <para>Failing to observe the translation issue might lead to - un-bootable systems or operating systems overwriting each others - partitions. Using fdisk you should be able to see all - partitions.</para> - - <para>You might have heard some talk of <quote>lying</quote> devices? - Older FreeBSD kernels used to report the geometry of SCSI disks - when booting. An example from one of my systems:</para> - - <screen>aha0 targ 0 lun 0: <MICROP 1588-15MB1057404HSP4> -da0: 636MB (1303250 total sec), 1632 cyl, 15 head, 53 sec, bytes/sec 512</screen> - - <para>Newer kernels usually do not report this information. - e.g.</para> - - <screen>(bt0:0:0): "SEAGATE ST41651 7574" type 0 fixed SCSI 2 -da0(bt0:0:0): Direct-Access 1350MB (2766300 512 byte sectors)</screen> - - <para>Why has this changed?</para> - - <para>This info is retrieved from the SCSI disk itself. Newer disks - often use a technique called zone bit recording. The idea is that - on the outer cylinders of the drive there is more space so more - sectors per track can be put on them. This results in disks that - have more tracks on outer cylinders than on the inner cylinders - and, last but not least, have more capacity. You can imagine that - the value reported by the drive when inquiring about the geometry - now becomes suspect at best, and nearly always misleading. When - asked for a geometry, it is nearly always better to supply the - geometry used by the BIOS, or <emphasis>if the BIOS is never going - to know about this disk</emphasis>, (e.g. it is not a booting - disk) to supply a fictitious geometry that is convenient.</para> - </sect3> - - <sect3> - <title>SCSI subsystem design</title> - - <para>FreeBSD uses a layered SCSI subsystem. For each different - controller card a device driver is written. This driver knows all - the intimate details about the hardware it controls. The driver - has a interface to the upper layers of the SCSI subsystem through - which it receives its commands and reports back any status.</para> - - <para>On top of the card drivers there are a number of more generic - drivers for a class of devices. More specific: a driver for tape - devices (abbreviation: sa, for serial access), - magnetic disks (da, for direct access), CDROMs (cd) etc. - In case you are wondering where you can find this stuff, it all - lives in <filename>/sys/cam/scsi</filename>. See the man pages in - section 4 for more details.</para> - - <para>The multi level design allows a decoupling of low-level bit - banging and more high level stuff. Adding support for another - piece of hardware is a much more manageable problem.</para> - </sect3> - - <sect3> - <title>Kernel configuration</title> - - <para>Dependent on your hardware, the kernel configuration file must - contain one or more lines describing your host adapter(s). This - includes I/O addresses, interrupts etc. Consult the manual page for - your adapter driver to get more info. Apart from that, check out - <filename>/sys/i386/conf/LINT</filename> for an overview of a - kernel config file. <filename>LINT</filename> contains every - possible option you can dream of. It does - <emphasis>not</emphasis> imply <filename>LINT</filename> will - actually get you to a working kernel at all.</para> - - <para>Although it is probably stating the obvious: the kernel config - file should reflect your actual hardware setup. So, interrupts, - I/O addresses etc must match the kernel config file. During - system boot messages will be displayed to indicate whether the - configured hardware was actually found.</para> - - <note> - <para>Note that most of the EISA/PCI drivers (namely - <devicename>ahb</devicename>, <devicename>ahc</devicename>, - <devicename>ncr</devicename> and <devicename>amd</devicename> - will automatically obtain the correct parameters from the host - adapters themselves at boot time; thus, you just need to write, - for instance, <literal>controller ahc0</literal>.</para> - </note> - - <para>An example loosely based on the FreeBSD 2.2.5-Release kernel - config file <filename>LINT</filename> with some added comments - (between []):</para> - - <programlisting># SCSI host adapters: `aha', `ahb', `aic', `bt', `nca' -# -# aha: Adaptec 154x -# ahb: Adaptec 174x -# ahc: Adaptec 274x/284x/294x -# aic: Adaptec 152x and sound cards using the Adaptec AIC-6360 (slow!) -# amd: AMD 53c974 based SCSI cards (e.g., Tekram DC-390 and 390T) -# bt: Most Buslogic controllers -# nca: ProAudioSpectrum cards using the NCR 5380 or Trantor T130 -# ncr: NCR/Symbios 53c810/815/825/875 etc based SCSI cards -# uha: UltraStore 14F and 34F -# sea: Seagate ST01/02 8 bit controller (slow!) -# wds: Western Digital WD7000 controller (no scatter/gather!). -# - -[For an Adaptec AHA274x/284x/294x/394x etc controller] -controller ahc0 - -[For an NCR/Symbios 53c875 based controller] -controller ncr0 - -[For an Ultrastor adapter] -controller uha0 at isa? port "IO_UHA0" bio irq ? drq 5 vector uhaintr - -# Map SCSI buses to specific SCSI adapters -controller scbus0 at ahc0 -controller scbus2 at ncr0 -controller scbus1 at uha0 - -# The actual SCSI devices -disk da0 at scbus0 target 0 unit 0 [SCSI disk 0 is at scbus 0, LUN 0] -disk da1 at scbus0 target 1 [implicit LUN 0 if omitted] -disk da2 at scbus1 target 3 [SCSI disk on the uha0] -disk da3 at scbus2 target 4 [SCSI disk on the ncr0] -tape sa1 at scbus0 target 6 [SCSI tape at target 6] -device cd0 at scbus? [the first ever CDROM found, no wiring]</programlisting> - - <para>The example above tells the kernel to look for a ahc (Adaptec - 274x) controller, then for an NCR/Symbios board, and so on. The - lines following the controller specifications tell the kernel to - configure specific devices but <emphasis>only</emphasis> attach - them when they match the target ID and LUN specified on the - corresponding bus.</para> - - <para>Wired down devices get <quote>first shot</quote> at the unit - numbers so the first non <quote>wired down</quote> device, is - allocated the unit number one greater than the highest - <quote>wired down</quote> unit number for that kind of device. So, - if you had a SCSI tape at target ID 2 it would be configured as - sa2, as the tape at target ID 6 is wired down to unit number - 1.</para> - - <note> - <para>Wired down devices need not be found to get their unit - number. The unit number for a wired down device is reserved for - that device, even if it is turned off at boot time. This allows - the device to be turned on and brought on-line at a later time, - without rebooting. Notice that a device's unit number has - <emphasis>no</emphasis> relationship with its target ID on the - SCSI bus.</para> - </note> - - <para>Below is another example of a kernel config file as used by - FreeBSD version < 2.0.5. The difference with the first example - is that devices are not <quote>wired down</quote>. <quote>Wired - down</quote> means that you specify which SCSI target belongs to - which device.</para> - - <para>A kernel built to the config file below will attach the first - SCSI disk it finds to da0, the second disk to da1 etc. If you ever - removed or added a disk, all other devices of the same type (disk - in this case) would <quote>move around</quote>. This implies you have to - change <filename>/etc/fstab</filename> each time.</para> - - <para>Although the old style still works, you are - <emphasis>strongly</emphasis> recommended to use this new feature. - It will save you a lot of grief whenever you shift your hardware - around on the SCSI buses. So, when you re-use your old trusty - config file after upgrading from a pre-FreeBSD2.0.5.R system check - this out.</para> - - <programlisting>[driver for Adaptec 174x] -controller ahb0 at isa? bio irq 11 vector ahbintr - -[for Adaptec 154x] -controller aha0 at isa? port "IO_AHA0" bio irq 11 drq 5 vector ahaintr - -[for Seagate ST01/02] -controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr - -controller scbus0 - -device da0 [support for 4 SCSI harddisks, da0 up da3] -device sa0 [support for 2 SCSI tapes] - -[for the CDROM] -device cd0 #Only need one of these, the code dynamically grows</programlisting> - - <para>Both examples support SCSI disks. If during boot more devices - of a specific type (e.g. da disks) are found than are configured - in the booting kernel, the system will simply allocate more - devices, incrementing the unit number starting at the last number - <quote>wired down</quote>. If there are no <quote>wired - down</quote> devices then counting starts at unit 0.</para> - - <para>Use <command>man 4 scsi</command> to check for the latest info - on the SCSI subsystem. For more detailed info on host adapter - drivers use e.g., <command>man 4 ahc</command> for info on the - Adaptec 294x driver.</para> - </sect3> - - <sect3> - <title>Tuning your SCSI kernel setup</title> - - <para>Experience has shown that some devices are slow to respond to - INQUIRY commands after a SCSI bus reset (which happens at boot - time). An INQUIRY command is sent by the kernel on boot to see - what kind of device (disk, tape, CDROM etc.) is connected to a - specific target ID. This process is called device probing by the - way.</para> - - <para>To work around the <quote>slow response</quote> problem, FreeBSD allows a - tunable delay time before the SCSI devices are probed following a - SCSI bus reset. You can set this delay time in your kernel - configuration file using a line like:</para> - - <programlisting>options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device</programlisting> - - <para>This line sets the delay time to 15 seconds. On my own system - I had to use 3 seconds minimum to get my trusty old CDROM drive - to be recognized. Start with a high value (say 30 seconds or so) - when you have problems with device recognition. If this helps, - tune it back until it just stays working.</para> - </sect3> - - <sect3 id="scsi-rogue-devices"> - <title>Rogue SCSI devices</title> - - <para>Although the SCSI standard tries to be complete and concise, - it is a complex standard and implementing things correctly is no - easy task. Some vendors do a better job then others.</para> - - <para>This is exactly where the <quote>rogue</quote> devices come - into view. Rogues are devices that are recognized by the FreeBSD - kernel as behaving slightly (...) non-standard. Rogue devices are - reported by the kernel when booting. An example for two of my - cartridge tape units:</para> - - <screen>Feb 25 21:03:34 yedi /kernel: ahb0 targ 5 lun 0: <TANDBERG TDC 3600 -06:> -Feb 25 21:03:34 yedi /kernel: sa0: Tandberg tdc3600 is a known rogue - -Mar 29 21:16:37 yedi /kernel: aha0 targ 5 lun 0: <ARCHIVE VIPER 150 21247-005> -Mar 29 21:16:37 yedi /kernel: sa1: Archive Viper 150 is a known rogue </screen> - - <para>For instance, there are devices that respond to all LUNs on a - certain target ID, even if they are actually only one device. It - is easy to see that the kernel might be fooled into believing that - there are 8 LUNs at that particular target ID. The confusion this - causes is left as an exercise to the reader.</para> - - <para>The SCSI subsystem of FreeBSD recognizes devices with bad - habits by looking at the INQUIRY response they send when probed. - Because the INQUIRY response also includes the version number of - the device firmware, it is even possible that for different - firmware versions different workarounds are used. See e.g. - <filename>/sys/cam/scsi/scsi_sa.c</filename> and - <filename>/sys/cam/scsi/scsi_all.c</filename> for more info on how - this is done.</para> - - <para>This scheme works fine, but keep in mind that it of course - only works for devices that are known to be weird. If you are the - first to connect your bogus Mumbletech SCSI CDROM you might be - the one that has to define which workaround is needed.</para> - - <para>After you got your Mumbletech working, please send the - required workaround to the FreeBSD development team for inclusion - in the next release of FreeBSD. Other Mumbletech owners will be - grateful to you.</para> - </sect3> - - <sect3> - <title>Multiple LUN devices</title> - - <para>In some cases you come across devices that use multiple - logical units (LUNs) on a single SCSI ID. In most cases FreeBSD - only probes devices for LUN 0. An example are so called bridge - boards that connect 2 non-SCSI hard disks to a SCSI bus (e.g. an - Emulex MD21 found in old Sun systems).</para> - - <para>This means that any devices with LUNs != 0 are not normally - found during device probe on system boot. To work around this - problem you must add an appropriate entry in /sys/cam/scsi - and rebuild your kernel.</para> - - <para>Look for a struct that is initialized like below: - (FIXME: which file? Do these entries still exist in this form - now that we use CAM?)</para> - - <programlisting>{ - T_DIRECT, T_FIXED, "MAXTOR", "XT-4170S", "B5A", - "mx1", SC_ONE_LU -}</programlisting> - - <para>For your Mumbletech BRIDGE2000 that has more than one LUN, acts - as a SCSI disk and has firmware revision 123 you would add - something like:</para> - - <programlisting>{ - T_DIRECT, T_FIXED, "MUMBLETECH", "BRIDGE2000", "123", - "da", SC_MORE_LUS -}</programlisting> - - <para>The kernel on boot scans the inquiry data it receives against - the table and acts accordingly. See the source for more - info.</para> - </sect3> - - <sect3> - <title>Tagged command queuing</title> - - <para>Modern SCSI devices, particularly magnetic disks, - support what is called tagged command queuing (TCQ).</para> - - <para>In a nutshell, TCQ allows the device to have multiple I/O - requests outstanding at the same time. Because the device is - intelligent, it can optimize its operations (like head - positioning) based on its own request queue. On SCSI devices - like RAID (Redundant Array of Independent Disks) arrays the TCQ - function is indispensable to take advantage of the device's - inherent parallelism.</para> - - <para>Each I/O request is uniquely identified by a <quote>tag</quote> - (hence the name tagged command queuing) and this tag is used by - FreeBSD to see which I/O in the device drivers queue is reported - as complete by the device.</para> - - <para>It should be noted however that TCQ requires device driver - support and that some devices implemented it <quote>not quite - right</quote> in their firmware. This problem bit me once, and it - leads to highly mysterious problems. In such cases, try to - disable TCQ.</para> - </sect3> - - <sect3> - <title>Bus-master host adapters</title> - - <para>Most, but not all, SCSI host adapters are bus mastering - controllers. This means that they can do I/O on their own without - putting load onto the host CPU for data movement.</para> - - <para>This is of course an advantage for a multitasking operating - system like FreeBSD. It must be noted however that there might be - some rough edges.</para> - - <para>For instance an Adaptec 1542 controller can be set to use - different transfer speeds on the host bus (ISA or AT in this - case). The controller is settable to different rates because not - all motherboards can handle the higher speeds. Problems like - hang-ups, bad data etc might be the result of using a higher data - transfer rate then your motherboard can stomach.</para> - - <para>The solution is of course obvious: switch to a lower data - transfer rate and try if that works better.</para> - - <para>In the case of a Adaptec 1542, there is an option that can be - put into the kernel config file to allow dynamic determination of - the right, read: fastest feasible, transfer rate. This option is - disabled by default:</para> - - <programlisting>options "TUNE_1542" #dynamic tune of bus DMA speed</programlisting> - - <para>Check the manual pages for the host adapter that you use. Or - better still, use the ultimate documentation (read: driver - source).</para> - </sect3> - </sect2> - - <sect2> - <title>Tracking down problems</title> - - <para>The following list is an attempt to give a guideline for the - most common SCSI problems and their solutions. It is by no means - complete.</para> - - <itemizedlist> - <listitem> - <para>Check for loose connectors and cables.</para> - </listitem> - - <listitem> - <para>Check and double check the location and number of your - terminators.</para> - </listitem> - - <listitem> - <para>Check if your bus has at least one supplier of terminator - power (especially with external terminators.</para> - </listitem> - - <listitem> - <para>Check if no double target IDs are used.</para> - </listitem> - - <listitem> - <para>Check if all devices to be used are powered up.</para> - </listitem> - - <listitem> - <para>Make a minimal bus config with as little devices as - possible.</para> - </listitem> - - <listitem> - <para>If possible, configure your host adapter to use slow bus - speeds.</para> - </listitem> - - <listitem> - <para>Disable tagged command queuing to make things as simple as - possible (for a NCR host adapter based system see man - ncrcontrol)</para> - </listitem> - - <listitem> - <para>If you can compile a kernel, make one with the - <literal>SCSIDEBUG</literal> option, and try accessing the - device with debugging turned on for that device. If your device - does not even probe at startup, you may have to define the - address of the device that is failing, and the desired debug - level in <filename>/sys/cam/cam_debug.h</filename>. If it - probes but just does not work, you can use the - &man.camcontrol.8; command to dynamically set a debug level to - it in a running kernel (if <literal>CAMDEBUG</literal> is - defined). This will give you <emphasis>copious</emphasis> - debugging output with which to confuse the gurus. See - <command>man camcontrol</command> for more exact information. Also - look at <command>man 4 pass</command>.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="scsi-further-reading"> - <title>Further reading</title> - - <para>If you intend to do some serious SCSI hacking, you might want to - have the official standard at hand:</para> - - <para>Approved American National Standards can be purchased from - ANSI at - - <address> - <otheraddr>13th Floor</otheraddr> - <street>11 West 42nd Street</street> - <city>New York</city> - <state>NY</state> <postcode>10036</postcode> - Sales Dept: <phone>(212) 642-4900</phone> - </address> - </para> - - <para>You can also buy many ANSI - standards and most committee draft documents from Global - Engineering Documents, - - <address> - <street>15 Inverness Way East</street> - <city>Englewood</city> - <state>CO</state>, <postcode>80112-5704</postcode> - Phone: <phone>(800) 854-7179</phone> - Outside USA and Canada: <phone>(303) 792-2181</phone> - Fax: <fax>(303) 792- 2192</fax> - </address> - </para> - - <para>Many X3T10 draft documents are available electronically on the - SCSI BBS (719-574-0424) and on the <hostid - role="fqdn">ncrinfo.ncr.com</hostid> anonymous FTP site.</para> - - <para>Latest X3T10 committee documents are:</para> - - <itemizedlist> - <listitem> - <para>AT Attachment (ATA or IDE) [X3.221-1994] - (<emphasis>Approved</emphasis>)</para> - </listitem> - - <listitem> - <para>ATA Extensions (ATA-2) [X3T10/948D Rev 2i]</para> - </listitem> - - <listitem> - <para>Enhanced Small Device Interface (ESDI) - [X3.170-1990/X3.170a-1991] - (<emphasis>Approved</emphasis>)</para> - </listitem> - - <listitem> - <para>Small Computer System Interface — 2 (SCSI-2) - [X3.131-1994] (<emphasis>Approved</emphasis>)</para> - </listitem> - - <listitem> - <para>SCSI-2 Common Access Method Transport and SCSI Interface - Module (CAM) [X3T10/792D Rev 11]</para> - </listitem> - </itemizedlist> - - <para>Other publications that might provide you with additional - information are:</para> - - <itemizedlist> - <listitem> - <para><quote>SCSI: Understanding the Small Computer System - Interface</quote>, written by NCR Corporation. Available from: - Prentice Hall, Englewood Cliffs, NJ, 07632 Phone: (201) 767-5937 - ISBN 0-13-796855-8</para> - </listitem> - - <listitem> - <para><quote>Basics of SCSI</quote>, a SCSI tutorial written by - Ancot Corporation Contact Ancot for availability information at: - Phone: (415) 322-5322 Fax: (415) 322-0455</para> - </listitem> - - <listitem> - <para><quote>SCSI Interconnection Guide Book</quote>, an AMP - publication (dated 4/93, Catalog 65237) that lists the various - SCSI connectors and suggests cabling schemes. Available from - AMP at (800) 522-6752 or (717) 564-0100</para> - </listitem> - - <listitem> - <para><quote>Fast Track to SCSI</quote>, A Product Guide written by - Fujitsu. Available from: Prentice Hall, Englewood Cliffs, NJ, - 07632 Phone: (201) 767-5937 ISBN 0-13-307000-X</para> - </listitem> - - <listitem> - <para><quote>The SCSI Bench Reference</quote>, <quote>The SCSI - Encyclopedia</quote>, and the <quote>SCSI Tutor</quote>, ENDL - Publications, 14426 Black Walnut Court, Saratoga CA, 95070 - Phone: (408) 867-6642</para> - </listitem> - - <listitem> - <para><quote>Zadian SCSI Navigator</quote> (quick ref. book) and - <quote>Discover the Power of SCSI</quote> (First book along with - a one-hour video and tutorial book), Zadian Software, Suite 214, - 1210 S. Bascom Ave., San Jose, CA 92128, (408) 293-0800</para> - </listitem> - </itemizedlist> - - <para>On Usenet the newsgroups <ulink - url="news:comp.periphs.scsi">comp.periphs.scsi</ulink> and <ulink - url="news:comp.periphs">comp.periphs</ulink> are noteworthy places - to look for more info. You can also find the <ulink - url="http://scsifaq.org:9080/scsi_faq/scsifaq.html">SCSI-FAQ</ulink> - there, which is posted periodically.</para> - - <para>Most major SCSI device and host adapter suppliers operate FTP - sites and/or BBS systems. They may be valuable sources of - information about the devices you own.</para> - </sect2> - </sect1> - - <sect1 id="hw-storage-controllers"> - <title>* Disk/tape controllers</title> - - <sect2> - <title>* SCSI</title> - - <para></para> - </sect2> - - <sect2> - <title>* IDE</title> - - <para></para> - </sect2> - - <sect2> - <title>* Floppy</title> - - <para></para> - </sect2> - </sect1> - - <sect1> - <title>Hard drives</title> - - <sect2> - <title>SCSI hard drives</title> - - <para><emphasis>Contributed by &a.asami;. 17 February - 1998.</emphasis></para> - - <para>As mentioned in the <link linkend="scsi">SCSI</link> section, - virtually all SCSI hard drives sold today are SCSI-2 compliant and - thus will work fine as long as you connect them to a supported SCSI - host adapter. Most problems people encounter are either due to - badly designed cabling (cable too long, star topology, etc.), - insufficient termination, or defective parts. Please refer to the - <link linkend="scsi">SCSI</link> section first if your SCSI hard - drive is not working. However, there are a couple of things you may - want to take into account before you purchase SCSI hard drives for - your system.</para> - - <sect3> - <title>Rotational speed</title> - - <para>Rotational speeds of SCSI drives sold today range from around - 4,500RPM to 15,000RPM. Most of them are either 7,200RPM or - 10,000RPM, with 15,000RPM becoming affordable (June 2002). - Even though the 10,000RPM drives can generally transfer - data faster, they run considerably hotter than their 7,200RPM - counterparts. A large fraction of today's disk drive malfunctions - are heat-related. If you do not have very good cooling in your PC - case, you may want to stick with 7,200RPM or slower drives.</para> - - <para>Note that newer drives, with higher areal recording densities, - can deliver much more bits per rotation than older ones. Today's - top-of-line 7,200RPM drives can sustain a throughput comparable to - 10,000RPM drives of one or two model generations ago. The number - to find on the spec sheet for bandwidth is <quote>internal data - (or transfer) rate</quote>. It is usually in megabits/sec so - divide it by 8 and you will get the rough approximation of how much - megabytes/sec you can get out of the drive.</para> - - <para>(If you are a speed maniac and want a 15,000RPM drive for your - cute little PC, be my guest; however, those drives become - extremely hot. Do not even think about it if you do not have a fan - blowing air <emphasis>directly at</emphasis> the drive or a - properly ventilated disk enclosure.)</para> - - <para>Obviously, the latest 15,000RPM drives and 10,000RPM drives can - deliver more data than the latest 7,200RPM drives, so if absolute - bandwidth is the necessity for your applications, you have little - choice but to get the faster drives. Also, if you need low - latency, faster drives are better; not only do they usually have - lower average seek times, but also the rotational delay is one - place where slow-spinning drives can never beat a faster one. - (The average rotational latency is half the time it takes to - rotate the drive once; thus, it is 2 milliseconds for 15,000RPM, - 3ms for 10,000RPM - drives, 4.2ms for 7,200RPM drives and 5.6ms for 5,400RPM drives.) - Latency is seek time plus rotational delay. Make sure you - understand whether you need low latency or more accesses per - second, though; in the latter case (e.g., news servers), it may - not be optimal to purchase one big fast drive. You can achieve - similar or even better results by using the ccd (concatenated - disk) driver to create a striped disk array out of multiple slower - drives for comparable overall cost.</para> - - <para>Make sure you have adequate air flow around the drive, - especially if you are going to use a fast-spinning drive. You - generally need at least 1/2” (1.25cm) of spacing above and below a - drive. Understand how the air flows through your PC case. Most - cases have the power supply suck the air out of the back. See - where the air flows in, and put the drive where it will have the - largest volume of cool air flowing around it. You may need to seal - some unwanted holes or add a new fan for effective cooling.</para> - - <para>Another consideration is noise. Many 10,000 or faster drives - generate a high-pitched whine which is quite unpleasant to most - people. That, plus the extra fans often required for cooling, may - make 10,000 or faster drives unsuitable for some office and home - environments.</para> - </sect3> - - <sect3> - <title>Form factor</title> - - <para>Most SCSI drives sold today are of 3.5” form factor. They - come in two different heights; 1.6” (<quote>half-height</quote>) or - 1” (<quote>low-profile</quote>). The half-height drive is the same - height as a CDROM drive. However, do not forget the spacing rule - mentioned in the previous section. If you have three standard - 3.5” drive bays, you will not be able to put three half-height - drives in there (without frying them, that is).</para> - </sect3> - - <sect3> - <title>Interface</title> - - <para>The majority of SCSI hard drives sold today are Ultra, - Ultra-wide, or Ultra160 SCSI. As of this writing (June 2002), - the first Ultra320 host adapters and devices become available. - The maximum bandwidth of Ultra SCSI is 20MB/sec, - and Ultra-wide SCSI is 40MB/sec. Ultra160 can transfer 160MB/sec - and Ultra320 can transfer 320MB/sec. There is no difference in max - cable length between Ultra and Ultra-wide; however, the more - devices you have on the same bus, the sooner you will start having - bus integrity problems. Unless you have a well-designed disk - enclosure, it is not easy to make more than 5 or 6 Ultra SCSI - drives work on a single bus.</para> - - <para>On the other hand, if you need to connect many drives, going - for Fast-wide SCSI may not be a bad idea. That will have the same - max bandwidth as Ultra (narrow) SCSI, while electronically it is - much easier to get it <quote>right</quote>. My advice would be: if - you want to connect many disks, get wide or Ultra160 SCSI drives; - they usually - cost a little more but it may save you down the road. (Besides, - if you can not afford the cost difference, you should not be building - a disk array.)</para> - - <para>There are two variant of wide SCSI drives; 68-pin and 80-pin - SCA (Single Connector Attach). The SCA drives do not have a - separate 4-pin power connector, and also read the SCSI ID settings - through the 80-pin connector. If you are really serious about - building a large storage system, get SCA drives and a good SCA - enclosure (dual power supply with at least one extra fan). They - are more electronically sound than 68-pin counterparts because - there is no <quote>stub</quote> of the SCSI bus inside the disk - canister as in arrays built from 68-pin drives. They are easier - to install too (you just need to screw the drive in the canister, - instead of trying to squeeze in your fingers in a tight place to - hook up all the little cables (like the SCSI ID and disk activity - LED lines).</para> - </sect3> - </sect2> - - <sect2> - <title>* IDE hard drives</title> - - <para></para> - </sect2> - </sect1> - - <sect1> - <title>Tape drives</title> - - <para><emphasis>Contributed by &a.jmb;. 2 July - 1996.</emphasis></para> - - <sect2> - <title>General tape access commands</title> - - <para>&man.mt.1; provides generic access to the tape drives. Some of - the more common commands are <command>rewind</command>, - <command>erase</command>, and <command>status</command>. See the - &man.mt.1; manual page for a detailed description.</para> - </sect2> - - <sect2> - <title>Controller Interfaces</title> - - <para>There are several different interfaces that support tape drives. - The interfaces are SCSI, IDE, Floppy and Parallel Port. A wide - variety of tape drives are available for these interfaces. - Controllers are discussed in <link - linkend="hw-storage-controllers">Disk/tape - controllers</link>.</para> - </sect2> - - <sect2> - <title>SCSI drives</title> - - <para>The &man.st.4; driver provides support for 8mm (Exabyte), 4mm - (DAT: Digital Audio Tape), QIC (Quarter-Inch Cartridge), DLT - (Digital Linear Tape), QIC Mini cartridge and 9-track (remember the - big reels that you see spinning in Hollywood computer rooms) tape - drives. See the &man.st.4; manual page for a detailed - description.</para> - - <para>The drives listed below are currently being used by members of - the FreeBSD community. They are not the only drives that will work - with FreeBSD. They just happen to be the ones that we use.</para> - - <sect3> - <title>4mm (DAT: Digital Audio Tape)</title> - - <para><link linkend="hw-storage-python-28454">Archive Python - 28454</link></para> - - <para><link linkend="hw-storage-python-04687">Archive Python - 04687</link></para> - - <para><link linkend="hw-storage-hp1533a">HP C1533A</link></para> - - <para><link linkend="hw-storage-hp1534a">HP C1534A</link></para> - - <para><link linkend="hw-storage-hp35450a">HP 35450A</link></para> - - <para><link linkend="hw-storage-hp35470a">HP 35470A</link></para> - - <para><link linkend="hw-storage-hp35480a">HP 35480A</link></para> - - <para><link linkend="hw-storage-sdt5000">SDT-5000</link></para> - - <para><link linkend="hw-storage-wangtek6200">Wangtek - 6200</link></para> - </sect3> - - <sect3> - <title>8mm (Exabyte)</title> - - <para><link linkend="hw-storage-exb8200">EXB-8200</link></para> - - <para><link linkend="hw-storage-exb8500">EXB-8500</link></para> - - <para><link linkend="hw-storage-exb8505">EXB-8505</link></para> - </sect3> - - <sect3> - <title>QIC (Quarter-Inch Cartridge)</title> - - <para><link linkend="hw-storage-anaconda">Archive Anaconda - 2750</link></para> - - <para><link linkend="hw-storage-viper60">Archive Viper - 60</link></para> - - <para><link linkend="hw-storage-viper150">Archive Viper - 150</link></para> - - <para><link linkend="hw-storage-viper2525">Archive Viper - 2525</link></para> - - <para><link linkend="hw-storage-tandberg3600">Tandberg TDC - 3600</link></para> - - <para><link linkend="hw-storage-tandberg3620">Tandberg TDC - 3620</link></para> - - <para><link linkend="hw-storage-tandberg3800">Tandberg TDC - 3800</link></para> - - <para><link linkend="hw-storage-tandberg4222">Tandberg TDC - 4222</link></para> - - <para><link linkend="hw-storage-wangtek5525es">Wangtek - 5525ES</link></para> - </sect3> - - <sect3> - <title>DLT (Digital Linear Tape)</title> - - <para><link linkend="hw-storage-dectz87">Digital TZ87</link></para> - </sect3> - - <sect3> - <title>Mini-Cartridge</title> - - <para><link linkend="hw-storage-ctms3200">Conner CTMS - 3200</link></para> - - <para><link linkend="hw-storage-exb2501">Exabyte 2501</link></para> - </sect3> - - <sect3> - <title>Autoloaders/Changers</title> - - <para><link linkend="hw-storage-hp1553a">Hewlett-Packard HP C1553A - Autoloading DDS2</link></para> - </sect3> - </sect2> - - <sect2> - <title>* IDE drives</title> - - <para></para> - </sect2> - - <sect2> - <title>Floppy drives</title> - - <para><link linkend="hw-storage-conner420r">Conner 420R</link></para> - </sect2> - - <sect2> - <title>* Parallel port drives</title> - - <para></para> - </sect2> - - <sect2> - <title>Detailed Information</title> - - <sect3 id="hw-storage-anaconda"> - <title>Archive Anaconda 2750</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - ANCDA 2750 28077 -003 type 1 removable SCSI 2</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 1.35GB when using QIC-1350 tapes. This - drive will read and write QIC-150 (DC6150), QIC-250 (DC6250), and - QIC-525 (DC6525) tapes as well.</para> - - <para>Data transfer rate is 350kB/s using &man.dump.8;. - Rates of 530kB/s have been reported when using - Amanda</para> - - <para>Production of this drive has been discontinued.</para> - - <para>The SCSI bus connector on this tape drive is reversed from - that on most other SCSI devices. Make sure that you have enough - SCSI cable to twist the cable one-half turn before and after the - Archive Anaconda tape drive, or turn your other SCSI devices - upside-down.</para> - - <para>Two kernel code changes are required to use this drive. This - drive will not work as delivered.</para> - - <para>If you have a SCSI-2 controller, short jumper 6. Otherwise, - the drive behaves are a SCSI-1 device. When operating as a SCSI-1 - device, this drive, <quote>locks</quote> the SCSI bus during some - tape operations, including: fsf, rewind, and rewoffl.</para> - - <para>If you are using the NCR SCSI controllers, patch the file - <filename>/usr/src/sys/pci/ncr.c</filename> (as shown below). - Build and install a new kernel.</para> - - <programlisting>*** 4831,4835 **** - }; - -! if (np->latetime>4) { - /* - ** Although we tried to wake it up, ---- 4831,4836 ---- - }; - -! if (np->latetime>1200) { - /* - ** Although we tried to wake it up,</programlisting> - - <para>Reported by: &a.jmb;</para> - </sect3> - - <sect3 id="hw-storage-python-28454"> - <title>Archive Python 28454</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - Python 28454-XXX4ASB</literal> <literal>type 1 removable SCSI - 2</literal> <literal>density code 0x8c, 512-byte - blocks</literal></para> - - <para>This is a DDS-1 tape drive.</para> - - <para>Native capacity is 2.5GB on 90m tapes.</para> - - <para>Data transfer rate is XXX.</para> - - <para>This drive was repackaged by Sun Microsystems as model - 595-3067.</para> - - <para>Reported by: Bob Bishop <email>rb@gid.co.uk</email></para> - - <para>Throughput is in the 1.5 MByte/sec range, however this will - drop if the disks and tape drive are on the same SCSI - controller.</para> - - <para>Reported by: Robert E. Seastrom - <email>rs@seastrom.com</email></para> - </sect3> - - <sect3 id="hw-storage-python-04687"> - <title>Archive Python 04687</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - Python 04687-XXX 6580</literal> <literal>Removable Sequential - Access SCSI-2 device</literal></para> - - <para>This is a DAT-DDS-2 drive.</para> - - <para>Native capacity is 4GB when using 120m tapes.</para> - - <para>This drive supports hardware data compression. Switch 4 - controls MRS (Media Recognition System). MRS tapes have stripes - on the transparent leader. Switch 4 <emphasis>off</emphasis> - enables MRS, <emphasis>on</emphasis> disables MRS.</para> - - <para>Parity is controlled by switch 5. Switch 5 - <emphasis>on</emphasis> to enable parity control. Compression is - enabled with Switch 6 <emphasis>off</emphasis>. It is possible to - override compression with the <literal>SCSI MODE SELECT</literal> - command (see &man.mt.1;).</para> - - <para>Data transfer rate is 800kB/s.</para> - </sect3> - - <sect3 id="hw-storage-viper60"> - <title>Archive Viper 60</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - VIPER 60 21116 -007</literal> <literal>type 1 removable SCSI - 1</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 60MB.</para> - - <para>Data transfer rate is XXX.</para> - - <para>Production of this drive has been discontinued.</para> - - <para>Reported by: Philippe Regnauld - <email>regnauld@hsc.fr</email></para> - </sect3> - - <sect3 id="hw-storage-viper150"> - <title>Archive Viper 150</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - VIPER 150 21531 -004</literal> <literal>Archive Viper 150 is a - known rogue</literal> <literal>type 1 removable SCSI - 1</literal>. A multitude of firmware revisions exist for this - drive. Your drive may report different numbers (e.g - <literal>21247 -005</literal>.</para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 150/250MB. Both 150MB (DC6150) and 250MB - (DC6250) tapes have the recording format. The 250MB tapes are - approximately 67% longer than the 150MB tapes. This drive can - read 120MB tapes as well. It can not write 120MB tapes.</para> - - <para>Data transfer rate is 100kB/s</para> - - <para>This drive reads and writes DC6150 (150MB) and DC6250 (250MB) - tapes.</para> - - <para>This drives quirks are known and pre-compiled into the SCSI - tape device driver (&man.st.4;).</para> - - <para>Under FreeBSD 2.2-CURRENT, use <command>mt blocksize - 512</command> to set the blocksize. (The particular drive had - firmware revision 21247 -005. Other firmware revisions may behave - differently) Previous versions of FreeBSD did not have this - problem.</para> - - <para>Production of this drive has been discontinued.</para> - - <para>Reported by: Pedro A M Vazquez - <email>vazquez@IQM.Unicamp.BR</email></para> - - <para>&a.msmith;</para> - </sect3> - - <sect3 id="hw-storage-viper2525"> - <title>Archive Viper 2525</title> - - <para>The boot message identifier for this drive is <literal>ARCHIVE - VIPER 2525 25462 -011</literal> <literal>type 1 removable SCSI - 1</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 525MB.</para> - - <para>Data transfer rate is 180kB/s at 90 inches/sec.</para> - - <para>The drive reads QIC-525, QIC-150, QIC-120 and QIC-24 tapes. - Writes QIC-525, QIC-150, and QIC-120.</para> - - <para>Firmware revisions prior to <literal>25462 -011</literal> are - bug ridden and will not function properly.</para> - - <para>Production of this drive has been discontinued.</para> - </sect3> - - <sect3 id="hw-storage-conner420r"> - <title>Conner 420R</title> - - <para>The boot message identifier for this drive is <literal>Conner - tape</literal>.</para> - - <para>This is a floppy controller, mini cartridge tape drive.</para> - - <para>Native capacity is XXXX</para> - - <para>Data transfer rate is XXX</para> - - <para>The drive uses QIC-80 tape cartridges.</para> - - <para>Reported by: Mark Hannon - <email>mark@seeware.DIALix.oz.au</email></para> - </sect3> - - <sect3 id="hw-storage-ctms3200"> - <title>Conner CTMS 3200</title> - - <para>The boot message identifier for this drive is <literal>CONNER - CTMS 3200 7.00</literal> <literal>type 1 removable SCSI - 2</literal>.</para> - - <para>This is a mini cartridge tape drive.</para> - - <para>Native capacity is XXXX</para> - - <para>Data transfer rate is XXX</para> - - <para>The drive uses QIC-3080 tape cartridges.</para> - - <para>Reported by: Thomas S. Traylor - <email>tst@titan.cs.mci.com</email></para> - </sect3> - - <sect3 id="hw-storage-dectz87"> - <title><ulink - url="http://www.digital.com/info/Customer-Update/931206004.txt.html">DEC TZ87</ulink></title> - - <para>The boot message identifier for this drive is <literal>DEC - TZ87 (C) DEC 9206</literal> <literal>type 1 removable SCSI - 2</literal> <literal>density code 0x19</literal></para> - - <para>This is a DLT tape drive.</para> - - <para>Native capacity is 10GB.</para> - - <para>This drive supports hardware data compression.</para> - - <para>Data transfer rate is 1.2MB/s.</para> - - <para>This drive is identical to the Quantum DLT2000. The drive - firmware can be set to emulate several well-known drives, - including an Exabyte 8mm drive.</para> - - <para>Reported by: &a.wilko;</para> - </sect3> - - <sect3 id="hw-storage-exb2501"> - <title><ulink - url="http://www.Exabyte.COM:80/Products/Minicartridge/2501/Rfeatures.html">Exabyte EXB-2501</ulink></title> - - <para>The boot message identifier for this drive is <literal>EXABYTE - EXB-2501</literal></para> - - <para>This is a mini-cartridge tape drive.</para> - - <para>Native capacity is 1GB when using MC3000XL - mini cartridges.</para> - - <para>Data transfer rate is XXX</para> - - <para>This drive can read and write DC2300 (550MB), DC2750 (750MB), - MC3000 (750MB), and MC3000XL (1GB) mini cartridges.</para> - - <para>WARNING: This drive does not meet the SCSI-2 specifications. - The drive locks up completely in response to a SCSI MODE_SELECT - command unless there is a formatted tape in the drive. Before - using this drive, set the tape blocksize with</para> - - <screen>&prompt.root; <userinput>mt -f /dev/st0ctl.0 blocksize 1024</userinput></screen> - - <para>Before using a mini cartridge for the first time, the - mini cartridge must be formated. FreeBSD 2.1.0-RELEASE and - earlier:</para> - - <screen>&prompt.root; <userinput>/sbin/scsi -f /dev/rst0.ctl -s 600 -c "4 0 0 0 0 0"</userinput></screen> - - <para>(Alternatively, fetch a copy of the - <command>scsiformat</command> shell script from FreeBSD - 2.1.5/2.2.) FreeBSD 2.1.5 and later:</para> - - <screen>&prompt.root; <userinput>/sbin/scsiformat -q -w /dev/rst0.ctl</userinput></screen> - - <para>Right now, this drive cannot really be recommended for - FreeBSD.</para> - - <para>Reported by: Bob Beaulieu - <email>ez@eztravel.com</email></para> - </sect3> - - <sect3 id="hw-storage-exb8200"> - <title>Exabyte EXB-8200</title> - - <para>The boot message identifier for this drive is <literal>EXABYTE - EXB-8200 252X</literal> <literal>type 1 removable SCSI - 1</literal></para> - - <para>This is an 8mm tape drive.</para> - - <para>Native capacity is 2.3GB.</para> - - <para>Data transfer rate is 270kB/s.</para> - - <para>This drive is fairly slow in responding to the SCSI bus during - boot. A custom kernel may be required (set SCSI_DELAY to 10 - seconds).</para> - - <para>There are a large number of firmware configurations for this - drive, some have been customized to a particular vendor's - hardware. The firmware can be changed via EPROM - replacement.</para> - - <para>Production of this drive has been discontinued.</para> - - <para>Reported by: &a.msmith;</para> - </sect3> - - <sect3 id="hw-storage-exb8500"> - <title>Exabyte EXB-8500</title> - - <para>The boot message identifier for this drive is <literal>EXABYTE - EXB-8500-85Qanx0 0415</literal> <literal>type 1 removable SCSI - 2</literal></para> - - <para>This is an 8mm tape drive.</para> - - <para>Native capacity is 5GB.</para> - - <para>Data transfer rate is 300kB/s.</para> - - <para>Reported by: Greg Lehey <email>grog@lemis.de</email></para> - </sect3> - - <sect3 id="hw-storage-exb8505"> - <title><ulink - url="http://www.Exabyte.COM:80/Products/8mm/8505XL/Rfeatures.html">Exabyte EXB-8505</ulink></title> - - <para>The boot message identifier for this drive is - <literal>EXABYTE EXB-85058SQANXR1 05B0</literal> <literal>type 1 - removable SCSI 2</literal></para> - - <para>This is an 8mm tape drive which supports compression, and is - upward compatible with the EXB-5200 and EXB-8500.</para> - - <para>Native capacity is 5GB.</para> - - <para>The drive supports hardware data compression.</para> - - <para>Data transfer rate is 300kB/s.</para> - - <para>Reported by: Glen Foster - <email>gfoster@gfoster.com</email></para> - </sect3> - - <sect3 id="hw-storage-hp1533a"> - <title>Hewlett-Packard HP C1533A</title> - - <para>The boot message identifier for this drive is <literal>HP - C1533A 9503</literal> <literal>type 1 removable SCSI - 2</literal>.</para> - - <para>This is a DDS-2 tape drive. DDS-2 means hardware data - compression and narrower tracks for increased data - capacity.</para> - - <para>Native capacity is 4GB when using 120m tapes. This drive - supports hardware data compression.</para> - - <para>Data transfer rate is 510kB/s.</para> - - <para>This drive is used in Hewlett-Packard's SureStore 6000eU and - 6000i tape drives and C1533A DDS-2 DAT drive.</para> - - <para>The drive has a block of 8 dip switches. The proper settings - for FreeBSD are: 1 ON; 2 ON; 3 OFF; 4 ON; 5 ON; 6 ON; 7 ON; 8 - ON.</para> - - <informaltable frame="none"> - <tgroup cols="3"> - <thead> - <row> - <entry>switch 1</entry> - <entry>switch 2</entry> - <entry>Result</entry> - </row> - </thead> - - <tbody> - <row> - <entry>On</entry> - <entry>On</entry> - <entry>Compression enabled at power-on, with host - control</entry> - </row> - - <row> - <entry>On</entry> - <entry>Off</entry> - <entry>Compression enabled at power-on, no host - control</entry> - </row> - - <row> - <entry>Off</entry> - <entry>On</entry> - <entry>Compression disabled at power-on, with host - control</entry> - </row> - - <row> - <entry>Off</entry> - <entry>Off</entry> - <entry>Compression disabled at power-on, no host - control</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Switch 3 controls MRS (Media Recognition System). MRS tapes - have stripes on the transparent leader. These identify the tape - as DDS (Digital Data Storage) grade media. Tapes that do not have - the stripes will be treated as write-protected. Switch 3 OFF - enables MRS. Switch 3 ON disables MRS.</para> - - <para>See <ulink url="http://www.hp.com/tape/c_intro.html">HP - SureStore Tape Products</ulink> and <ulink - url="http://www.impediment.com/hp/hp_technical.html">Hewlett-Packard - Disk and Tape Technical Information</ulink> for more information - on configuring this drive.</para> - - <para><emphasis>Warning:</emphasis> Quality control on these drives - varies greatly. One FreeBSD core-team member has returned 2 of - these drives. Neither lasted more than 5 months.</para> - - <para>Reported by: &a.se;</para> - </sect3> - - <sect3 id="hw-storage-hp1534a"> - <title>Hewlett-Packard HP 1534A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35470A T503</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code 0x13, - variable blocks</literal>.</para> - - <para>This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format.</para> - - <para>Native capacity is 2GB when using 90m tapes.</para> - - <para>Data transfer rate is 183kB/s.</para> - - <para>The same mechanism is used in Hewlett-Packard's SureStore - <ulink url="http://www.dmo.hp.com/tape/sst2000.htm">2000i</ulink> - tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT - drive and HP C1536A DDS format DAT drive.</para> - - <para>The HP C1534A DDS format DAT drive has two indicator lights, - one green and one amber. The green one indicates tape action: - slow flash during load, steady when loaded, fast flash during - read/write operations. The amber one indicates warnings: slow - flash when cleaning is required or tape is nearing the end of its - useful life, steady indicates an hard fault. (factory service - required?)</para> - - <para>Reported by Gary Crutcher - <email>gcrutchr@nightflight.com</email></para> - </sect3> - - <sect3 id="hw-storage-hp1553a"> - <title>Hewlett-Packard HP C1553A Autoloading DDS2</title> - - <para>The boot message identifier for this drive is "".</para> - - <para>This is a DDS-2 tape drive with a tape changer. DDS-2 means - hardware data compression and narrower tracks for increased data - capacity.</para> - - <para>Native capacity is 24GB when using 120m tapes. This drive - supports hardware data compression.</para> - - <para>Data transfer rate is 510kB/s (native).</para> - - <para>This drive is used in Hewlett-Packard's SureStore <ulink - url="http://www.dmo.hp.com/tape/sst12000.htm">12000e</ulink> - tape drive.</para> - - <para>The drive has two selectors on the rear panel. The selector - closer to the fan is SCSI id. The other selector should be set to - 7.</para> - - <para>There are four internal switches. These should be set: 1 ON; - 2 ON; 3 ON; 4 OFF.</para> - - <para>At present the kernel drivers do not automatically change - tapes at the end of a volume. This shell script can be used to - change tapes:</para> - - <programlisting>#!/bin/sh -PATH="/sbin:/usr/sbin:/bin:/usr/bin"; export PATH - -usage() -{ - echo "Usage: dds_changer [123456ne] raw-device-name - echo "1..6 = Select cartridge" - echo "next cartridge" - echo "eject magazine" - exit 2 -} - -if [ $# -ne 2 ] ; then - usage -fi - -cdb3=0 -cdb4=0 -cdb5=0 - -case $1 in - [123456]) - cdb3=$1 - cdb4=1 - ;; - n) - ;; - e) - cdb5=0x80 - ;; - ?) - usage - ;; -esac - -scsi -f $2 -s 100 -c "1b 0 0 $cdb3 $cdb4 $cdb5"</programlisting> - </sect3> - - <sect3 id="hw-storage-hp35450a"> - <title>Hewlett-Packard HP 35450A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35450A -A C620</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal></para> - - <para>This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format.</para> - - <para>Native capacity is 1.2GB.</para> - - <para>Data transfer rate is 160kB/s.</para> - - <para>Reported by: Mark Thompson - <email>mark.a.thompson@pobox.com</email></para> - </sect3> - - <sect3 id="hw-storage-hp35470a"> - <title>Hewlett-Packard HP 35470A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35470A 9 09</literal> <literal>type 1 removable SCSI - 2</literal></para> - - <para>This is a DDS-1 tape drive. DDS-1 is the original DAT tape - format.</para> - - <para>Native capacity is 2GB when using 90m tapes.</para> - - <para>Data transfer rate is 183kB/s.</para> - - <para>The same mechanism is used in Hewlett-Packard's SureStore - <ulink url="http://www.dmo.hp.com/tape/sst2000.htm">2000i</ulink> - tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT - drive, and HP C1536A DDS format DAT drive.</para> - - <para><emphasis>Warning:</emphasis> Quality control on these drives - varies greatly. One FreeBSD core-team member has returned 5 of - these drives. None lasted more than 9 months.</para> - - <para>Reported by: David Dawes - <email>dawes@rf900.physics.usyd.edu.au</email> (9 09)</para> - - </sect3> - - <sect3 id="hw-storage-hp35480a"> - <title>Hewlett-Packard HP 35480A</title> - - <para>The boot message identifier for this drive is <literal>HP - HP35480A 1009</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal>.</para> - - <para>This is a DDS-DC tape drive. DDS-DC is DDS-1 with hardware - data compression. DDS-1 is the original DAT tape format.</para> - - <para>Native capacity is 2GB when using 90m tapes. It cannot handle - 120m tapes. This drive supports hardware data compression. - Please refer to the section on <link - linkend="hw-storage-hp1533a">HP C1533A</link> for the proper - switch settings.</para> - - <para>Data transfer rate is 183kB/s.</para> - - <para>This drive is used in Hewlett-Packard's SureStore <ulink - url="http://www.dmo.hp.com/tape/sst5000.htm">5000eU</ulink> and - <ulink url="http://www.dmo.hp.com/tape/sst5000.htm">5000i</ulink> - tape drives and C35480A DDS format DAT drive..</para> - - <para>This drive will occasionally hang during a tape eject - operation (<command>mt offline</command>). Pressing the front - panel button will eject the tape and bring the tape drive back to - life.</para> - - <para>WARNING: HP 35480-03110 only. On at least two occasions this - tape drive when used with FreeBSD 2.1.0, an IBM Server 320 and an - 2940W SCSI controller resulted in all SCSI disk partitions being - lost. The problem has not be analyzed or resolved at this - time.</para> - </sect3> - - <sect3 id="hw-storage-sdt5000"> - <title><ulink - url="http://www.sel.sony.com/SEL/ccpg/storage/tape/t5000.html">Sony SDT-5000</ulink></title> - - <para>There are at least two significantly different models: one is - a DDS-1 and the other DDS-2. The DDS-1 version is - <literal>SDT-5000 3.02</literal>. The DDS-2 version is - <literal>SONY SDT-5000 327M</literal>. The DDS-2 version has a 1MB - cache. This cache is able to keep the tape streaming in almost - any circumstances.</para> - - <para>The boot message identifier for this drive is <literal>SONY - SDT-5000 3.02</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal></para> - - <para>Native capacity is 4GB when using 120m tapes. This drive - supports hardware data compression.</para> - - <para>Data transfer rate is depends upon the model or the drive. The - rate is 630kB/s for the <literal>SONY SDT-5000 327M</literal> - while compressing the data. For the <literal>SONY SDT-5000 - 3.02</literal>, the data transfer rate is 225kB/s.</para> - - <para>In order to get this drive to stream, set the blocksize to 512 - bytes (<command>mt blocksize 512</command>) reported by Kenneth - Merry <email>ken@ulc199.residence.gatech.edu</email>.</para> - - <para><literal>SONY SDT-5000 327M</literal> information reported by - Charles Henrich <email>henrich@msu.edu</email>.</para> - - <para>Reported by: &a.jmz;</para> - </sect3> - - <sect3 id="hw-storage-tandberg3600"> - <title>Tandberg TDC 3600</title> - - <para>The boot message identifier for this drive is - <literal>TANDBERG TDC 3600 =08:</literal> <literal>type 1 - removable SCSI 2</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 150/250MB.</para> - - <para>This drive has quirks which are known and work around code is - present in the SCSI tape device driver (&man.st.4;). - Upgrading the firmware to XXX version will fix the quirks and - provide SCSI 2 capabilities.</para> - - <para>Data transfer rate is 80kB/s.</para> - - <para>IBM and Emerald units will not work. Replacing the firmware - EPROM of these units will solve the problem.</para> - - <para>Reported by: &a.msmith;</para> - </sect3> - - <sect3 id="hw-storage-tandberg3620"> - <title>Tandberg TDC 3620</title> - - <para>This is very similar to the <link - linkend="hw-storage-tandberg3600">Tandberg TDC 3600</link> - drive.</para> - - <para>Reported by: &a.joerg;</para> - </sect3> - - <sect3 id="hw-storage-tandberg3800"> - <title>Tandberg TDC 3800</title> - - <para>The boot message identifier for this drive is - <literal>TANDBERG TDC 3800 =04Y</literal> <literal>Removable - Sequential Access SCSI-2 device</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 525MB.</para> - - <para>Reported by: &a.jhs;</para> - </sect3> - - <sect3 id="hw-storage-tandberg4222"> - <title>Tandberg TDC 4222</title> - - <para>The boot message identifier for this drive is - <literal>TANDBERG TDC 4222 =07</literal> <literal>type 1 removable - SCSI 2</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 2.5GB. The drive will read all cartridges - from the 60 MB (DC600A) upwards, and write 150 MB (DC6150) - upwards. Hardware compression is optionally supported for the 2.5 - GB cartridges.</para> - - <para>This drives quirks are known and pre-compiled into the SCSI - tape device driver (&man.st.4;) beginning with FreeBSD - 2.2-CURRENT. For previous versions of FreeBSD, use - <command>mt</command> to read one block from the tape, rewind the - tape, and then execute the backup program (<command>mt fsr 1; mt - rewind; dump ...</command>)</para> - - <para>Data transfer rate is 600kB/s (vendor claim with compression), - 350 KB/s can even be reached in start/stop mode. The rate - decreases for smaller cartridges.</para> - - <para>Reported by: &a.joerg;</para> - </sect3> - - <sect3 id="hw-storage-wangtek5525es"> - <title>Wangtek 5525ES</title> - - <para>The boot message identifier for this drive is <literal>WANGTEK - 5525ES SCSI REV7 3R1</literal> <literal>type 1 removable SCSI - 1</literal> <literal>density code 0x11, 1024-byte - blocks</literal></para> - - <para>This is a QIC tape drive.</para> - - <para>Native capacity is 525MB.</para> - - <para>Data transfer rate is 180kB/s.</para> - - <para>The drive reads 60, 120, 150, and 525MB tapes. The drive will - not write 60MB (DC600 cartridge) tapes. In order to overwrite 120 - and 150 tapes reliably, first erase (<command>mt erase</command>) - the tape. 120 and 150 tapes used a wider track (fewer tracks per - tape) than 525MB tapes. The <quote>extra</quote> width of the - previous tracks is not overwritten, as a result the new data lies - in a band surrounded on both sides by the previous data unless the - tape have been erased.</para> - - <para>This drives quirks are known and pre-compiled into the SCSI - tape device driver (&man.st.4;).</para> - - <para>Other firmware revisions that are known to work are: - M75D</para> - - <para>Reported by: Marc van Kempen <email>marc@bowtie.nl</email> - <literal>REV73R1</literal> Andrew Gordon - <email>Andrew.Gordon@net-tel.co.uk</email> - <literal>M75D</literal></para> - </sect3> - - <sect3 id="hw-storage-wangtek6200"> - <title>Wangtek 6200</title> - - <para>The boot message identifier for this drive is <literal>WANGTEK - 6200-HS 4B18</literal> <literal>type 1 removable SCSI - 2</literal> <literal>Sequential-Access density code - 0x13</literal></para> - - <para>This is a DDS-1 tape drive.</para> - - <para>Native capacity is 2GB using 90m tapes.</para> - - <para>Data transfer rate is 150kB/s.</para> - - <para>Reported by: Tony Kimball <email>alk@Think.COM</email></para> - </sect3> - </sect2> - - <sect2> - <title>* Problem drives</title> - - <para></para> - </sect2> - </sect1> - - <sect1> - <title>CDROM drives</title> - - <para><emphasis>Contributed by &a.obrien;. 23 November - 1997.</emphasis></para> - - <para>Generally speaking those in <emphasis>The FreeBSD - Project</emphasis> prefer SCSI CDROM drives over IDE CDROM - drives. However not all SCSI CDROM drives are equal. Some - feel the quality of some SCSI CDROM drives have been - deteriorating to that of IDE CDROM drives. Toshiba used to be - the favored stand-by, but many on the SCSI mailing list have - found displeasure with the 12x speed XM-5701TA as its volume - (when playing audio CDROMs) is not controllable by the various - audio player software.</para> - - <para>Another area where SCSI CDROM manufacturers are cutting corners is - adherence to the <link linkend="scsi-further-reading">SCSI - specification</link>. Many SCSI CDROMs will respond to <link - linkend="scsi-rogue-devices">multiple LUNs</link> for its target - address. Known violators include the 6x Teac CD-56S 1.0D.</para> - </sect1> - -</article> diff --git a/en_US.ISO8859-1/articles/vinum/Makefile b/en_US.ISO8859-1/articles/vinum/Makefile deleted file mode 100644 index 27dbbd7c65..0000000000 --- a/en_US.ISO8859-1/articles/vinum/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Bootstrapping Vinum - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml -IMAGES_EN= ad0b4aft.eps -IMAGES_EN+= ad2b4aft.eps -IMAGES_EN+= arch.eps - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/vinum/article.sgml b/en_US.ISO8859-1/articles/vinum/article.sgml deleted file mode 100644 index 730605d2cc..0000000000 --- a/en_US.ISO8859-1/articles/vinum/article.sgml +++ /dev/null @@ -1,2547 +0,0 @@ -<!-- $FreeBSD$ --> -<!-- FreeBSD Documentation Project --> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; - -<!ENTITY vinum.ap "<application>Vinum</application>"> -]> - -<article> - <articleinfo> - <title> - Bootstrapping Vinum: A Foundation for Reliable Servers - </title> - <author> - <firstname>Robert A.</firstname> - <surname>Van Valzah</surname> - </author> - <copyright> - <year>2001</year> - <holder>Robert A. Van Valzah</holder> - </copyright> - <pubdate>$Date: 2004-08-08 13:43:56 $ GMT</pubdate> - <releaseinfo>$Id: article.sgml,v 1.15 2004-08-08 13:43:56 hrs Exp $</releaseinfo> - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.general; - </legalnotice> - </articleinfo> - - <abstract> - <para> In the most abstract sense, these instructions show how - to build a pair of disk drives where either one is adequate - to keep your server running if the other fails. - Life is better if they are both working, but your server will never die - unless both disk drives die at once. - If you choose ATAPI drives and use a fairly generic kernel, you can - be confident that either of these drives can be plugged into most any - main board to produce a working server in a pinch. - The drives need not be identical. - These techniques work equally well with SCSI drives as they do with ATAPI, - but I will focus on ATAPI here because main boards with this interface are - ubiquitous. - After building the foundation of a reliable server as shown here, you - can expand to as many disk drives as necessary to build the - failure-resilient server of your dreams.</para> - </abstract> - - <section id="Introduction"> - <title>Introduction</title> - - <para>Any machine that is going to provide reliable service needs - to have either redundant components on-line or a pool of - off-line spares that can be promptly swapped in. Commodity - PC hardware makes it affordable for even small organizations - to have some spare parts available that could be pressed - into service following the failure of production equipment. - In many organizations, a failed power supply, NIC, memory, - or main board could easily be swapped with a standby in a - matter of minutes and be ready to return to production work.</para> - - <para>If a disk drive fails, however, it often has to be restored - from a tape backup. This may take many hours. With disk - drive capacities rising faster than tape drive capacities, - the time needed to restore a failed disk drive seems to - increase as technology progresses.</para> - - <para>&vinum.ap; - is a volume manager for FreeBSD that provides a standard block - I/O layer interface to the filesystem code just as any hardware - device driver would. - It works by managing partitions - of type <literal>vinum</literal> and - allows you to subdivide and group the space in such - partitions into logical devices called - <firstterm>volumes</firstterm> that - can be used in the same way as disk partitions. - Volumes can - be configured for resilience, performance, or both. Experienced - system administrators will immediately recognize the benefits - of being able to configure each filesystem to match the way - it is most often used.</para> - - <para>In some ways, <application>Vinum</application> is similar to - &man.ccd.4;, but it is far more flexible and robust in the face - of failures. - It is only slightly more difficult to set up than &man.ccd.4;. - &man.ccd.4; may meet your needs if you are only interested in - concatenation.</para> - - <section id="Terminology"> - <title>Terminology</title> - - <para>Discussion of storage management can get very tricky - simply because of the terminology involved. - As we will see below, - the terms <firstterm>disk</firstterm>, - <firstterm>slice</firstterm>, <firstterm>partition</firstterm>, - <firstterm>subdisk</firstterm>, and <firstterm>volume</firstterm> - each refer to different things that present the same interface - to a kernel function like swapping. - The potential for confusion is compounded because the objects - that these terms represent can be nested inside each other.</para> - - <para>I will refer to a physical disk drive as a - <firstterm>spindle</firstterm>. - A <firstterm>partition</firstterm> here means a BSD partition as - maintained by <command>disklabel</command>. - It does not refer to <firstterm>slices</firstterm> or - <firstterm>BIOS partitions</firstterm> as - maintained by <command>fdisk</command>.</para> - </section> - - <section id="Objects"> - <title>Vinum Objects</title> - - <para><application>Vinum</application> - defines a hierarchy of four objects that it uses to manage storage - (see <xref linkend="arch">). - Different combinations of these objects are used to achieve - failure resilience, performance, and/or extra capacity. - I will give a whirlwind tour of the objects here--see the - <ulink url="http://www.vinumvm.org/">Vinum web site</ulink> - for a more thorough description.</para> - - <figure id="arch"> - <title>Vinum Objects and Architecture</title> - - <mediaobject> - <imageobject> - <imagedata fileref="arch" format="EPS"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+-----+------+------+ -| UFS | swap | Etc. | -+---+-+------+----+ + -| volume | | -+ V +-------------+ + -| i plex | | -+ n +-------------+ + -| u subdisk | | -+ m +-------------+ + -| drive | | -+-----------------+ + -| Block I/O devices | -+-------------------+</literallayout> - </textobject> - - <textobject> - <phrase>Vinum Objects and Architecture</phrase> - </textobject> - </mediaobject> - </figure> - - <para>The top object, a vinum <firstterm>volume</firstterm>, - implements a virtual disk that - provides a standard block I/O layer - interface to other parts of the kernel. - The bottom object, a vinum <firstterm>drive</firstterm>, - uses this same interface to - request I/O from physical devices below it.</para> - - <para>In between these two (from top to bottom) we have objects called - a vinum <firstterm>plex</firstterm> - and a vinum <firstterm>subdisk</firstterm>. - As you can probably guess from the name, a vinum subdisk is a - contiguous subset of the space available on a vinum drive. - It lets you subdivide a vinum drive in much the same way that - a disk BSD partition lets you subdivide a BIOS slice.</para> - - <para>A plex allows subdisks to be grouped together making the space - of all subdisks available as a single object.</para> - - <para>A plex can be organized with its constituent subdisks concatenated - or striped. - Both organizations are useful for spreading I/O requests across - spindles since plexes reside on distinct spindles. - A striped plex will switch spindles each time a multiple of the - stripe size is reached. - A concatenated plex will switch spindles only when the end of - a subdisk is reached.</para> - - <para>An important characteristic of a - <application>Vinum</application> volume is that it can be - made up of more than one plex. - In this case, writes go to all plexes and a read may be satisfied - by any plex. - Configuring two or more plexes on distinct spindles yields a - volume that is resilient to failure.</para> - - <para><application>Vinum</application> maintains a - <firstterm>configuration</firstterm> - that defines instances of the above objects and the way they - are related to each other. - This configuration is automatically written to all spindles under - <application>Vinum</application> management whenever it changes.</para> - </section> - - <section id="Organizations"> - <title>Vinum Volume/Plex Organization</title> - - <para>Although <application>Vinum</application> - can manage any number of spindles, - I will only cover scenarios with two spindles here - for simplification. - See <xref linkend=OrgCompare> to see how - two spindles organized with <application>Vinum</application> - compare to two spindles without <application>Vinum</application>.</para> - - <para> - <table id=OrgCompare frame=all> - <title>Characteristics of Two Spindles Organized with Vinum</title> - - <tgroup cols="5"> - <thead> - <row> - <entry>Organization</entry> - <entry>Total Capacity</entry> - <entry>Failure Resilient</entry> - <entry>Peak Read Performance</entry> - <entry>Peak Write Performance</entry> - </row> - </thead> - <tbody> - <row> - <entry>Concatenated Plexes</entry> - <entry>Unchanged, but appears as a single drive</entry> - <entry>No</entry> - <entry>Unchanged</entry> - <entry>Unchanged</entry> - </row> - <row> - <entry>Striped Plexes (RAID-0)</entry> - <entry>Unchanged, but appears as a single drive</entry> - <entry>No</entry> - <entry>2x</entry> - <entry>2x</entry> - </row> - <row> - <entry>Mirrored Volumes (RAID-1)</entry> - <entry>1/2, appearing as a single drive</entry> - <entry>Yes</entry> - <entry>2x</entry> - <entry>Unchanged</entry> - </row> - </tbody> - </tgroup> - </table> - </para> - - <para><xref linkend=OrgCompare> shows that striping yields - the same capacity and lack of failure resilience - as concatenation, but it has better peak read and write performance. - Hence we will not be using concatenation in any of the examples here. - Mirrored volumes provide the benefits of improved peak read performance - and failure resilience--but this comes at a loss in capacity.</para> - - <note><para>Both concatenation and striping bring their benefits over a - single spindle at the cost of increased likelihood of failure since - more than one spindle is now involved.</para></note> - - <para>When three or more spindles are present, - <application>Vinum</application> also supports rotated, - block-interleaved parity (also called <firstterm>RAID-5</firstterm>) - that provides better - capacity than mirroring (but not quite as good as striping), better - read performance than both mirroring and striping, - and good failure resilience. - There is, however, - a substantial decrease in write performance with RAID-5. - Most of the benefits become more pronounced with five or more - spindles.</para> - - <para>The organizations described above may be combined to provide - benefits that no single organization can match. - For example, mirroring and striping can be combined to provide - failure-resilience with very fast read performance.</para> - - </section> - - <section id="History"> - <title>Vinum History</title> - - <para><application>Vinum</application> - is a standard part of even a "minimum" FreeBSD distribution and - it has been standard since 3.0-RELEASE. - The official pronunciation of the name is - <emphasis>VEE-noom</emphasis>.</para> - - <para>&vinum.ap; was inspired by the Veritas Volume Manager, but - was not derived from it. - The name is a play on that history and the Latin adage - <foreignphrase>In Vino Veritas</foreignphrase> - (<foreignphrase>Vino</foreignphrase> is the ablative form of - <foreignphrase>Vinum</foreignphrase>). - Literally translated, that is <quote>Truth lies in wine</quote> hinting that - drunkards have a hard time lying. - </para> - - <para>I have been using it in production on six different servers for - over two years with no data loss. - Like the rest of FreeBSD, <application>Vinum</application> - provides <quote>rock-stable performance.</quote> - (On a personal note, I have seen <application>Vinum</application> - panic when I misconfigured something, but I have - never had any trouble in normal operation.) - Greg Lehey wrote - <application>Vinum</application> for FreeBSD, - but he is seeking - help in porting it to NetBSD and OpenBSD.</para> - - <warning> - <para>Just like the rest of FreeBSD, <application>Vinum</application> - is undergoing continuous - development. - Several subtle, but significant bugs have been fixed in recent - releases. - It is always best to use the most recent code base that meets your - stability requirements.</para></warning> - - </section> - - <section id="Strategy"> - <title>Vinum Deployment Strategy</title> - - <para><application>Vinum</application>, - coupled with prudent partition management, lets you - keep <quote>warm-spare</quote> spindles on-line so that failures - are transparent to users. Failed spindles can be replaced - during regular maintenance periods or whenever it is convenient. - When all spindles are working, the server benefits from increased - performance and capacity.</para> - - <para>Having redundant copies of your home directory does not - help you if the spindle holding root, - <filename>/usr</filename>, or swap fails on your server. - Hence I focus here on building a simple - foundation for a failure-resilient server covering the root, - <filename>/usr</filename>, - <filename>/home</filename>, and swap partitions.</para> - - <warning> - <para><application>Vinum</application> - mirroring does not remove the need for making backups! - Mirroring cannot help you recover from site disasters - or the dreaded - <command>rm -r -f /</command> command.</para></warning> - </section> - - <section id="WhyBootstrap"> - <title>Why Bootstrap Vinum?</title> - - <para>It is possible to add <application>Vinum</application> - to a server configuration after - it is already in production use, but this is much harder than - designing for it from the start. Ironically, - <application>Vinum</application> is not supported by - <command>/stand/sysinstall</command> - and hence you cannot install - <filename>/usr</filename> right onto a - <application>Vinum</application> volume.</para> - - <note><para><application>Vinum</application> currently does not - support the root filesystem (this feature - is in development).</para></note> - - <para>Hence it is a bit - tricky to get started using - <application>Vinum</application>, but these instructions - take you though the process of planning for - <application>Vinum</application>, installing FreeBSD - without it, and then beginning to use it.</para> - - <para>I have come to call this whole process <quote>bootstrapping Vinum.</quote> - That is, the process of getting <application>Vinum</application> - initially installed - and operating to the point where you have met your resilience - or performance goals. My purpose here is to document a - <application>Vinum</application> - bootstrapping method that I have found that works well for me.</para> - </section> - - <section id="Benefits"> - <title>Vinum Benefits</title> - - <para>The server foundation scenario I have chosen here allows me - to show you examples of configuring for resilience on - <filename>/usr</filename> and - <filename>/home</filename>. - Yet <application>Vinum</application> - provides benefits other than resilience--namely - performance, capacity, and manageability. - It can significantly improve disk performance (especially - under multi-user loads). - <application>Vinum</application> - can easily concatenate many smaller disks to produce the - illusion of a single larger disk (but my server foundation - scenario does not allow me to illustrate these benefits here).</para> - - <para>For servers with many spindles, <application>Vinum</application> - provides substantial - benefits in volume management, particularly when coupled with - hot-pluggable hardware. Data can be moved from spindle to - spindle while the system is running without loss of production - time. Again, details of this will not be given here, but once - you get your feet wet with <application>Vinum</application>, - other documentation will help you do things like this. - See - "<ulink url="http://www.vinumvm.org/vinum/vinum.ps">The Vinum - Volume Manager</ulink>" for a technical introduction to - <application>Vinum</application>, - &man.vinum.8; for a description of the <command>vinum</command> - command, and - &man.vinum.4; - for a description of the vinum device - driver and the way <application>Vinum</application> - objects are named.</para> - - <note> - <para>Breaking up your disk space into smaller and smaller partitions - has the benefit of allowing you to <quote>tune</quote> for the most common - type of access and tends to keep disk hogs <quote>within their pens.</quote> - However it also causes some loss in total available disk space - due to fragmentation.</para></note> - </section> - - <section id="DegradedOperation"> - <title>Server Operation in Degraded Mode</title> - - <para>Some disk failures in this two-spindle scenario will result in - <application>Vinum</application> - automatically routing - all disk I/O to the remaining good spindle. - Others will require brief manual intervention on the console - to configure the server for degraded mode operation and a quick reboot. - Other than actual hardware repairs, most recovery work - can be done while the server is running in multi-user degraded - mode so there is as little production impact - from failures as possible.</para> - - <para>I give the instructions in <xref linkend=Failures> needed to - configure the server for degraded mode operation - in those cases where <application>Vinum</application> - cannot do it automatically. - I also give the instructions needed to - return to normal operation once the failed hardware is repaired. - You might call these instructions <application>Vinum</application> - failure recovery techniques.</para> - - <para>I recommend practicing using these instructions - by recovering from simulated failures. - For each failure scenario, I also give tips below for simulating - a failure even when your hardware is working well. - Even a minimum <application>Vinum</application> - system as described in - <xref linkend="HW"> - below can be a good place to experiment with - recovery techniques without impacting production equipment.</para> - </section> - - <section id="HWvsSW"> - <title>Hardware RAID vs. Vinum (Software RAID)</title> - - <para>Manual intervention is sometimes required to configure a server for - degraded mode because - <application>Vinum</application> - is implemented in software that runs after the FreeBSD - kernel is loaded. One disadvantage of such - <firstterm>software RAID</firstterm> - solutions is that there is nothing that can be done to hide spindle - failures from the BIOS or the FreeBSD boot sequence. Hence - the manual reconfiguration of the server - for degraded operation mentioned - above just informs the BIOS and boot sequence of failed - spindles. - <firstterm>Hardware RAID</firstterm> solutions generally have an - advantage in that they require no such reconfiguration since - spindle failures are hidden from the BIOS and boot sequence.</para> - - <para>Hardware RAID, however, may have some disadvantages that can - be significant in some cases: - <itemizedlist> - <listitem><para> - The hardware RAID controller itself may become a single - point of failure for the system. - </para></listitem> - <listitem><para> - The data is usually kept in a proprietary - format so that a disk drive cannot be simply plugged - into another main board and booted. - </para></listitem> - <listitem><para> - You often cannot mix and - match drives with different sizes and interfaces. - </para></listitem> - <listitem><para> - You are often limited to the number of drives supported by the - hardware RAID controller (often only four or eight). - </para></listitem> - </itemizedlist> - In other words, &vinum.ap; may offer advantages in that - there is no single point of failure, - the drives can boot on most any main board, and - you are free to mix and match as many drives using - whatever interface you choose.</para> - - <tip> - <para>Keep your kernel fairly generic (or at least keep - <filename>/kernel.GENERIC</filename> around). - This will improve the chances that you can come back up on - <quote>foreign</quote> hardware more quickly.</para> - </tip> - - <para>The pros and cons discussed above suggest - that the root filesystem and swap partition are good - candidates for hardware RAID if available. - This is especially true for servers where it is difficult for - administrators to get console access (recall that this is sometimes - required to configure a server for degraded mode operation). - A server with only software RAID is well suited to office and home - environments where an administrator can be close at hand.</para> - - <note><para>A common myth is that hardware RAID is always faster - than software RAID. - Since it runs on the host CPU, <application>Vinum</application> - often has more CPU power and memory available than a - dedicated RAID controller would have. - If performance is a prime concern, it is best to benchmark - your application running on your CPU with your spindles using - both hardware and software RAID systems before making - a decision.</para></note> - - </section> - - <section id="HW"> - <title>Hardware for Vinum</title> - - <para>These instructions may be timely since commodity PC hardware - can now easily host several hundred gigabytes of reasonably - high-performance disk space at a low price. Many disk - drive manufactures now sell 7,200 RPM disk drives with quite - low seek times and high transfer rates through ATA-100 - interfaces, all at very attractive prices. Four such drives, - attached to a suitable main board and configured with - <application>Vinum</application> - and prudent partitioning, yields a failure-resilient, high - performance disk server at a very reasonable cost.</para> - - <para>However, you can indeed get started with - <application>Vinum</application> very simply. - A minimum system can be as simple as - an old CPU (even a 486 is fine) and a pair of drives - that are 500 MB or more. They need not be the same size or - even use the same interface (i.e., it is fine to mix ATAPI and - SCSI). So get busy and give this a try today! You will have - the foundation of a failure-resilient server running in an - hour or so!</para> - </section> - </section> - - <section id="BootstrappingPhases"> - <title>Bootstrapping Phases</title> - - <para>Greg Lehey suggested this bootstrapping method. - It uses knowledge of how <application>Vinum</application> - internally allocates disk space to avoid copying data. - Instead, <application>Vinum</application> - objects are configured so that they occupy the - same disk space where <command>/stand/sysinstall</command> built - filesystems. - The filesystems are thus embedded within - <application>Vinum</application> objects without copying.</para> - - <para>There are several distinct phases to the - <application>Vinum</application> bootstrapping - procedure. Each of these phases is presented in a separate section below. - The section starts with a general overview of the phase and its goals. - It then gives example steps for the two-spindle scenario - presented here and advice on how to adapt them for your server. - (If you are reading for a general understanding - of <application>Vinum</application> - bootstrapping, the example sections for each phase - can safely be skipped.) - The remainder of this section gives - an overview of the entire bootstrapping process.</para> - - <para>Phase 1 involves planning and preparation. - We will balance requirements - for the server against available resources and make design - tradeoffs. - We will plan the transition from no - <application>Vinum</application> to - <application>Vinum</application> - on just one spindle, to <application>Vinum</application> - on two spindles.</para> - - <para>In phase 2, we will install a minimum FreeBSD system on a - single spindle using partitions of type - <literal>4.2BSD</literal> (regular UFS filesystems).</para> - - <para>Phase 3 will embed the non-root filesystems from phase 2 in - <application>Vinum</application> objects. - Note that <application>Vinum</application> will be up and - running at this point, - but it cannot yet provide any resilience since it only has - one spindle on which to store data.</para> - - <para>Finally in phase 4, we configure <application>Vinum</application> - on a second spindle and make a backup copy of the root filesystem. - This will give us resilience on all filesystems.</para> - - <section id="P1"> - <title>Bootstrapping Phase 1: Planning and Preparation</title> - - <para>Our goal in this phase is to define the different partitions - we will need and examine their requirements. - We will also look at available disk drives and controllers and allocate - partitions to them. - Finally, we will determine the size of - each partition and its use during the bootstrapping process. - After this planning is complete, we can optionally prepare to use some - tools that will make bootstrapping <application>Vinum</application> - easier.</para> - - <para>Several key questions must be answered in this - planning phase:</para> - - <itemizedlist> - <listitem><para> - What filesystem and partitions will be needed? - </para></listitem> - <listitem><para> - How will they be used? - </para></listitem> - <listitem><para> - How will we name each spindle? - </para></listitem> - <listitem><para> - How will the partitions be ordered for each spindle? - </para></listitem> - <listitem><para> - How will partitions be assigned to the spindles? - </para></listitem> - <listitem><para> - How will partitions be configured? Resilience or performance? - </para></listitem> - <listitem><para> - What technique will be used to achieve resilience? - </para></listitem> - <listitem><para> - What spindles will be used? - </para></listitem> - <listitem><para> - How will they be configured on the available controllers? - </para></listitem> - <listitem><para> - How much space is required for each partition? - </para></listitem> - </itemizedlist> - - <section id="P1E"> - <title>Phase 1 Example</title> - - <para>In this example, I will assume a scenario - where we are building - a minimal foundation for a failure-resilient server. - Hence we will need at least root, - <filename>/usr</filename>, - <filename>/home</filename>, - and swap partitions. - The root, - <filename>/usr</filename>, and - <filename>/home</filename> filesystems all need resilience since the - server will not be much good without them. - The swap partition needs performance first and - generally does - not need resilience since nothing it holds needs to be retained - across a reboot.</para> - - <section> - <title>Spindle Naming</title> - - <para>The kernel would refer to the master spindle on - the primary and secondary ATA controllers as - <devicename>/dev/ad0</devicename> and - <devicename>/dev/ad2</devicename> respectively. - <footnote> - <para> - This assumes that you have not removed the line - <programlisting>options ATA_STATIC_ID</programlisting> - from your kernel configuration. - </para> - </footnote> - But <application>Vinum</application> - also needs to have a name for each spindle - that will stay the same name regardless - of how it is attached to the CPU (i.e., if the drive moves, the - <application>Vinum</application> name moves with the drive).</para> - - <para>Some recovery techniques documented below suggest - moving a spindle from - the secondary ATA controller to the primary ATA controller. - (Indeed, the flexibility of making such moves is a key benefit - of <application>Vinum</application> - especially if you are managing a large number of spindles.) - After such a drive/controller swap, - the kernel will see what used to be - <devicename>/dev/ad2</devicename> as - <devicename>/dev/ad0</devicename> - but <application>Vinum</application> - will still call - it by whatever name it had when it was attached to - <devicename>/dev/ad2</devicename> - (i.e., when it was <quote>created</quote> or first made known to - <application>Vinum</application>).</para> - - <para>Since connections can change, it is best to give - each spindle a unique, abstract - name that gives no hint of how it is attached. - Avoid names that suggest a manufacturer, model number, - physical location, or membership in a sequence - (e.g. avoid names like - <literal>upper</literal>, <literal>lower</literal>, etc., - <literal>alpha</literal>, <literal>beta</literal>, etc., - <literal>SCSI1</literal>, <literal>SCSI2</literal>, etc., or - <literal>Seagate1</literal>, <literal>Seagate2</literal> etc.). - Such names are likely to lose their uniqueness or - get out of sequence - someday even if they seem like great names today.</para> - - <tip> - <para>Once you have picked names for your spindles, - label them with a permanent marker. - If you have hot-swappable hardware, write the names on the sleds - in which the spindles are mounted. - This will significantly reduce the likelihood of - error when you are moving spindles around later as - part of failure recovery or routine system management - procedures.</para></tip> - - <para>In the instructions that follow, - <application>Vinum</application> - will name the root spindle <literal>YouCrazy</literal> - and the rootback spindle <literal>UpWindow</literal>. - I will only use <devicename>/dev/ad0</devicename> - when I want to refer to whichever - of the two spindles is currently attached as - <devicename>/dev/ad0</devicename>.</para> - </section> - - <section> - <title>Partition Ordering</title> - - <para>Modern disk drives operate with fairly uniform areal - density across the surface of the disk. - That implies that more data is available under the heads without - seeking on the outer cylinders than on the inner cylinders. - We will allocate partitions most critical to system performance - from these outer cylinders as - <command>/stand/sysinstall</command> generally does.</para> - - <para>The root filesystem is traditionally the outermost, even though - it generally is not as critical to system performance as others. - (However root can have a larger impact on performance if it contains - <filename>/tmp</filename> and <filename>/var</filename> as it - does in this example.) - The FreeBSD boot loaders assume that the - root filesystem lives in the <literal>a</literal> partition. - There is no requirement that the <literal>a</literal> - partition start on the outermost cylinders, but this - convention makes it easier to manage disk labels.</para> - - <para>Swap performance is critical so it comes next on our way toward - the center. - I/O operations here tend to be large and contiguous. - Having as much data under the heads as possible avoids seeking - while swapping.</para> - - <para>With all the smaller partitions out of the way, we finish - up the disk with - <filename>/home</filename> and - <filename>/usr</filename>. - Access patterns here tend not to be as intense as for other - filesystems (especially if there is an abundant supply of RAM - and read cache hit rates are high).</para> - - <para>If the pair of spindles you have are large enough to allow - for more than - <filename>/home</filename> and - <filename>/usr</filename>, - it is fine to plan for additional filesystems here.</para> - - </section> - - <section> - <title>Assigning Partitions to Spindles</title> - - <para>We will want to assign - partitions to these spindles so that either can fail - without loss of data on filesystems configured for - resilience.</para> - - <para>Reliability on - <filename>/usr</filename> and - <filename>/home</filename> - is best achieved using <application>Vinum</application> - mirroring. - Resilience will have to come differently, however, for the root - filesystem since <application>Vinum</application> - is not a part of the FreeBSD boot sequence. - Here we will have to settle for two identical - partitions with a periodic copy from the primary to the - backup secondary.</para> - - <para>The kernel already has support for interleaved swap across - all available partitions so there is no need for help from - <application>Vinum</application> here. - <command>/stand/sysinstall</command> - will automatically configure <filename>/etc/fstab</filename> - for all swap partitions given.</para> - - <para>The &vinum.ap; bootstrapping method given below - requires a pair of spindles that I will call the - <firstterm>root spindle</firstterm> and the - <firstterm>rootback spindle</firstterm>.</para> - - <important><para>The rootback spindle must be the same size or - larger than the root spindle.</para></important> - - <para>These instructions first allocate all space on the root - spindle and then allocate exactly that amount of space on - a rootback spindle. - (After &vinum.ap; is bootstrapped, there is nothing special - about either of these spindles--they are interchangeable.) - You can later use the remaining space on the rootback spindle for - other filesystems.</para> - - <para>If you have more than two spindles, the - <literal>bootvinum</literal> Perl script and the procedure - below will help you initialize them for use with &vinum.ap;. - However you will have to figure out how to assign partitions - to them on your own.</para> - - </section> - - <section> - <title>Assigning Space to Partitions</title> - - <para>For this example, I will use two spindles: one with - 4,124,673 blocks (about 2 GB) on <devicename>/dev/ad0</devicename> - and one with 8,420,769 blocks (about 4 GB) on - <devicename>/dev/ad2</devicename>.</para> - - <para>It is best to configure your two spindles on separate - controllers so that both can operate in parallel and - so that you will have failure resilience in case a - controller dies. - Note that mirrored volume write performance will be halved - in cases where both spindles share a controller that requires - they operate serially (as is often the case with ATA controllers). - One spindle will be the master on the primary ATA - controller and the other will be the master on the - secondary ATA controller.</para> - - <para>Recall that we will be allocating space on the smaller - spindle first and the larger spindle second.</para> - - </section> - - <section id=AssignSmall> - <title>Assigning Partitions on the Root Spindle</title> - - <para>We will allocate 200,000 blocks (about 93 MB) - for a root filesystem on each spindle - (<devicename>/dev/ad0s1a</devicename> and - <devicename>/dev/ad2s1a</devicename>). - We will initially allocate 200,265 blocks for a swap partition - on each spindle, - giving a total of about 186 MB of - swap space (<devicename>/dev/ad0s1b</devicename> and - <devicename>/dev/ad2s1b</devicename>).</para> - - <note><para>We will lose 265 blocks from each swap partition - as part of the bootstrapping process. - This is the size of the space used by - <application>Vinum</application> to store configuration - information. - The space will be taken from swap and given to a vinum - partition but will be unavailable for - <application>Vinum</application> subdisks.</para></note> - - <note><para>I have done the partition allocation in nice round - numbers of blocks just to emphasize where the 265 blocks go. - There is nothing wrong with allocating space in MB if that is - more convenient for you.</para></note> - - <para>This leaves 4,124,673 - 200,000 - 200,265 = 3,724,408 blocks - (about 1,818 MB) on the root spindle for - <application>Vinum</application> - partitions (<devicename>/dev/ad0s1e</devicename> and - <devicename>/dev/ad2s1f</devicename>). - From this, allocate the 265 blocks for - <application>Vinum</application> configuration information, - 1,000,000 blocks (about 488 MB) - for <filename>/home</filename>, and the remaining - 2,724,408 blocks (about 1,330 MB) for - <filename>/usr</filename>. - See <xref linkend=ad0b4aft> below to see this graphically.</para> - - <para>The left-hand side of - <xref linkend="ad0b4aft"> below shows what spindle ad0 will - look like at the end of phase 2. - The right-hand side shows what it will look like at the - end of phase 3.</para> - - <figure id="ad0b4aft"> - <title>Spindle ad0 Before and After Vinum</title> - - <mediaobject> - <imageobject> - <imagedata fileref="ad0b4aft" format="EPS"> - </imageobject> - - <textobject> - <literallayout class="monospaced"> ad0 Before Vinum Offset (blocks) ad0 After Vinum -+----------------------+ <-- 0--> +----------------------+ -| root | | root | -| /dev/ad0s1a | | /dev/ad0s1a | -+----------------------+ <-- 200000--> +----------------------+ -| swap | | swap | -| /dev/ad0s1b | | /dev/ad0s1b | -| | 400000--> +----------------------+ -| | | Vinum drive YouCrazy | -| | | /dev/ad0s1h | -+----------------------+ <-- 400265--> +-----------------+ | -| /home | | Vinum sd | | -| /dev/ad0s1e | | home.p0.s0 | | -+----------------------+ <--1400265--> +-----------------+ | -| /usr | | Vinum sd | | -| /dev/ad0s1f | | usr.p0.s0 | | -+----------------------+ <--4124673--> +-----------------+----+ -Not to scale</literallayout> - </textobject> - - <textobject> - <phrase>Spindle /dev/ad0 Before and After Vinum</phrase> - </textobject> - </mediaobject> - </figure> - - </section> - - <section id=AssignLarge> - <title>Assigning Partitions on the Rootback Spindle</title> - - <para>The <filename>/rootback</filename> and swap partition sizes - on the rootback spindle must - match the root and swap partition sizes on the root spindle. - That leaves 8,420,769 - 200,000 - 200,265 = 8,020,504 - blocks for the <application>Vinum</application> partition. - Mirrors of <filename>/home</filename> and - <filename>/usr</filename> receive the same allocation as on - the root spindle. - That will leave an extra 2 GB or so that we can deal - with later. - See <xref linkend=ad2b4aft> below to see this graphically.</para> - - <para>The left-hand side of - <xref linkend="ad2b4aft"> below shows what spindle ad2 will - look like at the beginning of phase 4. - The right-hand side shows what it will look like at the end.</para> - - <figure id="ad2b4aft"> - <title>Spindle ad2 Before and After Vinum</title> - - <mediaobject> - <imageobject> - <imagedata fileref="ad2b4aft" format="EPS"> - </imageobject> - - <textobject> - <literallayout class="monospaced"> ad2 Before Vinum Offset (blocks) ad2 After Vinum -+----------------------+ <-- 0--> +----------------------+ -| /rootback | | /rootback | -| /dev/ad2s1e | | /dev/ad2s1a | -+----------------------+ <-- 200000--> +----------------------+ -| swap | | swap | -| /dev/ad2s1b | | /dev/ad2s1b | -| | 400000--> +----------------------+ -| | | Vinum drive UpWindow | -| | | /dev/ad2s1h | -+----------------------+ <-- 400265--> +-----------------+ | -| /NOFUTURE | | Vinum sd | | -| /dev/ad2s1f | | home.p1.s0 | | -| | 1400265--> +-----------------+ | -| | | Vinum sd | | -| | | usr.p1.s0 | | -| | 4124673--> +-----------------+ | -| | | Vinum sd | | -| | | hope.p0.s0 | | -+----------------------+ <--8420769--> +-----------------+----+ -Not to scale</literallayout> - </textobject> - - <textobject> - <phrase>Spindle ad2 Before and After Vinum</phrase> - </textobject> - </mediaobject> - </figure> - - </section> - - <section id=floppy> - <title>Preparation of Tools</title> - - <para>The <literal>bootvinum</literal> Perl script given below in - <xref linkend=Perl> will make the - <application>Vinum</application> bootstrapping process much - easier if you can run it on the machine being bootstrapped. - It is over 200 lines and you would not want to type it in. - At this point, I recommend that you - copy it to a floppy or arrange some - alternative method of making it readily available - so that it can be available later when needed. - For example:</para> - -<screen>&prompt.root; <userinput>fdformat -f 1440 /dev/fd0</userinput> -&prompt.root; <userinput>newfs_msdos -f 1440 /dev/fd0</userinput> -&prompt.root; <userinput>mount_msdos /dev/fd0 /mnt</userinput> -&prompt.root; <userinput>cp /usr/share/examples/vinum/bootvinum /mnt</userinput></screen> - - <para>XXX Someday, I would like this script to live in - <filename>/usr/share/examples/vinum</filename>. - Till then, please use this - <ulink url="http://www.BGPBook.Com/vinum/bootvinum">link</ulink> - to get a copy.</para> - </section> - </section> - </section> - - <section id="P2"> - <title>Bootstrapping Phase 2: Minimal OS Installation</title> - - <para>Our goal in this phase is to complete the smallest possible - FreeBSD installation in such a way that we can later install - <application>Vinum</application>. - We will use only - partitions of type <literal>4.2BSD</literal> (i.e., regular UFS file - systems) since that is the only type supported by - <command>/stand/sysinstall</command>.</para> - - <section id="P2E"> - <title>Phase 2 Example</title> - - <procedure> - <step> - <para>Start up the FreeBSD installation process by running - <command>/stand/sysinstall</command> from - installation media as you normally would.</para></step> - - <step> - <para>Fdisk partition all spindles as needed.</para> - - <important> - <para>Make sure to select BootMgr for all spindles.</para></important> - </step> - - <step> - <para>Partition the root spindle with appropriate block - allocations as described above in <xref linkend=AssignSmall>. - For this example on a 2 GB spindle, I will use - 200,000 blocks for root, 200,265 blocks for swap, - 1,000,000 blocks for <filename>/home</filename>, and - the rest of the spindle (2,724,408 blocks) for - <filename>/usr</filename>. - (<command>/stand/sysinstall</command> - should automatically assign these to - <devicename>/dev/ad0s1a</devicename>, - <devicename>/dev/ad0s1b</devicename>, - <devicename>/dev/ad0s1e</devicename>, and - <devicename>/dev/ad0s1f</devicename> - by default.)</para> - - <note><para>If you prefer Soft Updates as I do and you are - using 4.4-RELEASE or better, this is a good time to enable - them.</para></note> - - </step> - - <step> - <para>Partition the rootback spindle with the appropriate block - allocations as described above in <xref linkend=AssignLarge>. - For this example on a 4 GB spindle, I will use - 200,000 blocks for <filename>/rootback</filename>, - 200,265 blocks for swap, and - the rest of the spindle (8,020,504 blocks) for - <filename>/NOFUTURE</filename>. - (<command>/stand/sysinstall</command> - should automatically assign these to - <devicename>/dev/ad2s1e</devicename>, - <devicename>/dev/ad2s1b</devicename>, and - <devicename>/dev/ad2s1f</devicename> by default.)</para> - - <note> - <para>We do not really want to have a - <filename>/NOFUTURE</filename> UFS filesystem (we - want a vinum partition instead), but that is the - best choice we have for the space given the limitations of - <command>/stand/sysinstall</command>. - Mount point names beginning with <literal>NOFUTURE</literal> - and <literal>rootback</literal> - serve as sentinels to the bootstrapping - script presented in <xref linkend=Perl> below.</para></note> - </step> - - <step> - <para>Partition any other spindles with swap if desired and a - single <filename>/NOFUTURExx</filename> filesystem.</para> - </step> - - <step> - <para>Select a minimum system install for now even if you - want to end up with more distributions loaded later.</para> - - <tip> - <para>Do not worry about system configuration options at this - point--get <application>Vinum</application> - set up and get the partitions in - the right places first.</para></tip> - </step> - - <step> - <para>Exit <command>/stand/sysinstall</command> and reboot. - Do a quick test to verify that the minimum - installation was successful.</para> - </step> - </procedure> - - <para>The left-hand side of <xref linkend=ad0b4aft> above - and the left-hand side of <xref linkend=ad2b4aft> above - show how the disks will look at this point.</para> - </section> - </section> - - <section id="P3"> - <title>Bootstrapping Phase 3: Root Spindle Setup</title> - - <para>Our goal in this phase is get <application>Vinum</application> - set up and running on the - root spindle. - We will embed the existing - <filename>/usr</filename> and - <filename>/home</filename> filesystems in a - <application>Vinum</application> partition. - Note that the <application>Vinum</application> - volumes created will not yet be - failure-resilient since we have - only one underlying <application>Vinum</application> - drive to hold them. - The resulting system will automatically start - <application>Vinum</application> as it boots to multi-user mode.</para> - - <section id="P3E"> - <title>Phase 3 Example</title> - - <procedure> - <step> - <para>Login as root.</para> - </step> - - <step> - <para>We will need a directory in the root filesystem in - which to keep a few files that will be used in the - <application>Vinum</application> - bootstrapping process.</para> - - <screen>&prompt.root; <userinput>mkdir /bootvinum</userinput> -&prompt.root; <userinput>cd /bootvinum</userinput></screen> - </step> - - <step> - <para>Several files need to be prepared for use in bootstrapping. - I have written a Perl script that makes all the required - files for you. - Copy this script to <filename>/bootvinum</filename> by - floppy disk, tape, network, or any convenient means and - then run it. - (If you cannot get this script copied onto the machine being - bootstrapped, then see <xref linkend=ManualBoot> - below for a manual alternative.)</para> - - <screen>&prompt.root; <userinput>cp /mnt/bootvinum .</userinput> -&prompt.root; <userinput>./bootvinum</userinput></screen> - - <note><para><literal>bootvinum</literal> produces no output - when run successfully. - If you get any errors, - something may have gone wrong when you were creating - partitions with - <command>/stand/sysinstall</command> above.</para></note> - - <para>Running <literal>bootvinum</literal> will:</para> - - <itemizedlist> - <listitem><para> - Create <filename>/etc/fstab.vinum</filename> - based on what it finds - in your existing <filename>/etc/fstab</filename> - </para></listitem> - <listitem><para> - Create new disk labels for each spindle mentioned - in <filename>/etc/fstab</filename> and keep copies of the - current disk labels - </para></listitem> - <listitem><para> - Create files needed as input to <command>vinum</command> - <option>create</option> for building - <application>Vinum</application> objects on each spindle - </para></listitem> - <listitem><para> - Create many alternates to <filename>/etc/fstab.vinum</filename> - that might come in handy should a spindle fail - </para></listitem> - </itemizedlist> - - <para>You may want to take a look at these files to learn more - about the disk partitioning required for - <application>Vinum</application> or to learn more about the - commands needed to create - <application>Vinum</application> objects.</para> - - </step> - - <step> - <para>We now need to install new spindle partitioning for - <devicename>/dev/ad0</devicename>. - This requires that - <devicename>/dev/ad0s1b</devicename> not be in use for - swapping so we have to reboot in single-user mode.</para> - - <substeps> - <step> - <para>First, reboot the system.</para> - - <screen>&prompt.root; <userinput>reboot</userinput></screen> - </step> - - <step> - <para>Next, enter single-user mode.</para> - <screen>Hit [Enter] to boot immediately, or any other key for command prompt. -Booting [kernel] in 8 seconds... - -Type '?' for a list of commands, 'help' for more detailed help. -ok <userinput>boot -s</userinput></screen> - - </step> - </substeps> - </step> - - <step> - <para>In single-user mode, install the new partitioning - created above.</para> - - <screen>&prompt.root; <userinput>cd /bootvinum</userinput> -&prompt.root; <userinput>disklabel -R ad0s1 disklabel.ad0s1</userinput> -&prompt.root; <userinput>disklabel -R ad2s1 disklabel.ad2s1</userinput></screen> - - <note><para>If you have additional spindles, repeat the - above commands as appropriate for them.</para></note> - - </step> - - <step> - <para>We are about to start <application>Vinum</application> - for the first time. - It is going to want to create several device nodes under - <filename>/dev/vinum</filename> so we will need to mount the - root filesystem for read/write access.</para> - - <screen>&prompt.root; <userinput>fsck -p /</userinput> -&prompt.root; <userinput>mount /</userinput></screen> - </step> - - <step> - <para>Now it is time to create the <application>Vinum</application> - objects that - will embed the existing non-root filesystems on - the root spindle in a - <application>Vinum</application> partition. - This will load the <application>Vinum</application> - kernel module and start <application>Vinum</application> - as a side effect.</para> - - <screen>&prompt.root; <userinput>vinum create create.YouCrazy</userinput></screen> - - <para> - You should see a list of <application>Vinum</application> - objects created that looks like the following:</para> -<screen>1 drives: -D YouCrazy State: up Device /dev/ad0s1h Avail: 0/1818 MB (0%) - -2 volumes: -V home State: up Plexes: 1 Size: 488 MB -V usr State: up Plexes: 1 Size: 1330 MB - -2 plexes: -P home.p0 C State: up Subdisks: 1 Size: 488 MB -P usr.p0 C State: up Subdisks: 1 Size: 1330 MB - -2 subdisks: -S home.p0.s0 State: up PO: 0 B Size: 488 MB -S usr.p0.s0 State: up PO: 0 B Size: 1330 MB</screen> - <para> - You should also see several kernel messages - which state that the <application>Vinum</application> - objects you have created are now <literal>up</literal>.</para> - </step> - - <step> - <para>Our non-root filesystems should now be embedded in a - <application>Vinum</application> partition and - hence available through <application>Vinum</application> - volumes. - It is important to test that this embedding worked.</para> - - <screen>&prompt.root; <userinput>fsck -n /dev/vinum/home</userinput> -&prompt.root; <userinput>fsck -n /dev/vinum/usr</userinput></screen> - - <para>This should produce no errors. - If it does produce errors <emphasis>do not fix them</emphasis>. - Instead, go back and examine the root spindle partition tables - before and after <application>Vinum</application> - to see if you can spot the error. - You can back out the partition table changes by using - <command>disklabel -R</command> with the - <filename>disklabel.*.b4vinum</filename> files.</para> - </step> - - <step> - <para>While we have the root filesystem mounted read/write, this is - a good time to install <filename>/etc/fstab</filename>.</para> - - <screen>&prompt.root; <userinput>mv /etc/fstab /etc/fstab.b4vinum</userinput> -&prompt.root; <userinput>cp /etc/fstab.vinum /etc/fstab</userinput></screen> - </step> - - <step> - <para>We are now done with tasks requiring single-user - mode, so it is safe to go multi-user from here on.</para> - - <screen>&prompt.root; <userinput>^D</userinput></screen> - </step> - - <step> - <para>Login as root.</para> - </step> - - <step> - <para>Edit <filename>/etc/rc.conf</filename> and add this line: - <programlisting>start_vinum="YES"</programlisting></para> - </step> - </procedure> - </section> - </section> - - <section id="P4"> - <title>Bootstrapping Phase 4: Rootback Spindle Setup</title> - - <para>Our goal in this phase is to get redundant copies of all data - from the root spindle to the rootback spindle. - We will first create the necessary <application>Vinum</application> - objects on the rootback spindle. - Then we will ask <application>Vinum</application> - to copy the data from the root spindle to the - rootback spindle. - Finally, we use <command>dump</command> and <command>restore</command> - to copy the root filesystem.</para> - - <section id="P4E"> - <title>Phase 4 Example</title> - - <procedure> - <step> - <para>Now that <application>Vinum</application> - is running on the root spindle, we can bring - it up on the rootback spindle so that our - <application>Vinum</application> volumes can become - failure-resilient.</para> - - <screen>&prompt.root; <userinput>cd /bootvinum</userinput> -&prompt.root; <userinput>vinum create create.UpWindow</userinput></screen> - - <para>You should see a list of <application>Vinum</application> - objects created that - looks like the following:</para> - -<screen>2 drives: -D YouCrazy State: up Device /dev/ad0s1h Avail: 0/1818 MB (0%) -D UpWindow State: up Device /dev/ad2s1h Avail: 2096/3915 MB (53%) - -2 volumes: -V home State: up Plexes: 2 Size: 488 MB -V usr State: up Plexes: 2 Size: 1330 MB - -4 plexes: -P home.p0 C State: up Subdisks: 1 Size: 488 MB -P usr.p0 C State: up Subdisks: 1 Size: 1330 MB -P home.p1 C State: faulty Subdisks: 1 Size: 488 MB -P usr.p1 C State: faulty Subdisks: 1 Size: 1330 MB - -4 subdisks: -S home.p0.s0 State: up PO: 0 B Size: 488 MB -S usr.p0.s0 State: up PO: 0 B Size: 1330 MB -S home.p1.s0 State: stale PO: 0 B Size: 488 MB -S usr.p1.s0 State: stale PO: 0 B Size: 1330 MB</screen> - - <para>You should also see several kernel messages - which state that some of the <application>Vinum</application> - objects you have created are now <literal>up</literal> - while others are <literal>faulty</literal> or - <literal>stale</literal>.</para> - </step> - - <step> - <para>Now we ask <application>Vinum</application> - to copy each of the subdisks on drive - <literal>YouCrazy</literal> to drive <literal>UpWindow</literal>. - This will change the state of the newly created - <application>Vinum</application> subdisks - from <literal>stale</literal> to <literal>up</literal>. - It will also change the state of the newly created - <application>Vinum</application> plexes - from <literal>faulty</literal> to <literal>up</literal>.</para> - - <para>First, we do the new subdisk we - added to <filename>/home</filename>.</para> - - <screen>&prompt.root; <userinput>vinum start -w home.p1.s0</userinput> -reviving home.p1.s0 -<emphasis>(time passes . . . )</emphasis> -home.p1.s0 is up by force -home.p1 is up -home.p1.s0 is up</screen> - <note> - <para> - My 5,400 RPM EIDE spindles copied at about 3.5 MBytes/sec. - Your mileage may vary. - </para> - </note> - </step> - - <step> - <para>Next we do the new subdisk we - added to <filename>/usr</filename>.</para> - - <screen>&prompt.root; <userinput>vinum start -w usr.p1.s0</userinput> -reviving usr.p1.s0 -<emphasis>(time passes . . . )</emphasis> -usr.p1.s0 is up by force -usr.p1 is up -usr.p1.s0 is up</screen> - - <para>All <application>Vinum</application> - objects should be in state <literal>up</literal> at this point. - The output of - <command>vinum list</command> should look - like the following:</para> - -<screen>2 drives: -D YouCrazy State: up Device /dev/ad0s1h Avail: 0/1818 MB (0%) -D UpWindow State: up Device /dev/ad2s1h Avail: 2096/3915 MB (53%) - -2 volumes: -V home State: up Plexes: 2 Size: 488 MB -V usr State: up Plexes: 2 Size: 1330 MB - -4 plexes: -P home.p0 C State: up Subdisks: 1 Size: 488 MB -P usr.p0 C State: up Subdisks: 1 Size: 1330 MB -P home.p1 C State: up Subdisks: 1 Size: 488 MB -P usr.p1 C State: up Subdisks: 1 Size: 1330 MB - -4 subdisks: -S home.p0.s0 State: up PO: 0 B Size: 488 MB -S usr.p0.s0 State: up PO: 0 B Size: 1330 MB -S home.p1.s0 State: up PO: 0 B Size: 488 MB -S usr.p1.s0 State: up PO: 0 B Size: 1330 MB</screen> - </step> - - <step> - <para>Copy the root filesystem so that you will have a backup.</para> - - <screen>&prompt.root; <userinput>cd /rootback</userinput> -&prompt.root; <userinput>dump 0f - / | restore rf -</userinput> -&prompt.root; <userinput>rm restoresymtable</userinput> -&prompt.root; <userinput>cd /</userinput></screen> - - <note> - <para>You may see errors like this:</para> - - <screen>./tmp/rstdir1001216411: (inode 558) not found on tape -cannot find directory inode 265 -abort? [yn] <userinput>n</userinput> -expected next file 492, got 491</screen> - - <para>They seem to cause no harm. - I suspect they are a consequence of dumping the filesystem - containing <filename>/tmp</filename> and/or the pipe - connecting <command>dump</command> and - <command>restore</command>.</para> - - </note> - </step> - - <step> - <para>Make a directory on which we can mount a damaged root - filesystem during the recovery process.</para> - - <screen>&prompt.root; <userinput>mkdir /rootbad</userinput></screen> - - </step> - - <step> - <para>Remove sentinel mount points that are now unused.</para> - - <screen>&prompt.root; <userinput>rmdir /NOFUTURE*</userinput></screen> - - </step> - - <step> - <para>Create empty &vinum.ap; drives on remaining spindles.</para> - - <screen>&prompt.root; <userinput>vinum create create.ThruBank</userinput> -&prompt.root; <userinput>...</userinput></screen> - - </step> - </procedure> - - <para>At this point, the reliable server foundation is complete. - The right-hand side of <xref linkend=ad0b4aft> above - and the right-hand side of <xref linkend=ad2b4aft> above - show how the disks will look.</para> - - <para>You may want to do a quick reboot to multi-user and give it - a quick test drive. - This is also a good point to complete installation - of other distributions beyond the minimal install. - Add packages, ports, and users as required. - Configure <filename>/etc/rc.conf</filename> as required.</para> - - <tip> - <para>After you have completed your server configuration, - remember to do one more copy of root to - <filename>/rootback</filename> as shown above before placing - the server into production.</para></tip> - - <tip> - <para>Make a schedule to refresh - <filename>/rootback</filename> periodically.</para></tip> - - <tip> - <para>It may be a good idea to mount - <filename>/rootback</filename> read-only for normal operation - of the server. - This does, however, complicate the periodic refresh a bit.</para></tip> - - <tip> - <para>Do not forget to watch - <filename>/var/log/messages</filename> carefully for errors. - <application>Vinum</application> - may automatically avoid failed hardware in a way that users - do not notice. - You must watch for such failures and get them repaired before a - second failure results in data loss. - You may see - <application>Vinum</application> noting damaged objects - at server boot time.</para></tip> - - </section> - </section> - </section> - - <section id="FromHere"> - <title>Where to Go from Here?</title> - - <para>Now that you have established the foundation of a reliable server, - there are several things you might want to try next.</para> - - <section> - <title>Make a Vinum Volume with Remaining Space</title> - - <para>Following are the steps to create another - <application>Vinum</application> volume with space remaining - on the rootback spindle.</para> - - <note><para>This volume will not be resilient to spindle failure - since it has only one plex on a single spindle.</para></note> - - <procedure> - <step> - <para>Create a file with the following contents:</para> - - <programlisting>volume hope - plex name hope.p0 org concat volume hope - sd name hope.p0.s0 drive UpWindow plex hope.p0 len 0</programlisting> - - <note> - <para>Specifying a length of <literal>0</literal> for - the <filename>hope.p0.s0</filename> subdisk - asks <application>Vinum</application> - to use whatever space is left available on the underlying - drive.</para></note> - </step> - - <step> - <para>Feed these commands into <command>vinum</command> <option>create</option>.</para> - <screen>&prompt.root; <userinput>vinum create <replaceable>filename</replaceable></userinput></screen> - </step> - - <step> - <para>Now we <command>newfs</command> the volume and - <command>mount</command> it.</para> - - <screen>&prompt.root; <userinput>newfs -v /dev/vinum/hope</userinput> -&prompt.root; <userinput>mkdir /hope</userinput> -&prompt.root; <userinput>mount /dev/vinum/hope /hope</userinput></screen> - - </step> - - <step> - <para>Edit <filename>/etc/fstab</filename> if you want - <filename>/hope</filename> mounted at boot time.</para> - </step> - - </procedure> - </section> - - <section> - <title>Try Out More Vinum Commands</title> - - <para>You might already be familiar with - <command>vinum</command> <option>list</option> to get a list of - all <application>Vinum</application> objects. - Try <option>-v</option> following it to see more detail.</para> - - <para>If you have more spindles and you want to bring them up as - concatenated, mirrored, or striped volumes, then give - <command>vinum</command> <option>concat</option> <replaceable>drivelist</replaceable>, - <command>vinum</command> <option>mirror</option> <replaceable>drivelist</replaceable>, or - <command>vinum</command> <option>stripe</option> <replaceable>drivelist</replaceable> a try.</para> - - <para>See &man.vinum.8; for sample configurations and important - performance considerations before settling on a final organization - for your additional spindles.</para> - - <para>The failure recovery instructions below will also give you - some experience using more <application>Vinum</application> - commands.</para> - - </section> - </section> - - <section id="Failures"> - <title>Failure Scenarios</title> - - <para>This section contains descriptions of various failure scenarios. - For each scenario, there is a subsection on how to configure your - server for degraded mode operation, how to recover from the failure, - how to exit degraded mode, and how to simulate the failure.</para> - - <tip> - <para>Make a hard copy of these instructions and leave them inside the CPU - case, being careful not to interfere with ventilation.</para></tip> - - <section id="ad0RootBad"> - <title>Root filesystem on ad0 unusable, rest of drive ok</title> - - <note> - <para>We assume here that the boot blocks and disk label on - <devicename>/dev/ad0</devicename> are ok. - If your BIOS can boot from a drive other than - <devicename>C:</devicename>, you may be able to get around this - limitation.</para></note> - - <section id="enter1"> - <title>Configure Server for Degraded Mode</title> - - <procedure> - <step> - <para>Use BootMgr to load kernel from - <devicename>/dev/ad2s1a</devicename>.</para> - - <substeps> - <step> - <para>Hit <keycap>F5</keycap> in BootMgr to select - <literal>Drive 1</literal>.</para> - </step> - - <step> - <para>Hit <keycap>F1</keycap> to select - <literal>FreeBSD</literal>.</para> - </step> - </substeps> - </step> - - <step> - <para>After the kernel is loaded, hit any key but enter to interrupt - the boot sequence. - Boot into single-user mode and allow explicit entry of - a root filesystem.</para> - - <screen>Hit [Enter] to boot immediately, or any other key for command prompt. -Booting [kernel] in 8 seconds... - -Type '?' for a list of commands, 'help' for more detailed help. -ok <userinput>boot -as</userinput></screen> - - </step> - - <step> - <para>Select <filename>/rootback</filename> - as your root filesystem.</para> - - <screen>Manual root filesystem specification: - <fstype>:<device> Mount <device> using filesystem <fstype> - e.g. ufs:/dev/da0s1a - ? List valid disk boot devices - <empty line> Abort manual input - - mountroot> <userinput>ufs:/dev/ad2s1a</userinput></screen> - </step> - - <step> - <para>Now that you are in single-user mode, change - <filename>/etc/fstab</filename> to avoid the - bad root filesystem.</para> - - <tip> - <para>If you used the <literal>bootvinum</literal> Perl script from <xref linkend=Perl> - below, then these commands should configure your server for - degraded mode.</para> - - <screen>&prompt.root; <userinput>fsck -p /</userinput> -&prompt.root; <userinput>mount /</userinput> -&prompt.root; <userinput>cd /etc</userinput> -&prompt.root; <userinput>mv fstab fstab.bak</userinput> -&prompt.root; <userinput>cp fstab_ad0s1_root_bad fstab</userinput> -&prompt.root; <userinput>cd /</userinput> -&prompt.root; <userinput>mount -o ro /</userinput> -&prompt.root; <userinput>vinum start</userinput> -&prompt.root; <userinput>fsck -p</userinput> -&prompt.root; <userinput>^D</userinput></screen> - </tip> - </step> - </procedure> - </section> - - <section> - <title>Recovery</title> - - <procedure> - <step> - <para>Restore <devicename>/dev/ad0s1a</devicename> from - backups or copy - <filename>/rootback</filename> to it with these commands:</para> - - <screen>&prompt.root; <userinput>umount /rootbad</userinput> -&prompt.root; <userinput>newfs /dev/ad0s1a</userinput> -&prompt.root; <userinput>tunefs -n enable /dev/ad0s1a</userinput> -&prompt.root; <userinput>mount /rootbad</userinput> -&prompt.root; <userinput>cd /rootbad</userinput> -&prompt.root; <userinput>dump 0f - / | restore rf -</userinput> -&prompt.root; <userinput>rm restoresymtable</userinput></screen> - </step> - </procedure> - </section> - - <section> - <title>Exiting Degraded Mode</title> - - <procedure> - <step> - <para>Enter single-user mode.</para> - - <screen>&prompt.root; <userinput>shutdown now</userinput></screen> - </step> - - <step> - <para>Put <filename>/etc/fstab</filename> back to - normal and reboot.</para> - - <screen>&prompt.root; <userinput>cd /rootbad/etc</userinput> -&prompt.root; <userinput>rm fstab</userinput> -&prompt.root; <userinput>mv fstab.bak fstab</userinput> -&prompt.root; <userinput>reboot</userinput></screen> - </step> - - <step> - <para>Reboot and hit <keycap>F1</keycap> to boot from - <devicename>/dev/ad0</devicename> when - prompted by BootMgr.</para> - </step> - </procedure> - </section> - - <section> - <title>Simulation</title> - - <para>This kind of failure can be simulated by shutting down to - single-user mode and then booting as shown above in - <xref linkend=enter1>.</para> - </section> - </section> - - <section id="ad2Bad"> - <title>Drive ad2 Fails</title> - - <para>This section deals with the total failure of - <devicename>/dev/ad2</devicename>.</para> - - <section> - <title>Configure Server for Degraded Mode</title> - - <procedure> - <step> - <para>After the kernel is loaded, hit any key but - <keycap>Enter</keycap> to interrupt the boot sequence. - Boot into single-user mode.</para> - - <screen>Hit [Enter] to boot immediately, or any other key for command prompt. -Booting [kernel] in 8 seconds... - -Type '?' for a list of commands, 'help' for more detailed help. -ok <userinput>boot -s</userinput></screen> - - </step> - - <step> - <para>Change - <filename>/etc/fstab</filename> to avoid the bad drive. - If you used the <literal>bootvinum</literal> Perl script from <xref linkend=Perl> - below, then - these commands should configure your server for - degraded mode.</para> - - <screen>&prompt.root; <userinput>fsck -p /</userinput> -&prompt.root; <userinput>mount /</userinput> -&prompt.root; <userinput>cd /etc</userinput> -&prompt.root; <userinput>mv fstab fstab.bak</userinput> -&prompt.root; <userinput>cp fstab_only_have_ad0s1 fstab</userinput> -&prompt.root; <userinput>cd /</userinput> -&prompt.root; <userinput>mount -o ro /</userinput> -&prompt.root; <userinput>vinum start</userinput> -&prompt.root; <userinput>fsck -p</userinput> -&prompt.root; <userinput>^D</userinput></screen> - - <para>If you do not have modified versions of - <filename>/etc/fstab</filename> that are ready for use, - then you can use <command>ed</command> to make one. - Alternatively, you can <command>fsck</command> and - <command>mount</command> - <filename>/usr</filename> and then use your - favorite editor.</para> - - </step> - </procedure> - </section> - - <section id=ad2Recov> - <title>Recovery</title> - <procedure> - - <para>We assume here that your server is up and running multi-user in - degraded mode on just - <devicename>/dev/ad0</devicename> and that you have - a new spindle now on - <devicename>/dev/ad2</devicename> ready to go.</para> - - <para>You will need a new spindle with enough room to hold root and swap - partitions plus a <application>Vinum</application> - partition large enough to hold - <filename>/home</filename> and <filename>/usr</filename>.</para> - - <step> - <para>Create a BIOS partition (slice) on the new spindle.</para> - - <screen>&prompt.root; <userinput>/stand/sysinstall</userinput></screen> - - <substeps> - <step><para>Select <literal>Custom</literal>.</para></step> - <step><para>Select <literal>Partition</literal>.</para></step> - <step><para>Select <devicename>ad2</devicename>.</para></step> - <step><para>Create a FreeBSD (type 165) slice - large enough to hold everything mentioned above.</para></step> - <step><para>Write changes.</para></step> - <step><para>Yes, you are absolutely sure.</para></step> - <step><para>Select BootMgr.</para></step> - <step><para>Quit Partitioning.</para></step> - <step><para>Exit <command>/stand/sysinstall</command>.</para></step> - </substeps> - </step> - - <step> - <para>Create disk label partitioning based on current - <devicename>/dev/ad0</devicename> partitioning.</para> - - <screen>&prompt.root; <userinput>disklabel ad0 > /tmp/ad0</userinput> -&prompt.root; <userinput>disklabel -e ad2</userinput></screen> - - <para>This will drop you into your favorite editor.</para> - - <substeps> - <step> - <para>Copy the lines for the <literal>a</literal> and - <literal>b</literal> partitions from - <filename>/tmp/ad0</filename> to the - <devicename>ad2</devicename> disklabel.</para> - </step> - - <step> - <para>Add the <literal>size</literal> of the - <literal>a</literal> and - <literal>b</literal> partitions to find the proper - <literal>offset</literal> for the - <literal>h</literal> partition.</para> - </step> - - <step> - <para>Subtract this <literal>offset</literal> from the - <literal>size</literal> of the <literal>c</literal> - partition to find the proper <literal>size</literal> for the <literal>h</literal> - partition.</para> - </step> - - <step> - <para>Define an <literal>h</literal> partition with the - <literal>size</literal> and - <literal>offset</literal> calculated above.</para> - </step> - - <step> - <para>Set the <literal>fstype</literal> column to - <literal>vinum</literal>.</para> - </step> - - <step> - <para>Save the file and quit your editor.</para> - </step> - </substeps> - </step> - - <step> - <para>Tell <application>Vinum</application> - about the new drive.</para> - - <substeps> - <step> - <para>Ask <application>Vinum</application> to start an - editor with a copy of the current configuration.</para> - - <screen>&prompt.root; <userinput>vinum create</userinput></screen> - - </step> - - <step> - <para>Uncomment the drive line referring to drive - <literal>UpWindow</literal> and set - <literal>device</literal> to - <devicename>/dev/ad2s1h</devicename>.</para></step> - - <step> - <para>Save the file and quit your editor.</para></step> - - </substeps> - </step> - - <step> - <para>Now that <application>Vinum</application> - has two spindles again, revive the mirrors.</para> - - <screen>&prompt.root; <userinput>vinum start -w usr.p1.s0</userinput> -&prompt.root; <userinput>vinum start -w home.p1.s0</userinput></screen> - </step> - - <step> - <para>Now we need to restore - <filename>/rootback</filename> to a current copy of the - root filesystem. - These commands will accomplish this.</para> - - <screen>&prompt.root; <userinput>newfs /dev/ad2s1a</userinput> -&prompt.root; <userinput>tunefs -n enable /dev/ad2s1a</userinput> -&prompt.root; <userinput>mount /dev/ad2s1a /mnt</userinput> -&prompt.root; <userinput>cd /mnt</userinput> -&prompt.root; <userinput>dump 0f - / | restore rf -</userinput> -&prompt.root; <userinput>rm restoresymtable</userinput> -&prompt.root; <userinput>cd /</userinput> -&prompt.root; <userinput>umount /mnt</userinput></screen> - </step> - </procedure> - </section> - - <section> - <title>Exiting Degraded Mode</title> - - <procedure> - <step> - <para>Enter single-user mode.</para> - - <screen>&prompt.root; <userinput>shutdown now</userinput></screen> - </step> - - <step> - <para>Return <filename>/etc/fstab</filename> to - its normal state and reboot.</para> - - <screen>&prompt.root; <userinput>cd /etc</userinput> -&prompt.root; <userinput>rm fstab</userinput> -&prompt.root; <userinput>mv fstab.bak fstab</userinput> -&prompt.root; <userinput>reboot</userinput></screen> - </step> - </procedure> - </section> - - <section> - <title>Simulation</title> - - <para>You can simulate this kind of failure by unplugging - <devicename>/dev/ad2</devicename>, write-protecting it, - or by this procedure:</para> - - <procedure> - <step> - <para>Shutdown to single-user mode.</para> - </step> - - <step> - <para>Unmount all non-root filesystems.</para> - </step> - - <step> - <para>Clobber any existing <application>Vinum</application> - configuration and partitioning on - <devicename>/dev/ad2</devicename>.</para> - - <screen>&prompt.root; <userinput>vinum stop</userinput> -&prompt.root; <userinput>dd if=/dev/zero of=/dev/ad2s1h count=512</userinput> -&prompt.root; <userinput>dd if=/dev/zero of=/dev/ad2 count=512</userinput></screen> - </step> - </procedure> - </section> - </section> - - <section id="ad0Bad"> - <title>Drive ad0 Fails</title> - - <para>Some BIOSes can boot from drive 1 or drive 2 (often called - <devicename>C:</devicename> or <devicename>D:</devicename>), - while others can boot only from drive 1. - If your BIOS can boot from either, the fastest road to recovery - might be to boot directly from <filename>/dev/ad2</filename> - in single-user mode and - install <filename>/etc/fstab_only_have_ad2s1</filename> as - <filename>/etc/fstab</filename>. - You would then have to adapt the <filename>/dev/ad2</filename> - failure recovery instructions from <xref linkend=ad2Recov> above.</para> - - <para>If your BIOS can only boot from drive one, then you will have to - unplug drive <literal>YouCrazy</literal> from the controller for - <devicename>/dev/ad2</devicename> and plug it - into the controller for <devicename>/dev/ad0</devicename>. - Then continue with the instructions for - <devicename>/dev/ad2</devicename> failure recovery - in <xref linkend=ad2Recov> above.</para> - </section> - </section> - - <appendix id="Perl"> - <title>bootvinum Perl Script</title> - - <para>The <literal>bootvinum</literal> Perl script below reads <filename>/etc/fstab</filename> - and current drive partitioning. - It then writes several files in the current directory and several - variants of <filename>/etc/fstab</filename> in <filename>/etc</filename>. - These files significantly simplify the installation of - <application>Vinum</application> and recovery from - spindle failures.</para> - - <programlisting>#!/usr/bin/perl -w -use strict; -use FileHandle; - -my $config_tag1 = '$Id: article.sgml,v 1.15 2004-08-08 13:43:56 hrs Exp $'; -# Copyright (C) 2001 Robert A. Van Valzah -# -# Bootstrap Vinum -# -# Read /etc/fstab and current partitioning for all spindles mentioned there. -# Generate files needed to mirror all filesystems on root spindle. -# A new partition table for each spindle -# Input for the vinum create command to create Vinum objects on each spindle -# A copy of fstab mounting Vinum volumes instead of BSD partitions -# Copies of fstab altered for server's degraded modes of operation -# See handbook for instructions on how to use the the files generated. -# N.B. This bootstrapping method shrinks size of swap partition by the size -# of Vinum's on-disk configuration (265 sectors). It embeds existing file -# systems on the root spindle in Vinum objects without having to copy them. -# Thanks to Greg Lehey for suggesting this bootstrapping method. -# Expectations: -# The root spindle must contain at least root, swap, and /usr partitions -# The rootback spindle must have matching /rootback and swap partitions -# Other spindles should only have a /NOFUTURE* filesystem and maybe swap -# File systems named /NOFUTURE* will be replaced with Vinum drives - -# Change configuration variables below to suit your taste -my $vip = 'h'; # VInum Partition -my @drv = ('YouCrazy', 'UpWindow', 'ThruBank', # Vinum DRiVe names - 'OutSnakes', 'MeWild', 'InMovie', 'HomeJames', 'DownPrices', 'WhileBlind'); -# No configuration variables beyond this point - -my %vols; # One entry per Vinum volume to be created -my @spndl; # One entry per SPiNDLe -my $rsp; # Root SPindle (as in /dev/$rsp) -my $rbsp; # RootBack SPindle (as in /dev/$rbsp) -my $cfgsiz = 265; # Size of Vinum on-disk configuration info in sectors -my $nxtpas = 2; # Next fsck pass number for non-root filesystems - -# Parse fstab, generating the version we'll need for Vinum and noting -# spindles in use. -my $fsin = "/etc/fstab"; -#my $fsin = "simu/fstab"; -open(FSIN, "$fsin") || die("Couldn't open $fsin: $!\n"); - -my $fsout = "/etc/fstab.vinum"; -open(FSOUT, ">$fsout") || die("Couldn't open $fsout for writing: $!\n"); - -while (<FSIN>) { - my ($dev, $mnt, $fstyp, $opt, $dump, $pass) = split; - next if $dev =~ /^#/; - if ($mnt eq '/' || $mnt eq '/rootback' || $mnt =~ /^\/NOFUTURE/) { - my $dn = substr($dev, 5, length($dev)-6); # Device Name without /dev/ - push(@spndl, $dn) unless grep($_ eq $dn, @spndl); - $rsp = $dn if $mnt eq '/'; - next if $mnt =~ /^\/NOFUTURE/; - } - # Move /rootback from partition e to a - if ($mnt =~ /^\/rootback/) { - $dev =~ s/e$/a/; - $pass = 1; - $rbsp = substr($dev, 5, length($dev)-6); - print FSOUT "$dev\t\t$mnt\t$fstyp\t$opt\t\t$dump\t$pass\n"; - next; - } - # Move non-root filesystems on smallest spindle into Vinum - if (defined($rsp) && $dev =~ /^\/dev\/$rsp/ && $dev =~ /[d-h]$/) { - $pass = $nxtpas++; - print FSOUT "/dev/vinum$mnt\t\t$mnt\t\t$fstyp\t$opt\t\t$dump\t$pass\n"; - $vols{$dev}->{mnt} = substr($mnt, 1); - next; - } - print FSOUT $_; -} -close(FSOUT); -die("Found more spindles than we have abstract names\n") if $#spndl > $#drv; -die("Didn't find a root partition!\n") if !defined($rsp); -die("Didn't find a /rootback partition!\n") if !defined($rbsp); - -# Table of server's Degraded Modes -# One row per mode with hash keys -# fn FileName -# xpr eXPRession needed to convert fstab lines for this mode -# cm1 CoMment 1 describing this mode -# cm2 CoMment 2 describing this mode -# FH FileHandle (dynamically initialized below) -my @DM = ( - { cm1 => "When we only have $rsp, comment out lines using $rbsp", - fn => "/etc/fstab_only_have_$rsp", - xpr => "s:^/dev/$rbsp:#\$&:", - }, - { cm1 => "When we only have $rbsp, comment out lines using $rsp and", - cm2 => "rootback becomes root", - fn => "/etc/fstab_only_have_$rbsp", - xpr => "s:^/dev/$rsp:#\$&: || s:/rootback:/\t:", - }, - { cm1 => "When only $rsp root is bad, /rootback becomes root and", - cm2 => "root becomes /rootbad", - fn => "/etc/fstab_${rsp}_root_bad", - xpr => "s:\t/\t:\t/rootbad: || s:/rootback:/\t:", - }, -); - -# Initialize output FileHandles and write comments -foreach my $dm (@DM) { - my $fh = new FileHandle; - $fh->open(">$dm->{fn}") || die("Can't write $dm->{fn}: $!\n"); - print $fh "# $dm->{cm1}\n" if $dm->{cm1}; - print $fh "# $dm->{cm2}\n" if $dm->{cm2}; - $dm->{FH} = $fh; -} - -# Parse the Vinum version of fstab written above and write versions needed -# for server's degraded modes. -open(FSOUT, "$fsout") || die("Couldn't open $fsout: $!\n"); -while (<FSOUT>) { - my $line = $_; - foreach my $dm (@DM) { - $_ = $line; - eval $dm->{xpr}; - print {$dm->{FH}} $_; - } -} - -# Parse partition table for each spindle and write versions needed for Vinum -my $rootsiz; # ROOT partition SIZe -my $swapsiz; # SWAP partition SIZe -my $rspminoff; # Root SPindle MINimum OFFset of non-root, non-swap, non-c parts -my $rspsiz; # Root SPindle SIZe -my $rbspsiz; # RootBack SPindle SIZe -foreach my $i (0..$#spndl) { - my $dlin = "disklabel $spndl[$i] |"; -# my $dlin = "simu/disklabel.$spndl[$i]"; - open(DLIN, "$dlin") || die("Couldn't open $dlin: $!\n"); - - my $dlout = "disklabel.$spndl[$i]"; - open(DLOUT, ">$dlout") || die("Couldn't open $dlout for writing: $!\n"); - - my $dlb4 = "$dlout.b4vinum"; - open(DLB4, ">$dlb4") || die("Couldn't open $dlb4 for writing: $!\n"); - - my $minoff; # MINimum OFFset of non-root, non-swap, non-c partitions - my $totsiz = 0; # TOTal SIZe of all non-root, non-swap, non-c partitions - my $swapspndl = 0; # True if SWAP partition on this SPiNDLe - while (<DLIN>) { - print DLB4 $_; - my ($part, $siz, $off, $fstyp, $fsiz, $bsiz, $bps) = split; - - if ($part && $part eq 'a:' && $spndl[$i] eq $rsp) { - $rootsiz = $siz; - } - if ($part && $part eq 'e:' && $spndl[$i] eq $rbsp) { - if ($rootsiz != $siz) { - die("Rootback size ($siz) != root size ($rootsiz)\n"); - } - } - if ($part && $part eq 'c:') { - $rspsiz = $siz if $spndl[$i] eq $rsp; - $rbspsiz = $siz if $spndl[$i] eq $rbsp; - } - # Make swap partition $cfgsiz sectors smaller - if ($part && $part eq 'b:') { - if ($spndl[$i] eq $rsp) { - $swapsiz = $siz; - } else { - if ($swapsiz != $siz) { - die("Swap partition sizes unequal across spindles\n"); - } - } - printf DLOUT "%4s%9d%9d%10s\n", $part, $siz-$cfgsiz, $off, $fstyp; - $swapspndl = 1; - next; - } - # Move rootback spindle e partitions to a - if ($part && $part eq 'e:' && $spndl[$i] eq $rbsp) { - printf DLOUT "%4s%9d%9d%10s%9d%6d%6d\n", 'a:', $siz, $off, $fstyp, - $fsiz, $bsiz, $bps; - next; - } - # Delete non-root, non-swap, non-c partitions but note their minimum - # offset and total size that're needed below. - if ($part && $part =~ /^[d-h]:$/) { - $minoff = $off unless $minoff; - $minoff = $off if $off < $minoff; - $totsiz += $siz; - if ($spndl[$i] eq $rsp) { # If doing spindle containing root - my $dev = "/dev/$spndl[$i]" . substr($part, 0, 1); - $vols{$dev}->{siz} = $siz; - $vols{$dev}->{off} = $off; - $rspminoff = $minoff; - } - next; - } - print DLOUT $_; - } - if ($swapspndl) { # If there was a swap partition on this spindle - # Make a Vinum partition the size of all non-root, non-swap, - # non-c partitions + the size of Vinum's on-disk configuration. - # Set its offset so that the start of the first subdisk it contains - # coincides with the first filesystem we're embedding in Vinum. - printf DLOUT "%4s%9d%9d%10s\n", "$vip:", $totsiz+$cfgsiz, $minoff-$cfgsiz, - 'vinum'; - } else { - # No need to mess with size size and offset if there was no swap - printf DLOUT "%4s%9d%9d%10s\n", "$vip:", $totsiz, $minoff, - 'vinum'; - } -} -die("Swap partition not found\n") unless $swapsiz; -die("Swap partition not larger than $cfgsiz blocks\n") unless $swapsiz>$cfgsiz; -die("Rootback spindle size not >= root spindle size\n") unless $rbspsiz>=$rspsiz; - -# Generate input to vinum create command needed for each spindle. -foreach my $i (0..$#spndl) { - my $cfn = "create.$drv[$i]"; # Create File Name - open(CF, ">$cfn") || die("Can't open $cfn for writing: $!\n"); - print CF "drive $drv[$i] device /dev/$spndl[$i]$vip\n"; - next unless $spndl[$i] eq $rsp || $spndl[$i] eq $rbsp; - foreach my $dev (keys(%vols)) { - my $mnt = $vols{$dev}->{mnt}; - my $siz = $vols{$dev}->{siz}; - my $off = $vols{$dev}->{off}-$rspminoff+$cfgsiz; - print CF "volume $mnt\n" if $spndl[$i] eq $rsp; - print CF <<EOF; - plex name $mnt.p$i org concat volume $mnt - sd name $mnt.p$i.s0 drive $drv[$i] plex $mnt.p$i len ${siz}s driveoffset ${off}s -EOF - } -}</programlisting> - </appendix> - - <appendix id=ManualBoot> - <title>Manual Vinum Bootstrapping</title> - - <para>The <literal>bootvinum</literal> Perl script in <xref linkend=Perl> makes life easier, but - it may be necessary to manually perform some or all of the steps that - it automates. - This appendix describes how you would manually mimic the script.</para> - - <procedure> - <step> - <para>Make a copy of <filename>/etc/fstab</filename> - to be customized.</para> - - <screen>&prompt.root; <userinput>cp /etc/fstab /etc/fstab.vinum</userinput></screen> - </step> - - <step> - <para>Edit <filename>/etc/fstab.vinum</filename>.</para> - - <substeps> - <step> - <para>Change the <literal>device</literal> column of - non-root partitions on the root spindle to - <filename>/dev/vinum/mnt</filename>.</para></step> - - <step> - <para>Change the <literal>pass</literal> column of - non-root partitions on the root spindle to <userinput>2</userinput>, - <userinput>3</userinput>, etc.</para></step> - - <step> - <para>Delete any lines with mountpoint - matching <filename>/NOFUTURE*</filename>.</para></step> - - <step> - <para>Change the <literal>device</literal> column of - <filename>/rootback</filename> - from <literal>e</literal> to - <literal>a</literal>.</para></step> - - <step> - <para>Change the <literal>pass</literal> column of - <filename>/rootback</filename> to - <userinput>1</userinput>.</para></step> - - </substeps> - </step> - - <step> - <para>Prepare disklabels for editing:</para> - - <screen>&prompt.root; <userinput>cd /bootvinum</userinput> -&prompt.root; <userinput>disklabel ad0s1 > disklabel.ad0s1</userinput> -&prompt.root; <userinput>cp disklabel.ad0s1 disklabel.ad0s1.b4vinum</userinput> -&prompt.root; <userinput>disklabel ad2s1 > disklabel.ad2s1</userinput> -&prompt.root; <userinput>cp disklabel.ad2s1 disklabel.ad2s1.b4vinum</userinput></screen> - </step> - - <step> - <para>Edit <filename>/etc/disklabel.ad?s1</filename>.</para> - - <substeps> - <step> - <para>On the root spindle:</para> - - <substeps> - <step> - <para>Decrease the <literal>size</literal> of the - <literal>b</literal> partition by 265 blocks.</para></step> - - <step> - <para>Note the <literal>size</literal> and - <literal>offset</literal> of the <literal>a</literal> and - <literal>b</literal> partitions.</para></step> - - <step> - <para>Note the smallest <literal>offset</literal> for partitions - <literal>d</literal>-<literal>h</literal>.</para></step> - - <step> - <para>Note the <literal>size</literal> and - <literal>offset</literal> for all non-root, non-swap - partitions (<filename>/home</filename> was probably on - <literal>e</literal> and <filename>/usr</filename> was - probably on <literal>f</literal>).</para></step> - - <step> - <para>Delete partitions - <literal>d</literal>-<literal>h</literal>.</para></step> - - <step> - <para>Create a new <literal>h</literal> partition with - <literal>offset</literal> 265 blocks less than the - smallest <literal>offset</literal> - for partitions <literal>d</literal>-<literal>h</literal> - noted above. - Set its <literal>size</literal> to the <literal>size</literal> - of the <literal>c</literal> partition less the - smallest <literal>offset</literal> - for partitions <literal>d</literal>-<literal>h</literal> - noted above + 265 blocks.</para> - - <note> - <para><application>Vinum</application> - can use any partition other than <literal>c</literal>. - It is not strictly necessary to use <literal>h</literal> - for all your <application>Vinum</application> - partitions, but it is good practice to - be consistent across all spindles.</para></note> - </step> - - <step> - <para>Set the <literal>fstype</literal> of this new - partition to <userinput>vinum</userinput>.</para></step> - </substeps> - </step> - - <step> - <para>On the rootback spindle:</para> - - <substeps> - <step> - <para>Move the <literal>e</literal> partition to - <literal>a</literal>.</para></step> - - <step> - <para>Verify that the <literal>size</literal> of the - <literal>a</literal> and - <literal>b</literal> partitions matches the - root spindle.</para></step> - - <step> - <para>Note the smallest <literal>offset</literal> for partitions - <literal>d</literal>-<literal>h</literal>.</para></step> - - <step> - <para>Delete partitions - <literal>d</literal>-<literal>h</literal>.</para></step> - - <step> - <para>Create a new <literal>h</literal> partition with - <literal>offset</literal> 265 blocks less than the - smallest <literal>offset</literal> - noted above for partitions - <literal>d</literal>-<literal>h</literal>. - Set its <literal>size</literal> to the <literal>size</literal> - of the <literal>c</literal> partition less the - smallest <literal>offset</literal> - for partitions <literal>d</literal>-<literal>h</literal> - noted above + 265 blocks.</para></step> - - <step> - <para>Set the <literal>fstype</literal> of this new - partition to <userinput>vinum</userinput>.</para></step> - </substeps> - </step> - - </substeps> - </step> - - <step> - <para>Create a file named - <filename>create.YouCrazy</filename> that contains:</para> - - <programlisting>drive YouCrazy device /dev/ad0s1h -volume home - plex name home.p0 org concat volume home - sd name home.p0.s0 drive YouCrazy plex home.p0 len $hl driveoffset $ho -volume usr - plex name usr.p0 org concat volume usr - sd name usr.p0.s0 drive YouCrazy plex usr.p0 len $ul driveoffset $uo</programlisting> - - <para>Where:</para> - <itemizedlist> - <listitem><para> - <literal>$hl</literal> is the length noted above for - <filename>/home</filename>.</para></listitem> - - <listitem><para> - <literal>$ho</literal> is the offset noted above for - <filename>/home</filename> less the smallest offset - noted above + 265 blocks.</para></listitem> - - <listitem><para> - <literal>$ul</literal> is the length noted above for - <filename>/usr</filename>.</para></listitem> - - <listitem><para> - <literal>$uo</literal> is the offset noted above for - <filename>/usr</filename> less the smallest offset - noted above + 265 blocks.</para></listitem> - </itemizedlist> - </step> - - <step> - <para>Create a file named - <filename>create.UpWindow</filename> containing:</para> - - <programlisting>drive UpWindow device /dev/ad2s1h - plex name home.p1 org concat volume home - sd name home.p1.s0 drive UpWindow plex home.p1 len $hl driveoffset $ho - plex name usr.p1 org concat volume usr - sd name usr.p1.s0 drive UpWindow plex usr.p1 len $ul driveoffset $uo</programlisting> - - <para>Where <literal>$hl</literal>, <literal>$ho</literal>, <literal>$ul</literal>, and <literal>$uo</literal> are set as above.</para> - </step> - </procedure> - </appendix> - - <appendix id="Acknowledgements"> - <title>Acknowledgements</title> - - <para>I would like to thank Greg Lehey for writing &vinum.ap; and for - providing very helpful comments on early drafts. - Several others made helpful suggestions after reviewing later drafts - including - Dag-Erling Smørgrav, - Michael Splendoria, - Chern Lee, - Stefan Aeschbacher, - Fleming Froekjaer, - Bernd Walter, - Aleksey Baranov, and - Doug Swarin.</para> - </appendix> -</article> diff --git a/en_US.ISO8859-1/articles/vm-design/Makefile b/en_US.ISO8859-1/articles/vm-design/Makefile deleted file mode 100644 index 718d474191..0000000000 --- a/en_US.ISO8859-1/articles/vm-design/Makefile +++ /dev/null @@ -1,21 +0,0 @@ -# -# $FreeBSD$ -# -# Article: Design elements of the FreeBSD VM system - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml -IMAGES_EN= fig1.eps -IMAGES_EN+= fig2.eps -IMAGES_EN+= fig3.eps -IMAGES_EN+= fig4.eps - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/vm-design/article.sgml b/en_US.ISO8859-1/articles/vm-design/article.sgml deleted file mode 100644 index b022a1203d..0000000000 --- a/en_US.ISO8859-1/articles/vm-design/article.sgml +++ /dev/null @@ -1,846 +0,0 @@ -<!-- $FreeBSD$ --> -<!-- FreeBSD Documentation Project --> - -<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>Design elements of the FreeBSD VM system</title> - - <authorgroup> - <author> - <firstname>Matthew</firstname> - - <surname>Dillon</surname> - - <affiliation> - <address> - <email>dillon@apollo.backplane.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.linux; - &tm-attrib.microsoft; - &tm-attrib.opengroup; - &tm-attrib.general; - </legalnotice> - - <abstract> - <para>The title is really just a fancy way of saying that I am going to - attempt to describe the whole VM enchilada, hopefully in a way that - everyone can follow. For the last year I have concentrated on a number - of major kernel subsystems within FreeBSD, with the VM and Swap - subsystems being the most interesting and NFS being <quote>a necessary - chore</quote>. I rewrote only small portions of the code. In the VM - arena the only major rewrite I have done is to the swap subsystem. - Most of my work was cleanup and maintenance, with only moderate code - rewriting and no major algorithmic adjustments within the VM - subsystem. The bulk of the VM subsystem's theoretical base remains - unchanged and a lot of the credit for the modernization effort in the - last few years belongs to John Dyson and David Greenman. Not being a - historian like Kirk I will not attempt to tag all the various features - with peoples names, since I will invariably get it wrong.</para> - </abstract> - - <legalnotice> - <para>This article was originally published in the January 2000 issue of - <ulink url="http://www.daemonnews.org/">DaemonNews</ulink>. This - version of the article may include updates from Matt and other authors - to reflect changes in FreeBSD's VM implementation.</para> - </legalnotice> - </articleinfo> - - <sect1> - <title>Introduction</title> - - <para>Before moving along to the actual design let's spend a little time - on the necessity of maintaining and modernizing any long-living - codebase. In the programming world, algorithms tend to be more - important than code and it is precisely due to BSD's academic roots that - a great deal of attention was paid to algorithm design from the - beginning. More attention paid to the design generally leads to a clean - and flexible codebase that can be fairly easily modified, extended, or - replaced over time. While BSD is considered an <quote>old</quote> - operating system by some people, those of us who work on it tend to view - it more as a <quote>mature</quote> codebase which has various components - modified, extended, or replaced with modern code. It has evolved, and - FreeBSD is at the bleeding edge no matter how old some of the code might - be. This is an important distinction to make and one that is - unfortunately lost to many people. The biggest error a programmer can - make is to not learn from history, and this is precisely the error that - many other modern operating systems have made. &windowsnt; is the best example - of this, and the consequences have been dire. Linux also makes this - mistake to some degree—enough that we BSD folk can make small - jokes about it every once in a while, anyway. Linux's problem is simply - one of a lack of experience and history to compare ideas against, a - problem that is easily and rapidly being addressed by the Linux - community in the same way it has been addressed in the BSD - community—by continuous code development. The &windowsnt; folk, on the - other hand, repeatedly make the same mistakes solved by &unix; decades ago - and then spend years fixing them. Over and over again. They have a - severe case of <quote>not designed here</quote> and <quote>we are always - right because our marketing department says so</quote>. I have little - tolerance for anyone who cannot learn from history.</para> - - <para>Much of the apparent complexity of the FreeBSD design, especially in - the VM/Swap subsystem, is a direct result of having to solve serious - performance issues that occur under various conditions. These issues - are not due to bad algorithmic design but instead rise from - environmental factors. In any direct comparison between platforms, - these issues become most apparent when system resources begin to get - stressed. As I describe FreeBSD's VM/Swap subsystem the reader should - always keep two points in mind. First, the most important aspect of - performance design is what is known as <quote>Optimizing the Critical - Path</quote>. It is often the case that performance optimizations add a - little bloat to the code in order to make the critical path perform - better. Second, a solid, generalized design outperforms a - heavily-optimized design over the long run. While a generalized design - may end up being slower than an heavily-optimized design when they are - first implemented, the generalized design tends to be easier to adapt to - changing conditions and the heavily-optimized design winds up having to - be thrown away. Any codebase that will survive and be maintainable for - years must therefore be designed properly from the beginning even if it - costs some performance. Twenty years ago people were still arguing that - programming in assembly was better than programming in a high-level - language because it produced code that was ten times as fast. Today, - the fallibility of that argument is obvious—as are the parallels - to algorithmic design and code generalization.</para> - </sect1> - - <sect1> - <title>VM Objects</title> - - <para>The best way to begin describing the FreeBSD VM system is to look at - it from the perspective of a user-level process. Each user process sees - a single, private, contiguous VM address space containing several types - of memory objects. These objects have various characteristics. Program - code and program data are effectively a single memory-mapped file (the - binary file being run), but program code is read-only while program data - is copy-on-write. Program BSS is just memory allocated and filled with - zeros on demand, called demand zero page fill. Arbitrary files can be - memory-mapped into the address space as well, which is how the shared - library mechanism works. Such mappings can require modifications to - remain private to the process making them. The fork system call adds an - entirely new dimension to the VM management problem on top of the - complexity already given.</para> - - <para>A program binary data page (which is a basic copy-on-write page) - illustrates the complexity. A program binary contains a preinitialized - data section which is initially mapped directly from the program file. - When a program is loaded into a process's VM space, this area is - initially memory-mapped and backed by the program binary itself, - allowing the VM system to free/reuse the page and later load it back in - from the binary. The moment a process modifies this data, however, the - VM system must make a private copy of the page for that process. Since - the private copy has been modified, the VM system may no longer free it, - because there is no longer any way to restore it later on.</para> - - <para>You will notice immediately that what was originally a simple file - mapping has become much more complex. Data may be modified on a - page-by-page basis whereas the file mapping encompasses many pages at - once. The complexity further increases when a process forks. When a - process forks, the result is two processes—each with their own - private address spaces, including any modifications made by the original - process prior to the call to <function>fork()</function>. It would be - silly for the VM system to make a complete copy of the data at the time - of the <function>fork()</function> because it is quite possible that at - least one of the two processes will only need to read from that page - from then on, allowing the original page to continue to be used. What - was a private page is made copy-on-write again, since each process - (parent and child) expects their own personal post-fork modifications to - remain private to themselves and not effect the other.</para> - - <para>FreeBSD manages all of this with a layered VM Object model. The - original binary program file winds up being the lowest VM Object layer. - A copy-on-write layer is pushed on top of that to hold those pages which - had to be copied from the original file. If the program modifies a data - page belonging to the original file the VM system takes a fault and - makes a copy of the page in the higher layer. When a process forks, - additional VM Object layers are pushed on. This might make a little - more sense with a fairly basic example. A <function>fork()</function> - is a common operation for any *BSD system, so this example will consider - a program that starts up, and forks. When the process starts, the VM - system creates an object layer, let's call this A:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig1" format="EPS"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ -| A | -+---------------+</literallayout> - </textobject> - - <textobject> - <phrase>A picture</phrase> - </textobject> - </mediaobject> - - <para>A represents the file—pages may be paged in and out of the - file's physical media as necessary. Paging in from the disk is - reasonable for a program, but we really do not want to page back out and - overwrite the executable. The VM system therefore creates a second - layer, B, that will be physically backed by swap space:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig2" format="EPS"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ -| B | -+---------------+ -| A | -+---------------+</literallayout> - </textobject> - </mediaobject> - - <para>On the first write to a page after this, a new page is created in B, - and its contents are initialized from A. All pages in B can be paged in - or out to a swap device. When the program forks, the VM system creates - two new object layers—C1 for the parent, and C2 for the - child—that rest on top of B:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig3" format="EPS"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+-------+-------+ -| C1 | C2 | -+-------+-------+ -| B | -+---------------+ -| A | -+---------------+</literallayout> - </textobject> - </mediaobject> - - <para>In this case, let's say a page in B is modified by the original - parent process. The process will take a copy-on-write fault and - duplicate the page in C1, leaving the original page in B untouched. - Now, let's say the same page in B is modified by the child process. The - process will take a copy-on-write fault and duplicate the page in C2. - The original page in B is now completely hidden since both C1 and C2 - have a copy and B could theoretically be destroyed if it does not - represent a <quote>real</quote> file). However, this sort of optimization is not - trivial to make because it is so fine-grained. FreeBSD does not make - this optimization. Now, suppose (as is often the case) that the child - process does an <function>exec()</function>. Its current address space - is usually replaced by a new address space representing a new file. In - this case, the C2 layer is destroyed:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="fig4" format="EPS"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+-------+ -| C1 | -+-------+-------+ -| B | -+---------------+ -| A | -+---------------+</literallayout> - </textobject> - </mediaobject> - - <para>In this case, the number of children of B drops to one, and all - accesses to B now go through C1. This means that B and C1 can be - collapsed together. Any pages in B that also exist in C1 are deleted - from B during the collapse. Thus, even though the optimization in the - previous step could not be made, we can recover the dead pages when - either of the processes exit or <function>exec()</function>.</para> - - <para>This model creates a number of potential problems. The first is that - you can wind up with a relatively deep stack of layered VM Objects which - can cost scanning time and memory when you take a fault. Deep - layering can occur when processes fork and then fork again (either - parent or child). The second problem is that you can wind up with dead, - inaccessible pages deep in the stack of VM Objects. In our last example - if both the parent and child processes modify the same page, they both - get their own private copies of the page and the original page in B is - no longer accessible by anyone. That page in B can be freed.</para> - - <para>FreeBSD solves the deep layering problem with a special optimization - called the <quote>All Shadowed Case</quote>. This case occurs if either - C1 or C2 take sufficient COW faults to completely shadow all pages in B. - Lets say that C1 achieves this. C1 can now bypass B entirely, so rather - then have C1->B->A and C2->B->A we now have C1->A and C2->B->A. But - look what also happened—now B has only one reference (C2), so we - can collapse B and C2 together. The end result is that B is deleted - entirely and we have C1->A and C2->A. It is often the case that B will - contain a large number of pages and neither C1 nor C2 will be able to - completely overshadow it. If we fork again and create a set of D - layers, however, it is much more likely that one of the D layers will - eventually be able to completely overshadow the much smaller dataset - represented by C1 or C2. The same optimization will work at any point in - the graph and the grand result of this is that even on a heavily forked - machine VM Object stacks tend to not get much deeper then 4. This is - true of both the parent and the children and true whether the parent is - doing the forking or whether the children cascade forks.</para> - - <para>The dead page problem still exists in the case where C1 or C2 do not - completely overshadow B. Due to our other optimizations this case does - not represent much of a problem and we simply allow the pages to be - dead. If the system runs low on memory it will swap them out, eating a - little swap, but that is it.</para> - - <para>The advantage to the VM Object model is that - <function>fork()</function> is extremely fast, since no real data - copying need take place. The disadvantage is that you can build a - relatively complex VM Object layering that slows page fault handling - down a little, and you spend memory managing the VM Object structures. - The optimizations FreeBSD makes proves to reduce the problems enough - that they can be ignored, leaving no real disadvantage.</para> - </sect1> - - <sect1> - <title>SWAP Layers</title> - - <para>Private data pages are initially either copy-on-write or zero-fill - pages. When a change, and therefore a copy, is made, the original - backing object (usually a file) can no longer be used to save a copy of - the page when the VM system needs to reuse it for other purposes. This - is where SWAP comes in. SWAP is allocated to create backing store for - memory that does not otherwise have it. FreeBSD allocates the swap - management structure for a VM Object only when it is actually needed. - However, the swap management structure has had problems - historically.</para> - - <para>Under FreeBSD 3.X the swap management structure preallocates an - array that encompasses the entire object requiring swap backing - store—even if only a few pages of that object are swap-backed. - This creates a kernel memory fragmentation problem when large objects - are mapped, or processes with large runsizes (RSS) fork. Also, in order - to keep track of swap space, a <quote>list of holes</quote> is kept in - kernel memory, and this tends to get severely fragmented as well. Since - the <quote>list of holes</quote> is a linear list, the swap allocation and freeing - performance is a non-optimal O(n)-per-page. It also requires kernel - memory allocations to take place during the swap freeing process, and - that creates low memory deadlock problems. The problem is further - exacerbated by holes created due to the interleaving algorithm. Also, - the swap block map can become fragmented fairly easily resulting in - non-contiguous allocations. Kernel memory must also be allocated on the - fly for additional swap management structures when a swapout occurs. It - is evident that there was plenty of room for improvement.</para> - - <para>For FreeBSD 4.X, I completely rewrote the swap subsystem. With this - rewrite, swap management structures are allocated through a hash table - rather than a linear array giving them a fixed allocation size and much - finer granularity. Rather then using a linearly linked list to keep - track of swap space reservations, it now uses a bitmap of swap blocks - arranged in a radix tree structure with free-space hinting in the radix - node structures. This effectively makes swap allocation and freeing an - O(1) operation. The entire radix tree bitmap is also preallocated in - order to avoid having to allocate kernel memory during critical low - memory swapping operations. After all, the system tends to swap when it - is low on memory so we should avoid allocating kernel memory at such - times in order to avoid potential deadlocks. Finally, to reduce - fragmentation the radix tree is capable of allocating large contiguous - chunks at once, skipping over smaller fragmented chunks. I did not take - the final step of having an <quote>allocating hint pointer</quote> that would trundle - through a portion of swap as allocations were made in order to further - guarantee contiguous allocations or at least locality of reference, but - I ensured that such an addition could be made.</para> - </sect1> - - <sect1> - <title>When to free a page</title> - - <para>Since the VM system uses all available memory for disk caching, - there are usually very few truly-free pages. The VM system depends on - being able to properly choose pages which are not in use to reuse for - new allocations. Selecting the optimal pages to free is possibly the - single-most important function any VM system can perform because if it - makes a poor selection, the VM system may be forced to unnecessarily - retrieve pages from disk, seriously degrading system performance.</para> - - <para>How much overhead are we willing to suffer in the critical path to - avoid freeing the wrong page? Each wrong choice we make will cost us - hundreds of thousands of CPU cycles and a noticeable stall of the - affected processes, so we are willing to endure a significant amount of - overhead in order to be sure that the right page is chosen. This is why - FreeBSD tends to outperform other systems when memory resources become - stressed.</para> - - <para>The free page determination algorithm is built upon a history of the - use of memory pages. To acquire this history, the system takes advantage - of a page-used bit feature that most hardware page tables have.</para> - - <para>In any case, the page-used bit is cleared and at some later point - the VM system comes across the page again and sees that the page-used - bit has been set. This indicates that the page is still being actively - used. If the bit is still clear it is an indication that the page is not - being actively used. By testing this bit periodically, a use history (in - the form of a counter) for the physical page is developed. When the VM - system later needs to free up some pages, checking this history becomes - the cornerstone of determining the best candidate page to reuse.</para> - - <sidebar> - <title>What if the hardware has no page-used bit?</title> - - <para>For those platforms that do not have this feature, the system - actually emulates a page-used bit. It unmaps or protects a page, - forcing a page fault if the page is accessed again. When the page - fault is taken, the system simply marks the page as having been used - and unprotects the page so that it may be used. While taking such page - faults just to determine if a page is being used appears to be an - expensive proposition, it is much less expensive than reusing the page - for some other purpose only to find that a process needs it back and - then have to go to disk.</para> - </sidebar> - - <para>FreeBSD makes use of several page queues to further refine the - selection of pages to reuse as well as to determine when dirty pages - must be flushed to their backing store. Since page tables are dynamic - entities under FreeBSD, it costs virtually nothing to unmap a page from - the address space of any processes using it. When a page candidate has - been chosen based on the page-use counter, this is precisely what is - done. The system must make a distinction between clean pages which can - theoretically be freed up at any time, and dirty pages which must first - be written to their backing store before being reusable. When a page - candidate has been found it is moved to the inactive queue if it is - dirty, or the cache queue if it is clean. A separate algorithm based on - the dirty-to-clean page ratio determines when dirty pages in the - inactive queue must be flushed to disk. Once this is accomplished, the - flushed pages are moved from the inactive queue to the cache queue. At - this point, pages in the cache queue can still be reactivated by a VM - fault at relatively low cost. However, pages in the cache queue are - considered to be <quote>immediately freeable</quote> and will be reused - in an LRU (least-recently used) fashion when the system needs to - allocate new memory.</para> - - <para>It is important to note that the FreeBSD VM system attempts to - separate clean and dirty pages for the express reason of avoiding - unnecessary flushes of dirty pages (which eats I/O bandwidth), nor does - it move pages between the various page queues gratuitously when the - memory subsystem is not being stressed. This is why you will see some - systems with very low cache queue counts and high active queue counts - when doing a <command>systat -vm</command> command. As the VM system - becomes more stressed, it makes a greater effort to maintain the various - page queues at the levels determined to be the most effective. An urban - myth has circulated for years that Linux did a better job avoiding - swapouts than FreeBSD, but this in fact is not true. What was actually - occurring was that FreeBSD was proactively paging out unused pages in - order to make room for more disk cache while Linux was keeping unused - pages in core and leaving less memory available for cache and process - pages. I do not know whether this is still true today.</para> - </sect1> - - <sect1> - <title>Pre-Faulting and Zeroing Optimizations</title> - - <para>Taking a VM fault is not expensive if the underlying page is already - in core and can simply be mapped into the process, but it can become - expensive if you take a whole lot of them on a regular basis. A good - example of this is running a program such as &man.ls.1; or &man.ps.1; - over and over again. If the program binary is mapped into memory but - not mapped into the page table, then all the pages that will be accessed - by the program will have to be faulted in every time the program is run. - This is unnecessary when the pages in question are already in the VM - Cache, so FreeBSD will attempt to pre-populate a process's page tables - with those pages that are already in the VM Cache. One thing that - FreeBSD does not yet do is pre-copy-on-write certain pages on exec. For - example, if you run the &man.ls.1; program while running <command>vmstat - 1</command> you will notice that it always takes a certain number of - page faults, even when you run it over and over again. These are - zero-fill faults, not program code faults (which were pre-faulted in - already). Pre-copying pages on exec or fork is an area that could use - more study.</para> - - <para>A large percentage of page faults that occur are zero-fill faults. - You can usually see this by observing the <command>vmstat -s</command> - output. These occur when a process accesses pages in its BSS area. The - BSS area is expected to be initially zero but the VM system does not - bother to allocate any memory at all until the process actually accesses - it. When a fault occurs the VM system must not only allocate a new page, - it must zero it as well. To optimize the zeroing operation the VM system - has the ability to pre-zero pages and mark them as such, and to request - pre-zeroed pages when zero-fill faults occur. The pre-zeroing occurs - whenever the CPU is idle but the number of pages the system pre-zeros is - limited in order to avoid blowing away the memory caches. This is an - excellent example of adding complexity to the VM system in order to - optimize the critical path.</para> - </sect1> - - <sect1> - <title>Page Table Optimizations</title> - - <para>The page table optimizations make up the most contentious part of - the FreeBSD VM design and they have shown some strain with the advent of - serious use of <function>mmap()</function>. I think this is actually a - feature of most BSDs though I am not sure when it was first introduced. - There are two major optimizations. The first is that hardware page - tables do not contain persistent state but instead can be thrown away at - any time with only a minor amount of management overhead. The second is - that every active page table entry in the system has a governing - <literal>pv_entry</literal> structure which is tied into the - <literal>vm_page</literal> structure. FreeBSD can simply iterate - through those mappings that are known to exist while Linux must check - all page tables that <emphasis>might</emphasis> contain a specific - mapping to see if it does, which can achieve O(n^2) overhead in certain - situations. It is because of this that FreeBSD tends to make better - choices on which pages to reuse or swap when memory is stressed, giving - it better performance under load. However, FreeBSD requires kernel - tuning to accommodate large-shared-address-space situations such as - those that can occur in a news system because it may run out of - <literal>pv_entry</literal> structures.</para> - - <para>Both Linux and FreeBSD need work in this area. FreeBSD is trying to - maximize the advantage of a potentially sparse active-mapping model (not - all processes need to map all pages of a shared library, for example), - whereas Linux is trying to simplify its algorithms. FreeBSD generally - has the performance advantage here at the cost of wasting a little extra - memory, but FreeBSD breaks down in the case where a large file is - massively shared across hundreds of processes. Linux, on the other hand, - breaks down in the case where many processes are sparsely-mapping the - same shared library and also runs non-optimally when trying to determine - whether a page can be reused or not.</para> - </sect1> - - <sect1> - <title>Page Coloring</title> - - <para>We will end with the page coloring optimizations. Page coloring is a - performance optimization designed to ensure that accesses to contiguous - pages in virtual memory make the best use of the processor cache. In - ancient times (i.e. 10+ years ago) processor caches tended to map - virtual memory rather than physical memory. This led to a huge number of - problems including having to clear the cache on every context switch in - some cases, and problems with data aliasing in the cache. Modern - processor caches map physical memory precisely to solve those problems. - This means that two side-by-side pages in a processes address space may - not correspond to two side-by-side pages in the cache. In fact, if you - are not careful side-by-side pages in virtual memory could wind up using - the same page in the processor cache—leading to cacheable data - being thrown away prematurely and reducing CPU performance. This is true - even with multi-way set-associative caches (though the effect is - mitigated somewhat).</para> - - <para>FreeBSD's memory allocation code implements page coloring - optimizations, which means that the memory allocation code will attempt - to locate free pages that are contiguous from the point of view of the - cache. For example, if page 16 of physical memory is assigned to page 0 - of a process's virtual memory and the cache can hold 4 pages, the page - coloring code will not assign page 20 of physical memory to page 1 of a - process's virtual memory. It would, instead, assign page 21 of physical - memory. The page coloring code attempts to avoid assigning page 20 - because this maps over the same cache memory as page 16 and would result - in non-optimal caching. This code adds a significant amount of - complexity to the VM memory allocation subsystem as you can well - imagine, but the result is well worth the effort. Page Coloring makes VM - memory as deterministic as physical memory in regards to cache - performance.</para> - </sect1> - - <sect1> - <title>Conclusion</title> - - <para>Virtual memory in modern operating systems must address a number of - different issues efficiently and for many different usage patterns. The - modular and algorithmic approach that BSD has historically taken allows - us to study and understand the current implementation as well as - relatively cleanly replace large sections of the code. There have been a - number of improvements to the FreeBSD VM system in the last several - years, and work is ongoing.</para> - </sect1> - - <sect1> - <title>Bonus QA session by Allen Briggs - <email>briggs@ninthwonder.com</email></title> - - <qandaset> - <qandaentry> - <question> - <para>What is <quote>the interleaving algorithm</quote> that you - refer to in your listing of the ills of the FreeBSD 3.X swap - arrangements?</para> - </question> - - <answer> - <para>FreeBSD uses a fixed swap interleave which defaults to 4. This - means that FreeBSD reserves space for four swap areas even if you - only have one, two, or three. Since swap is interleaved the linear - address space representing the <quote>four swap areas</quote> will be - fragmented if you do not actually have four swap areas. For - example, if you have two swap areas A and B FreeBSD's address - space representation for that swap area will be interleaved in - blocks of 16 pages:</para> - - <literallayout>A B C D A B C D A B C D A B C D</literallayout> - - <para>FreeBSD 3.X uses a <quote>sequential list of free - regions</quote> approach to accounting for the free swap areas. - The idea is that large blocks of free linear space can be - represented with a single list node - (<filename>kern/subr_rlist.c</filename>). But due to the - fragmentation the sequential list winds up being insanely - fragmented. In the above example, completely unused swap will - have A and B shown as <quote>free</quote> and C and D shown as - <quote>all allocated</quote>. Each A-B sequence requires a list - node to account for because C and D are holes, so the list node - cannot be combined with the next A-B sequence.</para> - - <para>Why do we interleave our swap space instead of just tack swap - areas onto the end and do something fancier? Because it is a whole - lot easier to allocate linear swaths of an address space and have - the result automatically be interleaved across multiple disks than - it is to try to put that sophistication elsewhere.</para> - - <para>The fragmentation causes other problems. Being a linear list - under 3.X, and having such a huge amount of inherent - fragmentation, allocating and freeing swap winds up being an O(N) - algorithm instead of an O(1) algorithm. Combined with other - factors (heavy swapping) and you start getting into O(N^2) and - O(N^3) levels of overhead, which is bad. The 3.X system may also - need to allocate KVM during a swap operation to create a new list - node which can lead to a deadlock if the system is trying to - pageout pages in a low-memory situation.</para> - - <para>Under 4.X we do not use a sequential list. Instead we use a - radix tree and bitmaps of swap blocks rather than ranged list - nodes. We take the hit of preallocating all the bitmaps required - for the entire swap area up front but it winds up wasting less - memory due to the use of a bitmap (one bit per block) instead of a - linked list of nodes. The use of a radix tree instead of a - sequential list gives us nearly O(1) performance no matter how - fragmented the tree becomes.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I do not get the following:</para> - - <blockquote> - <para>It is important to note that the FreeBSD VM system attempts - to separate clean and dirty pages for the express reason of - avoiding unnecessary flushes of dirty pages (which eats I/O - bandwidth), nor does it move pages between the various page - queues gratuitously when the memory subsystem is not being - stressed. This is why you will see some systems with very low - cache queue counts and high active queue counts when doing a - <command>systat -vm</command> command.</para> - </blockquote> - - <para>How is the separation of clean and dirty (inactive) pages - related to the situation where you see low cache queue counts and - high active queue counts in <command>systat -vm</command>? Do the - systat stats roll the active and dirty pages together for the - active queue count?</para> - </question> - - <answer> - <para>Yes, that is confusing. The relationship is - <quote>goal</quote> verses <quote>reality</quote>. Our goal is to - separate the pages but the reality is that if we are not in a - memory crunch, we do not really have to.</para> - - <para>What this means is that FreeBSD will not try very hard to - separate out dirty pages (inactive queue) from clean pages (cache - queue) when the system is not being stressed, nor will it try to - deactivate pages (active queue -> inactive queue) when the system - is not being stressed, even if they are not being used.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para> In the &man.ls.1; / <command>vmstat 1</command> example, - would not some of the page faults be data page faults (COW from - executable file to private page)? I.e., I would expect the page - faults to be some zero-fill and some program data. Or are you - implying that FreeBSD does do pre-COW for the program data?</para> - </question> - - <answer> - <para>A COW fault can be either zero-fill or program-data. The - mechanism is the same either way because the backing program-data - is almost certainly already in the cache. I am indeed lumping the - two together. FreeBSD does not pre-COW program data or zero-fill, - but it <emphasis>does</emphasis> pre-map pages that exist in its - cache.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>In your section on page table optimizations, can you give a - little more detail about <literal>pv_entry</literal> and - <literal>vm_page</literal> (or should vm_page be - <literal>vm_pmap</literal>—as in 4.4, cf. pp. 180-181 of - McKusick, Bostic, Karel, Quarterman)? Specifically, what kind of - operation/reaction would require scanning the mappings?</para> - - <para>How does Linux do in the case where FreeBSD breaks down - (sharing a large file mapping over many processes)?</para> - </question> - - <answer> - <para>A <literal>vm_page</literal> represents an (object,index#) - tuple. A <literal>pv_entry</literal> represents a hardware page - table entry (pte). If you have five processes sharing the same - physical page, and three of those processes's page tables actually - map the page, that page will be represented by a single - <literal>vm_page</literal> structure and three - <literal>pv_entry</literal> structures.</para> - - <para><literal>pv_entry</literal> structures only represent pages - mapped by the MMU (one <literal>pv_entry</literal> represents one - pte). This means that when we need to remove all hardware - references to a <literal>vm_page</literal> (in order to reuse the - page for something else, page it out, clear it, dirty it, and so - forth) we can simply scan the linked list of - <literal>pv_entry</literal>'s associated with that - <literal>vm_page</literal> to remove or modify the pte's from - their page tables.</para> - - <para>Under Linux there is no such linked list. In order to remove - all the hardware page table mappings for a - <literal>vm_page</literal> linux must index into every VM object - that <emphasis>might</emphasis> have mapped the page. For - example, if you have 50 processes all mapping the same shared - library and want to get rid of page X in that library, you need to - index into the page table for each of those 50 processes even if - only 10 of them have actually mapped the page. So Linux is - trading off the simplicity of its design against performance. - Many VM algorithms which are O(1) or (small N) under FreeBSD wind - up being O(N), O(N^2), or worse under Linux. Since the pte's - representing a particular page in an object tend to be at the same - offset in all the page tables they are mapped in, reducing the - number of accesses into the page tables at the same pte offset - will often avoid blowing away the L1 cache line for that offset, - which can lead to better performance.</para> - - <para>FreeBSD has added complexity (the <literal>pv_entry</literal> - scheme) in order to increase performance (to limit page table - accesses to <emphasis>only</emphasis> those pte's that need to be - modified).</para> - - <para>But FreeBSD has a scaling problem that Linux does not in that - there are a limited number of <literal>pv_entry</literal> - structures and this causes problems when you have massive sharing - of data. In this case you may run out of - <literal>pv_entry</literal> structures even though there is plenty - of free memory available. This can be fixed easily enough by - bumping up the number of <literal>pv_entry</literal> structures in - the kernel config, but we really need to find a better way to do - it.</para> - - <para>In regards to the memory overhead of a page table verses the - <literal>pv_entry</literal> scheme: Linux uses - <quote>permanent</quote> page tables that are not throw away, but - does not need a <literal>pv_entry</literal> for each potentially - mapped pte. FreeBSD uses <quote>throw away</quote> page tables but - adds in a <literal>pv_entry</literal> structure for each - actually-mapped pte. I think memory utilization winds up being - about the same, giving FreeBSD an algorithmic advantage with its - ability to throw away page tables at will with very low - overhead.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Finally, in the page coloring section, it might help to have a - little more description of what you mean here. I did not quite - follow it.</para> - </question> - - <answer> - <para>Do you know how an L1 hardware memory cache works? I will - explain: Consider a machine with 16MB of main memory but only 128K - of L1 cache. Generally the way this cache works is that each 128K - block of main memory uses the <emphasis>same</emphasis> 128K of - cache. If you access offset 0 in main memory and then offset - offset 128K in main memory you can wind up throwing away the - cached data you read from offset 0!</para> - - <para>Now, I am simplifying things greatly. What I just described - is what is called a <quote>direct mapped</quote> hardware memory - cache. Most modern caches are what are called - 2-way-set-associative or 4-way-set-associative caches. The - set-associatively allows you to access up to N different memory - regions that overlap the same cache memory without destroying the - previously cached data. But only N.</para> - - <para>So if I have a 4-way set associative cache I can access offset - 0, offset 128K, 256K and offset 384K and still be able to access - offset 0 again and have it come from the L1 cache. If I then - access offset 512K, however, one of the four previously cached - data objects will be thrown away by the cache.</para> - - <para>It is extremely important… - <emphasis>extremely</emphasis> important for most of a processor's - memory accesses to be able to come from the L1 cache, because the - L1 cache operates at the processor frequency. The moment you have - an L1 cache miss and have to go to the L2 cache or to main memory, - the processor will stall and potentially sit twiddling its fingers - for <emphasis>hundreds</emphasis> of instructions worth of time - waiting for a read from main memory to complete. Main memory (the - dynamic ram you stuff into a computer) is - <emphasis>slow</emphasis>, when compared to the speed of a modern - processor core.</para> - - <para>Ok, so now onto page coloring: All modern memory caches are - what are known as <emphasis>physical</emphasis> caches. They - cache physical memory addresses, not virtual memory addresses. - This allows the cache to be left alone across a process context - switch, which is very important.</para> - - <para>But in the &unix; world you are dealing with virtual address - spaces, not physical address spaces. Any program you write will - see the virtual address space given to it. The actual - <emphasis>physical</emphasis> pages underlying that virtual - address space are not necessarily physically contiguous! In fact, - you might have two pages that are side by side in a processes - address space which wind up being at offset 0 and offset 128K in - <emphasis>physical</emphasis> memory.</para> - - <para>A program normally assumes that two side-by-side pages will be - optimally cached. That is, that you can access data objects in - both pages without having them blow away each other's cache entry. - But this is only true if the physical pages underlying the virtual - address space are contiguous (insofar as the cache is - concerned).</para> - - <para>This is what Page coloring does. Instead of assigning - <emphasis>random</emphasis> physical pages to virtual addresses, - which may result in non-optimal cache performance, Page coloring - assigns <emphasis>reasonably-contiguous</emphasis> physical pages - to virtual addresses. Thus programs can be written under the - assumption that the characteristics of the underlying hardware - cache are the same for their virtual address space as they would - be if the program had been run directly in a physical address - space.</para> - - <para>Note that I say <quote>reasonably</quote> contiguous rather - than simply <quote>contiguous</quote>. From the point of view of a - 128K direct mapped cache, the physical address 0 is the same as - the physical address 128K. So two side-by-side pages in your - virtual address space may wind up being offset 128K and offset - 132K in physical memory, but could also easily be offset 128K and - offset 4K in physical memory and still retain the same cache - performance characteristics. So page-coloring does - <emphasis>not</emphasis> have to assign truly contiguous pages of - physical memory to contiguous pages of virtual memory, it just - needs to make sure it assigns contiguous pages from the point of - view of cache performance and operation.</para> - </answer> - </qandaentry> - </qandaset> - </sect1> -</article> diff --git a/en_US.ISO8859-1/articles/zip-drive/Makefile b/en_US.ISO8859-1/articles/zip-drive/Makefile deleted file mode 100644 index b275408717..0000000000 --- a/en_US.ISO8859-1/articles/zip-drive/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -# -# $FreeBSD$ -# -# Article: IOmega ZIP Drives - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?=gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/zip-drive/article.sgml b/en_US.ISO8859-1/articles/zip-drive/article.sgml deleted file mode 100644 index be56e8bf23..0000000000 --- a/en_US.ISO8859-1/articles/zip-drive/article.sgml +++ /dev/null @@ -1,283 +0,0 @@ -<!-- $FreeBSD$ --> - -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ -<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN"> -%articles.ent; -]> - -<article> - <articleinfo> - <title>&iomegazip; Drives</title> - - <authorgroup> - <author> - <firstname>Jason</firstname> - <surname>Bacon</surname> - - <affiliation> - <address><email>acadix@execpc.com</email></address> - </affiliation> - </author> - </authorgroup> - - <legalnotice id="trademarks" role="trademarks"> - &tm-attrib.freebsd; - &tm-attrib.adaptec; - &tm-attrib.iomega; - &tm-attrib.microsoft; - &tm-attrib.opengroup; - &tm-attrib.general; - </legalnotice> - </articleinfo> - - <sect1> - <title>&iomegazip; Drive Basics</title> - - <para>&iomegazip; disks are high capacity, removable, magnetic disks, which can be - read or written by ZIP drives from IOMEGA corporation. ZIP disks are - similar to floppy disks, except that they are much faster, and have a - much greater capacity. While floppy disks typically hold 1.44 - megabytes, ZIP disks are available in two sizes, namely 100 megabytes - and 250 megabytes. ZIP drives should not be confused with the - super-floppy, a 120 megabyte floppy drive which also handles traditional - 1.44 megabyte floppies.</para> - - <para>IOMEGA also sells a higher capacity, higher performance drive called - the &jaz;/JAZZ drive. Jaz drives come in 1 gigabyte and 2 gigabyte - sizes.</para> - - <para>ZIP drives are available as internal or external units, using one of - three interfaces:</para> - - <orderedlist> - <listitem> - <para>The SCSI (Small Computer Standard Interface) interface is the - fastest, most sophisticated, most expandable, and most expensive - interface. The SCSI interface is used by all types of computers - from PC's to RISC workstations to minicomputers, to connect all - types of peripherals such as disk drives, tape drives, scanners, and - so on. SCSI ZIP drives may be internal or external, assuming your - host adapter has an external connector.</para> - - <note> - <para>If you are using an external SCSI device, it is important - never to connect or disconnect it from the SCSI bus while the - computer is running. Doing so may cause file-system damage on the - disks that remain connected.</para> - </note> - - <para>If you want maximum performance and easy setup, the SCSI - interface is the best choice. This will probably require adding a - SCSI host adapter, since most PC's (except for high-performance - servers) do not have built-in SCSI support. Each SCSI host adapter - can support either 7 or 15 SCSI devices, depending on the - model.</para> - - <para>Each SCSI device has its own controller, and these - controllers are fairly intelligent and well standardized, (the - second `S' in SCSI is for Standard) so from the operating system's - point of view, all SCSI disk drives look about the same, as do all - SCSI tape drives, etc. To support SCSI devices, the operating - system need only have a driver for the particular host adapter, and - a generic driver for each type of device, i.e. a SCSI disk driver, - SCSI tape driver, and so on. There are some SCSI devices that can - be better utilized with specialized drivers (e.g. DAT tape drives), - but they tend to work OK with the generic driver, too. It is just - that the generic drivers may not support some of the special - features.</para> - - <para>Using a SCSI zip drive is simply a matter of determining which - device file in the <filename>/dev</filename> directory represents - the ZIP drive. This can be determined by looking at the boot - messages while FreeBSD is booting (or in - <filename>/var/log/messages</filename> after booting), where you - will see a line something like this:</para> - - <programlisting>da1: <IOMEGA ZIP 100 D.13> Removable Direct Access SCSI-2 Device</programlisting> - - <para>This means that the ZIP drive is represented by the file - <filename>/dev/da1</filename>.</para> - </listitem> - - <listitem> - <para>The IDE (Integrated Drive Electronics) interface is a low-cost - disk drive interface used by many desktop PC's. Most IDE devices - are strictly internal.</para> - - <para>Performance of IDE ZIP drives is comparable to SCSI ZIP drives. - (The IDE interface is not as fast as SCSI, but ZIP drives - performance is limited mainly by the mechanics of the drive, not by - the bus interface.)</para> - - <para>The drawback of the IDE interface is the limitations it imposes. - Most IDE adapters can only support 2 devices, and IDE interfaces are - not typically designed for the long term. For example, the original - IDE interface would not support hard disks with more than 1024 - cylinders, which forced a lot of people to upgrade their hardware - prematurely. If you have plans to expand your PC by adding another - disk, a tape drive, or scanner, you may want to invest in a SCSI - host adapter and a SCSI ZIP drive to avoid problems in the - future.</para> - - <para>IDE devices in FreeBSD are prefixed with an <literal>a</literal>. - For example, an IDE hard disk might be - <filename>/dev/ad0</filename>, an IDE (ATAPI) CDROM might be - <filename>/dev/acd1</filename>, and so on.</para> - </listitem> - - <listitem> - <para>The parallel port interface is popular for portable external - devices such as external ZIP drives and scanners, because virtually - every computer has a standard parallel port (usually used for - printers). This makes things easy for people to transfer data - between multiple computers by toting around their ZIP drive.</para> - - <para>Performance will generally be slower than a SCSI or IDE ZIP - drive, since it is limited by the speed of the parallel port. - Parallel port speed varies considerably between various computers, - and can often be configured in the system BIOS. Some machines will - also require BIOS configuration to operate the parallel port in - bidirectional mode. (Parallel ports were originally designed only - for output to printers)</para> - </listitem> - </orderedlist> - </sect1> - - <sect1> - <title>Parallel ZIP: The <devicename>vpo</devicename> Driver</title> - - <para>To use a parallel-port ZIP drive under FreeBSD, the - <devicename>vpo</devicename> driver must be configured into the kernel. - Parallel port ZIP drives also have a built-in SCSI controller. The vpo - driver allows the FreeBSD kernel to communicate with the ZIP drive's - SCSI controller through the parallel port.</para> - - <para>Since the vpo driver is not a standard part of the kernel (as of - FreeBSD 3.2), you will need to rebuild the kernel to enable this device. - The process of building a kernel is outlined in detail in the - <ulink url="&url.books.handbook;/kernelconfig.html">&os; Handbook</ulink>. - The following steps outline the process in brief for the - purpose of enabling the vpo driver:</para> - - <orderedlist> - <listitem> - <para>Run <command>/stand/sysinstall</command>, and install the kernel - source code on your system.</para> - </listitem> - - <listitem> - <para>Create a custom kernel configuration, that includes the - driver for the vpo driver:</para> - - <screen>&prompt.root; <userinput>cd /sys/i386/conf</userinput> -&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen> - - <para>Edit <filename>MYKERNEL</filename>, change the - <literal>ident</literal> line to <literal>MYKERNEL</literal>, and - uncomment the line describing the vpo driver.</para> - - <para>If you have a second parallel port, you may need to copy the - section for <literal>ppc0</literal> to create a - <literal>ppc1</literal> device. The second parallel port usually - uses IRQ 5 and address 378. Only the IRQ is required in the config - file.</para> - - <para>If your root hard disk is a SCSI disk, you might run into a - problem with probing order, which will cause the system to attempt - to use the ZIP drive as the root device. This will cause a boot - failure, unless you happen to have a FreeBSD root file-system on - your ZIP disk! In this case, you will need to <quote>wire - down</quote> the root disk, i.e. force the kernel to bind a - specific device to <filename>/dev/da0</filename>, the root SCSI - disk. It will then assign the ZIP disk to the next available SCSI - disk, e.g. <literal>/dev/da1</literal>. To wire down your SCSI hard - drive as <literal>da0</literal>, change the line - - <programlisting>device da0</programlisting> - - to - - <programlisting>disk da0 at scbus0 target 0 unit 0</programlisting></para> - - <para>You may need to change the target above to match the SCSI ID of - your disk drive. You should also wire down the scbus0 entry to your - controller. For example, if you have an &adaptec; 15xx controller, - you would change - - <programlisting>controller scbus0</programlisting> - - to - - <programlisting>controller scbus0 at aha0</programlisting></para> - - <para>Finally, since you are creating a custom kernel configuration, - you can take the opportunity to remove all the unnecessary drivers. - This should be done with a great deal of caution, and only if you - feel confident about making modifications to your kernel - configuration. Removing unnecessary drivers will reduce the kernel - size, leaving more memory available for your applications. To - determine which drivers are not needed, go to the end of the file - <filename>/var/log/messages</filename>, and look for lines reading - "not found". Then, comment out these devices in your config file. - You can also change other options to reduce the size and increase - the speed of your kernel. Read the section on rebuilding your kernel - for more complete information.</para> - </listitem> - - <listitem> - <para>Now it is time to compile the kernel:</para> - - <screen>&prompt.root; <userinput>/usr/sbin/config MYKERNEL</userinput> -&prompt.root; <userinput>cd ../../compile/MYKERNEL</userinput> -&prompt.root; <userinput>make clean depend && make all install</userinput></screen> - </listitem> - </orderedlist> - - <para>After the kernel is rebuilt, you will need to reboot. Make sure the - ZIP drive is connected to the parallel port before the boot begins. You - should see the ZIP drive show up in the boot messages as device vpo0 or - vpo1, depending on which parallel port the drive is attached to. It - should also show which device file the ZIP drive has been bound to. This - will be <filename>/dev/da0</filename> if you have no other SCSI disks in - the system, or <filename>/dev/da1</filename> if you have a SCSI hard - disk wired down as the root device.</para> - </sect1> - - <sect1> - <title>Mounting ZIP disks</title> - - <para>To access the ZIP disk, you simply mount it like any other disk - device. The file-system is represented as slice 4 on the device, so for - SCSI or parallel ZIP disks, you would use:</para> - - <screen>&prompt.root; <userinput>mount_msdos /dev/da1s4 /mnt</userinput></screen> - - <para>For IDE ZIP drives, use:</para> - - <screen>&prompt.root; <userinput>mount_msdos /dev/ad1s4 /mnt</userinput></screen> - - <para>It will also be helpful to update <filename>/etc/fstab</filename> to - make mounting easier. Add a line like the following, edited to suit your - system: - - <programlisting>/dev/da1s4 /zip msdos rw,noauto 0 0</programlisting> - - and create the directory <filename>/zip</filename>.</para> - - <para>Then, you can mount simply by typing - - <screen>&prompt.root; <userinput>mount /zip</userinput></screen> - - and unmount by typing - - <screen>&prompt.root; <userinput>umount /zip</userinput></screen></para> - - <para>For more information on the format of - <filename>/etc/fstab</filename>, see &man.fstab.5;.</para> - - <para>You can also create a FreeBSD file-system on the ZIP disk using - &man.newfs.8;. However, the disk will only be usable on a FreeBSD - system, or perhaps a few other &unix; clones that recognize FreeBSD - file-systems. (Definitely not &ms-dos; or &windows;.)</para> - </sect1> -</article> |